---

name: progressive-disclosure-mcp description: Use when an MCP server (or any tool surface an agent reads) exposes a collection whose items are too big to dump at once - skills, files, docs, records, design systems. Teaches the three-tier lean index -> manifest -> item pattern so an agent spends context only on what it opens, plus how to name the tiers, shape each payload, and decide when to collapse the middle tier.

Progressive Disclosure for MCP Surfaces

An agent pays for every token a tool returns. A tool that lists ten skills by dumping all ten SKILL.md bodies burns the context budget before the agent has decided which one it needs. Progressive disclosure fixes this: the agent walks from a cheap overview down to exactly one item's contents, and never loads what it did not ask for.

This is the house pattern behind a well-built library surface (skills, agents, files, design systems). It generalizes to any MCP server exposing a collection - internal docs, a records table, a catalog.

When to trigger

• You are exposing a collection over MCP where each item is large (a document, a file, a multi-part skill) and an agent will only want one or two.
• Your list_* tool returns so much that a few calls blow the context window.
• You are adding a new library surface and want it to match an existing disclosure contract.
• An agent keeps fetching whole items just to find the right one, then discards most of what it loaded.

The three tiers

1. Lean index (list_<plural>): id/slug plus a one-line descriptor per item. No contents. This is the map. It must stay small enough that listing the whole collection costs little.
2. Overview + manifest (get_<singular>): one item's summary (for a skill, the SKILL.md body) plus a file/section manifest - each part's path and a one-line purpose, still no part contents. The agent reads this to decide which parts are worth pulling.
3. Item / part (get_<singular>_<part>): the actual contents of ONE part, fetched on demand.

The purpose line in the manifest is load-bearing: it is the only signal the agent has to decide whether a part is worth its tokens. Write it as "what this covers and when to pull it," not a title. See reference/tiers.md.

Core rules

• Index tools are list_<plural>; item tools are get_<singular>. Keep the naming symmetric so an agent can predict the next call. See reference/naming.md.
• The lean index carries NO contents - only enough to choose. If a field would tempt the agent to skip get_*, it does not belong in the index.
• Every manifest entry needs a one-line purpose. No purpose means the agent fetches blind.
• Collapse the middle tier when the item IS the unit (a single file, a short note). A two-tier list/get is correct there; do not add ceremony. See reference/collapsing.md.
• Cap and paginate item payloads. A textual item over the byte cap returns a truncation sidecar ({bytes, truncated, maxBytes, url}); a binary returns a durable URL, not bytes.
• Cross-reference sibling lenses. If two tools view the same data differently (a lean lens and a with-URLs lens), each description should point at the other so the agent picks correctly.

Build sequence

1. Inventory the collection: how big is one item, how many parts does it have, will an agent want one or many? This decides two-tier vs three-tier.
2. Design the lean index payload - the minimum fields to choose an item. See reference/tiers.md.
3. Design the manifest: overview body plus parts with purposes. Skip if collapsing.
4. Design the item tier: caps, truncation sidecar, binary-as-URL. See reference/tiers.md.
5. Write descriptions as prompt engineering so the model walks the tiers in order. See reference/naming.md.

Reference files

• reference/tiers.md - the payload shape for each tier, byte caps, truncation and binary handling, worked examples.
• reference/naming.md - naming symmetry, descriptions as prompt engineering, cross-referencing sibling lenses.
• reference/collapsing.md - when a two-tier surface is right, and the failure modes of over- and under-disclosing.