Tools
How the agent does real work on a call, with builtin and webhook tools, prerequisites, and mocks.
A tool lets the agent do something instead of only saying something: look up an order, search your knowledge base, text a link, transfer to a person, hang up.
Caller: "Where's my order? It's 4-8-2-9-1."
Agent: "Let me check that for you."
(the agent runs lookup_order with order_id 48291)
Agent: "That one shipped Tuesday. It's due with you tomorrow."You never tell the agent when to call a tool. On every turn the model reads each tool's description and decides for itself, which makes the description an instruction rather than a label.
Tools open from the Tools row on the agent's Build tab. Click a tool in the list to open its editor, and go back to return to the list. In a wide window the list and the editor sit side by side.
The description is the lever
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. A precise "call this first, before revealing any order details" changes behaviour more reliably than a paragraph in the prompt.
Two kinds of tool
Builtin tools run inside Vertical AI. We write and maintain the handler, so there is nothing to configure. You pick one and tune its description.
Webhook tools call your own HTTPS endpoint. This is how the agent reaches
your CRM, your ordering system, or anything else you run. A plain http:// URL
is refused.
Most agents mix both: the builtin search_knowledge_base and
transfer_to_human next to a webhook lookup_order that hits your own system.
The full catalogue of builtins is on Builtin tools.
Building a webhook tool
A webhook tool describes one HTTP request. Its editor has a card for each part: Identity, Prerequisites, Request, Inputs and Mock & testing.
Identity
A snake_case name the model sees, such as lookup_order, and a description
that tells the model when to call it. Write the description for the model, not
for a human reader.
Request and inputs
The Request card holds the URL, the method, the headers and an optional response template. The Inputs card holds the parameters the model fills in from the conversation. GET and POST are the two methods.
- GET sends parameters as a query string. Use it for lookups.
- POST sends parameters as a JSON body. Use it for anything that changes something.
GET https://api.example.com/orders?order_id=...
POST https://api.example.com/returns (parameters go in the JSON body)Each parameter has a name, a type, a description and an optional required flag. The parameter description matters as much as the tool description, because it tells the model what to put there.
Miss a required parameter and the runtime returns an error naming it rather than sending a broken request. The model supplies it on the next turn.
Headers
Static headers sent with every request, usually authentication. They go in the Request card as JSON.
Variables and secrets
Write {{token}} anywhere in the URL, a header or the body and the runtime
substitutes the value at call time.
URL: {{crm_base_url}}/customers
Header: Authorization: Bearer {{crm_api_key}}Use a plain variable for a base URL or an account ID, and a secret variable for an API key. Secrets are stored encrypted and read only by the runtime, so a key never enters the model's context. See variables and secrets.
Prerequisites
Some tools should only run after another has succeeded. The usual case: do not
reveal order details until the caller has passed verify_order_code.
List the tools that must run first in the later tool's Prerequisites card, under Run these tools first.
lookup_order requires: verify_order_code
get_order_status requires: verify_order_code
start_return requires: verify_order_codeThat is a list of names, not a diagram.
Until its prerequisites have run, a gated tool is usually hidden from the model.
If the model calls it early anyway, it 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 one first.
The gate is success-aware. A prerequisite counts only if it actually succeeded, so a failed verification never unlocks the tools it guards.
Tool errors are instructions
A failing tool does not crash the call and does not invent a result. It returns a short message written for the model, saying what happened and what to do next.
- A timeout tells the model to apologise and offer a transfer or another try.
- Your endpoint's own error body is handed back, so the model can read the real reason.
- A missing input is named, so the model can supply it and call again.
That is why a broken integration usually sounds like a graceful recovery rather than a dead end.
Writing a good description
Four rules that hold up on real calls. The full bar, including what a tool's result should and shouldn't say, is in Writing prompts and tool descriptions.
- Say when to call it, not just what it is. "Search the knowledge base before answering a 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.
- Describe every parameter. Vague parameters produce wrong calls.
Keep your endpoint's responses to facts: what happened, what is confirmed, what is missing. The model treats an instruction inside a tool's result as a possible prompt injection, so what the agent should say belongs in the description.
What the caller hears while a tool runs
The agent speaks no scripted holding line. A quiet typing sound covers the wait instead, so the caller knows something is happening. It is on for new agents, and you control it on the agent's Background sound page.
A read-only lookup with no side effects can be marked background-safe, with the Keep talking while this runs switch in its Prerequisites card. The agent then keeps talking while it runs, and voices a brief "still working on it" if the lookup drags. Anything that changes something, such as a booking, is not background-safe: the agent waits.
Testing with a mock
You do not need a finished endpoint to test an agent.
- Build the tool's identity, request and parameters as if the endpoint existed.
- In the Mock & testing card, turn on Mock this tool and paste a
realistic body. You can reference
{{variables}}in it. Keep it to data, never instructions to the model. - Add a delay if you want to hear how the agent handles a slow lookup.
- Test the agent.
- When your endpoint is ready, turn the mock off. The same tool now calls the real URL.
The model sees a mock exactly as it would see a real result, with no marker saying it is fake. Mocks still enforce required parameters and can reject a non-matching input, so you can test a verification gate honestly rather than only the happy path.
Tool edits are saved explicitly, land in a draft, and reach live callers only when you publish.