Designing tools a model can use well

A tool is a function your code exposes to the model: a name, a description, an input schema and a result. The model never sees your implementation. It chooses tools and fills arguments from the definition alone, so the definition is the user interface and the model is the user. Good tools have unambiguous names, descriptions that say when to use them and when not to, parameters with precise types, enums, formats and bounds, results that return only what the next step needs, and errors that tell the model how to fix its call. Fewer, workflow-shaped tools beat many thin API wrappers on both accuracy and tokens. Write tools are separate, idempotent and explicit, because that is where authorisation and approval attach. You find out whether a tool is good by running evals, not by reading it.

Key takeaways:

• Every tool definition is sent on every step. Tool count is a token cost and a selection-accuracy cost.
• The description is the most important field. "When not to use" is what separates similar tools.
• Do not ask the model for values the system already knows (acting user, tenant, idempotency context). Inject them.
• Errors are part of the interface. A good error message is a free retry with the right arguments.
• Tool annotations such as "read-only" are hints for clients, not security controls.