Skip to main content

Progressive Disclosure Beyond the Chat Window

· 3 min read
Calvin Cheng
Calvin Cheng
Shape what gets built and the value it creates.

Agents increasingly work with large files, large tool catalogs, and large context. Loading everything upfront wastes tokens, degrades performance, and overwhelms both model and user. Progressive disclosure - revealing detail only when needed - is a design principle that applies to more than traditional UI. It applies to how agents encounter and use information.

The Problem of Bloat​

A 5MB PDF may contain only 10-20KB of relevant text. A catalog of 200 tools may need only 5 for a given task. Loading the full PDF or all tool definitions into context consumes space that could go to actual reasoning. The agent - and the user - pay for relevance they never use.

Progressive disclosure says: start with metadata and structure; load detail on demand.

Files: Metadata First, Content on Demand​

Instead of shoving entire files into context:

  1. Include metadata only: filename, size, type. Enough for the agent to decide what's relevant.
  2. Provide load operations: load_file(id), peek_file(id, start, stop), extract_file(id) for PDFs/DOCX. The agent requests content when it needs it.
  3. Optional preload: For some workflows, preload the first N KB. Configurable; sometimes zero is right.

The agent sees a manifest of available files, chooses what to load, and requests it. Content is pulled, not pushed.

Tools: Hierarchy and Discovery​

Same idea for tools. Instead of dumping 200 tool definitions into the prompt:

  1. Present a hierarchy: e.g., servers/google-drive/, servers/slack/, servers/github/.
  2. Support discovery: list_directory, search_tools, get_tool_definition. The agent explores structure, then fetches full schemas only for tools it will use.
  3. Levels of detail: Name only → name + description → full schema. Escalate as needed.

The agent browses before committing. Most tools never get fully loaded.

Design Implications for Product​

Lazy loading as default. Don't assume "more context is better." Design ingestion pipelines that minimize initial load and maximize on-demand access.

Clear affordances for "load more." The agent needs to know what's available and how to request it. Skills, documentation, and tool design should make the discovery path obvious.

User-facing parallel. Progressive disclosure in agent context mirrors progressive disclosure in UI - don't show everything at once. Consider how the same principle applies when surfacing agent state to users: summaries first, details on demand.

Trade-offs​

Pros: Enables work with assets larger than context; agent controls what to load; scales to hundreds of tools or files.

Cons: Adds round-trips (discovery → load → process); agent may make poor loading decisions without guidance; requires clear structure and naming.

The key is designing for the common case: most of the time, most content isn't needed. Optimize for that. Progressive disclosure turns "overwhelming" into "explorable."