Tool design and registration

Two builders configure the same image generation tool on the same platform.

Builder A toggles it on, writes nothing else, and spends a week wondering why the agent never draws anything. Builder B toggles it on and adds three lines to the prompt (when to use it, what the images should contain, how often) and the agent illustrates every scenario beautifully.

Identical tool. Identical platform. The difference was never the tool. This chapter is about the part of tool design that the toggle doesn’t cover.

The three parts of every tool

Every tool in every agent system has exactly three parts, and all three must exist for the tool to work:

1. Implementation: the code that executes. When the agent asks for an image, something actually calls an image model and returns a URL. When it asks to book a meeting, something hits a calendar API. On platforms, the built-ins (image generation, MCQ, slides, whiteboard) are already implemented. For your custom calendar booking, you implement the endpoint.

2. Registration: the schema in the model’s context: the tool’s name, description, and parameters. This is how the model knows the tool exists at all. Platforms handle registration when you toggle a tool on; on DIY stacks you pass the schemas yourself.

3. Prompt instructions: where you tell the agent when, why, and how often to use the tool. Platforms may auto-add boilerplate instructions when you enable a tool; good agents override the boilerplate with specifics.

The diagnostic rule: whatever the platform covers, all three parts must exist somewhere. Find the gaps you own. On a good platform, parts one and two arrive with the toggle, which means the gap you own is almost always part three. That is Builder A’s missing week.

Writing tool instructions

Good tool instructions answer three questions. Write all three for every tool you enable.

When to use it. Trigger conditions, anchored in the session flow:

## TOOL: image
- Use when presenting any new scenario: paint the scene before asking for a response
- Use when the user seems confused by a verbal description

How to interpret the result. What to do after the call returns:

- After showing an MCQ, do not reveal the answer. Ask the user to justify their choice first.
- After memory_search returns, weave the facts in naturally; never recite them.

How often. Frequency calibration, the most forgotten line in agent building:

- Use image and MCQ tools frequently: at least once per scenario each
- Use end_session exactly once, only after the wrap-up summary

Without frequency guidance, agents drift to one of two extremes: they ignore the tool entirely (Builder A), or they call it on every turn until the session feels like a slideshow. A tool the prompt never mentions is a tool the agent rarely uses; a tool the prompt mentions without a frequency is a coin flip.

The built-in toolbox

The standard experience-platform toolbox, and when each tool shines:

• Image generation: scene-setting. Chapter 1’s rule made executable: more than two sentences of description, show it instead.
• MCQ and cards: checks for understanding. Options stay on screen while the user thinks, bypassing voice’s working-memory ceiling.
• Slides: structured teaching along an existing deck; the agent navigates and discusses per slide.
• Memory search: recall from past sessions, on demand (Part 3).
• End session: the deliberate close (Chapter 20), invoked exactly once.

On Tough Tongue: the toolbox is larger than the core five: the tool reference lists cards, MCQ, slide generation, Google Slides navigation, memory search, knowledge base search, image generation, Mermaid diagrams, whiteboard, a cloud browser, timers, notepads, and more. Each is enabled per scenario via tools_config, with should_register handling registration and add_to_system_prompt injecting starter instructions you can then tailor. That is the three-part model, mapped to configuration.

Chapter 22 returns to this toolbox with a harder question (which tools actually change user behavior), but you need the mechanics first.

Custom tools

Sooner or later your agent must touch your systems: check a real calendar, create a CRM lead, fetch an order status. That is a custom tool, and the same three-part discipline applies: you just own more of the parts.

The implementation is your HTTP endpoint. The registration is the schema you provide the platform: name, description, method, URL, and a JSON Schema for the parameters, the same pattern as OpenAI function calling. The instructions are the same three questions as always: when, interpret, how often.

Design guidance earned from watching these fail:

• Return small, structured results. The tool result enters the model’s context and is attended to like everything else: a 10,000-character JSON dump is context pollution the agent must wade through mid-sentence.
• Make tools idempotent where possible. Agents occasionally double-call; a booking endpoint that creates two meetings on a retry is a bug you built.
• Include a speakable error shape. The agent should be able to say “I couldn’t reach the calendar. Tell me your preferred time and I’ll note it down,” which means the error response has to tell it that much.

On Tough Tongue: custom tools are registered through the custom_function tool: you define the name, description, HTTP method, URL, headers, and parameter schema; the platform calls your endpoint with AI-generated arguments mid-conversation and speaks the result. The custom tools guide walks through the full setup, including response limits and testing.

One more term to file: MCP (Model Context Protocol), an emerging standard for third-party tool servers the agent connects to, rather than tools you wire one by one. Same mental model as everything above; the tools just live on someone else’s server. When your custom-tool list starts looking like a subscription list, MCP is the scaling path.

Tools let the agent act. The next surface lets it know things, without stuffing a single manual into the prompt.