DSH large MCP catalogs and Deferred Tools

DSH Large MCP Catalogs: Deferred Tools & Token Cost

Author
DeepSeekAgent.io Editorial Team
Published
Updated

A large MCP server can expose hundreds of tools at once. Before any tool runs, their names, descriptions, and JSON Schemas may already occupy the model request. In DeepSeek Harness, that affects first-turn tokens, KV Cache reuse, tool selection, and provider compatibility.

An October 2026 community reproduction used an MCP service with 207 tools and roughly 668 KB of schemas. Registered through dsh-mcp-client, its first Headless request reported 249,653 input tokens. This is one environment rather than a universal MCP cost, but it demonstrates the scale of catalog overhead.

Why PTC can still carry a large catalog

PTC lets the model organize tool use as code, but SDK types and documentation still need context. Translating the same capabilities from JSON Schema into TypeScript does not remove their descriptive cost.

The key design choice is when each part of the catalog becomes visible:

send every schema on every baseline request
  → large first turn and prompt prefix

discover on demand
  → retrieve a tool reference
  → expand a small number of schemas
  → execute an ordinary tool call

What the Deferred Tools experiment found

The community reproduction tested the official DeepSeek endpoint and reported several boundaries:

  • server-side tool_search variants returned 422;
  • marking every tool deferred returned 400 because at least one regular tool was required;
  • one regular tool plus 150 large deferred tools reported 166 input tokens, versus 261,938 without the defer flag;
  • a client-side tool_search returning tool_reference succeeded, followed by an ordinary tool_use on the next turn.

On-demand references can dramatically reduce the first request. They also expose an integration gap: API support for a content block does not mean the DSH adapter and MCP client can already map, persist, compact, and replay it.

Three layers DSH must support

  1. Catalog layer: the MCP client marks tools deferred and preserves source and version metadata.
  2. Content layer: the harness understands tool_reference, stores it in Session history, and restores it correctly.
  3. Execution layer: once resolved, the ordinary tool still uses existing approval, permission, and result-truncation rules.

Changing only the outbound tool array is insufficient. Session replay, compaction, model switching, and dynamic tool updates need the same reference semantics.

A catalog gateway available today

The community dsh-capability-catalog project demonstrates a practical compromise. It exposes a small fixed family of tools for capability search, schema description, and proxied calls. The report measured roughly 9.2K tokens on the first request instead of about 249K for the complete catalog.

The tradeoffs are an extra model step, weaker native-call visibility, and a new permission concentration point in the gateway. It is useful for a controlled architecture experiment, not as a way to bypass DSH approvals.

Implementation order

  1. record tool count, schema bytes, and blank first-turn input tokens as a baseline;
  2. split MCP servers by domain and enable only the current task's group;
  3. if using a catalog gateway, expose read-only search and describe before call;
  4. cap result counts and use stable ordering and version identifiers;
  5. test new Session, resume, compaction, model switching, and plugin reload;
  6. measure success rate, added turns, input tokens, and cache hits together.

For prompt-prefix behavior, continue with DSH dynamic tools and KV Cache. If a live tool change has already made an old Session return 400, use the dynamic-tool update recovery guide.

References