Sit in on the incident review after a production agent system misbehaves and listen to the language the on-call engineer actually uses. It is rarely a complaint about the model.
It is closer to this: the agent called update_ticket when it should have called create_ticket. Or it passed a Salesforce Account ID into a field expecting a Contact ID, or it read a 500 from Zendesk and retried the same write eleven times.
Those three descriptions all point at one layer — the function interfaces you handed the agent and the contract you wrote around them. That layer is agent tool design, and it deserves the same specification rigor you already apply to a public API.
Agent tool design is the practice of specifying the function interfaces an agent calls — names, parameter schemas, error contracts, and return shapes. It is the layer where most production agent failures originate.
Why The Tool Layer Absorbs So Much Failure
An agent's entire capacity to affect the world runs through its tool definitions. The model reasons in text, and the tools are the only place that text becomes a write to DynamoDB, a POST to ServiceNow, or a row in Snowflake.
This matters because the model reads the tool layer as its only documentation. It does not have your runbook, your architecture diagram, or the tribal knowledge that account_id means the billing account in one service and the CRM object in every other one.
What's more, ambiguity in a tool spec does not fail loudly. The agent produces a confident, well-formed call against the wrong tool, gets a 200 back, and reports success — which means the defect surfaces days later in a reconciliation report rather than in the trace.
Naturally, teams reach for the model first when quality drops. Swapping Claude for GPT-5, raising the context budget, or rewriting the system prompt all feel like progress, and none of them fix a parameter whose description reads the id.
Our guide to agent orchestration architecture covers how these calls get sequenced across a full workflow. This post stays inside a single call: how it is specified, versioned, and tested.
The Four Tool-Definition Failures That Show Up In Production
Across the agent systems we build and operate, tool-layer defects cluster into four recognizable shapes. Each has a distinct symptom in the trace and a distinct fix in the specification.
Ambiguous Parameter Schemas
The most common defect is a parameter whose name and description do not fully determine what value belongs there. A field called id described as the record id is an invitation for the agent to supply whichever identifier appeared most recently in context.
The fix is boring and effective: name the entity, state the format, give a worked example, and constrain the type. A parameter named salesforce_contact_id, described as an 18-character Salesforce Contact record ID with a sample value and an explicit note that Account and Lead IDs do not belong there, removes the guess entirely.
Enums matter here more than downstream validation does. If a status field accepts five values, put those five values in the schema rather than describing them in prose, because a rejected call costs a full round trip and the retry often repeats the same mistake.
Be aware that optional parameters carry hidden ambiguity too. An optional limit with no documented default means the agent will sometimes send 10 and sometimes send 1000, and your P95 latency will move accordingly.
Overlapping Tool Names And Descriptions
Two tools that could plausibly satisfy the same request will be selected inconsistently, and the inconsistency compounds as the registry grows. A surface carrying search_customers, lookup_customer, and get_customer_by_email guarantees a coin flip on some fraction of requests.
A tool description is failing when two tools in the same registry could plausibly answer the same request. Give each tool a description that names when not to call it, not only what it does.
The practical rule is that every tool description should carry an exclusion clause. Stating that a tool finds a customer when an email address is available, and that partial names route to search_customers instead, resolves the ambiguity at selection time rather than in postmortem.
Registry size is the second lever. Once a single agent carries more than roughly 15 to 20 tools, selection accuracy degrades, and the right move is to split the surface across specialized agents joined by explicit handoff contracts between agents.
Missing Error Contracts
Most tool specs describe the happy path in detail and leave failure to whatever the underlying API happens to return. The agent then receives a raw stack trace, a bare 500, or an HTML error page, and has to infer whether to retry, escalate, or abandon the task.
An error contract tells the agent what happened and what to do next: retryable or terminal, with a machine-readable code. Free-text errors force the model to guess, and it guesses inconsistently.
A usable error contract is small. Return a stable code, a retryable boolean, and one sentence of remediation — enough for the agent to distinguish RATE_LIMITED, meaning wait and retry, from PERMISSION_DENIED, meaning stop and escalate, without parsing English prose.
This is also where retry budgets belong. If the tool does not declare a failure terminal, the orchestration layer should cap attempts anyway, because an agent looping on a permission error will burn tokens until something else stops it — a pattern worth reading alongside agent cost governance controls.
Unbounded Return Payloads
A tool that returns whatever the upstream API returns will eventually return 4,000 rows. The immediate cost is context: the window fills with data the agent cannot use, and the reasoning quality of every subsequent step drops.
Therefore, specify the return shape as deliberately as the input. Cap the row count, project only the fields the agent needs, and return a cursor or a count of matching records rather than shipping all of them into the conversation.
Truncation without notice is its own defect. If you cap at 50 rows, say so in the payload — returned 50, total matched 4,182 — so the agent does not silently reason over a partial set and then report a total.
The diagnostic question for any tool spec: if you handed only this description and schema to a new engineer with no access to your codebase, could they call it correctly on the first attempt? The model has strictly less context than that engineer does.
How Should A Tool Description Be Written?
Treat the description as the only prompt the model will ever receive about that capability. It should read like an interface contract, and it should be reviewed by whoever owns the downstream system.
- The action, in one line. A verb and an object, stated as what the tool does to the system of record. Creates a new incident in ServiceNow and returns the incident number.
- When to use it. The conditions under which this tool is the correct choice, phrased as a situation the agent will actually recognize in a user request.
- When not to use it. The explicit exclusion, naming the neighboring tool so the model has somewhere specific to go instead.
- Preconditions and side effects. What must already be true before the call, and what changes in the world after it succeeds, including whether the change is reversible.
- Failure behavior. The error codes the tool can return, and which of them are retryable.
All of this adds up to a description longer than most teams expect, often 80 to 150 words per tool. That length is bought back the first time an agent stops calling the wrong function under load.
Tool Granularity Is A Retry And Approval Decision
Granularity is usually argued as an engineering aesthetic, and it is better treated as an operational one. The unit of the tool determines the unit of the retry, the unit of the approval gate, and the unit of the audit entry.
Here is how the three common granularity choices trade off in production:
| Design choice | What it optimizes | What it costs |
|---|---|---|
| One tool per API endpoint | Fast to generate from an OpenAPI spec, with a thin maintenance surface | Business actions span three to five calls, so a partial failure leaves inconsistent state and no compensating path |
| One tool per business action | Retries, approvals, and audit entries align to something a human can reverse | Hand-written wrappers per action, which is more code to own and version |
| One mega-tool with a mode parameter | A tiny registry with no name-overlap problem | Parameter validity becomes conditional on mode, which is exactly where schema ambiguity concentrates |
The middle row is the one that survives contact with production. Wrap the endpoints so that one tool call equals one thing a human would approve or reverse, and your agent approval gate design becomes a routing decision rather than a rewrite.
Why Every Mutating Tool Needs An Idempotency Key
Agents retry, and they retry for more reasons than a service client does. They retry on timeouts, on ambiguous errors, on orchestration-level restarts, and occasionally because the model decided the first call did not look like it worked.
Every mutating tool should accept an idempotency key the caller generates once per intent. Retries then collapse into a single write instead of three refunds, three tickets, or three duplicate bookings.
The key should be derived from the intent, not minted per attempt. A hash of the conversation ID plus the business action plus the target record survives an orchestration restart, and a UUID generated inside the retry loop does not.
Note that this pushes work into the tool implementation, which is where it belongs. The agent should never be responsible for detecting its own duplicates, because the model's judgment about whether it already performed an action is the least reliable component in the path.
How Do You Version A Tool Without Breaking Running Agents?
Tool definitions drift the way API contracts drift, with one added complication: the consumer is a model whose behavior was tuned against the previous wording. A renamed parameter is a breaking change, and so is a rewritten description, even when the schema itself is untouched.
Version tools additively: add optional parameters, never rename or remove required ones. Breaking changes ship under a new tool name with the old one deprecated on a published date, not swapped silently.
- Additive-only within a version. New optional parameters with documented defaults are safe to add. Renaming, removing, or tightening an existing required parameter is not.
- Pin agents to a registry version. An agent should resolve its tool set from a versioned registry snapshot, so a change to a shared tool cannot silently alter the behavior of six other workflows.
- Deprecate on a published date. A breaking change ships as a new tool name, the old name keeps working, and both remain in the registry until the announced removal date passes.
Description changes deserve the same treatment as schema changes, which surprises most teams the first time it comes up. Reword a description and you have changed the model's selection behavior, so route it through the same agent release management process you already use for prompts and model-version pins.
How Do You Test The Tool Layer?
Output review catches tone problems and factual problems, and it is nearly blind to tool-selection problems. An agent can produce an impeccable summary of an action it performed against entirely the wrong record.
Test the tool layer with a fixed suite of intents and assert on the call the agent made — tool name, parameters, and order — before assessing the prose. Selection errors surface here, not in output review.
The suite that catches this is unglamorous. Fifty to two hundred fixed intents, each annotated with the tool call a competent operator would make, run on every registry change and every model-version bump.
- Tool name. Assert the agent selected the intended tool rather than a neighbor with an overlapping description.
- Parameter binding. Assert the right value landed in the right field, especially across the identifier types that look alike to a reader and to a model.
- Call order and count. Assert it made one call where one was required, and that it read the current state before it wrote.
Additionally, run the suite in shadow mode against a sample of real traffic before promotion. Synthetic intents miss the phrasings your users actually produce, and shadow mode surfaces those without exposing anyone to a bad write — the broader practice is covered in our post on agent evaluation methods.
What A Tool Registry Should Hold
Once more than one agent exists, tool definitions stop being application code and become shared infrastructure. A registry is where ownership of that infrastructure becomes explicit.
- The definition and its version. Name, description, parameter schema, return shape, and error codes, immutable once published.
- An owner. A named team that approves changes, because whoever owns Zendesk should approve what an agent is permitted to do inside Zendesk.
- A risk classification. Read-only, reversible write, or irreversible write, which drives whether an approval gate is required at all.
- The identity it executes under. The IAM role or service account the tool assumes, so permissions are scoped per tool rather than per agent.
- Consumers. Which agents currently resolve this tool, so a deprecation notice has a distribution list.
That last field is what makes deprecation survivable at scale. Without it, removing a tool becomes a search-and-hope exercise across every workflow you run.
Risk classification and execution identity connect directly to agent identity and access design. An agent that assumes one broad role for every tool it holds has no meaningful blast-radius control, whatever the approval gate says.
Instrumenting Tool Calls In Production
The tool boundary is the highest-value place to instrument an agent system, because it is precisely where intent becomes effect. Every call should emit a structured record whether it succeeded or not.
At minimum, capture the tool name and version, the parameters with PII redacted, the outcome code, latency, the retry attempt number, and the trace ID tying the call back to the originating request. That single record is simultaneously your debugging surface, your agent audit trail, and your cost attribution.
Two derived metrics deserve dashboards of their own. Selection distribution — how often each tool is chosen, tracked over time — surfaces a description regression within hours, and tool error rate segmented by code separates a flaky upstream from a schema the agent cannot satisfy.
Keep in mind that a spike in retries is often a specification problem wearing an infrastructure costume. Our post on agent observability instrumentation goes deeper on what to emit, where to store it, and which alerts are worth paging on.
A Rollout Sequence For A New Tool
Adding a tool to a live agent is a production change, and it benefits from the same staging you would give a database migration. The sequence below is the one we run.
- Specify before you implement. Write the description, schema, error codes, and risk classification first, and have the owner of the downstream system read it.
- Add the evaluation cases. Write the intents that should select the new tool, and the near-miss intents that should still select its neighbors.
- Run in shadow. Register the tool, let the agent select it, and log the call without executing the write.
- Promote read-only paths first. Execute the non-mutating calls in production while every mutation stays shadowed.
- Gate the first mutations. Route writes through a human approval step for a fixed window, then relax the gate once the selection distribution holds steady.
Overall, this takes days rather than minutes, and it converts the failure mode from a silent data-integrity incident into a logged mis-selection nobody had to page for. When something does go wrong regardless, the tool-call record is what makes agent incident response tractable instead of archaeological.
Common Questions About Agent Tool Design
These are the questions that come up most often when a team moves from a single prototype agent to a production tool registry.
How many tools should a single agent have?
Keep a single agent under roughly 15 to 20 tools. Beyond that, selection accuracy degrades and descriptions start to overlap; split the surface across specialized agents with explicit handoffs instead.
What belongs in a tool's error contract?
A stable machine-readable code, a retryable-or-terminal flag, and a short remediation hint. The agent needs to distinguish a transient timeout from a permission denial, because the correct next action differs completely.
Should tools be coarse-grained or fine-grained?
Match granularity to the unit of work a human would approve or reverse. One tool per reversible business action keeps retries, approval gates, and audit entries aligned; splitting one write across three calls breaks all three.
How do you version an agent tool safely?
Add optional parameters rather than renaming or removing required ones, and pin agents to a tool-registry version. Breaking changes ship under a new tool name with the prior version deprecated on a published date.
How do you test tool selection before production?
Build a fixed suite of intents with the expected tool call for each, then assert on tool name, parameters, and call order. Run it on every registry change and every model-version bump, in shadow mode against real traffic.
What should a tool description contain?
Name the action, the parameters in business terms, the preconditions, and explicitly when not to call the tool. Disambiguation from neighboring tools matters more than an elegant summary of what the tool does.
Getting A Second Set Of Eyes On Your Tool Layer
If you're specifying the tool surface for a production agent and want it reviewed before it ships, the team at iSimplifyMe builds and operates agent systems across CRM, ticketing, and data warehouse environments every week. Reach out for a working session — we'll audit your tool definitions against the failure modes above, classify each tool by risk and execution identity, and leave you with a versioned registry spec plus an evaluation suite you can run on every change.
For the wider operating picture around this layer, start with our overview of AI agent operations and the architecture work in Bedrock agent patterns.