Deferred-tool block should carry one-line descriptions, not just names (context-window economy for tool discovery)

Open 💬 0 comments Opened Jul 6, 2026 by fp2s92d5pd-bit

Problem

When many MCP servers are registered, Claude Code presents deferred tools to the model as a name-only list before their schemas are loaded — for example (redacted from a real session with 23 registered MCP servers):

mcp__blender__download_polyhaven_asset
mcp__blender__download_sketchfab_model
mcp__blender__execute_blender_code
...
mcp__codebase-memory__delete_project
mcp__codebase-memory__detect_changes
...
mcp__dynamic-model-quality__list_live_training_quality_resources

For a large registry this is hundreds of lines. The model has no way to know that mcp__codebase-memory__query_graph is a code-graph query or that mcp__davinci-resolve__timeline_ai is video timeline scripting without invoking ToolSearch to load the schema. In practice this means:

  • The model can't pick which tools to load without knowing what they do
  • Loading them all defeats the point of deferral
  • Keyword-search on tool names only works when the model already knows the domain-specific vocabulary

Proposed direction

Add one-line descriptions to the deferred-tool block so the model can triage before schema-load:

mcp__codebase-memory__query_graph  — Query the code graph by pattern
mcp__codebase-memory__search_code  — Full-text search over indexed source
mcp__davinci-resolve__timeline_ai  — Scripting entry for the DaVinci timeline AI

Two implementation notes:

  1. The 2026-07-28 MCP RC's server/discover returns capability advertisements per server, and the Tasks extension (with tasks/get/update/cancel) formally models pending work. Deferred tools are conceptually the same shape — a description-carrying handle before invocation — so aligning the deferred-tool block with the RC's Tasks-extension framing keeps this a single primitive not two.
  2. Descriptions should be sourced from each tool's own description field in its JSON Schema 2020-12 definition (already standardized in the SDK betas), so servers don't need a separate advertisement mechanism.

Success criteria

  • Deferred-tool block for a registry of N servers stays under a bounded prefix (e.g. one line per tool with a hard cap on line length), not a name-dump
  • The model can meaningfully triage which tools to load without a ToolSearch round-trip on every one
  • Descriptions travel with the tool schema, no separate manifest needed

Related

  • Anthropic memory doc (2026-07-06): code.claude.com/docs/en/memory — establishes that CLAUDE.md is user context, not system prompt, so token economy at cold start matters
  • MCP RC (2026-07-28): blog.modelcontextprotocol.io/posts/2026-07-28-release-candidate/server/discover + Tasks extension + extensions map + ttlMs/cacheScope
  • Anthropic engineering (2026-06-02): claude.com/blog/a-harness-for-every-task-dynamic-workflows-in-claude-code — task-tailored harness pattern; per-turn tool availability is orthogonal to per-turn context tailoring

View original on GitHub ↗