Tools

How the agent does real work on a call, with builtin and webhook tools, prerequisites, mocks, and fillers.

Tools are how the agent does real work during a call instead of only talking. A tool can look up an order, search your knowledge base, text the caller a link, transfer to a person, or hang up. Without tools the agent can only say what is in its prompt and knowledge base. With them it can act.

The agent is one language model reading a flat list of tools. There is no diagram and no visual builder. On every turn the model reads each tool's description and decides, in the moment, whether to call one. So a description is not a label, it is the instruction the model follows. Most of your work on tools is writing those descriptions well.

You manage tools on the Tools page of the agent editor. The left side lists the agent's tools; clicking one opens its editor on the right. On a phone you drill into a tool and back out again.

The two kinds of tool

Every tool is one of two kinds.

Builtin tools run inside Vertical AI. They have a fixed handler written and maintained by us, so you do not configure a URL, headers, or parameters. You pick one from a fixed set, then tune its description. Transferring a call, ending a call, searching the knowledge base, and texting the caller are all builtins.
Webhook tools call your own HTTPS endpoint. You give the agent a URL, a method, headers, and the parameters the model should fill in. When the model calls the tool, the runtime sends the request to your system and hands the response back to the model. This is how the agent reaches your CRM, your ordering system, or any API you run.

You can mix both on the same agent. A support agent might use the builtin search_knowledge_base and transfer_to_human alongside a webhook lookup_order that hits your order system.

The description is the lever

The model decides when to call a tool by reading its description, nothing else. If the agent calls a tool at the wrong moment, or never calls one it should, fix the tool's description before you touch the system prompt. Tool descriptions are the highest-leverage text in the whole agent. A precise description ("call this first, before revealing any order details") shapes behaviour more reliably than a paragraph buried in the prompt.

Builtin tools

You add a builtin from a fixed set. Each one ships with a default description already written to the quality bar, which you can keep or sharpen for your business. Here is the set and when the agent uses each one.

Tool	What it does	When the agent uses it
`transfer_to_human`	Hands the call off to a person. On a live phone call with a transfer destination configured, it dials the destination, either a straight hand-off or a screened warm transfer that announces the caller first.	The caller asks for a person, policy requires escalation, or nothing else can resolve the request. With no destination configured the agent honestly says it cannot connect them and keeps helping. See phone numbers.
`book_meeting`	Captures a name, email, and preferred time to book a meeting (Cal.com).	The caller wants to schedule something. The agent gathers the details first, then calls the tool.
`take_a_message`	Takes a message when the person or team the caller needs is not available: it gathers the caller's name, a callback number, and a short summary, then emails it to the inbox the operator configured.	The caller wants a callback, leaves an enquiry, or asks for someone who cannot take the call. The agent confirms the message has been passed on.
`end_call`	Ends the call after a warm closing line.	The caller has clearly signed off and there is nothing left to handle. The runtime refuses to hang up mid-task or on an ambiguous "that's okay", so the agent does not cut a caller off early.
`search_knowledge_base`	Runs a search over the agent's knowledge base and returns the matching passages.	The caller asks a factual question about the business: pricing, hours, policies, products. The agent searches first, answers from what it found, and cites the source by name.
`get_current_time`	Returns the current date and time in the agent's timezone, and the caller's when known.	To ground the greeting in the time of day and to resolve relative times like "tomorrow" or "next Tuesday" before booking. A model cannot read a clock, so this gives it a real one.
`escalate_emergency`	Speaks one fixed "hang up and call triple zero" line and routes to a person. It never triages or advises.	The caller indicates a genuine emergency: injury, medical crisis, fire, a safety threat. The guidance biases hard toward escalating, because failing to escalate a real emergency is the worst outcome.
`send_text_message`	Texts the caller, on the number they are calling from, a link or a short piece of info.	The caller asks for a link, or reading a long URL aloud would be awkward. If texting is unavailable the tool tells the agent to read the link aloud instead.
`send_order_verification_code`	Texts the caller a one-time six-digit code to prove they own an order.	First, before revealing any order details. The agent then asks the caller to read the code back.
`verify_order_code`	Checks the code the caller reads back.	Right after the caller reads the code. A match unlocks the order tools for the rest of the call; a wrong, expired, or missing code keeps them locked and tells the agent what to do next.

send_order_verification_code and verify_order_code work as a pair: the first sends, the second checks, and only a correct read-back opens the order tools. See prerequisites below for how that gate is wired.

Webhook tools

A webhook tool is a description of one HTTP request the agent can make. You build it from a small set of cards in the tool editor.

Identity

The tool's name and description. The name is a snake_case identifier the model sees, like lookup_order. The description is the instruction that tells the model when to call the tool and what it does. Write it for the model, not for a human reader.

Request

The URL, the method, and the parameters.

GET sends the model's parameters as query-string values on the URL. Use it for lookups that read data.
POST sends the model's parameters as a JSON body. Use it for actions that change something.

