Why it matters
Tool catalogues, skill libraries and document sets grow faster than a context budget. Sending everything makes the prompt expensive and makes selection harder, because similar descriptions compete. Progressive disclosure separates the index from the content: the model sees names and one-line descriptions, chooses, and then receives the full definition. The engineering problem is writing an index precise enough to choose from without duplicating the content it indexes.
Mental model
Progressive disclosure is a table of contents rather than the whole book: you read the chapter you need. The comparison breaks because the model must choose a chapter from titles alone, and a misleading title sends it to the wrong one.
How it works
Tool context · illustrative tokens
2,840 input+ 400 reserve= 3,240 of 3,000
over by 240
Step 1Send everything
The twelve definitions are 2,520 tokens; with instructions and the question the request is 2,840, 240 over the available window. A catalogue of forty would not be close.
Output reserve
4002,840 input + 400 reserve = 3,240 of 3,000. Every definition competes with the answer for the same space.
Pick a section to read its token count, its role and its state.
Figure. Twelve full definitions do not fit: 2,840 tokens against 2,600 available. A 216-token index does, at 8.6% of the catalogue, and each expansion re-sends that index — so the cap on expansions, not the index, decides what a request costs.
What to notice. Counts are authored for a 3,000-token window with a 400-token answer reserve; no tool catalogue was measured and no retrieval was run. Definitions are grouped in the first step and drawn individually once expanded, so the two shapes are comparable but not the same list. Selection accuracy and near-duplicate descriptions are omitted: the figure shows what the index keeps and what each expansion adds.
Text version
A 3,000-token window with a 400-token answer reserve, so 2,600 tokens are available. The default first step sends the whole catalogue: instructions 200, schema groups of 900, 840 and 780 tokens, and the question 120, for 2,840 tokens — 240 over the window, with the cells crossing the cap rule. The second step sends the index of twelve one-line descriptions instead: 216 tokens, for 536 input tokens and 2,064 free. The third step expands two entries, adding 260 and 240 tokens for 1,036 input tokens and 1,564 free. The fourth step has a switch labelled Expansion cap, off by default: with the cap off it loads seven definitions for 2,676 tokens, 76 over the window, and capped at two expansions it shows 1,036 tokens. Selecting a section shows its count and role.
- Write a one-line description for each tool, skill or document, focused on when to use it rather than what it contains.
- Load the index into the context and keep the full definitions outside it.
- Let the model request an entry, then inject the full content as a separate turn or tool result.
- Cap how many entries can be expanded per request, so a confused model cannot load everything.
- Test selection accuracy on requests that map to each entry, including near-duplicates.
- Keep descriptions stable, since changing them changes selection behaviour.
Trade-offs
| Choice | Good for | Cost | Fails when |
|---|---|---|---|
| Full catalogue in context | No lookup step, complete information | Large prompt and harder selection | The catalogue exceeds a few dozen entries |
| Index plus lookup | Small working context | Extra turn and latency | The model cannot judge from descriptions |
| Hierarchical index | Scales to large libraries | More navigation steps and wrong turns | The task needs a specific detail quickly |
| Fixed shortlist | Predictable and cheap | Misses the entry the task needed | Requests span the whole catalogue |
Good for
No lookup step, complete information
Cost
Large prompt and harder selection
Fails when
The catalogue exceeds a few dozen entries
- The catalogue exceeds a few dozen entries
- The model cannot judge from descriptions
- The task needs a specific detail quickly
- Requests span the whole catalogue
Figure. Each choice with what it buys, what it costs, and the case where it loses.
What to notice. The fourth column is the decision: if the losing case describes your situation, the choice is wrong.
Text version
Four trade-offs: Full catalogue in context is good for No lookup step, complete information, costs Large prompt and harder selection, and fails when The catalogue exceeds a few dozen entries. Index plus lookup is good for Small working context, costs Extra turn and latency, and fails when The model cannot judge from descriptions. Hierarchical index is good for Scales to large libraries, costs More navigation steps and wrong turns, and fails when The task needs a specific detail quickly. Fixed shortlist is good for Predictable and cheap, costs Misses the entry the task needed, and fails when Requests span the whole catalogue
Failure modes
- Index ambiguity. Two entries have similar descriptions and the model picks the wrong one. Debug: label requests per entry and inspect confusion between pairs.
- Expansion loop. The model loads entries repeatedly without acting. Debug: count expansions per request and inspect the returned descriptions.
- Missing detail. The model answers from the one-line description instead of expanding. Debug: check whether answers cite details that only exist in the full content.
In production
Track selection accuracy and expansions per request, and alert when expansion rate jumps, which usually means the index drifted. Keep a fallback that exposes the full catalogue when selection fails repeatedly.
Common misconceptions
People think: Smaller context is always cheaper overall.
Actually: It saves input tokens but can add turns, and each turn resends the conversation.
People think: A good index is a summary.
Actually: It is a selection aid: it should say when to use an entry, not compress its contents.
Interview angle
Explain the index-and-expand loop and what it costs, then say how you would measure whether the index is precise enough. Strong answers mention caps and a fallback. Weak answers describe lazy loading without connecting it to selection accuracy or extra turns.
Sources
- Anthropic, Building effective agents — tool design and keeping the working context small.
- Model Context Protocol — a standard way to expose tools and resources on demand.
- Hsieh et al., RULER — effective context length: more material does not reliably mean more usable context.