perplexity

Name: perplexity
Author: Softaworks

Perplexityweb searchAI researchinformation retrievalcoding assistantexternal dataknowledge basetooling

⭐ 2.0k📄 MIT🕒 2026-03-05Source ↗

Install this skill

npx skills add softaworks/agent-toolkit

Works across Claude Code, Cursor, Codex, Copilot & Antigravity

The Perplexity integration within the agent-toolkit provides direct access to live internet data for answering queries and gathering information. It functions as a specialized tool for generic information retrieval, distinguishing between raw search results and synthesized conversational responses. Agents using this skill must manage token consumption by strictly adhering to default limits, as excessive data retrieval impacts efficiency. This tool serves as the middle tier in the agent's research stack, positioned after specialized local knowledge sources like Context7 or Nx MCP but before generic web scraping. By routing specific technical documentation, CLI commands, and project-internal inquiries to their designated handlers, the Perplexity tool maintains a clean information pipeline focused solely on broad knowledge and external web trends.

When to Use This Skill

•Looking up current industry trends in microservices
•Finding general programming tutorials or blog posts
•Asking for explanations of complex architectural trade-offs
•Researching best practices for general technology stacks

How to Invoke This Skill

Example prompts that trigger this skill in Claude Code, Cursor, or Antigravity:

“search for
“find
“look up
“ask
“what's the latest
“research

Pro Tips

💡Always specify `max_results: 3` and `max_tokens_per_page: 512` by default to keep results concise and relevant, increasing only for comprehensive research needs.
💡Distinguish clearly between generic web searches (Perplexity) and specific library/framework documentation (Context7) or workspace queries (Nx MCP) to utilize the correct tool.
💡For conversational answers, explicitly use `Perplexity Ask`; for deep, multi-step research, leverage the dedicated `/research <topic>` agent.

What this skill does

•Fetching external web search results with controllable page limits
•Synthesizing conversational explanations for conceptual queries
•Managing search query volume through token-limited result sets
•Providing real-time information retrieval for non-technical topics

When not to use it

✕Retrieving documentation for specific libraries or frameworks (use Context7)
✕Executing commands or queries related to the local Nx workspace
✕Interacting with the Graphite CLI tool (use Graphite MCP)

Example workflow

Identify if the request requires external web information.
Verify the request does not involve local docs or specific CLI commands.
Select Perplexity Search for finding resources or Perplexity Ask for explanations.
Execute the call with default parameters of 3 results and 512 tokens.
Review the returned information for relevance.
Synthesize the findings into a clear response for the user.

Prerequisites

–Active internet connectivity
–Valid API credentials for the Perplexity service

Pitfalls & limitations

!Ignoring the specific hierarchy, leading to inefficient use of search for documented technical content.
!Over-requesting tokens by failing to use the 3-result default limit.
!Attempting to use the prohibited perplexity_research tool instead of the dedicated agent command.

FAQ

Why should I use Context7 instead of Perplexity for documentation?

Context7 provides direct access to internal library documentation, which is more accurate and faster than fetching general search results from the web.

What should I do if my search returns no relevant information?

You may cautiously increase the limit to 5 results and 1024 tokens, or fallback to the specialized researcher agent for deep dives.

Can I use this for Graphite CLI questions?

No. All inquiries regarding the Graphite CLI must be routed through the Graphite MCP to ensure usage of the correct toolset.

How it compares

This tool automates the process of querying a live search engine and parsing results, replacing manual browser-based searching with programmatic, token-controlled data retrieval.

Source & trust

⭐ 2.0k stars📄 MIT🕒 Updated 2026-03-05

View original skill on GitHub →

📄 Full skill instructions — original source: softaworks/agent-toolkit

# Perplexity Tools

Use ONLY when user says "search", "find", "look up", "ask", "research", or "what's the latest" for generic queries. NOT for library/framework docs (use Context7), gt CLI (use Graphite MCP), or workspace questions (use Nx MCP).

## Quick Reference

