Tools Are the Real Interface

Tools Are the Real Interface because they are where intention becomes action. Everything before the tool call is reasoning that can be discarded. Everything after it is a fact about the world, and the tool's design decides how easy it was to create the wrong one.

Key takeaways

• Build tools at the level of intent, not at the level of your API endpoints. Anthropic's guidance is explicit: rather than list_users, list_events and create_event, implement schedule_event, which finds availability and schedules.
• Error messages are the highest-value prompt in the system. Return what went wrong, what would work, and the values that would satisfy the constraint, because that response is the model's next input.
• Fewer tools beat more. Every additional tool adds a selection decision, and selection errors are among the cheapest failures to design out.
• Return less. Pagination, filtering and truncation with sensible defaults keep tool output from consuming the context the run needs to reason with.
• Make destructive tools hard to call by accident: separate them from read tools, require an explicit scope argument, cap the scope in the tool rather than in the prompt, and treat tool descriptions from third parties as untrusted, which the Model Context Protocol says in its own security principles.

Read this beside Chapter 5, whose gates depend on tools returning verifiable results, and Chapter 9, which bounds what tools may consume. The security dimension of tool surfaces is the subject of the trust boundary argument.

An agent is given eleven tools that wrap eleven REST endpoints. It calls the right five in the right order most of the time, and about one run in twelve it calls update_record with an identifier from the wrong list.

Nobody would say the model misunderstood the task. It assembled a plausible sequence from an interface that made the wrong sequence just as easy to assemble as the right one.

The interface is what the model can get wrong

A tool definition is a contract offered to a caller with a specific set of weaknesses. It reads descriptions literally, it fills required fields even when it is unsure, and it cannot see the system behind the endpoint.

Anthropic's December 2024 guidance frames the design task as an interface problem, recommending that agent-computer interfaces receive the same investment as human-computer ones, and applying poka-yoke thinking so that mistakes are harder to make. The engineering note that follows is the one worth repeating: they spent more time optimising tools than prompts on a benchmark agent.

That reframing matters for reliability work because it moves a class of failure out of the model and into your code, where you can fix it. The April 2026 diagnostic study across four domains and more than 3,100 trajectories treats failures as attributable to identifiable steps, and in practice a large share of attributable failures are tool selection and tool argument errors rather than reasoning errors.

You cannot patch the model. You can change the tool.

Design for intent, not for your endpoints

The default move is to wrap each API endpoint in a tool. It is fast, it is uniform, and it pushes all the composition work onto the model.

Anthropic's September 2025 tool guidance recommends the opposite: instead of implementing list_users, list_events and create_event, consider implementing a schedule_event tool that finds availability and schedules. The composition moves into code that runs the same way every time.

Three benefits follow, and the third is the one this book cares about. The number of selection decisions falls. The number of intermediate results the model has to carry falls with it. And the intermediate steps become deterministic, so the failure surface shrinks to the arguments of one call rather than the sequencing of six.

There is a limit worth respecting. A tool that hides too much becomes unpredictable in its own way, and the model cannot reason about what it cannot see. The useful boundary is the unit a competent human would name as one request: schedule the meeting, refund the order, publish the draft. Anything smaller is plumbing, and anything larger is a workflow that belongs in the plan artifact from Chapter 3.

Error messages are prompts

When a tool returns an error, that text goes straight into the model's context and becomes the basis of its next attempt. It is a prompt, written by you, at the moment the model is most likely to be wrong.

The guidance is to return responses that communicate specific and actionable improvements rather than opaque error codes or tracebacks. In practice that means three components. What was rejected, in the caller's terms. Why, referring to the argument rather than to your internal validation layer. And what would work, with concrete values where you can supply them.

Compare two responses to the same failure. A 400 with the body "invalid date range" gives the model nothing except permission to guess again. A response saying that the requested window contains no availability, that the next three open slots are these, and that windows must start in the future, tells it exactly what to do and usually gets a correct second call.

There is a security caveat on generosity here. Do not leak identifiers, records or internal structure the caller was not entitled to see, because the error path is a common route for exactly that kind of disclosure. Return what is needed to correct the call, and nothing more about the system behind it.

Return less than you have

Tool output competes with reasoning for the same context. A tool that returns two hundred records has spent the run's attention on data it did not ask for.

The recommendation is to implement some combination of pagination, range selection, filtering and truncation, with sensible default parameter values. The defaults are the part that gets skipped. A tool with an optional limit parameter and no default will be called without one, and the model will discover the size of the result only after it arrives.

