note · growing
Designing a tool
The model sees a name, a description and a schema. That is where the quality lives.
The model never sees your code. It sees a name, a description and a schema — so that is where quality lives.
Few and widefive good tools beat forty narrow ones
Honest descriptionssay when NOT to use it, not just when to
Typed inputa strict schema is cheaper than a retry
Readable errorsreturn text the model can act on
Paginatenever hand back an unbounded blob
The failure modes
- Tool soup. Forty tools with terse names. The model picks wrong, and no amount of prompt engineering above it fixes a bad menu.
- Swallowed errors. A tool that returns an empty result on failure teaches the model that the answer is "nothing".
- Unpaginated returns. One tool dumping a full JSON document is the most common cause of a blown context window.
The loop consuming these tools is its own subject — see an agent is a loop in the AI garden.