Opening

A software company's support bot started with one tool to get a user. Then came another to fetch a user by email. One to look up a customer by tax ID. One to search users by free text. Get account. Get account version two. And an export to spreadsheet that someone added, for the data team.

Seven names. Four ways to find the same person.

Now a simple request. What's Maria's plan? Here's her tax ID.

The model searches users for Maria, and gets forty rows back.

Then it gets the user with the first id in the list.

Then it asks for the account, with a user id where an account id belongs. Three calls. No plan. And the export tool? Zero calls in ninety days of traces.

In this lesson, you'll merge that list down to what the model can actually choose from, safely, and without changing a line of your backend.

The idea

The solution is simple to state. Merge tools that do the same thing into one, with clear parameters. And remove the ones your traces show nobody uses.

There's a telling detail from teams that build agents seriously. Some spend more time designing their tools than designing the prompt. A long list of overlapping names is the opposite. The model reads seven vague descriptions, and guesses.

Before and after

Before, seven tools, with four ways to find the same person, and two versions of the same account lookup.

After, the same request arrives, and the model sees a short list, with descriptions that say when to use each tool.

A single tool finds the customer, with the key as a parameter. By id, by email, or by tax ID.

And the next tool makes it clear that it depends on the previous result. It asks for a customer id, by name.

Here's the new list. Find customer. By id, email or tax ID. Use it before any question about plan, billing or account. Returns the id, name, plan and status.

And get account. Billing data. Needs the customer id returned by find customer.

So Maria's question becomes: find customer, by tax ID. It returns her plan. If the plan already answers the question, the model stops. If it needs invoices, it calls get account, with her customer id. No list of forty Marias. No account lookup with the wrong kind of id.

Why it works

The model picks tools by reading names and descriptions. When several options describe the same thing in different words, the choice becomes a guess. One tool per intent removes the guess. The decision stops being which of these four, and becomes which value goes in the by field. And the schema constrains that.

Removing unused tools has an extra effect. The prompt shrinks on every call. That export tool in the schema is noise you pay for in every conversation, including the ones that never export.

And there's a limit. If you merge synonyms, delete the ghosts, and still have forty tools with good descriptions, the next move isn't another merge. It's exposing a subset per intent, with a router, or by revealing tools progressively.

A challenge

Here's one for you. A colleague proposes a single customer tool, with a parameter called action. Its values are get, search, export, or delete. They call that consolidated. Is it?

No. Reading, searching, exporting and deleting are different intents. Now the model chooses among action values that are as vague as the seven old names. And a poorly chosen delete has a side effect. That's not consolidating. It's hiding the sprawl inside one function.

Consolidating merges what answers the same question. Who is this customer? Delete isn't a way to find a customer.

Safe mechanics

Step zero, measure. Run the agent's eval, and record the completion rate, the steps per task, and the rate of wrong calls. A tool that returned an argument error, or was followed by a similar one.

Gather real usage. From sixty to ninety days of traces, count how often each tool was called, and its error rate. Zero calls makes it a candidate for removal, not for a merge.

Group by intent. Tools that answer the same question go in the same group. And reads and writes never mix in the same group.

Design one tool per group. A choice parameter with a closed list of values, a description that says when to use it and what comes back, and a verb plus noun name. And build it on top of the old code. The new tool calls the functions that already existed. Nothing changes in the backend.

Remove the unused tools in a separate change, so you can revert one without the other.

Update the eval cases that referred to the old tools by name. Say after the merge, the completion rate drops, because the old eval still calls get account with a user id. Don't accept both parameter names, to keep the eval green. That brings the ambiguity right back. The eval is what's stale. Fix the dataset first, then compare.

And measure again. Completion the same or higher, fewer steps, fewer wrong calls, and fewer input tokens per call.

Risks

A few risks. A tool too big. Merging different things into one tool with ten optional parameters recreates the confusion inside it. If the parameters depend on each other, like if the action is refund, the amount is required, that's two tools.

A rare flow broken. The export tool had zero calls in ninety days. Then the data team says they use it at quarter close, which fell outside the window. Zero calls in the window doesn't prove it's unused. Confirm with the flow's owner, keep the removal reversible, and if it goes, take it out in its own change.

Changed semantics. If version two returned fields version one didn't, the merged tool must return them. Otherwise you simplified by deleting data.

And mixed permissions. Never merge a read tool with a write tool, even when they share a key. Getting an invoice and issuing a refund both take an order id. Merging them leaves the model one guess away from sending money, when it only wanted to see the invoice.

Practice

Let's practice on an HR agent. Four tools. Get vacation balance. Vacation days left. Check paid time off. And request vacation. One of them shouldn't be merged with the others. Which one?

The first three answer the same question, and become one read tool. Get the vacation balance, by employee id or by email. Use it before suggesting dates.

And request vacation has a side effect. It stays separate, ideally behind a confirmation step from the employee. Its description says it only creates a request for the manager's approval, only after the employee confirms the dates, and approves nothing on its own.

Wrap-up

So here's the idea to take with you. Count what's really used, merge what answers the same question, and keep side effects in tools of their own. Build on the code you already have, remove in separate steps, and let the eval prove the model now picks right the first time.

In the next lesson, we'll handle what's left when the list is still long, because the agent really covers many topics: the tool router. See you there.