Proposal: Progressive disclosure pattern for MCP tool schemas to reduce token overhead

[nafey7]

Pre-submission Checklist

• I have verified this would not be more appropriate as a feature request in a specific repository
• I have searched existing discussions to avoid duplicates

Your Idea

Proposal: Native Progressive Disclosure for MCP Tool Discovery

I would like to propose adding native support for progressive disclosure in MCP tool discovery.

The core idea is that MCP clients should not always need to load every tool's full description, schema, examples, and metadata into the model context upfront. Instead, MCP could support a layered discovery flow where the client first receives a lightweight tool directory and only fetches the full schema or details for a tool when it is likely to be used.

High-Level Flow

At a high level, this would look like:

1. Client fetches lightweight tool summaries.
2. Model selects the most relevant tool or tool category.
3. Client fetches the full schema/details only for selected tools.
4. Model generates validated tool arguments.
5. Client executes the tool.

This would make MCP more scalable when an agent has access to many tools or multiple MCP servers.

Problem

As MCP usage grows, agents may be connected to many servers and many tools at the same time. In the current discovery pattern, clients often need to expose a large amount of tool metadata to the model, including names, descriptions, and input schemas.

This can create a few problems.

1. Context and Token Overhead

If a server exposes dozens or hundreds of tools, the model context can become overloaded with tool definitions that may not be relevant to the user's current request.

For example, a travel assistant may have tools like:

• search_flights
• book_flight
• cancel_flight
• search_hotels
• book_hotel
• cancel_hotel
• create_itinerary
• check_visa_requirements
• get_weather
• convert_currency

For a simple request like "find hotels in Dubai," the model likely does not need the full schema for flight booking, flight cancellation, itinerary generation, currency conversion, and other unrelated tools.

2. Tool Selection Noise

When the model sees too many detailed tool definitions at once, tool selection can become harder. The model has to reason over many schemas and descriptions even when only a small subset is relevant.

A smaller first-stage tool index could make routing cleaner.

3. Poor Scalability for Multi-Server Setups

A single MCP server with 5-10 tools may be manageable. But a production agent may connect to many MCP servers across areas like CRM, email, calendar, database, billing, analytics, support, search, and internal APIs.

Without progressive disclosure, the tool context can grow quickly.

4. Repeated Schema Loading

Many tool schemas are stable and do not need to be repeatedly injected into the model context unless the tool is actually being used.

Proposed Idea

MCP could support a native layered tool discovery mechanism.

Instead of only exposing full tool definitions, servers could optionally expose lightweight summaries first.

For example:

{
  "name": "search_flights",
  "summary": "Search available flights by route, date, cabin, and passengers.",
  "category": "travel.flight.search",
  "risk": "read_only",
  "schema_ref": "mcp://tools/search_flights/schema"
}

Then, if the model/client determines that search_flights is relevant, the client can fetch the full contract:

{
  "name": "search_flights",
  "description": "Search available flights using origin, destination, departure date, return date, cabin class, and passenger count.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "origin": { "type": "string" },
      "destination": { "type": "string" },
      "departure_date": { "type": "string", "format": "date" },
      "return_date": { "type": "string", "format": "date" },
      "passengers": { "type": "integer" }
    },
    "required": ["origin", "destination", "departure_date", "passengers"]
  }
}

This would allow clients to keep the initial context small while still preserving full schema accuracy before execution.

What Problem This Solves

This would help solve:

• High context usage caused by exposing all tool schemas upfront.
• Tool overload when many MCP servers are connected.
• Reduced model focus caused by irrelevant tool definitions.
• Scaling issues for agents with dozens or hundreds of available tools.
• Repeated prompt bloat from stable tool schemas that are only occasionally needed.
• Manual workaround patterns, where developers build custom MCP gateways or tool directories outside the protocol.

Who Would Benefit

1. MCP Client Developers

Client developers could build more efficient agents by fetching only the tool information needed for the current request.

2. MCP Server Developers

Server developers could expose large tool surfaces without forcing every client to load every schema upfront.

3. Agent Framework Builders

Frameworks could build better routing, dynamic tool loading, and multi-step planning flows on top of a standard MCP mechanism.

4. Users of Tool-Heavy Agents

