Capability Discovery: How AI Should Explain What It Can Do Before It Acts
Capability discovery should teach users what an agent can and cannot do through progressive, contextual demonstrations rather than vague claims of intelligence or giant tool catalogs.
Users cannot form a strategy around invisible capabilities
Microsoft’s HAX guidance begins with a simple requirement: make clear what the AI system can do. [1] This becomes harder with agents because capability is no longer a fixed menu. Available actions depend on connected tools, permissions, account state, runtime environment, and sometimes dynamic tool search. A motivational assistant that can create focus blocks today but loses calendar authorization tomorrow has a changing action surface. Capability discovery must therefore be treated as live product state, not a one-time onboarding slide.
Discovery is part of agency
Users can delegate intelligently only when they know which actions are available and which remain theirs to perform.
Capability and reliability should be communicated separately
HAX also recommends making clear how well a system can do what it can do, because users otherwise over- or under-estimate performance. [2] “I can plan a workout” and “I can reliably infer whether this plan is medically appropriate” are very different claims. “I can create calendar events” and “I can always resolve scheduling conflicts correctly” are different too. Capability discovery should therefore pair verbs with meaningful limits, especially where the system may be uncertain, dependent on third-party data, or subject to external service failure.
Dynamic tool search makes progressive discovery possible
Anthropic’s advanced tool-use work describes tool search as a way to find relevant capabilities without loading an entire tool catalog into context. [3] Product design can mirror that behavior. Instead of confronting users with fifty integrations, reveal capabilities in response to intent: after a goal is defined, show that the agent can create tasks; when scheduling friction appears, offer calendar connection; when a review begins, offer evidence retrieval. This keeps capability discovery close to the job the user is trying to accomplish.
Progressive disclosure reduces both cognitive and model clutter
The best time to explain a tool is often when the user can immediately understand why it matters.
Examples teach capabilities better than abstract feature labels
“Agentic productivity” is not a meaningful affordance. “Find two free 45-minute blocks this week and propose them before adding anything” is. Capability interfaces should show representative requests, outputs, and side effects. This helps users learn the boundary between asking for information, asking for a draft, and asking the agent to modify an external system. Examples also reveal hidden prerequisites such as a connection or permission that would otherwise surface only after a failed attempt.
The catalog should avoid overlapping verbs
Anthropic’s tool-design guidance warns that too many overlapping tools can confuse agents and make selection less efficient. [4] The same is true for users. If an assistant exposes “plan,” “organize,” “schedule,” “arrange,” and “manage” without clear distinctions, people cannot predict consequences. Capability discovery should cluster related actions and use consistent language for read, draft, propose, execute, and delete. That vocabulary becomes part of the motivational system’s rules and makes progression feel fairer because users understand what each action actually means.
Name actions by consequence
“Draft message” and “send message” should never be visually or linguistically interchangeable.
Connected state should be visible in the moment
A capability can exist in theory but be unavailable now because a service is disconnected, a permission is missing, or the environment lacks the required tool. Interfaces should show this state directly and offer the smallest remedy. A user should not have to discover after several planning steps that the agent cannot perform the promised action. When capability disappears, the product should gracefully downgrade to a manual instruction or draft rather than pretending it still has execution authority.
Discovery metrics should measure useful understanding, not clicks
OpenAI’s current tools guidance includes function tools, MCP, skills, computer use, and dynamic tool search within one capability landscape. [5] A product team could easily optimize discovery for connection rate or tool usage. A better metric is whether users correctly predict what will happen when they ask for an action. Can they distinguish a tool that reads from one that writes? Do they know which account is affected? Do they understand whether approval will be requested? Comprehension is a more durable foundation for trust than raw feature activation.
The user’s mental model is the real interface
Capability discovery succeeds when users can anticipate outcomes without reading developer documentation.
Good capability discovery expands confidence without exaggerating intelligence
The goal is calibrated trust. The agent should neither hide useful power nor advertise itself as universally capable. Contextual examples, explicit limits, connected-state indicators, action labels, and clear failure messages let users build an accurate map of what the system can do right now. In a gamified product, that map is analogous to learning the available moves in a game: users become more willing to pursue ambitious goals because the rules are understandable. Confidence comes from legibility, not from magical framing. The strongest discovery interfaces also let users test a capability safely before depending on it. A sandboxed preview, simulated action, or read-only demonstration can reveal what inputs the agent needs and what output it produces without creating side effects. This is especially useful during onboarding because users learn from consequence-free experiments rather than marketing language. The product can then introduce write access only after the user understands the corresponding read or preview behavior, creating a graduated path from curiosity to confident delegation.
Works Cited
- 01
- 02
- 03Anthropic — Introducing Advanced Tool Use anthropic.com
- 04Anthropic — Writing Effective Tools for Agents anthropic.com
- 05OpenAI Developers — Using Tools developers.openai.com
CodeHistory is a living archive. Citations document the evidence used for this edition; later evidence may refine the account.