Designing Tools Agents Love to Use
Naming, descriptions, parameters, and error messages: the craft of designing tools that models call correctly on the first try.
When an agent misuses a tool, it's tempting to blame the model. It passed a name where an ID was expected. It called search five times with nearly identical queries. It deleted the wrong record because two tools sounded alike. Look closely, though, and the tool usually invited the mistake: a vague description, an ambiguous parameter, an error message that said "400 Bad Request" and nothing else.
Tools are an interface, and the agent is a very particular kind of user: smart, literal, unable to ask clarifying questions, and with no knowledge beyond what you wrote. This lesson teaches the craft of designing for that user. You'll learn how to choose the right set of tools, name them, describe them, shape their parameters and outputs, and write error messages that help the model recover, so agents call your tools correctly on the first try.
Tools are a user interface for models
In Tools and Function Calling you learned the mechanics: a tool has a name, a description, and an input schema; the model emits a tool call; your code runs it and returns a result. This lesson is about everything that mechanical view leaves out.
The key insight is that every part of a tool definition is a prompt. The name, the description, each parameter's name and description, and even the text of your results and error messages all land in the model's context and shape its behavior. A good API for human developers isn't automatically a good tool for an agent, because developers can read docs, experiment, and look at source code. The model gets only what you wrote.
A useful test: could a capable new hire use this tool correctly from the definition alone, with no other documentation? If not, the model can't either.