Why Your Agent Is Only As Good As The Tools You Hand It
We have spent the last two years arguing about prompts. The next two years will be spent arguing about tools.
Once an agent moves out of a notebook and into a production workflow, the model itself becomes the least interesting variable. Frontier models converge in capability. What separates an agent that closes the loop from an agent that loops forever is almost always the same thing: the tools we hand it, how those tools are described, what they return when they fail, and whether the model can reason about which one to call.
Tool design is becoming its own engineering discipline.It borrows from API design, from UX writing, from compiler design, and from observability. It is not a side concern. In production agentic systems, it is the concern.
Why Tool Design, and Why Now
In a traditional API, the consumer is a human developer reading documentation. They can interpret ambiguity, ask a colleague, retry with curl, and inspect a stack trace. When something fails, they read the error, refactor, and try again.
In an agentic system, the consumer is a language model. It sees only what fits in the context window. It cannot ask a colleague. Its only feedback loop is the string the tool returns. If the description is ambiguous, the model guesses. If the schema is loose, the model hallucinates arguments. If the error message is opaque, the model retries with the same broken input until budget runs out.
That shift in consumer changes everything about how tools must be designed. We are no longer writing APIs for engineers who already understand the domain. We are writing APIs for a probabilistic reader who knows our system only through the tool description we wrote and the last few hundred tokens of output it received.
In regulated industries this gets sharper. A tool description is no longer just developer ergonomics. It is part of the model's effective system prompt, which means it is part of the model's risk surface. Every tool description, parameter, and error string is now subject to model risk management scrutiny. SR 11-7 reviewers should be reading tool schemas with the same care they review feature documentation.
API vs Tool: A Shift in Consumer
The Anatomy of a Well-Designed Tool
1. The name.Models select tools partly by lexical match against the user's intent. A tool called "process data" will lose against a tool called "extract_customer_transactions_by_date". Names should be verbs followed by specific nouns. They should be unique enough that the model cannot confuse two similar tools, and specific enough that the model can choose without reading the description.
2. The description.This is the most undervalued surface in agentic engineering. The description is not documentation; it is selection logic. A good description tells the model when to call the tool, when not to call it, what it returns, and what it costs in latency, side effects, and idempotency. I have seen agent quality jump double digits on internal evaluations by rewriting nothing but tool descriptions.
3. The parameter schema.Types are not enough. JSON Schema gives us types, but production tools need constraints: enumerations for closed value sets, regex patterns for identifiers, minimum and maximum values, examples in the schema description, and explicit required versus optional fields. The model treats the schema as authoritative. If the schema is loose, the agent will invent values.
4. The return value.Returns must be structured, predictable, and self-describing. Models reason far better over a JSON object with named fields than over a free-form string. Include enough context in the response that the model does not need to re-call the tool to remember what it asked for. A returned transaction record should include the account ID, not just the amount.
5. The error surface.Errors are not failures; they are instructions to the model. A useful error tells the model what went wrong, whether it should retry, and what to change. "Invalid input"is useless."Field 'account_id' must match pattern ^[A-Z]{2}\d{10}$. Received 'ACC123'. Did you mean to call lookup_account_by_name first?" is a tool recovering itself.
Tool Selection: How Models Actually Choose
When an agent decides which tool to call, three signals dominate: the tool name, the first sentence of the description, and the parameter names. Everything else in the description is tiebreaker information.
This has practical consequences. If you have two tools that overlap, the model will pick wrong somewhere between five and twenty percent of the time, and that wrong choice will cascade through the rest of the trajectory. The fix is rarely a better model. The fix is collapsing the two tools into one or making the difference between them lexically loud.
A second heuristic: tool count matters. Once an agent has more than fifteen to twenty tools available in a single turn, selection accuracy degrades noticeably across all current frontier models. The right answer is not a smarter model. It is hierarchical tool selection, where the agent first picks a domain or tool category, and only then sees the tools inside that category.
Parameter Design: Preventing Hallucinated Arguments
Most agent failures in production look like hallucinated parameters. The model fills in an account ID it never saw, an instrument identifier it inferred, a date it guessed. The cause is almost always the schema.
Three practices reduce this dramatically
First, use enums everywhere the value space is closed. If transaction_type can only be one of four values, the schema should say so. Free-string fields invite hallucination.
Second, add examples to the description of each field.The model uses these as anchors. A field documented as "account ID, e.g. US1234567890" produces far fewer hallucinations than one documented as "the account ID."
Third, design tools so the model retrieves identifiers before using them. Do not expose a tool that takes an account ID as input without also exposing a tool that returns account IDs. If the only way the model can produce an ID is to invent one, it will invent one.
A return value is the only window the model has into the world it just touched. Designing it well requires three things.
Return Values and Error Surfaces
A return value is the only window the model has into the world it just touched.
Designing it well requires three things.
It should be structured. Return JSON, not prose. The model can reason over fields; it has to re-parse prose.
It should be self-contained. Include the inputs that produced the output, especially for tools called many times in parallel. When the model receives ten parallel responses, it needs to know which response corresponds to which call.
It should be honest about partial success.If a batch operation succeeded for eight items and failed for two, the response should make both visible. Burying failures inside a status code teaches the model to ignore them.
Error design deserves the same care as the rest of the components of a tool. Treat every error as a teaching moment for the agent.The error string should answer three questions: what went wrong, whether retry is safe, and what alternative action might work. Errors that include a suggested next tool call are the single highest leverage change I have seen in production agent reliability.
Parallel Tool Calling
Modern models can call multiple tools in a single turn. This is a performance unlock and a correctness risk at the same time.
The unlock is obvious. Ten sequential tool calls become one parallel batch, and end to end latency drops from thirty seconds to three.For any read-heavy workflow such as account lookups, market data fetches, or reconciliation queries, parallel calling becomes the default.
The risk is less obvious. Parallel calls assume independence.If two tools have hidden coupling, where one writes state the other reads, parallel execution creates race conditions the model cannot reason about. Tools that mutate state should be explicitly marked as non-parallel safein their descriptions and ideally rejected by the runtime when issued in parallel.
MCP: Where Tool Design Meets Distribution
The Model Context Protocol changes the economics of tool design. Until now, every team built its own tools for its own agents. MCP makes tools portable across agents and across organizations. That is a step forward, and it raises the stakes on tool design.
An MCP server that technically works is not the same as one that performs. A well-formed MCP server passes the protocol tests. A well-designed MCP server passes the protocol tests and is used correctly by models that have never seen it before. The difference is everything we have discussed above: names, descriptions, schemas, errors, idempotency, and the discipline to expose ten good tools rather than fifty mediocre ones.
For enterprises, MCP introduces a new artifact that requires governance: the tool catalog.Which tools are approved? Who reviews their descriptions? What is the model risk treatment for a tool whose description was changed last week? These are not hypothetical questions. They are the next generation of model risk controls, and the firms that build the muscle early will move faster.
Anti-Patterns to Avoid
A short list of the failures I see most often in production agentic systems:
The overloaded tool.One tool with twelve optional parameters that behaves differently depending on which are set. The model cannot reliably learn the behavior. Split it.
The whisper description.A one-line description that assumes the model knows the domain. The model does not. Write more.
The opaque error.Returning raw HTTP status codes or stack traces to the model. The model cannot recover from "500 Internal Server Error." It can recover from "Database connection timed out, safe to retry after one second."
The missing inverse.A tool that takes an entity ID with no companion tool that produces an entity ID. The model will fabricate.
The duplicated tool.Two tools that do almost the same thing with subtly different names. The model picks wrong consistently. Merge or partition.
The chatty tool.A tool that returns five paragraphs of prose when one structured field would do. Context window pressure is real, and verbose tools degrade reasoning over long trajectories.
A Tool Design Checklist
Before exposing any tool to an agent in production, run it through this list.
Can a model that has never seen our system pick this tool correctly from its name alone?
Does the first sentence of the description state when to call it and when not to?
Are all parameters typed, constrained, and exemplified?
Is there a tool elsewhere in the catalog thatproduces every required identifier this tool consumes?
Are return valuesstructured JSON with self-contained context?
Doerror messagestell the model what went wrong, whether to retry, and what alternative to try?
Is the tool marked parallel safe or not, and does the runtime enforce that?
Is there a written description of side effects, idempotency, and cost?
Has the description been reviewed as a model-facing artifact, not just developer documentation?
In a regulated environment, is the tool catalog versioned and tied to a model risk record?
If you can answer yes to all ten, the model has a fighting chance.
Closing: The New Engineering Discipline
Five years ago, the best engineers in API design wrote for human developers. They obsessed over endpoint naming, status codes, idempotency, and developer experience. The discipline produced beautiful APIs.
That discipline has not gone away. It has been promoted. The consumer is now a probabilistic reader inside a context window,and the stakes are higher because the consumer cannot ask questions, cannot read your blog post, and cannot file a GitHub issue.
If you are building agentic systems in financial services, in healthcare, or in any other domain where the cost of a wrong action is high, the strongest investment you can make this year is not a fine-tuned model. It is a better tool catalog. Better names. Better descriptions. Better schemas. Better errors.Tested with the same rigor we used to test APIs, governed with the same discipline we use to govern models.
Explore more: Start Here · Topics · Archive · About