Each parameter you declare has a name, a type, and a description, and can be marked required. The model fills these in from the conversation. The parameter description matters as much as the tool description: it tells the model exactly what to put there. If the model omits a required parameter, the runtime returns an error naming the missing input instead of sending a broken request, and the model supplies it on the next turn.

GET   https://api.example.com/orders?order_id=...
POST  https://api.example.com/returns      (parameters go in the JSON body)

Headers

Static headers sent with every request, most often authentication. You typically put a credential here as a variable, for example an Authorization header set to Bearer {{api_key}}.

Variables and secrets

Anywhere in the URL, a header, or the body you can write a {{token}} and the runtime substitutes the variable's value at call time. Use a plain variable for a base URL or an account ID, and a secret variable for an API key. Secret values are stored encrypted and only the runtime ever reads them, so a key never appears in the model's context. Define a token once and reuse it across tools. See variables and secrets.

URL:    {{crm_base_url}}/customers
Header: Authorization: Bearer {{crm_api_key}}

Mock response

Before your real endpoint is built or wired up, turn on a mock response and the tool returns a canned body instead of making a real request. The model sees the mock exactly as it would see a real result, with no "this is fake" marker, so you can test the agent's behaviour end to end before the API exists. A mock can add a delay so the agent's filler and waiting behaviour matches a real call, and it still enforces required parameters, so a verification tool you mock still rejects a missing input. See testing a tool with a mock.

Prerequisites

Some tools should only run after another tool has run. The classic case: do not reveal order details until the caller has passed verify_order_code. You express this with a tool's prerequisites, a flat list of the tool names that must run first.

This is a list, not a diagram and not a sequence the agent steps through. There is no graph, no branching, no visual builder. You name the prerequisite tools and the runtime enforces them.

If the model calls a tool before its prerequisites have run, the tool does not fire. The runtime returns a short precondition_unmet message naming the tools that still need to run, and the model self-corrects on its next turn, usually by calling the missing tool first. The gate is success-aware: a prerequisite counts as met only if it actually succeeded, so a failed verification does not unlock the tools it guards.

lookup_order        requires: verify_order_code
get_order_status    requires: verify_order_code
start_return        requires: verify_order_code

Tool errors are instructions

When a tool cannot do its job, it does not crash the call and it does not invent a result. It returns a short message written for the model, telling it what happened and what to do next. A timeout tells the model to apologise and offer to transfer or try again. An endpoint's own error body is handed back so the model can read the real reason and recover in the conversation. A missing required input names the input so the model can supply it and call the tool again.

This is deliberate. Every error is phrased as an instruction the model can act on, which is why a webhook tool that fails usually leads to a graceful recovery rather than a dead end.

Writing great tool descriptions

The description is the single most important thing you write for a tool. A few rules that hold up on real calls:

Say when to call it, not just what it is. "Search the knowledge base before answering a factual question about pricing, hours, or policies" beats "searches the knowledge base".
State the order when order matters. "Call this first, before revealing any order details" is what makes a verification tool actually run first.
Name the recovery. If the tool can fail or return nothing, say what the agent should do then, for example offer to take a message or transfer.
Describe every parameter. The parameter descriptions tell the model what to put in each field. Vague parameters produce wrong calls.
Fix the description before the prompt. If the agent calls a tool at the wrong time, the lever is the description, not the system prompt.

Per-tool fillers

A filler is a short natural line the agent speaks while a tool runs, so the caller does not sit in silence during a lookup. You can set fillers per tool, so the line matches what the tool is doing ("let me pull that up" before an order lookup). If a tool returns instantly, no filler is needed; on a slow lookup the right filler is the difference between a call that feels responsive and one that feels broken.

A tool can also be marked background-safe when it is a read-only lookup with no side effects. A background-safe tool lets the agent keep the conversation moving while the lookup runs, and on a genuinely slow lookup the agent voices a brief, natural "still working on it" line so the call never goes quiet. Tools that change something, like a booking or a return, are not background-safe: the agent waits for them to finish before moving on.

Testing a tool with a mock

You do not need a finished endpoint to test an agent. The workflow:

Build the tool's identity, request, and parameters as if the endpoint existed.
Turn on the mock response and paste a realistic body the endpoint would return. You can reference {{variables}} in it the same way you would in a real request.
Add a delay if you want to feel the agent's filler and waiting behaviour on a slow call.
Test the agent. The model treats the mock as a real result, so you can confirm the agent calls the tool at the right moment, handles the response, and recovers when a required input is missing, all before any real request is ever sent.
When your endpoint is ready, turn the mock off and the same tool now calls the real URL.

Because a mock still enforces required parameters and can reject a non-matching input, you can test identity checks and verification gates honestly, not just the happy path.

Tool edits are saved explicitly: make your changes and save the tool. Like every other change, they land in a draft and reach live callers only when you publish.

On this page