Tool Design for AI Agents: The Interface Decides Everything

Most agent failures are not reasoning failures. They are interface failures: a tool that does three things, a description that never says when to use it, an error message written for a log and not for the caller. The model routes on what you wrote, so the fix is usually in the text and not in the model.

The description is the routing logic

An agent choosing between tools is reading descriptions. Not names, not implementations — descriptions. Two tools whose descriptions overlap produce routing that looks random, and the instinct is to blame the model.

A description that works says three things: what the tool does, when to use it, and when not to. The third is the one almost always missing, and it is the one that separates two tools that otherwise sound alike.

Before changing the model, changing the prompt, or adding a routing layer, read your tool descriptions as if you were the one choosing. If you cannot tell them apart, neither can the agent.

One tool, one job

Instead of	Split into	Why
`createAndNotifyCustomer`	`createCustomer` · `sendNotification`	One is reversible, one reaches a human. Different approval needs.
`updateOrder` with a mode flag	Separate tools per operation	A flag the agent picks wrongly is a silent wrong action.
`queryDatabase` taking raw SQL	Named queries with typed parameters	An arbitrary query surface is an arbitrary blast radius.

Typed, validated, and validated again

Declare parameter types and constraints in the schema, and validate them in the tool anyway. The schema steers the model; it does not bind it. An agent will pass a date as a string, a quantity as text, or an identifier it inferred from context.

Validation inside the tool is what turns those into handled errors rather than corrupted records.

Write errors for the caller

An agent reads the error and decides what to do next. That makes error text part of the interface, and it is usually the part written last and for a human.

Unhelpful: Error 400: Bad Request — the agent retries identically.
Useful: customerId must be 8 digits; received 6 — the agent can correct.
Useful: No customer matches that name. Try searchCustomers first. — it can route.
Terminal: Period is closed. This cannot be posted. — it stops instead of looping.

Assume every call happens twice

Agents retry: on timeouts, on ambiguous responses, on their own uncertainty about whether the last call landed. A create operation that runs twice produces two records, and nothing in the agent will notice.

Key writes on a correlation identifier so a repeat updates instead of duplicating. This is ordinary distributed-systems hygiene, and it becomes urgent the moment the caller is a model rather than a deterministic client.

Budgets and terminal failures

Cap steps per task. Without a budget, a loop runs until something else stops it.
Make terminal failures unmistakable. Most loops are a retryable-looking error that will never succeed.
Route the stuck case to a person. Silent give-up is worse than a visible error, because nobody learns the work did not happen.
Alert on call-volume anomalies. It is the earliest signal that something is spinning.

Test the tools, not just the agent

Agent behaviour is hard to test end to end and easy to test at the boundary. Every tool should have ordinary tests: valid input, invalid input, boundary values, duplicate call, downstream failure.

A tool suite that passes tells you the agent's failures are routing or reasoning. Without it, every investigation starts by working out which layer broke — and that is most of the time spent debugging agents.

Frequently Asked Questions

Why do AI agents call the wrong tool?

Almost always because the description does not say when the tool applies. The model routes on the description, not on the name or the implementation, so two tools with overlapping descriptions produce coin-flip routing. The fix is nearly always in the text rather than the code: say what the tool is for, when to use it, and explicitly when not to.

Should a tool do more than one thing?

No. A tool that creates a record and emails a notification will be called when the agent wanted one of those. Splitting them gives the agent a choice it can make correctly and gives you an authorisation boundary you can place between them — which matters when one is reversible and the other is not.

How should a tool report an error to an agent?

In a form the agent can act on. "Error 400" tells it nothing and it will retry identically. "Customer ID must be 8 digits; received 6" lets it correct and proceed. Error text is part of the interface, and it is the part most likely to have been written for a human reading a log.

Do agent tools need to be idempotent?

Anything that writes, yes. Agents retry — on a timeout, on an ambiguous response, on their own uncertainty. A create operation that runs twice produces two records, and nothing in the agent will notice. Key on a correlation identifier so a repeat updates instead of duplicating.

How do you stop an agent looping?

A step budget per task, and tools that fail definitively, never ambiguously. Most loops are an agent retrying a tool that returns something it reads as retryable. Cap the steps, make the terminal failure unmistakable, and route the stuck case to a person instead of letting it spin.