Skip to content

CONCEPT Cited by 2 sources

Progressive capability disclosure

Definition

Progressive capability disclosure is the design principle that an agent (or any consumer) should discover a system's capabilities incrementally, at the moment they are needed, rather than being handed the entire capability surface up-front in its context window.

The canonical CLI shape: the agent starts knowing the root command (sprite, flyctl, kubectl, gh) and a short prose hint about what the tool is for; it discovers subcommands by running sprite --help, further subcommands by sprite checkpoint --help, and specific flags by sprite checkpoint create --help. Each exploration step adds capability to the agent's working memory only if needed.

Thomas Ptacek, Fly.io, 2026-03-10:

"CLI-driven agent skills are efficient because they reveal capabilities progressively. You can do CLI subcommands, like sprite checkpoint and sprite exec, or with API endpoints and subpaths. Good agent harnesses are uncanny at quickly working out how to use these things."

(Source: sources/2026-03-10-flyio-unfortunately-sprites-now-speak-mcp.)

The alternative: up-front disclosure

The default MCP shape is the opposite: all tools and their parameter schemas sit in the agent's context from session start, whether the agent uses them or not. Tool descriptions for features the user doesn't need still consume token budget and — worse — signal importance-weighting to the model (see concepts/context-as-importance-signal).

Ptacek's framing: "When we plug an MCP into your agent, we're filling its context with tool descriptions, many of which you'll probably never use. Really, all your agent should need is a short sentence, like 'Use this skill whenever users want to create a new VM to run a task on, or to manage the VMs already available.' The skill should take care of the rest."

The "short sentence" plus a discoverable CLI is the minimal input to the agent. Everything else is discovered on demand.

Three disclosure surfaces

Progressive capability disclosure maps onto three concrete surfaces:

  1. CLI subcommand tree. root --help lists top-level subcommands. Each subcommand has its own --help. The agent walks the tree as far as its task requires. Canonical instances: flyctl, sprite, kubectl, gh, aws.
  2. API endpoint sub-paths. /api/v1/sprites lists Sprites; /api/v1/sprites/{id}/checkpoints lists checkpoints for a Sprite. The URL structure itself encodes discoverability — the agent can follow sub-paths as needed. (Ptacek gestures at this as a co-equal approach: "CLI subcommands, like sprite checkpoint and sprite exec, or with API endpoints and subpaths.")
  3. --help output as documentation. Agent harnesses (Claude Code, Codex, Gemini CLI) treat --help as runnable documentation. Good --help output (consistent flag naming, structured examples, JSON-output flag noted) is load-bearing — see concepts/agent-ergonomic-cli.

Distinct from but composes with agent-skills

concepts/agent-skills-discovery (Cloudflare's .well-known/agent-skills/index.json proposal) is an index-level discovery mechanism: the agent learns a site offers N skill documents and which one applies to which task. Progressive capability disclosure is the within-skill navigation strategy: given that the agent has picked a skill, it discovers the specific operations via subcommand / sub-path exploration, not by pre-loading the whole operation list.

The two compose: well-known URLs tell the agent this CLI exists for these tasks; progressive disclosure tells the agent how to use this CLI.

Why "good agent harnesses are uncanny at this"

Ptacek's empirical claim (unsourced but load-bearing to the post's thesis): Claude Code / Codex / Gemini CLI are already adept at exploring CLI trees. They will call --help, extract subcommands, call deeper --help, and converge on the correct invocation — without the flag listing being pre-loaded into their context.

This is the structural reason the thesis survives. Progressive capability disclosure is only viable if the agent-side cost of exploration is low. Empirically, at 2026-Q1 LLM capability, it is.

See concepts/agent-ergonomic-cli for the correlate claim — when CLI conventions are consistent, the agent's exploration is more uncanny because the inference "if X has a verb create, Y probably does too" is reliable.

Why it matters for context-window cost

Tool descriptions for N operations consume O(N) tokens up-front. Progressive capability disclosure consumes O(depth × breadth-at-walk) tokens — and only for operations actually used. For large capability surfaces (Cloudflare's ~3,000 operations, AWS's ~thousands, Kubernetes's hundreds), the difference is order-of-magnitude.

Cloudflare's Code Mode is a different answer to the same problem (fit ~3,000 ops into <1,000 tokens via code synthesis instead of tool listing). Progressive capability disclosure + CLI is the Fly-sized (hundreds of ops) answer; Code Mode is the Cloudflare-sized (thousands of ops) answer. Both beat flat tool-listing.

Why it matters for attention weighting

Tool descriptions in context signal importance, not just availability. If the agent sees a sprite network policy tool in its tool list from session start, it may decide network policies are relevant to the current task even when they are not. Progressive disclosure avoids this: sprite network policy isn't loaded unless the task walks toward it.

Canonical instance shapes

Surface Instance Context at start
CLI subcommand systems/fly-flyctl, systems/cf-cli, sprite, kubectl One sentence + binary name
API sub-path REST/HATEOAS-style, /api/v1/… Root URL + one sentence
MCP Server Card concepts/mcp-server-card pre-connect metadata Short server description + no tools loaded
Agent Skills concepts/agent-skills-discovery well-known index Task-description list + no operation schemas

MCP-flat-tool-listing is the anti-instance: all N tools loaded into context from session start.

Limits

  • CLI exists. Progressive disclosure via CLI requires the CLI to exist and be well-designed — good subcommand names, consistent flags, --json everywhere, actionable --help. See concepts/agent-ergonomic-cli for the correlate requirement.
  • Agent has shell access. Progressive disclosure via CLI assumes the agent can run some-cli --help in a subprocess. Agents without shell access (Claude Desktop, older clients) need MCP as the fallback protocol — see patterns/mcp-as-fallback-for-shell-less-agents.
  • Latency. Each exploration step is a round-trip (process exec + stdin/stdout). For latency-sensitive interactive agents, the round-trip cost of multi-step discovery can exceed the token cost of pre-loading.
  • --help quality. A CLI with sparse / broken / inconsistent --help output defeats the approach. This is a common failure mode for CLIs that were designed human-first.

Seen in

Last updated · 319 distilled / 1,201 read