The tool catalogue is a subscription.
August 16, 2026
Tool catalogues grow the way permissions grow. Someone adds a browser tool, someone adds a database tool, someone adds five terminal operations, and a year later every agent in the estate is offered forty tools whether it needs them or not. This is usually raised as a safety concern. It is also a recurring charge, and one of the few AI cost levers that requires no negotiation with a vendor.
Why the catalogue is billed repeatedly
Tool definitions are not configuration that lives on a server somewhere. They are part of the request. DeepSeek Harness makes this visible by recording, as an event, the exact configuration, system prompt, and tool set that went out with each request. The tool set is re-transmitted on every model call in the session.
So the arithmetic is: tool catalogue size, times steps per session, times sessions. For a busy agent estate that is not a rounding error, and unlike most cost levers it can be pulled without changing model, vendor, or behaviour.
The second effect is larger than the first
A wide catalogue widens the model's choice space. More options means more plausible-but-wrong selections, and since a step is one model call plus its tools, every wrong selection costs a whole step — not a fraction of one.
This is why trimming the tool surface tends to outperform the token arithmetic that motivated it. You reduce the fixed charge and the error rate at the same time.
How per-agent scoping works
| Mechanism | What it does |
|---|---|
| Restriction | Filters the global tool set for one agent, by intersection |
| Scoped registration | Adds agent-specific tools after filtering, bound to that agent's lifetime |
| Shadowing | Replaces a same-named global tool within one scope only |
| Setup window | The creation slot where all of this is composed, before the first prompt |
The ordering is what makes least privilege practical. You start from an intersection with the global set — never more than global — and then add exactly what this agent needs. Shadowing covers the substitution case without forking anything: a read-only variant, a metered variant, or a cheaper backend can sit behind a familiar name for one agent while everyone else sees the original.
Children should not inherit the parent's tools
The harness treats lineage — who spawned whom, and how deep — as data that does not by itself affect what an agent can see. Access is composed deliberately for each child rather than inherited.
That distinction is where a lot of avoidable spend lives. Inherited-by-default privilege is how a cheap summarisation subagent ends up carrying the same forty-tool catalogue as the orchestrator that created it, paying the full fixed charge on every one of its own steps to do a job that needed two tools.
Four things to do this quarter
- Count the tokens in your tool definitions and multiply by steps per session. That number is your recurring tool charge, and most teams have never seen it.
- Define a minimum tool set per agent role and enforce it as a restriction rather than a convention.
- Substitute rather than remove where a capability is occasionally needed - a cheaper or read-only variant behind the same name.
- Audit what subagents inherit. If children get the parent's catalogue by default, that is the largest single item on this list.
Related
- Budget enforcement belongs inside the agent loop
- DeepSeek Harness and the real cost of delegation
- Prompt caching explained
- Reasoning token cost allocation
FAQ
Why do agent tool definitions cost money?
Because they are part of the request. The tool set is sent to the model on every request in the session, so a large catalogue is a fixed token charge repeated on every step rather than a one-time setup cost.
How does DeepSeek Harness scope tools per agent?
Through scopes. A restriction filters the global tool set for one agent by intersection, and scope-local registrations merge in afterwards. Scoped registrations are bound to that agent's lifetime, so they cannot leak into the parent.
What is shadowing?
Shadowing lets a scoped item replace a same-named global counterpart within that scope alone. One agent can be given a read-only or cheaper implementation behind a familiar tool name while every other agent continues to see the global version.
Does a smaller tool set only save tokens?
No. A wide catalogue also widens the model's choice space, which raises the rate of plausible-but-wrong tool selections. Since a step is the billing unit, each wrong selection costs a full step. Trimming the surface reduces the token floor and the error rate together.