Opening

An internal operations agent started with five tools. Every sprint, some team asked for one more. A year later, the list sent with every call looked like this.

Get user. Fetch user. Get user profile. Look up customer. Search users. Five tools, all saying, more or less, gets a user.

Then get account, and get account version two, described as: gets an account, new. And thirty-three more.

The trace shows the effect. A request comes in: which plan does the customer with this tax ID have?

The model calls get user, with the tax ID in the id field. Type error.

It tries search users, with the tax ID as free text. Nothing useful.

And only on the third try, it finds look up customer. Three turns, for one lookup. In this lesson, you'll learn to recognize this smell, what it really costs, and the order of work to shrink the list.

The diagnosis

Here's the shape. A simple request comes in.

The model has to pick among dozens of vaguely described options.

It picks the one whose name looks most like the request.

The result is an error, or data that doesn't help.

And after extra turns, it gets it right. Or gives up.

How do you spot it? More than fifteen or twenty tools available in the same call.

Similar names, like get something, fetch something, and something version two, with nearly identical descriptions.

One line descriptions that say what the tool does, but never when to use it.

Traces where the wrong tool gets called first, and corrected later. And tool definitions adding up to thousands of tokens on every call.

And nobody can say which tools are still used.

Why it happens

Each team adds its own. A new tool is the easiest way to give the agent a new capability, and nobody owns the whole list.

Removing feels risky. With no usage data, removing a tool might break a flow someone uses once a month.

Internal APIs become tools one by one. Each endpoint turns into a tool, named after the endpoint. The agent inherits the shape of your backend, not the shape of the task.

New versions live next to old ones. Version two came in so version one wouldn't break, and both stayed.

And connecting a tool server through MCP, the model context protocol, often exposes dozens of tools at once. The team flips the server on, and forgets to filter what the agent actually needs.

The trap for people starting out is treating more tools as more capable. The opposite is often true. Few tools, clearly distinct, beat a toolbox the model can't read in full.

What it costs

Now the cost. Accuracy first. Tool choice gets worse when the options are many, and alike. Each mistake costs an extra turn, or a wrong answer.

Then money, with illustrative numbers. Say each tool definition is about one hundred fifty tokens, and the agent makes ten thousand calls a day. With forty tools, that's about six thousand tokens per call, and about sixty million tokens a day. Just for the catalog.

With eight tools, about twelve million. And each wrong pick still pays an extra turn, with the full history again.

And security. More tools means more surface. Picture a marketplace agent with three payment tools. Pay a bank slip, send an instant payment, and wire a transfer. All three described as: pays the customer. A refund request can fire the wrong one. Now the mistake isn't just cost. Money goes down the wrong rail. And a forgotten write tool on the list is an open door. In security, this has a name. They call it excessive agency. The model has more power than the task needs.

A challenge

Here's one for you. You connected an internal product's tool server, and the agent now sees eighty tools, most of them admin. In production, a user asked for an order status, and the model called delete workspace. What does this case show, first?

That the list sent to the model is far too wide for the task, with destructive tools in the same set as simple reads. An order status doesn't need delete workspace.

It's not that the protocol is bad. It's a way to expose tools, not the cause. And blaming the user with an input filter comes second. The design already handed a destructive tool to a read task. Filter what the server exposes, consolidate, and keep side effects apart from reads.

The treatment

There are three refactorings. Consolidate tools, when there are duplicates, near twins, or tools nobody calls. It's almost always the first step.

Introduce a router, when even after consolidating there are many tools, because the agent covers several topics. Each route gets only its own tools. The orders agent doesn't need to see the HR tools.

And move instructions into the tool description, when the rules for when to use each tool live in the system prompt, far from where the model actually chooses.

In practice, the order is this. Measure usage in the traces from the last ninety days. A tool that never appears is a candidate to go.

Group tools that do the same thing with different keys. One tool, several parameters.

Rewrite each description for the moment of choice. What it does, when to use it, when not to, and what it returns.

And if the list still has more than a dozen, and the topics are distinct, route.

Back to the tax ID request. Before, forty visible tools, five of them for users, and three turns. After, eight tools, and one of them is find customer, with a key and a value. The first call uses the tax ID as the key. One turn.

And say you consolidated, and you still have twenty-eight tools, because the same agent serves HR, orders and finance. Choice is still poor on orders. Don't add a block to the system prompt saying, if the topic is orders, use only these. The model still sees all twenty-eight. The restriction has to be in the list you send, not in the prose. That's what the router does.

When to ignore

When can you ignore it? Twenty tools from different domains, with clear names and descriptions, can work fine. The smell is confusion, not the count. And the other way around, too. Eight tools, where three run the same customer lookup with different keys, is this smell.

If your provider lets the model see only an index, and load definitions on demand, the token cost goes away. The confusion between similar tools stays.

And in a prototype, starting wide to discover what the agent needs, and pruning later, is fine.

Wrap-up

So here's the idea to take with you. The model chooses from what you hand it, at the moment of choice. Hand it fewer doors, one per job, each with a sign that says when to walk through it. You get fewer turns, fewer tokens, and fewer ways to do damage.

In the next lesson, we'll do the first cut step by step: consolidate tools. See you there.