Tools are the API the model calls. Bad tool design is the #1 cause of agent unreliability: vague descriptions lead to wrong tool selection, missing constraints lead to wrong arguments. The patterns are simple but specific.
Description is the prompt
The tool description is how the model decides whether to call it. Spend more time on the description than the implementation. Include: what it does, when to call it, what NOT to call it for, common mistakes.
Narrow tools beat one big tool
'Search documents' + 'Get document by ID' beats one 'Documents' tool with a verb parameter. Each tool's contract is clearer; the model picks more accurately. Cost: more tools to maintain. Right trade-off.
Schema constrains, description guides
JSON schema enforces structure (required fields, types). Description explains intent. A field marked 'required' that the model doesn't understand gets called with garbage. Description on each field.
Idempotency built in
Every tool should be idempotent or have an idempotency key parameter. Agents retry. Networks drop. Idempotency prevents double-charges, double-sends, double-anything.
Error messages teach
Tool returns 'error: search_query parameter is empty; pass the user query as a string'. Model retries correctly. 'Error: Bad request' produces another bad request. Error messages are a debugging tool the model uses at runtime.