Give it tools
A model on its own answers only from what it already knows. Tools let an agent go beyond that — search the live web, fetch a page, run code, or call into your own systems. You enable tools by listing them in the tools array, and the model decides when to call each one based on your prompt. This page covers wiring tools in and reading their output. For the full settings of any single tool, follow the link to its reference page.
Three kinds of tools
Section titled “Three kinds of tools”| Kind | How it works |
|---|---|
| Built-in tools | Perplexity-hosted capabilities: web search, URL fetch, people and finance search, and a code sandbox. Enable each by type, and Perplexity runs it and returns the results inline. |
| MCP servers | Your own remote MCP server. The model discovers and calls the server's tools automatically, like the built-in ones — Perplexity relays each call to your server. |
| Custom tools | Bring your own — functions you control. You declare the schema, and when the model calls one, the run pauses and hands you the arguments to execute, then continues once you return the result. |
Enable built-in tools
Section titled “Enable built-in tools”Add each tool to the tools array by its type. Most built-in tools work with just the type — some accept optional settings (documented on their reference pages).
from perplexity import Perplexity
client = Perplexity()
response = client.responses.create(
model="openai/gpt-5.6-sol",
input="What are the leading approaches to grid-scale energy storage, and how do they compare?",
tools=[
{"type": "web_search"},
{"type": "fetch_url"},
],
max_steps=10,
)
print(response.output_text)import Perplexity from '@perplexity-ai/perplexity_ai';
const client = new Perplexity();
const response = await client.responses.create({
model: 'openai/gpt-5.6-sol',
input: 'What are the leading approaches to grid-scale energy storage, and how do they compare?',
tools: [
{ type: 'web_search' as const },
{ type: 'fetch_url' as const },
],
max_steps: 10,
});
console.log(response.output_text);curl https://api.perplexity.ai/v1/agent \
-H "Authorization: Bearer $PERPLEXITY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "openai/gpt-5.6-sol",
"input": "What are the leading approaches to grid-scale energy storage, and how do they compare?",
"tools": [
{ "type": "web_search" },
{ "type": "fetch_url" }
],
"max_steps": 10
}' | jqThe built-in tools, each with its own reference page for full settings, response shape, and pricing:
| Tool | type |
Use it to |
|---|---|---|
| Sandbox | sandbox |
Run code in an isolated container — see Run code |
| Web Search | web_search |
Search the live web, with domain/date/location filters |
| Fetch URL Content | fetch_url |
Pull and extract content from specific URLs |
| People Search | people_search |
Find professionals and people |
| Finance Search | finance_search |
Retrieve structured financial and market data |
Connect an MCP server
Section titled “Connect an MCP server”Instead of hosting each tool yourself, connect a remote Model Context Protocol (MCP) server with type: mcp. Agent API discovers the server's tools when the request starts, and the model calls them automatically like the built-in ones — you don't handle each call yourself. The example below connects to the public DeepWiki MCP server, which needs no authentication.
from perplexity import Perplexity
client = Perplexity()
response = client.responses.create(
model="openai/gpt-5.6-sol",
input="Use DeepWiki to explain what the perplexityai/perplexity-py repository does.",
tools=[
{
"type": "mcp",
"server_label": "deepwiki",
"server_url": "https://mcp.deepwiki.com/mcp",
}
],
)
print(response.output_text)import Perplexity from '@perplexity-ai/perplexity_ai';
const client = new Perplexity();
const response = await client.responses.create({
model: 'openai/gpt-5.6-sol',
input: 'Use DeepWiki to explain what the perplexityai/perplexity-py repository does.',
tools: [
{
type: 'mcp',
server_label: 'deepwiki',
server_url: 'https://mcp.deepwiki.com/mcp',
},
] as any, // The current SDK types do not yet include MCP tools.
});
console.log(response.output_text);curl https://api.perplexity.ai/v1/agent \
-H "Authorization: Bearer $PERPLEXITY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "openai/gpt-5.6-sol",
"input": "Use DeepWiki to explain what the perplexityai/perplexity-py repository does.",
"tools": [
{
"type": "mcp",
"server_label": "deepwiki",
"server_url": "https://mcp.deepwiki.com/mcp"
}
]
}' | jqFor authentication, response items, and the full tool settings, see the MCP reference.
Add your custom tool
Section titled “Add your custom tool”A custom tool (type: function) lets the agent call code you control — your database or an internal API. You declare it with a name, a description, and a JSON Schema for its parameters. The model fills in the arguments — you run the function. This is how the agent reaches data it can't know on its own — here, an order's current status in your internal system.
from perplexity import Perplexity
client = Perplexity()
tools = [
{
"type": "function",
"name": "get_order_status",
"description": "Look up the current status of an internal order by its order ID.",
"parameters": {
"type": "object",
"properties": {"order_id": {"type": "string"}},
"required": ["order_id"],
},
"strict": True,
}
]
response = client.responses.create(
model="openai/gpt-5.6-sol",
input="What's the status of order ORD-10042?",
tools=tools,
)import Perplexity from '@perplexity-ai/perplexity_ai';
const client = new Perplexity();
const tools = [
{
type: 'function' as const,
name: 'get_order_status',
description: 'Look up the current status of an internal order by its order ID.',
parameters: {
type: 'object',
properties: { order_id: { type: 'string' } },
required: ['order_id'],
},
strict: true,
},
];
const response = await client.responses.create({
model: 'openai/gpt-5.6-sol',
input: "What's the status of order ORD-10042?",
tools,
});curl https://api.perplexity.ai/v1/agent \
-H "Authorization: Bearer $PERPLEXITY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "openai/gpt-5.6-sol",
"input": "What is the status of order ORD-10042?",
"tools": [
{
"type": "function",
"name": "get_order_status",
"description": "Look up the current status of an internal order by its order ID.",
"parameters": {
"type": "object",
"properties": { "order_id": { "type": "string" } },
"required": ["order_id"]
},
"strict": true
}
]
}' | jqThe model never runs your function — the API can't execute your code. Instead, the run pauses and hands the call to you: the response output array contains a function_call item with the name and the arguments the model filled in.
{
"type": "function_call",
"id": "fc_abc123",
"call_id": "call_xyz789",
"name": "get_order_status",
"arguments": "{\"order_id\":\"ORD-10042\"}"
}Pull that item off the response, run the function on your side, then continue the run by sending the result back. The follow-up request replays the conversation so far — the original question, the function_call the model emitted, and a function_call_output carrying your result under the same call_id:
import json
function_call = next(item for item in response.output if item.type == "function_call")
def get_order_status(order_id: str) -> dict:
orders = {"ORD-10042": {"status": "in_transit", "carrier": "DHL", "eta": "2026-06-23"}}
return orders.get(order_id, {"error": "order not found"})
result = get_order_status(**json.loads(function_call.arguments))
followup = client.responses.create(
model="openai/gpt-5.6-sol",
input=[
{"role": "user", "content": "What's the status of order ORD-10042?"},
{
"type": "function_call",
"call_id": function_call.call_id,
"name": function_call.name,
"arguments": function_call.arguments,
},
{
"type": "function_call_output",
"call_id": function_call.call_id,
"output": json.dumps(result),
},
],
tools=tools,
)
print(followup.output_text)const functionCall = response.output.find((item) => item.type === 'function_call');
if (functionCall?.type !== 'function_call') throw new Error('No function call returned.');
function getOrderStatus(orderId: string) {
const orders: Record<string, unknown> = {
'ORD-10042': { status: 'in_transit', carrier: 'DHL', eta: '2026-06-23' },
};
return orders[orderId] ?? { error: 'order not found' };
}
const args = JSON.parse(functionCall.arguments) as { order_id: string };
const result = getOrderStatus(args.order_id);
const followup = await client.responses.create({
model: 'openai/gpt-5.6-sol',
input: [
{ type: 'message', role: 'user', content: "What's the status of order ORD-10042?" },
{
type: 'function_call',
call_id: functionCall.call_id,
name: functionCall.name,
arguments: functionCall.arguments,
},
{
type: 'function_call_output',
call_id: functionCall.call_id,
output: JSON.stringify(result),
},
],
tools,
});
console.log(followup.output_text);curl https://api.perplexity.ai/v1/agent \
-H "Authorization: Bearer $PERPLEXITY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "openai/gpt-5.6-sol",
"input": [
{ "role": "user", "content": "What is the status of order ORD-10042?" },
{
"type": "function_call",
"call_id": "call_xyz789",
"name": "get_order_status",
"arguments": "{\"order_id\":\"ORD-10042\"}"
},
{
"type": "function_call_output",
"call_id": "call_xyz789",
"output": "{\"status\": \"in_transit\", \"carrier\": \"DHL\", \"eta\": \"2026-06-23\"}"
}
]
}' | jqRead tool results
Section titled “Read tool results”Built-in tools attach their output to the response output array next to the message item — for example search_results, finance_results, or sandbox_results items, depending on which tool ran. Iterate the array to surface citations, generated files, or computed values. Each tool's reference page documents its exact result shape — see, for example, Web Search → Response shape.