Three habits keep output small. Default to a small page and say in the description that more is available. Return identifiers and the two or three fields the next step needs, rather than whole objects. And when truncating, say so explicitly in the response, with the total count, because a silently truncated list is a wrong premise of exactly the kind Chapter 2 is about.

Consistency helps as much as size. Tools that return the same envelope, with the same field names for identifiers and errors, let one gate be written for many tools instead of one gate per tool.

Dangerous tools need different rules

The tools that can hurt you are a small minority and deserve most of the design attention.

Separate them. A tool that deletes, sends, pays or publishes should never be adjacent in the tool list to a read-only tool with a similar name, because near-miss selection is a real failure mode. Give destructive tools an explicit scope argument that must be stated rather than defaulted, so an omission fails instead of applying to everything.

Cap the scope in the tool. A limit expressed in the prompt is a suggestion, and a limit enforced in the implementation is a control. If a tool should never affect more than fifty records in one call, that ceiling belongs in the code, returning an error that says how to batch the work instead.

The Model Context Protocol's specification, currently at version 2025-11-25, states two principles that belong in any tool design even outside MCP. Hosts must obtain explicit user consent before invoking a tool, and tool behaviour descriptions such as annotations should be considered untrusted unless they come from a trusted server. The second matters more than it first appears once an agent can reach third-party tool servers, because a tool description is text the model will follow.

Descriptions are code, and they drift

The tool description is the part of the interface the model actually reads, and it is usually written once, by whoever wrote the endpoint, and never revisited.

Write it for a caller with no access to your codebase. Say what the tool does in one sentence, name the unit of every quantity, state what happens when an optional field is omitted, and give one example of a correct call. Where two tools are easily confused, say in each description what the other one is for. That single sentence resolves most near-miss selections.

Then treat the description as versioned code. It ships with the implementation, it changes when behaviour changes, and a change to it should require the same review as a change to the function. The failure mode otherwise is silent: an endpoint gains a required field, the description keeps describing the old contract, and every call fails validation for a reason the model cannot see.

There is a lifecycle question underneath this. Tools accumulate, and an agent with thirty tools where six are current is carrying a selection problem in every call. Audit the list against real usage, delete what is unused, and merge pairs that are always called together. Deleting a tool is the cheapest reliability improvement in this chapter, and the only one that also reduces cost.

Give tools their own evaluation

Tools are components with measurable behaviour, and treating them as configuration rather than code is why they stay bad.

The recommended loop is to prototype, evaluate with realistic tasks, and iterate, including letting agents analyse the results and suggest improvements to the tools themselves. Small refinements to descriptions can produce disproportionate improvements, which is a strong argument for measuring rather than guessing.

Three measurements are worth keeping per tool. Selection accuracy: how often this tool was called when it was the right one, and how often it was called instead of the right one. Argument validity: what share of calls failed validation, and which field failed. And recovery rate: after an error response, how often the next call succeeded, which is the direct test of whether your error messages are working.

That last number is the one to watch during a rescue of a badly behaving agent. A low recovery rate after errors means the model is guessing, and improving the message is usually a smaller change than anything else available. Measure it per tool rather than per run, because the average across a toolset hides the one tool whose errors nobody can act on.

Chapter summary

Tools are where intention becomes action, so an agent's reliability is bounded by its tool design rather than by its reasoning, and the failures involved are yours to fix rather than the model's. Design at the level of intent instead of wrapping endpoints, following the guidance to prefer a schedule_event tool over separate list and create calls, which cuts selection decisions, removes intermediate results from the context and makes the sequencing deterministic, while keeping the boundary at the unit a human would call one request. Treat error messages as the prompt they are, returning what was rejected, why in terms of the argument, and what would work with concrete values, without leaking records or structure the caller was not entitled to. Return less than you have, with pagination, filtering and truncation carrying real defaults, small pages, only the fields the next step needs, explicit notice when a result was truncated, and a consistent envelope so gates can be written once. Give destructive tools their own rules: separated from read tools, explicit scope arguments that fail when omitted, ceilings enforced in code rather than requested in prompts, and third party tool descriptions treated as untrusted, as the Model Context Protocol's own principles require alongside explicit consent before invocation. Then evaluate tools like components, measuring selection accuracy, argument validity and the recovery rate after an error, because that last number tells you directly whether your error messages are doing their job.

Better tools reduce the rate of wrong actions. They do not bound what a run can spend or damage while getting things wrong. Chapter 9 is Budgets: Time, Tokens, Tool Calls, Blast Radius, which turns an open-ended loop into a bounded operation, and specifies what should happen at each ceiling rather than leaving it to whoever notices first.