Overview
This guide shows how to expose Perplexity’s Search API to Claude as a tool. The Anthropic Messages API uses a manual tool-use loop: the model emits atool_use block, you execute the tool (in this case, call client.search.create), and you send the result back as a tool_result. The loop continues until the model returns a final answer.
Prerequisites
Tool definition
Claude needs a tool description that tells it when and how to callweb_search. The description below was tuned for Perplexity’s Search API; keep it verbatim — the wording of the description and the parameter guidance is what produces good, short, keyword-style queries.
Tool handler
The handler is a thin wrapper aroundclient.search.create. The Search API natively accepts an array of queries (up to five), so the array Claude emits can be passed straight through.
Tool-use loop
Anthropic’s Messages API hands you astop_reason of "tool_use" and one or more ToolUseBlock items inside response.content. Run each tool call, build a tool_result block per call (paired by tool_use_id), and send all results back in a single user message. Loop until stop_reason is no longer "tool_use".
Streaming
For streaming responses, useclient.messages.stream(...) and accumulate tool_use blocks from the events. The model emits input_json_delta events with partial JSON arguments; the SDK helper accumulates them and exposes the completed tool_use block via stream.get_final_message() (Python) or stream.finalMessage() (TypeScript). The loop structure is otherwise identical to the non-streaming version.
Notes
- Parallel tool calls. Claude can emit multiple
tool_useblocks in a single assistant turn. Every block must have a matchingtool_resultin the same subsequent user message, paired bytool_use_id. To disable, settool_choice={"type": "auto", "disable_parallel_tool_use": True}. - Result formatting. The string returned to
tool_result.contentis what the model reads next. Including the URL alongside the snippet helps the model cite sources when it produces its final answer. - Errors. To signal that a tool call failed, set
"is_error": Trueon thetool_resultblock and put a short error message incontent. The model will see the error and can recover (for example, by reformulating queries). - Domains and dates. Pass
search_domain_filter,country, and other Search API parameters insiderun_web_searchif you want fixed retrieval constraints. See the Search API quickstart for the full parameter list.
Next Steps
Use with OpenAI SDK
Wire Search API into the OpenAI Responses API.
Use with Gemini SDK
Wire Search API into Google’s
google-genai SDK.Search API Quickstart
Full Search API parameter reference.
Search Best Practices
Patterns for production search workloads.