perplexity_search

This page is the full reference for the perplexity_search MCP tool: its purpose, input parameters, internal implementation, output format, error handling, and guidance on when to prefer it over other tools. For an overview of all four tools and a comparison table, see Tools Reference. For response processing details shared across tools (citation appending, <think> stripping), see Response Processing and Citations.

---

Purpose

perplexity_search performs a direct web search via the Perplexity /search API endpoint and returns a ranked list of raw result records—title, URL, snippet, and date—with no AI synthesis applied. It is the only tool in the server that calls the /search endpoint; all other tools call /chat/completions.

---

How It Fits Into the Server

Diagram: perplexity_search call flow

Sources: src/server.ts271-296 src/server.ts495-529 src/server.ts63-116

---

Input Parameters

The tool input schema is defined in createPerplexityServer() as searchInputSchema:

src/server.ts481-489

Parameter	Type	Required	Default	Constraints	Description
query	string	Yes	—	—	The search query string
max_results	number	No	10	min: 1, max: 20	Maximum number of result records to return
max_tokens_per_page	number	No	1024	min: 256, max: 2048	Token budget per webpage for snippet extraction
country	string	No	undefined	ISO 3166-1 alpha-2	Country code for regional result ranking (e.g., "US", "GB")

The handler extracts these values with safe defaults:

const maxResults = typeof max_results === "number" ? max_results : 10;
const maxTokensPerPage = typeof max_tokens_per_page === "number" ? max_tokens_per_page : 1024;
const countryCode = typeof country === "string" ? country : undefined;

src/server.ts519-521

The country field is only included in the API request body when it is explicitly provided; undefined values are omitted by the spread operator in performSearch.

src/server.ts278-284

---

API Endpoint

perplexity_search is the only tool that uses the /search endpoint. The request is assembled and dispatched by makeApiRequest("search", body, serviceOrigin).

Diagram: Request body construction

Sources: src/server.ts271-295 src/server.ts63-116

The request shares the same infrastructure (makeApiRequest, proxyAwareFetch, AbortController timeout) used by all other tools. The timeout is read from PERPLEXITY_TIMEOUT_MS at call time (default: 300,000 ms). See Environment Variables Reference and API Client and Network Layer for details.

---

Response Parsing and Validation

The raw JSON response is validated by SearchResponseSchema from src/validation.ts:

src/server.ts287-293

If parsing fails (malformed JSON or schema mismatch), an error is thrown:

Failed to parse JSON response from Perplexity Search API: <error>

The validated SearchResponse object is then passed to formatSearchResults().

---

Output Format

formatSearchResults() converts a SearchResponse into a plain-text string:

src/server.ts249-269

Structure of the formatted output:

Found N search results:

1. **<title>**
 URL: <url>
 <snippet>
 Date: <date>

2. **<title>**
 URL: <url>
 <snippet>

...

• snippet is included only when present on the result object.
• date is included only when present on the result object.
• If the results array is absent or not an array, the function returns "No search results found.".

Diagram: formatSearchResults() field mapping

Sources: src/server.ts249-269

The formatted string is returned to the MCP client in two places:

src/server.ts524-527

The structuredContent.results field matches the searchOutputSchema:

src/server.ts491-493

---

Tool Registration Metadata

The tool is registered in createPerplexityServer() with the following MCP annotations:

src/server.ts495-511

Annotation	Value	Meaning
readOnlyHint	true	Does not modify any state
openWorldHint	true	Accesses live external data
idempotentHint	false	Results may differ between calls
destructiveHint	false	No destructive side effects

Title displayed to clients: "Search the Web"

---

Error Handling

Errors follow the same classification used by all tools:

Condition	Error message
No PERPLEXITY_API_KEY set	"PERPLEXITY_API_KEY environment variable is required"
AbortSignal fires (timeout)	"Request timeout: Perplexity API did not respond within Nms..."
Network-level failure	"Network error while calling Perplexity API: ..."
HTTP status not OK	"Perplexity API error: <status> <statusText>\n<body>"
JSON / schema parse failure	"Failed to parse JSON response from Perplexity Search API: ..."

Sources: src/server.ts63-116 src/server.ts287-293

---

When to Use perplexity_search

perplexity_search returns raw search result records, not an AI-generated answer. Choose based on what the downstream task needs:

Need	Tool
Specific URLs, source discovery, news headlines	perplexity_search
An AI-synthesized answer with citations	perplexity_ask (see perplexity_ask)
Step-by-step reasoning over web content	perplexity_reason (see perplexity_reason)
Comprehensive multi-source deep research	perplexity_research (see perplexity_research)

Key distinguishing properties of perplexity_search:

• No AI synthesis — the model is not invoked; results are direct index records.
• Structured metadata — each result carries a title, URL, optional snippet, and optional date, making it machine-parseable.
• Regional control — the country parameter lets you bias results toward a specific locale, which the chat-completion tools do not expose.
• Token-budget control — max_tokens_per_page controls how much text is extracted per page, useful for keeping responses compact.
• Fast and deterministic — no language model inference path, so latency is lower and results are closer to the raw search index.

The server instructions registered with McpServer explicitly guide clients: "Use perplexity_search for finding URLs, facts, and recent news."

src/server.ts305-312