[DOCS] MCP docs do not mention the 2KB cap on tool descriptions and server instructions

Documentation Type

Missing documentation (feature not documented)

Documentation Location

https://code.claude.com/docs/en/mcp#scale-with-mcp-tool-search

Section/Topic

"Scale with MCP Tool Search" → "For MCP server authors"

Current Documentation

The docs currently say:

When you have many MCP servers configured, tool definitions can consume a significant portion of your context window. MCP Tool Search solves this by dynamically loading tools on-demand instead of preloading all of them.

If you're building an MCP server, the server instructions field becomes more useful with Tool Search enabled. Server instructions help Claude understand when to search for your tools, similar to how skills work.

Add clear, descriptive server instructions that explain: What category of tasks your tools handle When Claude should search for your tools * Key capabilities your server provides

Related context-usage guidance on the costs page says:

Each MCP server adds tool definitions to your context, even when idle. Run /context to see what's consuming space.

Tool search is automatic: When MCP tool descriptions exceed 10% of your context window, Claude Code automatically defers them and loads tools on-demand via tool search.

No documentation currently explains that Claude Code caps MCP tool descriptions and server instructions at 2KB.

What's Wrong or Missing?

Claude Code v2.1.84 added a hard cap: MCP tool descriptions and server instructions are now limited to 2KB to prevent OpenAPI-generated servers from bloating context.

The current docs explain that MCP metadata consumes context and advise authors to write clear server instructions, but they do not tell users or MCP server authors:

1. that Claude Code truncates individual MCP tool descriptions and server instructions at 2KB,
2. that this limit exists specifically to keep verbose/OpenAPI-generated servers from flooding context, or
3. that important guidance should be front-loaded because content beyond the first 2KB will not reach the model.

Without this information, authors may keep expanding descriptions/instructions expecting better behavior, while Claude Code is silently capping what is actually sent.

Suggested Improvement

Add a note in the MCP page near the Tool Search/server-author guidance that explains the limit explicitly. Suggested wording:

Claude Code caps each MCP tool description and the server instructions field at 2 KB. Longer descriptions or instructions are truncated before being sent to the model to prevent verbose servers (including OpenAPI-generated servers) from consuming excessive context.

Also add brief practical guidance:

• put the most important usage and discovery information near the start of the description,
• keep server instructions concise and task-oriented, and
• expect very long autogenerated metadata to be truncated.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

| Page | Context |
|------|---------|
| https://code.claude.com/docs/en/mcp | Documents Tool Search, context pressure, and server instructions for MCP server authors, but not the new 2KB cap |
| https://code.claude.com/docs/en/costs | Documents MCP tool-description context overhead and Tool Search activation, but not the per-description/per-instructions cap |

Total scope: 2 pages affected

Source: Changelog v2.1.84

Exact changelog entry:

MCP tool descriptions and server instructions are now capped at 2KB to prevent OpenAPI-generated servers from bloating context