What a tool is
A tool lets a Finn do something during a call besides talk: check open slots on a calendar, book one, hand the caller to a person, or call an API you own.
Tools are configured in the dashboard, on a step of the Finn's call flow canvas. There is no API for defining tools. The Finns API doesn't read or write them.
Tools need a call flow canvas
Tools only run on a Finn that has a call flow canvas. Without one, the Finn gets no tools: it can't transfer, check a calendar, or call your API, even if its prompt tells it to.
To build a canvas, open the Finn, click Edit, go to the Call flow tab and click Convert to conversational flow. See workflow editor.
Where tools attach
A tool is not a step of its own. You attach it to a Conversation step: select the step, then use Add a tool in the step's Tools section. The Finn calls it during that step and then keeps talking.
A tool can only be called on the step it's attached to. If two steps both need a lookup, attach it to both.
The tools
| Tool | What it does | Page |
|---|---|---|
| Check Calendar | Reads open slots from a Cal.com event type | Built-in tools |
| Book Calendar | Books a slot on a Cal.com event type | Built-in tools |
| Call Transfer | Hands the live call to a phone number. Ends the Finn's part of the call. | Transfer |
| API request | Calls your endpoint, waits, and uses the response in its next reply | Custom tools |
| Webhook | Calls your endpoint and carries on without waiting. The response is ignored. | Custom tools |
| Custom function | Same form as API request (URL, method, headers, parameters) and behaves the same way: the Finn waits for the response | Custom tools |
Ending the call is not a tool you attach. It's the End Call step, which you connect a Conversation step to. See workflow nodes.
There are no built-in tools for sending SMS or writing to a CRM.
How the Finn decides to call a tool
The AI decides when to call a tool, based on:
- The step's Instruction prompt. Say plainly when to use the tool, for example "Once the caller gives a preferred date, check the calendar."
- The tool's description. For API request, Webhook and Custom function, that's the What does this do? field. Built-in tools come with their own description.
For tools that send data to your API, you declare Parameters, and the AI fills them from the conversation. See custom tools.
What the caller hears
| Situation | What happens |
|---|---|
| A tool that waits for a result (Check Calendar, Book Calendar, API request, Custom function) | The Finn says the Filler line, waits for the result, then answers using it. The caller can't interrupt during the wait. Anything they say is kept and answered once the result is in. |
| Webhook | The Finn says the filler if one is set, fires the request in the background, and the conversation carries on. |
| Call Transfer | The Finn says the Message before transfer and connects the caller. |
| The tool doesn't answer within Timeout (ms) | The Finn is told the service didn't respond in time and apologizes instead of inventing an answer. |
| The request fails | The Finn is told the tool couldn't be reached and carries on with the conversation. |
Results are not variables
A tool's result goes to the AI for its next reply. It isn't stored as a variable you can reference in later steps. If a later step needs a value from an earlier lookup, the Finn has to carry it in the conversation. There is no {{state.*}} syntax. For the variables that do exist, see workflow variables.
What goes wrong
The tool never fires. It's attached to a different step than the one the conversation is on, or the step's prompt never tells the Finn when to use it. Check the step first, then the wording.
The tool fires at the wrong time. The description is vague. Describe what the tool does and when it applies, not what the Finn says while it runs.
Your endpoint is slow. The caller hears the filler and then silence until your response comes back. Keep lookups fast and set a timeout.
The Finn sends bad parameter values. It fills parameters from what it heard. Write a description for every parameter that says what goes in it and in what format.
Testing tools
Use Test → Phone call on the Finn's page. It runs the saved canvas, tools included.
Simulation chat doesn't run tools. The canvas Test run doesn't either: it only traces a path through your steps. See testing a workflow.
Related
- Built-in tools: Check Calendar, Book Calendar, Call Transfer
- Custom tools: API request and Webhook
- Transfer: handing the call to a person
- Workflow editor: building the canvas
- Webhooks: Finn sending you data after a call, rather than during one