DeepSeek Harness tool scopes: a narrower surface is a cheaper one
Published 16 August 2026
Tool catalogues grow. Someone adds a browser tool, someone adds a database tool, someone adds five terminal operations, and a year later every agent in the system is offered forty tools whether it needs them or not. That is usually discussed as a safety problem. It is also a line item. DeepSeek Harness has a per-agent scoping model that addresses both at once.
Why the catalogue is a recurring cost
Tool definitions are part of the request. The harness records a request header event carrying the configuration, system prompt, and tool set exactly as sent, which makes the point concrete: the catalogue is re-transmitted on every model request in the session, so it is a fixed tax per step rather than a one-time cost.
There is a second, larger effect. A wide catalogue widens the model's choice space. More plausible-but-wrong tool selections mean more steps that produce nothing useful, and steps are the billing unit. Trimming the surface reduces the token floor and the error rate together.
The vocabulary
| Term | Meaning |
|---|---|
| Scope | The unit of per-agent registration for tools, prompts, variables, restrictions, and listeners |
| Scope key | The opaque identity a scope is keyed by, compared by object identity — usually the live agent itself |
| Agent context | The agent's own scoped context, where registrations are lifetime-bound and scope-visible |
| Restriction | A filter over the global tool set for one scope, applied by intersection |
| Shadowing | A scoped item replacing a same-named global counterpart, within that scope alone |
| Setup window | The creation slot where a creator composes an agent's scoped world, before publication or first prompt assembly |
How composition resolves
Restrictions filter the global set first, then scope-local registrations merge in. That ordering is what makes least privilege practical: you start from an intersection with the global catalogue — never more than global — and then add exactly the agent-specific tools this agent needs.
Shadowing gives you the substitution case without a fork. One agent can receive a different implementation behind a familiar tool name — a read-only variant, a metered variant, a cheaper backend — while every other agent continues to see the global one.
Lifetime binding matters for the same reason dispose does. Scoped registrations end with the agent's context, so a short-lived child cannot leak contributions into the parent's world.
Scoped dispatch and lineage
Events about one agent dispatch with that agent's carrier, so a listener can tell whose activity it is observing; registry-level events remain unfiltered. Separately, lineage — parent session, delegation depth, subagent depth — is described explicitly as data that does not itself affect visibility.
That separation is worth borrowing. A child does not inherit access because it is a child; access is composed deliberately in its setup window. Inherited-by-default privilege is how a cheap summarisation subagent ends up holding the same expensive tool set as its parent.
Four things to do with this
- Count your tool definitions and multiply by steps per session. That is your fixed per-session tool tax in tokens.
- Define a minimum viable tool set per agent role, and apply it as a restriction rather than a convention.
- Shadow expensive tools with cheap or read-only variants in low-value contexts instead of removing them entirely.
- Never inherit the parent's tool set into subagents by default. Compose it.
Related
- Where to put spend guardrails in DeepSeek Harness — enforcement at execution time.
- DeepSeek Harness subagents and delegation depth — tool filters at delegation time.
- DeepSeek Harness: what "everything is a plugin" buys you — where tools come from.
- DeepSeek Harness goals and the Ralph loop — bounding open-ended work.
Want this applied to your own LLM spend? FinOps LLM runs a free audit of your AI costs and shows where the savings are. Book free audit →
FAQ
What is a scope in DeepSeek Harness?
A scope is the unit of per-agent registration for contributions such as tools, prompts, variables, restrictions, and listeners. A contribution is either global or scoped to a single agent, and scoped registrations are lifetime-bound to that agent's context.
What is a restriction?
A restriction filters the global tool set for one scope by intersection. Scope-local registrations then merge in after filtering, so an agent can be given a narrow slice of the global tools plus its own additions.
What is shadowing in an agent harness?
Shadowing means a scoped item replaces a same-named global counterpart within that scope alone. Other agents continue to see the global version, so one agent can be given a different implementation of a named tool without affecting anyone else.
Why does the tool surface affect AI cost?
Every tool definition sits in the system prompt and is re-sent on every model request in the session. A large tool catalogue is a fixed per-step token tax, and it also widens the model's choice space, which raises the chance of an expensive wrong call.