**Which Perplexity tool?**
- Need search results/URLs? → **Perplexity Search**
- Need conversational answer? → **Perplexity Ask**
- Need deep research? → **Researcher agent** (/research <topic>)

**NOT Perplexity - use these instead:**
- Library/framework docs → **Context7 MCP**
- Graphite gt CLI → **Graphite MCP**
- THIS workspace → **Nx MCP**
- Specific URL → **URL Crawler**

## Perplexity Search

**When to use:**
- Generic searches, finding resources
- Current best practices, recent information
- Tutorial/blog post discovery
- User says "search for...", "find...", "look up..."

**Default parameters (ALWAYS USE):**

mcp__perplexity__perplexity_search({
  query: "your search query",
  max_results: 3,           // Default is 10 - too many!
  max_tokens_per_page: 512  // Reduce per-result content
})

**When to increase limits:**
Only if:
- User explicitly needs comprehensive results
- Initial search found nothing useful
- Complex topic needs multiple sources

// Increased limits (use sparingly)
mcp__perplexity__perplexity_search({
  query: "complex topic",
  max_results: 5,
  max_tokens_per_page: 1024
})

## Perplexity Ask

**When to use:**
- Need conversational explanation, not search results
- Synthesize information from web
- Explain concepts with current context

**Usage:**

mcp__perplexity__perplexity_ask({
  messages: [
    {
      role: "user",
      content: "Explain how postgres advisory locks work"
    }
  ]
})

**NOT for:**
- Library documentation (use Context7)
- Deep multi-source research (use researcher agent)

## Prohibited Tool

**NEVER use:** mcp__perplexity__perplexity_research

**Use instead:** Researcher agent (/research <topic>)
- Token cost: 30-50k tokens
- Provides multi-source synthesis with citations
- Use sparingly for complex questions only

## Tool Selection Chain

**Priority order:**
1. **Context7 MCP** - Library/framework docs
2. **Graphite MCP** - Any gt CLI mention
3. **Nx MCP** - THIS workspace questions
4. **Perplexity Search** - Generic searches
5. **Perplexity Ask** - Conversational answers
6. **Researcher agent** - Deep multi-source research
7. **WebSearch** - Last resort (after Perplexity exhausted)

## Examples

**✅ CORRECT - Use Perplexity Search:**
- "Find postgres migration best practices"
- "Search for React testing tutorials"
- "Look up latest trends in microservices"

**✅ CORRECT - Use Perplexity Ask:**
- "Explain how postgres advisory locks work"
- "What are the trade-offs of microservices?"

**❌ WRONG - Use Context7 instead:**
- "Search for React hooks documentation" → Context7 MCP
- "Find Next.js routing docs" → Context7 MCP
- "Look up Temporal workflow API" → Context7 MCP

**❌ WRONG - Use Graphite MCP instead:**
- "Search for gt stack commands" → Graphite MCP
- "Find gt branch workflow" → Graphite MCP

**❌ WRONG - Use Nx MCP instead:**
- "Search for build config" (in THIS workspace) → Nx MCP
- "Find project dependencies" (in THIS workspace) → Nx MCP

## Key Points

- **Default to limited results** - avoid context bloat
- **Library docs = Context7** - ALWAYS try Context7 first
- **"gt" = Graphite MCP** - ANY "gt" mention uses Graphite
- **Deep research = /research** - NOT perplexity_research tool
- **Fallback chain** - Search → Ask → WebSearch (last resort)

By Softaworks

How to Use This Skill Unit

Option A: Project-Specific (Recommended)

Click "Download" above
In your project, create the directory: .agent/skills/perplexity/
Save the file as SKILL.md
The agent will automatically discover the skill based on its description.

Option B: Global Installation (All Agents)

Save the file to these locations to make it available across all projects:

Claude Code: ~/.claude/skills/softaworks/agent-toolkit/perplexity/SKILL.md
Cursor: ~/.cursor/skills/softaworks/agent-toolkit/perplexity/SKILL.md
Antigravity: ~/.gemini/antigravity/skills/softaworks/agent-toolkit/perplexity/SKILL.md