Tools

A tool is a capability an assistant can invoke during a conversation to do something beyond talking: transfer the call, look up a customer record, book an appointment, or end the call. You define the tools an assistant is allowed to use, and the model decides when to use them.

Tools are configured in an assistant’s tools array, either in the Dashboard’s Tools section or through the API. A tool created in the Dashboard can be reused across multiple assistants, and tools are versioned, so an assistant can pin a specific version or always track the latest.

How a tool call works

Every tool call follows the same four steps, whatever the tool type:

1. The model decides. Based on the conversation and the tool’s name and description, the model chooses to call a tool and generates the arguments defined by its input schema.
2. Vapi resolves the call. Vapi merges in any static parameters you configured, which the model never sees and cannot override, then checks the rejection plan to confirm the call is allowed.
3. The tool executes. What happens here depends on the type. Vapi may send an HTTP request directly, POST a tool-calls webhook to your server, emit an event to the browser, or perform a built-in action such as transferring the call.
4. The result returns. The assistant receives the result and can speak it to the caller. Tools can also be configured to run asynchronously, so the assistant continues without waiting.

Because the model controls both when a tool runs and the arguments it receives, validate any caller-influenced value at the destination before using it for a sensitive action.

Tool types

If you are deciding between calling an API directly and running your own logic, see When to use API Request or Function tools.

Configuration shared by every tool

Most tool settings are specific to the type, but several apply across all of them:

• Name and description. The model reads both when deciding whether to call the tool, so describe the action, when it applies, and what to do with the result.
• Parameters. The model-facing input schema defines what the model generates. Separately, static parameters inject server-controlled values that the model never sees.
• Messages. Configure what the assistant says at each phase of the call, so a caller is not left in silence while a request is in flight.
• Rejection plan. Block a tool call based on conversation state with a tool rejection plan.
• Argument encryption. Encrypt sensitive fields before they reach your server with argument encryption.

Next steps