Perplexity Expert

Integration guide for using Perplexity AI as a real-time web search and research tool within Claude Code workflows, with proper tool selection routing.

When to Use

Use Perplexity Search when:

• You need current web search results with URLs
• Finding recent best practices, tutorials, or blog posts
• User says "search for...", "find...", "look up..."
• Need information beyond your training data

Use Perplexity Ask when:

• Need a conversational explanation synthesized from web sources
• Want concepts explained with current context
• Don't need individual URLs, just the answer

Don't use Perplexity when:

• Looking up library/framework documentation → use Context7 MCP
• Querying workspace structure → use Nx MCP or local tools
• Need deep multi-source research → use a dedicated researcher agent
• Fetching a specific URL → use URL Crawler or WebFetch

Quick Start

Perplexity Search

Copy
// Search with controlled output (avoid context bloat)
mcp__perplexity__perplexity_search({
  query: "React Server Components best practices 2025",
  max_results: 3,
  max_tokens_per_page: 512
})

Perplexity Ask

Copy
// Conversational answer synthesized from web
mcp__perplexity__perplexity_ask({
  messages: [
    {
      role: "user",
      content: "Explain how postgres advisory locks work and when to use them"
    }
  ]
})

Core Concepts

Tool Selection Priority

When a user asks for information, follow this priority chain:

Priority	Tool	Use When
1	Context7 MCP	Library/framework documentation
2	Graphite MCP	gt CLI commands
3	Nx MCP	This workspace's structure
4	Perplexity Search	Generic web searches
5	Perplexity Ask	Conversational web answers
6	Researcher agent	Deep multi-source research
7	WebSearch	Last resort fallback

Search vs Ask

Search returns structured results with URLs — use when you need sources or specific resources:

"Find postgres migration best practices" → Perplexity Search
"Search for React testing tutorials" → Perplexity Search

Ask returns a synthesized answer — use when you need understanding:

"Explain how postgres advisory locks work" → Perplexity Ask
"What are the trade-offs of microservices?" → Perplexity Ask

Parameter Optimization

Default to conservative limits to avoid context bloat:

Parameter	Default	When to Increase
max_results	3	Complex topics needing multiple sources
max_tokens_per_page	512	Results too truncated to be useful

Copy
// Conservative (default)
{ max_results: 3, max_tokens_per_page: 512 }

// Expanded (complex topics only)
{ max_results: 5, max_tokens_per_page: 1024 }

Configuration

Parameter	Type	Description
query	string	Search query text
max_results	number	Maximum search results (default: 10, recommended: 3)
max_tokens_per_page	number	Content limit per result (recommended: 512)
messages	array	Chat messages for Ask mode

Best Practices

1. Default to limited results (max_results=3) to avoid flooding the context window
2. Route to Context7 first for any library or framework documentation queries
3. Use Search for sources, Ask for understanding — pick the right mode
4. Never use perplexity_research directly — use a researcher agent instead for deep research
5. Include the year in queries for time-sensitive topics ("React best practices 2025")
6. Combine with local tools — search for the approach, then use Grep/Read to find relevant code

Common Issues

Context window bloat from search results: Reduce max_results to 3 and max_tokens_per_page to 512. Only increase if initial results are insufficient.

Wrong tool selected: Follow the priority chain. Library docs should go through Context7 MCP, not Perplexity. Workspace queries should use local tools.

Stale or irrelevant results: Add the current year to your query. Be specific about the technology version you're targeting.