Tool design

A tool definition is a prompt. The model never sees your implementation — it sees the name, the description, the parameter schema, and whatever came back last time. Most "the model is bad at using tools" is a tool that told the model the wrong thing.

When this fires

Adding a tool to an agent, changing an existing tool's parameters or return value, or diagnosing an agent that picks the wrong tool, passes bad arguments, loops, or stalls after a call. It does not fire for an internal function no model ever invokes.

Procedure

1. Start from the task, not the API. List the things the agent must accomplish, then define one tool per accomplishment. A thin one-to-one wrapper over an existing HTTP API pushes the orchestration into the model, which pays for it in extra turns and wrong guesses. Prefer one schedule_meeting over list_calendars + get_availability + create_event unless the agent genuinely needs the intermediate steps.
2. Count the tools. A large, overlapping surface is the main cause of wrong-tool selection. If two tools could plausibly answer the same request, either merge them or make each description state explicitly when the other one is correct.
3. Name it for what it does, from the caller's side. Verb plus object, unambiguous when read alone in a list: cancel_order, not order_v2 or process. Names sharing a prefix by domain (docs_search, docs_create) help the model group them; near-identical names across domains defeat it.
4. Write the description to be selected correctly, not to be complete. First line: what it does and when to reach for it. Then the boundary — what it does not do and which tool covers that instead. Then anything non-obvious: required ordering, what must be fetched first, side effects. Write it for a competent stranger with no access to your codebase.
5. Shape parameters so a wrong call is hard to express. Flat over nested. Enums over free strings whenever the set is known. Explicit types, formats and units in the field description ("ISO 8601 date, e.g. 2026-03-01", "amount in minor units"). Required only what is truly required; every optional parameter is another thing to get wrong. Never accept a raw query language, a SQL string or a path the model composed unless the implementation constrains it.
6. Do not make the model supply what you already know. Ids from the session, the current user, the project root, an auth token — bind them server-side. A parameter the model must invent is a parameter it will eventually hallucinate.
7. Return what the model needs for the next step, and cut the rest. Resolved human-readable values over opaque ids; the fields that drive a decision over the full record. On a paged or truncated result, say so in the payload and say how to get more. A response that blows the context window is a failed call, even when the API returned 200.
8. Write errors as instructions. "Invalid request" teaches nothing. "No customer with id 'X'; search by email with find_customer first" gets the next call right. Name what was wrong, what is valid, and what to do now. Return it as a normal tool result the model can read and act on — a thrown exception that never reaches the model turns a recoverable mistake into a dead turn.
9. Distinguish empty from broken. Zero results, a permission denial, an upstream outage and a malformed argument must be four distinguishable responses. Collapsing them makes the agent retry the same call forever or give up on data that exists.
10. Make the destructive ones announce themselves. A tool that deletes, sends, publishes, charges or deploys says so in its first sentence, and the agent stops and asks before it fires. A tool description never grants the permission — it only makes the consequence visible. Where the operation can be repeated, give it an idempotency key rather than hoping for one call.
11. Exercise it before believing it. Give the model five to ten realistic requests, including the ambiguous ones and the ones that should select a different tool, and read the actual calls: which tool, which arguments, what it did with the result and with the error. Fix the description and the schema, not the prompt around them, and run the set again.

Checklist

• Each tool maps to a task the agent must accomplish, not to one endpoint
• No two tools plausibly answer the same request without saying which wins
• Names readable in isolation; descriptions state when not to use the tool
• Enums and formats used wherever the value set is known; units stated
• Nothing required from the model that the server already knows
• Results carry the fields the next step needs, truncation is declared, size bounded
• Every error names the cause and the corrective action, and reaches the model as a result
• Empty, denied, upstream-failed and malformed are distinguishable
• Destructive and outward-facing tools are labelled, and stop for confirmation
• Run against realistic requests, wrong-tool cases included, and the transcripts read

Failure handling

• Wrong tool chosen — a description problem before a model problem. Add the boundary sentence to both tools. Overlap that cannot be written away should be a merge.
• Malformed or invented arguments — tighten the schema first (enum, format, fewer optionals), then the field descriptions. A retry prompt that patches a loose schema will keep paying for it.
• The agent loops on the same call — the error text is not actionable, or success and empty look alike. Read the exact tool result the model saw, not your log line.
• It works in your handful of examples — that is executed, not tested. A tool surface is tested when a fixed set of requests runs against it and asserts the selected tool and arguments.
• Unsure whether the framework supports a schema feature you want to rely on — check its current documentation rather than assuming. Silently dropped schema keywords fail as bad model behaviour.

Evidence to report

The tool list with each name, one-line purpose, and the boundary it cedes. The full schema of every added or changed tool. Real transcripts: the request, the tool chosen, the arguments, the returned payload, and at least one error path showing the model recovering. What was merely defined, what was executed once, and what has a repeatable selection check behind it.