Designing Tools for Agents

Your API is not a tool.

The most common production failure is mechanical: point the agent at an existing REST API, generate one tool per endpoint, ship. It nearly works, which is what makes it expensive. APIs are designed for a developer who has read the docs, holds state across calls, and writes code to stitch responses together. An agent has none of those.

• Responses are too wide. A typical endpoint returns forty fields when the agent needs three. Every unused field is paid for on this step and on every subsequent step of the loop, because the transcript is re-sent each time. Project down to what the task needs.
• Pagination leaks into the reasoning. An agent handed a cursor will spend turns fetching pages, and will sometimes stop early and answer from partial data. Handle paging inside the tool and return either a complete result or an explicit, structured "truncated at N of M" marker.
• Identifiers the model cannot know. A tool requiring an internal UUID forces a lookup call the agent has to guess its way to. Accept the human-legible handle and resolve it yourself.
• One endpoint is rarely one task. If completing a real user request always takes the same four calls in the same order, that sequence is the tool. Ship it as one.

Fewer tools, described as if to a competent stranger.

Tool definitions are prompt text. They occupy the context window on every single call, they compete for attention with the actual task, and past roughly a couple of dozen the model's selection accuracy starts to degrade noticeably — not because it cannot read them, but because near-duplicates create a choice with no clear right answer.

• Overlap is worse than absence. search_users and find_user guarantee a coin flip on every call. Merge them, or make the boundary unmistakable in the first sentence of each description.
• The description is where you spend words. Say what the tool does, when to reach for it, when not to, and what it returns. "Searches records" is not a description. "Finds customers by email or company domain; returns at most 20 matches with account status. Use get_customer when you already have an ID." is.
• Name for the caller, not the codebase. Names carry more selection weight than any other field, and an internal service name means nothing to the model.
• Constrain in the schema, not in the prose. Enums, required fields and formats are enforced by structured output machinery; a sentence asking politely for ISO dates is not enforced by anything. See tool calling for the mechanics.
• Budget the response. Decide the maximum tokens a tool may return and enforce it at the tool boundary. Truncate with a marker the agent can act on, and return large payloads by reference — a path, an ID, a summary with a way to fetch more.

Errors are the only feedback channel you have.

A tool's error message is not a log line. It is a prompt, delivered at the exact moment the model is deciding what to do next, and it is the only mechanism by which a running agent can learn it was wrong. Most stack traces and most HTTP status codes tell the agent that something failed and nothing about what would succeed, which is why agents retry identical failing calls: you gave them no other move.

• Say what to do next. "Invalid date format. Expected YYYY-MM-DD, received 'last Tuesday'." recovers on the following turn. "400 Bad Request" produces a retry loop.
• Distinguish retryable from terminal. A rate limit is worth waiting on; a permission denial is not. If the agent cannot tell them apart it will treat both the same way, and one of those choices is always wrong.
• Return failure as data, not as an exception. "No results" is a legitimate outcome and should look like one; an empty list plus a note on what was searched keeps the agent reasoning instead of guessing whether the tool broke.
• Make write tools idempotent. Retries are structural in agent systems — from the model, the harness, the network and the queue. A write tool that accepts a caller-supplied idempotency key turns four sources of duplication into one safe outcome; the operational depth is in idempotency and retries.
• Confirm side effects in the return value. "Created invoice INV-1042 for $240.00" lets the agent verify and lets your trace reconstruct what happened. "OK" does neither.

Iterate on tools the way you iterate on prompts.

Tool design is not a thing you get right by thinking. It is measured, and the measurement is cheap: a few dozen realistic tasks, run end to end, with the tool calls recorded. What you are looking for is narrower than task success.

• Selection accuracy — did it reach for the right tool? Systematic mistakes point at a name or a first sentence, not at the model.
• Argument validity — what fraction of calls were rejected by your own schema? That number is a description defect rate.
• Calls per completed task — the count that reveals a missing consolidated tool, and the count that shows up directly on the bill via quadratic transcript growth.
• Recovery rate after an error — of the failed calls, how many were followed by a corrected one rather than a repeat? This grades your error messages specifically.

Then read the transcripts. An agent that misuses a tool usually says why, in plain language, immediately before doing it — an unmatched signal you get for free and only from reading. Feed each fix back through the same tasks; this is agent evaluation pointed at your interface rather than at the model.

Related: tools, actions & environments for what a tool fundamentally is, MCP for the standard way to distribute one, and context engineering for the discipline that tool responses feed into.