End users would benefit from faster, more focused agents that are less likely to be distracted by irrelevant tools.

5. Enterprise and Internal API Teams

Organizations with large internal API surfaces could expose many tools through MCP without making the model context unmanageably large.

Possible High-Level Implementation

This could be implemented as an optional capability, so existing MCP servers and clients remain compatible.

Possible additions could include:

• tools/list_summaries
• tools/get_schema
• tools/get_details
• tools/search

Or the existing tools/list response could support different detail levels:

{
  "detailLevel": "summary"
}

Then clients could request:

• summary: small tool directory
• schema: exact input/output schema
• details: examples, constraints, usage notes

A possible flow:

User request
   |
   v
Client asks MCP server for lightweight tool summaries
   |
   v
Model/client selects likely tool candidates
   |
   v
Client fetches full schemas only for selected tools
   |
   v
Model prepares arguments
   |
   v
Client validates and executes tool

To prevent sync issues, each tool summary could also include:

{
  "name": "search_flights",
  "schema_hash": "abc123",
  "version": "1.2.0",
  "last_updated": "2026-06-05T00:00:00Z"
}

This would allow clients to cache summaries and schemas safely while refreshing them when tools change.

Why This Should Be Native to MCP

Developers can already create custom gateways, markdown tool directories, or vector-search-based tool routers around MCP. However, if every team solves this independently, the ecosystem may end up with many incompatible patterns.

Having progressive disclosure as a native MCP capability would provide a standard way to scale tool discovery while preserving the current strengths of MCP.

The goal is not to replace existing tool discovery. The goal is to make tool discovery more scalable for large real-world agent systems.

Closing Thought

MCP is already a strong protocol for connecting models to tools and external systems. Adding native progressive disclosure would make it easier to use MCP in larger, production-grade environments where agents may have access to many tools across many servers.

I would love to hear whether this is already being discussed, whether it fits the direction of the protocol, or whether there are existing design considerations around this.

Scope

• Protocol Specification
• SDK Features
• Documentation
• Developer Experience
• Other

[mnifzied-create]

Strong +1 on the framing — here's measured data to ground it, since the case for progressive disclosure gets a lot more concrete once you see the actual distribution of tool-schema cost. I measured 13 real open-source MCP servers + agents (79 tools) through one tokenizer (writeup; I posted a fuller cross-server version in the spec discussion #2812). The parts that bear on this proposal specifically:

1. The overhead is real and stacks across servers — exactly the regime this targets. Per-turn, schema-only: GitHub MCP 3,546 tok (26 tools), GitLab 1,194 (9), Slack 679 (8). Attach those three and you re-send ~5,400 tokens every turn before the user types anything — and for a request like your "find hotels in Dubai" example, almost all of it is irrelevant. The value of progressive disclosure is highest precisely in this multi-server, many-tool case.

2. The distribution is long-tailed, which is what makes a directory-first flow high-leverage. Median server overhead is only ~547 tok, but the tail is heavy: the single fattest tool I measured — sequentialthinking from the official servers repo — is 827 tokens by itself, larger than the entire toolset of 8 of the 12 multi-tool servers in the set. So "fetch full schema on demand" captures outsized savings from a small number of fat tools/servers — you don't need everything lazy-loaded to win, just the heavy tail.

3. One design caution + a complementary, zero-protocol-cost win. The summary→fetch-on-selection flow trades tokens for (a) an extra round-trip and (b) the tension that descriptions are what make tool selection accurate — so the first-stage lightweight summary has to carry enough disambiguation signal, or you trade token cost for wrong-tool selection (this came up in #2812 as well). Worth pairing it with a lever that needs no spec change: a meaningful slice of current overhead is non-semantic serialization cruft — pretty-printing alone swings a tool ~20% (Fetch MCP: 236 tok compact vs 288 pretty), Pydantic auto-adds a title to every field, zod-to-json-schema appends $schema/additionalProperties. Stripping that costs zero disambiguation signal and helps whether or not progressive disclosure lands — so it's a sensible baseline to assume before measuring this proposal's incremental gain.

(Tokenizer caveat: counts are o200k_base as a consistent Claude estimate, applied identically to all 13, so the relative shape is robust; absolute Claude numbers differ a few %.)