Tools let your Phonic Agent take actions beyond conversation — retrieving information, calling your own functions, injecting extra context, transferring calls, or using Model Context Protocol (MCP) servers. You can create tools two ways, and they behave identically at runtime:

In the dashboard — on the Tools page, click Create tool and pick a type.
Through the API/SDK — call tools.create (and tools.update, tools.list, tools.delete).

Every field described in these guides maps 1:1 between the dashboard form and the API. The dashboard label is shown alongside the API field name (e.g. Execution mode → execution_mode) so you can move between the two freely.

Tool Definition

Every custom tool shares the same core definition:

Name (name) — a unique, snake_case identifier (lowercase letters, numbers, and underscores).
Description (description) — tells the agent what the tool does and when to call it. Max 2000 characters.
Parameters (parameters) — the arguments the agent supplies when calling the tool. Each parameter has a name, description, is_required flag, and a type of string, integer, number, boolean, or array (arrays also take an item_type).
Timeout — how long the agent waits for a response before treating the call as failed. The exact field depends on the tool type (see each type’s guide).

The name, description, and parameters make up the tool schema the language model sees. How the tool is executed depends on its type.

Some parameter names are reserved and cannot be used: call_info, conversation_id, from_phone_number, to_phone_number, and twilio_call_sid. These are supplied automatically for phone calls (see Webhook Tools → Call Context Information).

Tool Types

Phonic supports the following tool types. In the dashboard, the Create tool menu exposes the first five; MCP tools and other built-ins are configured elsewhere. Each type has its own guide with fields and SDK examples.

Dashboard name	API `type`	What happens when it’s called	Guide
Webhook	`custom_webhook`	Phonic makes an HTTP request to your endpoint.	Webhook Tools
WebSocket	`custom_websocket`	Phonic sends a `tool_call` message over your WebSocket connection.	WebSocket Tools
Context	`custom_context`	Phonic injects additional context into the conversation.	Context Tools
Transfer to phone number	`built_in_transfer_to_phone_number`	Phonic transfers the call to a phone number.	Transfer Tools
Transfer to agent	`built_in_transfer_to_agent`	Phonic transfers the conversation to another agent.	Transfer Tools
—	`mcp`	Phonic calls a tool exposed by a connected MCP server.	MCP Tools
—	(built-in)	Phonic runs a built-in capability (keypad, hang up, stay silent).	Built-in Tools

The sections below (sync vs async, behavior configuration, attaching tools to agents) apply across all tool types.

Sync vs Async Tools

The execution mode (execution_mode) controls whether the agent waits for the tool before continuing:

Sync — the agent waits for the tool to complete before continuing. Once the output is received, the agent uses it to generate a response. If the user speaks while the tool is executing, the tool call is interrupted. Good for tools that return information the agent needs right away.
- Webhook: the conversation waits for your endpoint’s response.
- WebSocket: the conversation waits for the tool_call_output message.
Async — the agent continues the conversation without waiting. Async tools are not interrupted by user speech. When the result arrives it’s added to the agent’s context, but doesn’t immediately trigger a response. Good for background work (e.g. writing to a database) or fetching data that may be useful later.

Only custom_webhook and custom_websocket tools support choosing an execution mode. Context tools, transfer tools, and built-in tools always run in sync mode.

Tool Behavior Configuration

Beyond the schema and execution mode, tools expose switches that shape when and how the agent uses them. Each maps directly to a dashboard toggle and an API field. All default to the values below.

Dashboard toggle	API field	Default	Applies to	What it does
Require speech before tool call	`require_speech_before_tool_call`	off	all custom tools, transfers, MCP	Forces the agent to speak before executing the tool.
Wait for speech before tool call	`wait_for_speech_before_tool_call`	off	webhook, websocket	Makes the agent finish speaking before executing. Phonic normally executes tools as soon as possible to cut latency.
Forbid speech after tool call	`forbid_speech_after_tool_call`	off	webhook, websocket, context, MCP	Forces the agent to not speak after executing the tool.
Allow tool chaining	`allow_tool_chaining`	on	webhook, websocket, context, MCP	Allows the agent to execute more tools after this one.
Wait for response	`wait_for_response`	off	websocket (async only)	Makes an async WebSocket tool wait for its response, hold off other tools, and inform the user of the result.

These fields are stored per tool. When the same pre-defined tool is attached to an agent, the agent’s configuration can override some of them (a per-agent tool config), so you can reuse one tool with different behavior across agents.

Using Tools with Your Agents

Once you’ve created tools, attach them to an agent by including their names in the tools array (and MCP servers in mcp_servers):

1 await client.agents.create({
2   name: "support-agent",
3   tools: [
4     "keypad_input",
5     "natural_conversation_ending",
6     "transfer_to_support",
7     "book_appointment",
8   ],
9   mcp_servers: ["my-mcp-server"],
10   // ... other agent configuration
11 });

If you’ve included WebSocket tools in your agent, see the WebSocket Tools guide to learn how to handle those tool calls.