Article
Nov 19, 2026
read
Tools the AI calls, with the wording kept in code
Adam Kalsey
EVP, Product
Build it free.
Create a space and ship your first call flow in minutes.
Voice AI
AI Agents
Developer Tutorials
This is part 3 of a series about a jack-o'-lantern I built to talk with trick-or-treaters, and the build starts in part 1. In part 2 the pumpkin got a personality and three modes. In this part it gets tools, which are functions on my server that the model calls in the middle of a conversation. They give the model fresh material for the four-hundredth visitor of the night. They also hold the wording that has to be right, so that wording comes from code rather than from the model's best guess.
Write a tool
A tool is a method on the agent marked with the @AgentBase.tool decorator. The decorator gives it a name, a description, and a JSON schema for its parameters. When the model calls the tool, SignalWire posts the request to my server, our Python SDK runs the method, and the method returns a FunctionResult.
The pumpkin calls consult_memory when someone asks about its past:
The model reads the description to decide when to call the tool, which makes the description prompt text. It says in plain words when to call and sends the nearest wrong case to another tool. The enum limits topic to the topics the server has material for. The result is prompt text as well, since it carries the fragment along with instructions for how to use it.
Draw lines from a pool, without repeats
The pumpkin's backstory is a dictionary of topics, and each topic has a handful of fragments that contradict each other on purpose:
Asked its age twice, the pumpkin gives two different answers, which suits the character, but giving one group the same answer twice wouldn't. So pick_unused keeps a list in global_data of the fragments this visit has used, and it draws from the rest:
Every tool request we send carries the call's global_data, so the handler reads the visit's state from it and returns the update with its result. When the next group arrives, the server resets used_fragments, and the whole pool is available again.
Tell stories one beat at a time
The pumpkin never says "I don't know." When a visitor asks something it can't answer, it tells a story that starts on the question and wanders off. tell_a_story builds each story from three absurd turns drawn at random:
Each call returns only the next beat, and the story's place lives in global_data.story. A visitor who says "and then what?" gets the next turn, and one who changes the subject leaves the story behind.
Once the pumpkin should be sending a group on, the tool refuses, because a story is the surest way to keep them standing there.
Return exact wording for boundaries
Some requests need the same answer every time. A visitor asks to touch the pumpkin, wants a photo, swears, shares their address, or says "you're an AI." decline_to_answer takes the kind of request and returns the guidance for it from a table:
The model recognizes the moment and picks the category, and the response lives in code, where I can review it and test it.
Give each mode its own copy of a tool
Some tools need different wording in gentle mode: a cozy story rather than a grand one, and a warm refusal rather than a cold one. I register a gentle copy of each of those tools and list only the copies in gentle mode's step.
Each copy reuses the original's description, parameters, and settings, with a handler fixed to the gentle wording:
Gentle mode's step doesn't list the originals, so the model in gentle mode has no way to reach the act's wording.
Test a tool without a call
swaig-test runs a tool the way SignalWire would, with the arguments you give it and any global_data you want the request to carry:
The second command never returns the Tuesday fragment, however many times you run it. --list-tools shows every registered tool, and the gentle copies are in that list.
Traps to avoid
Don't have one tool read a mode flag to choose its wording. A flag in global_data can drift from the mode the agent is really in, and a tool request doesn't say which context it came from. Register a separate copy for each mode and list it only in that mode's steps, so the context decides.
Don't hand the model a multi-step plan to pace itself. Given all three turns of a story at once, a model tends to tell them in one breath or lose its place. Return one step per call and keep the place on the server.
Next
The pumpkin can talk and has plenty to say, but it can't see who it's talking to. In part 4 it gets eyes, and checks the camera before any decision that matters.
The series
- The system and the call.
The system and the call.
- The agent: a personality and three modes, as contexts and steps.
The agent: a personality and three modes, as contexts and steps.
- Tools: what the AI calls on my server, and why its material lives in code (this post).
Tools: what the AI calls on my server, and why its material lives in code (this post).
- Vision: letting the agent see, and checking the camera before any decision that matters.
Vision: letting the agent see, and checking the camera before any decision that matters.
- The stage: detecting who is standing in front of the pumpkin, in the browser.
The stage: detecting who is standing in front of the pumpkin, in the browser.
- The voice: audio effects in the browser.
The voice: audio effects in the browser.
- Pacing and state: the server keeps score.
Pacing and state: the server keeps score.
- The operator: a person with a phone who can overrule the agent.
The operator: a person with a phone who can overrule the agent.
- Testing it, and running it for a whole night.
Testing it, and running it for a whole night.












