DeepSeek Harness dynamic tools and KV Cache
DeepSeek Harness Dynamic Tools & KV Cache: rc.2 Analysis
- Author
- DeepSeekAgent.io Editorial Team
- Published
- Updated
DeepSeek Harness v0.1.7-rc.2 introduces dynamic tool updates. The feature is not about installing more plugins; it addresses what happens when the tool set changes during an Agent run and avoids repeatedly rebuilding the complete tool prefix whenever the provider can represent the change incrementally.
The implementation spans Session history, provider capability declarations, request projection, and the DeepSeek adapter. Following that path makes it easier to understand whether a plugin change preserves the cache and why token cost can shift suddenly.
Why tool changes affect caching
Tool names, descriptions, and JSON Schemas usually live in the request prefix. If every turn carries the full set, adding, removing, or modifying one tool can change that prefix. In a long Session, frequent changes reduce the stable portion a provider can reuse.
Dynamic updates separate the effective tool set from the events that changed it. Definitions already seen by the model remain in history, while additions and removals can be represented as updates before the provider builds its final request.
The DSH implementation path
1. Request headers record effective tools
DSH stores the names of the assembled tools in request/header.tools. This record does not depend on whether the selected model supports native updates, so the Session retains the complete history before any provider-specific projection.
2. The Session derives additions and removals
The loop compares the current names with the previous Header. An addition references the Header that contains its definition; a removal records the missing name. Session.toolHistory() incrementally reduces Headers and Developer Messages into a reusable history snapshot.
3. Providers project their supported mode
The adapter reads the route's toolUpdate capability:
| Mode | Behavior |
|---|---|
| Unsupported | Send the current complete definitions without update events |
addition-only | Preserve additions without projecting native removals |
in-history | Retain additions, removals, and previously seen definitions in history |
The current DeepSeek Flash route declares addition-only. Its adapter converts additions into system-role tool_addition content and attaches the required beta request header when updates exist.
Changes that still break the prefix
Dynamic updates are not a promise that the cache can never be invalidated. DSH may need to rebuild declarations when:
- a tool keeps its name but changes its description or Schema;
- the System Prompt, Profile, or preceding context changes;
- history is incomplete and the defining Header cannot be found;
- the route moves to a provider without update support;
- compaction, migration, or an intermediate gateway changes the prefix.
A same-name Schema change is particularly important: the model's contract has changed even though the registry name has not. DSH must declare the new contract instead of preserving an incorrect cached definition.
How to measure token savings
Do not rely on the Session's total token counter alone. Hold the model, task, initial tools, and prompt constant, then compare:
- a run that adds one tool in the middle; and
- a run that resends the complete tool set every turn.
Record cache-hit input, cache-miss input, latency on the first updated request, and the actual charge. If the provider exposes only aggregate input tokens, that number cannot prove a KV-cache hit; use billing categories or request-level usage fields where available.
Guidance for plugin authors
- Keep tool names, descriptions, and Schemas stable.
- Defer uncommon tools until the task actually needs them.
- Treat a Schema-changing plugin release as a cache boundary and compatibility change.
- Record the turn where tools were added or removed when investigating cost spikes.
- Do not assume the same update mode when switching providers.
Conclusion
Dynamic tool updates in v0.1.7-rc.2 are a projection layer between Session facts and provider request formats. They can reduce unnecessary changes to a stable prefix, but the savings depend on shared-prefix length, Schema stability, provider cache accounting, and task duration. Request-level A/B measurement is more useful than assuming every tool change is free because the route mentions KV caching.
Related reading
- DeepSeek Harness v0.1.7-rc.2 update
- DeepSeek Harness Sub-agent token billing
- Agent loop analysis for DeepSeek V4.1 Flash