The Fix Was Not Fewer Tools. It Was Less Text

In the previous article, I explained how we tried four times to hide tools from our agent, and how showing all of them was worse. Both instincts were answering the wrong question. We were asking which tools the model should see. The better question was what actually has to travel with each tool.

Where the weight really was

A tool definition has two very different parts. There is what the model needs to choose the tool: a name and a line saying when to use it. And there is what it needs to use the tool correctly: every parameter, every format, every exception, every warning.

The second part was the heavy one, and we were sending it for every tool, on every turn, including the ones the model would never touch.

The two-step manual

So we split them. Every permitted tool stays visible as a short card. Tools with a long manual show only their intent fields. The first call returns the manual and does nothing. The second call acts, through the same gate as everything else.

The idea had already worked on one tool in September, where a description went from 7,334 to 2,037 characters. In October we applied it across the board. For our reference composition, the payload went from 108,300 characters to 30,732.

Nothing is hidden. The only thing that removes a tool now is a right: the person's, the agent's or the audience's.

What it costs

I do not want to present this as a clean victory, because it is not one.

Each manual costs a round trip, around five seconds. On the tool that edits a process, a real test showed three exchanges of 15 to 21 tool calls each, and nothing modified. The first step was doing harm there, so we removed it for that tool: it now acts as soon as the call carries a change.

The lesson is that this pattern is a default, and each heavy tool has to earn it through measurement.

Where this is going

There is a further step, and it is the shape model providers now recommend for agents with many tools: a dozen clear actions always present, with everything else grouped into families per connected system, found through native tool search. That is the direction we chose in November, and the same rule applies. It has to beat the current version on real requests before it replaces anything.

Lessons

1. Separate what the model needs to choose a tool from what it needs to use it.
2. Shrink the description before you remove the tool.
3. Only a real permission should take a tool away.
4. Every extra step has a price in latency. Measure it per tool.