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

• Key message first - Is the main point upfront?

• "gt" = Graphite MCP - ANY "gt" mention uses Graphite

• Deep research = /research - NOT perplexity_research tool

• Fallback chain - Search → Ask → WebSearch (last resort)

References

MANDATORY - Self-containment Directive:

This is a self-contained skill. Do NOT load external files or reference directories unless explicitly created during the execution of this workflow.

Query Simplification & Endpoint Timeout Checks

1. Query simplification: Strip conversational filler expressions (such as "please find me the latest information about...") from input query strings to reduce search parsing costs.

2. Endpoint time out: If Perplexity tools fail or time out, fallback to local workspace index checks before running external web queries.