Skip to main content
Without tools an agent can only say what is already in its prompt. With them it can look up a real order, book a real slot, control the call, and drive your UI. A tool is a function the agent may call mid-conversation. You describe what it does; the model decides when to reach for it.

​
The three kinds

HTTP

Runs on your server. Works on every call type. The workhorse.

Client

Runs in your app over WebSocket. Browser and WebSocket calls only.

Built-in

Platform call control — hang up, send touch tones.

​
The description is the trigger

The description is the only thing the model uses to decide whether to call your tool. It is not documentation — it is the trigger condition. Name the phrasings callers actually use. Most “my tool never fires” problems are description problems, not wiring problems.
Fires too eagerly? Add a precondition — “Only call this once the caller has given an order number.” Never fires? Name more trigger phrasings.

​
Lifecycle

Tools belong to the workspace, and agents borrow them. One tool can serve every agent you have — fix a bug once and they all get it.
The attach body is toolIds, an array with at least one entry — not a single toolId. Attaching an already-attached tool is a no-op, so the call is safe to repeat.
There is also a legacy /tools surface on an older auth model that does not support encrypted credentials. Use /agent-tools for anything new.

​
Naming rules

modelToolName is the function name the model sees. It must match ^[a-zA-Z][a-zA-Z0-9_]*$ — start with a letter, then letters, numbers, and underscores only.

​
Where to go next

Parameters

The three maps, and which one to use.

Authentication

Credentials, safely.

Agent responses

What the agent does when a tool returns.

Long-running tools

Work that cannot finish in 40 seconds.