What is tool design?
A model never sees the code behind a tool. It sees a name, a description, a list of inputs and, after using it, a result. Every decision it makes about the tool is made from those four things, so they deserve the care usually given to a prompt.
Good names say what the tool does. Good descriptions say when to use it, when not to, and what each input must look like. Inputs are made hard to get wrong: a fixed list of choices beats free text. Results are short, use names a person would recognise, and say when there is more to fetch.
Fewer tools work better than many. Two tools that overlap make the model guess, and forty tools crowd the prompt. A tool built around a whole task usually beats three that mirror the tables of a database.
Tools are tested like any other part: a set of questions, and a count of how often the right tool was chosen with the right inputs.
Why does tool design matter?
When a model picks the wrong tool or fills it in badly, the usual instinct is to blame the model. More often the tool was unclear. A model knows a tool only by its name, description, inputs and results. Designing those four things well fixes most tool mistakes, without changing the model at all.
How does tool design work?
- Name the tool for what it does, in the words a user would use.
- Describe what it returns, when to use it, and when not to.
- Make inputs hard to get wrong: clear names, stated shapes, fixed choices.
- Return short results in plain words, and say when there is more.
- Write errors that explain what was wrong and what to try.
When should you use tool design?
Use it when
- Adding or changing any tool
- The model chooses the wrong tool or the wrong inputs
- The tool list has grown past a dozen
Think twice when
- The work is a single fixed step with no choice to make. Ordinary code is enough
Where does tool design sit in a real system?
Tool design lives in the tool definitions inside your harness. Those definitions are sent with every model call, so every word in them is read on every request.
What goes wrong with tool design?
- Offering two tools that could both answer the same request.
- Copying your database's tables as tools, so one question needs four calls.
- Returning raw internal codes for the model to decode.
What does tool design look like in practice?
Two tools called get_data and lookup were chosen correctly 43 times in 60. Renamed find_order and find_refund_status, with descriptions saying when not to use each, the score was 54. With fewer tools and fixed-choice inputs it reached 58. The model never changed.