name: perplexity
description: Web search and research using Perplexity AI. Use when user says "search", "find", "look up", "ask", "research", or "what's the latest" for generic queries. NOT for library/framework docs (use Context7) or workspace questions.

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)