Why AI Agents Misuse Enterprise Tools and How Tool Contracts Fix It

Here is an illustrative composite, not a real incident. A support team gives its agent a tool called update_account. The description says only: updates an account. The agent is asked to apply a goodwill credit for a customer who called about a late delivery. It finds two accounts with similar names, picks the first one, and passes the credit amount in dollars while the tool expects cents. The call succeeds. Nothing in the logs looks wrong. A week later finance finds a credit one hundred times too small on the wrong customer.

When the team reviewed the trace, the model's reasoning was sensible at every step. It understood the goal. It chose the closest tool available. It filled in the arguments the way the description implied. The failure was not in the model. It was in the interface the organization handed the model, an interface written for a developer who already knew the conventions, not for a reader who had only the words on the page.

This is the most common production failure we see in agentic systems, and it rarely gets the attention it deserves. Teams spend weeks choosing a model and an afternoon writing tool descriptions. The ratio should be closer to the other way around.

Developers think of a tool as a function: a name, some parameters, a return value. To a model, a tool is something else entirely. It is a piece of text in the context window that describes an action the model may take. The model has no other knowledge of what the tool does, when it is appropriate, or what happens if it is misused. The description is the whole truth as far as the agent is concerned.

That makes tool design a context engineering problem. Chapter 1 describes the gap between what the model knows and what the organization knows. Tools sit right in that gap. Your organization knows that credits are in cents, that refunds above a threshold need approval, and that test accounts start with a particular prefix. The model knows none of it unless the tool says so.

It is also a Control problem. A tool is the moment an agent stops talking and starts acting. Chapter 15 on guardrails and our essay on the blast radius argue that action control matters more than access control. The tool interface is where action control is either designed in or left to chance.

Across many agent traces, tool misuse tends to fall into four patterns. The first is wrong selection: the agent picks a tool that sounds right but does something different, because two tools have overlapping descriptions or because the right tool is described in jargon. The second is wrong arguments: the agent passes a value in the wrong unit, format, or identifier type, because the schema allowed it.

The third is wrong timing: the agent calls an action before it has gathered the facts the action depends on, or calls it twice because it could not tell the first attempt succeeded. The fourth is wrong recovery: the tool fails, returns a vague error or none at all, and the agent retries the same call, invents a workaround, or tells the user the task is done.

Notice that none of these are solved by a smarter model. A smarter model reasons more carefully over the information it has. If the information is ambiguous, careful reasoning produces a confident wrong answer. The fix is to remove the ambiguity, and that is what a tool contract does.

A tool contract is a short written specification that travels with every tool. It has five parts, and each one targets a failure from the previous section.

Purpose says what the tool does, when to use it, and just as importantly when not to. One clear sentence of purpose plus one sentence naming the nearest wrong tool removes most selection errors. Inputs define every argument with its type, unit, format, allowed values, and where the agent should get it from. Credit amount in cents, integer, taken from the approved credit policy, never estimated.

Limits state what the tool will refuse to do: maximum amounts, required approvals, environments, rate limits, and whether the action is reversible. Errors list what can go wrong and what each error means for the agent's next step: retry, ask the user, escalate, or stop. Owner names the human team responsible for the tool's behaviour and its contract, so when the contract is wrong, someone fixes it. The Agent Org Chart makes the case for named owners across all context.

None of this is exotic. It is the documentation a careful engineer would want before calling an unfamiliar internal API. The difference is that the agent reads it every single time, so the quality of the writing directly becomes the quality of the behaviour.

A tempting shortcut is to expose every internal API as a tool and let the model sort it out. This reliably makes agents worse. Every extra tool adds description text to the context, raises the chance of overlapping purposes, and makes selection harder. It also widens the blast radius, because every tool is a door.

The better pattern is task-shaped tools. Instead of a generic update_account that can change anything, offer apply_goodwill_credit with narrow inputs and hard limits. Instead of a raw SQL tool, offer a governed metrics lookup that answers from certified definitions, as Chapter 5 describes for the semantic layer. Narrow tools are easier to describe, easier to evaluate, and safer to grant.

This connects to the idea in The Skill Is the Unit of Work. A skill bundles instructions, tools, and examples for a job. Tool contracts are the building blocks inside that bundle, and a skill is only as reliable as its weakest contract.

A contract written in prose is a good start. A contract enforced in code is what makes it stick. Put a validation gate between the agent and every system it touches. The gate checks every call against the contract before anything executes: types, units, allowed values, limits, permissions, and whether the prerequisites have been met.

The key design choice is what the gate returns when a call fails. A generic error teaches the agent nothing and invites blind retries. A specific error, written for the model, teaches it to recover: the amount must be in cents, you passed 25 which looks like dollars, please confirm. Good error messages are context too, and they are among the cheapest reliability improvements available.

The gate is also the right place for the controls described in Chapter 16: logging every attempted action, requiring human approval above thresholds, and enforcing that each call runs under the agent's own scoped identity, as covered in Your Agent Needs an Identity. When repeated failures occur, a circuit breaker at the same gate stops the loop before it reaches production data.

Tools change. An API adds a field, a limit moves, a new region gets different rules. When the underlying system changes and the contract does not, the agent keeps acting on yesterday's truth, the same pattern Semantic Drift describes for data. Treat contracts like code: keep them in version control, review changes, and ship them with the tool.

Every tool should also have a small evaluation set: realistic requests where the right tool and the right arguments are known, plus tricky cases where the right answer is to refuse or ask. Run it when the contract changes and when the model changes. Chapter 20 covers evaluation practice, and The Evaluation Gap explains why demos hide exactly these failures.

Contracts also protect Choice. A contract written in plain, model-neutral language moves between models far more easily than a description tuned to one model's quirks. Chapter 19 covers model portability, and Open Weights Are Not Freedom explains how tool schemas quietly become lock-in when nobody owns them.

Writing a good contract takes an experienced engineer perhaps an hour per tool, plus review from the team that owns the system. That feels slow next to pasting an API spec into a prompt. It is fast next to the alternative: wasted tokens on retries, human time unwinding wrong actions, and the trust lost the first time an agent does something visibly wrong.

There is a direct Cost benefit as well. Clear contracts reduce failed calls and retry loops, which are among the largest hidden drivers of cost per task, as Chapter 17 and Every Agent Needs a P&L explain. Fewer, sharper tools also mean shorter context on every turn, which lowers cost and latency together.

And there is a Career benefit. Writing tool contracts sits exactly where data engineering skills meet agent design: schemas, definitions, ownership, testing. It is one of the most concrete things a data engineer can do to become the context engineer the organization relies on.

Before any tool reaches a production agent, confirm these ten points:

1. The purpose fits in one sentence and names when not to use the tool.

2. No other tool has an overlapping purpose without a clear rule for choosing between them.

3. Every input has a type, unit, format, allowed values, and a stated source.

4. Limits, approvals, and reversibility are written down and enforced in code.

5. Every known error has a specific, model-readable message and a recommended next step.

6. A validation gate checks every call before it executes and logs every attempt.

7. The tool runs under the agent's own scoped identity, not a shared service account.

8. A named team owns the tool and its contract.

9. The contract is versioned and changes are reviewed like code.

10. An evaluation set covers correct use, wrong-tool traps, and cases that should be refused.

If a tool cannot pass this list, it is not a tool yet. It is a risk with an API. The full framework behind these ideas is in the book, and you can test your understanding with the Context Engineer practice exam.