What a tool is
A Finn holds a conversation. A tool is how it does something outside the conversation: book a slot on a calendar, write to a CRM, hand the caller to a person, fetch a value that lives in your system and not in Finn.
Without tools an agent can only talk. It answers from its prompt and its knowledge base, and that is the ceiling. With tools it can change state in other systems and read data that did not exist when the call started.
The three kinds
| Kind | What it does | Where you configure it | Page |
|---|---|---|---|
| Built-in | Ships with the platform. Book Calendar, Send SMS, Update CRM. Depends on a connected integration. | Dashboard, on the Finn | Built-in tools |
| Custom | Calls a URL you own during the call. The response comes back as variables the agent can speak. | Dashboard, on the Finn | Custom tools |
| Transfer | Ends the agent's turn and hands the live call to a human. | Dashboard, on the Finn | Transfer |
All three are configured in the dashboard. There is no API for defining a tool. The API creates and runs Finns, deployments and calls, but the tool definitions themselves live on the agent you edit in the UI.
Free-form and workflow mode
How a tool fires depends on which mode the agent runs in.
In free-form mode the model decides. You describe the tool and when to use it, and the agent calls it when the conversation warrants. This is the right default for most agents.
In workflow mode you place an Action node on the canvas and wire it into the flow. The tool fires when the call reaches that node, and only then. Use this when order matters: check severity before booking, read the disclosure before ending.
The two mix. A workflow can hand off to free-form at an End node, and the free-form portion still has access to the same tools.
Tools return variables
When a tool runs, whatever it returns becomes available for the rest of the call under {{state.*}}.
A Book Calendar action returns the booked time. A custom webhook returns whatever JSON your endpoint sends. You reference it the same way you reference any other collected value:
"Got it, {{contact.name}}. I've booked you for {{state.appointment_time}}."
Contact fields from the audience row use {{contact.*}}. Values collected or returned during the call use {{state.*}}. See Variables.
If a variable name in a Say node does not match the name the tool wrote to, the raw {{state.x}} string appears in the transcript and the caller hears it read aloud. This is the most common tool bug and it is always a typo.
What goes wrong
The tool never fires. In free-form mode the model decided it was not relevant. Your description of when to use the tool is too vague. Be specific about the trigger condition, not just what the tool does.
The integration is not connected. Built-in tools depend on an integration being live in Settings → Integrations. A Book Calendar action with no calendar connected has nothing to book into. Connect it first. See Integrations.
Your endpoint is slow. A custom tool runs inside a live phone call. The caller is sitting in silence while your server thinks. Treat any lookup endpoint as latency-critical and return the smallest payload that answers the question.
Your endpoint returns an error. The agent has no result to speak from. Decide in advance what the agent should say when the lookup fails, and put that in the prompt or on a fallback edge.
Testing tools
Test a tool before it faces a real caller. Two ways, both from the dashboard:
Test on Chat opens a text simulator. Each node shows its inputs and outputs, so you can see exactly what a tool received and what it returned.
Test on Call dials your phone. Use this last, because it is the only test that exposes latency the way a caller experiences it.
Every fired tool is recorded on the call. Check Call logs after a test run to see the arguments and the response, and Troubleshooting when a call did not do what you expected.
Where to go next
- Built-in tools covers each shipped tool and what it needs.
- Custom tools covers endpoint contracts and payload shape.
- Transfer covers handing a call to a person.
- Webhooks covers the other direction: Finn sending you data after a call ends, rather than an agent calling you during one.