The quality of your AI agents is capped by the quality of the tools you hand them. Not the model. We have swapped models three times this year without touching task success rates. The two times we redesigned our tools, task completion jumped — from 71 to 84 percent, then from 84 to 92.
Tool design is API design with a new consumer: a reasoning model that reads your naming, your descriptions, and your error messages, then decides what to do next. Every principle that made APIs good for developers now has a sharper, stranger version for agents.
Here are the six rules we hold every tool to before an agent gets it, and the number each one moved.
Why tools decide agent performance
An agent's loop is simple: read the goal, pick a tool, read the result, repeat. Every failure we log lands in one of those steps, and most land on the tools — the agent picked the wrong one because two names overlapped, passed a bad argument because the description was vague, or gave up because the error message said nothing actionable. When we fixed the tools, the same model with the same prompts stopped failing.
This is good news operationally. Model quality you rent. Tool quality you own, and it compounds.
It also means agent reliability is mostly a design discipline, not a research problem. Design disciplines have checklists. This is ours.
We learned it the expensive way, with a quarter spent blaming the model and two weekends spent blaming the prompts.
Name tools for intent, not implementation
An agent chooses tools by matching your goal against tool names and descriptions, so the name must say what the tool accomplishes, not how it works. We renamed post_webhook_v2 to publish_post and misuse dropped immediately: the agent had been calling the webhook for drafts, because nothing in the name said publishing was final. Name the outcome. If two tools could plausibly answer the same intent, the naming is not done.
The test is brutal and cheap: show a colleague only your tool names and ask what each one does. Every hesitation predicts an agent error. We re-run it quarterly.
This is old API wisdom — REST got there twenty years ago — but the penalty for violating it used to be developer annoyance. Now it is a wrong action taken confidently at 2 a.m.
Verb plus object, no jargon, no version numbers. Boring names run better.
Write descriptions like onboarding docs
The description field is the tool's entire manual, and the agent re-reads it every single time. Ours follow a fixed template: one sentence on what the tool does, one on when to use it, one on when not to use it, and the constraints that matter — rate limits, size caps, side effects. Adding the when-not-to-use line to our search tool cut redundant calls by roughly a third.
Treat description writing as a writing task, not a schema chore. The difference between "sends email" and "sends a client-facing email immediately, with no draft step — for drafts use create_draft" is the difference between an incident and a normal Tuesday.
Descriptions are also where policy lives. "Never call this for clients on the legacy plan" belongs in the description, because the agent cannot read your intranet.
If a tool needs three paragraphs to explain, the tool is too complicated. Split it.
Errors are prompts too
Whatever your tool returns on failure becomes part of the agent's next prompt, so an error message is not a log line — it is an instruction. "Error 422" produces a retry loop. "Publish failed: the post has no publish date. Set publishedAt, then call publish_post again" produces a fix. We rewrote our 30 most common errors as next-step instructions and watched recovery without human help rise from about half to over 80 percent.
Include what succeeded, what failed, and the one action most likely to fix it. Never return a stack trace to an agent. It will read the whole thing, every time, at your expense.
The error catalog is now the file we review most often. It earns it.
Write errors for the reader who will actually read them.
Prefer small, orthogonal tools
One tool with 14 parameters fails more often than four tools with 3 parameters each. Big multi-purpose tools force the model to make several decisions in a single call, and every extra decision multiplies the ways a call can be half right. We split our content mega-tool — create, update, publish, archive behind one endpoint — into four verbs. Same backend. Argument errors fell by half, and the failures that remained got easier to read.
Orthogonal matters as much as small. When tool capabilities overlap, the agent alternates between them unpredictably, and your logs stop telling a clean story.
Fourteen-parameter tools are usually an org chart problem wearing an API costume. Split the tool and the confusion splits with it.
The rule of thumb we use: one tool, one decision, one side effect.
Design for retries, idempotency, and undo
Agents retry. They retry on timeouts, on ambiguity, and sometimes on pure enthusiasm, so any tool with a side effect must be safe to call twice. Our publish tool takes an idempotency key and returns already-published instead of duplicating the post. Anything destructive requires a two-step confirm, and anything client-facing has an undo window. We assume every tool will eventually be called at the wrong moment, because it will.
Undo is the underrated half. A reversible action can be delegated to an agent years before an irreversible one, whatever the benchmarks say. Every autonomy increase we granted our engine last year traces back to an undo we built first.
Idempotency keys cost an afternoon to add. The duplicate-post incident they prevent costs a client call.
Our standing rule: agents get write access in proportion to how cheaply we can undo them.
Instrument every call and read the logs weekly
Log every tool call with its arguments, its result, and what the agent did next, then read the aggregate weekly. The logs are where tool design problems announce themselves: a tool nobody calls is badly named, a tool with a high retry rate has a bad error message, a tool that always gets called in pairs wants to be one tool. Our Friday review takes 30 minutes and produces most of the next week's design fixes.
This is the same feedback loop that made APIs good: usage data beats intuition. The only change is that your consumer now explains its confusion in plain English, if you bother to capture it.
Design the tools, watch the agent, fix the tools. That loop is the job now.
The businesses that run it will quietly outship the ones still shopping for a better model.