Discoverability
Can an agent discover what a product can do?
Capabilities, resources, and entry points are published in a form an agent can find without scraping or guessing.
A human learns what a product can do by looking at it. Menus, buttons, and onboarding reveal capabilities gradually. An agent arriving cold has no such affordances unless the product declares them.
Discoverability is about publishing an honest inventory: what the product does, which actions exist, which resources can be read, and what is required to use each one. When this inventory is missing, agents fall back to crawling pages and inferring intent from markup, which is slow, expensive, and frequently wrong.
Good discoverability does not mean exposing everything. It means that whatever is intended for agents is findable from a predictable location and described in a way that lets an agent decide whether it is relevant before spending effort on it.
What good looks like
Signals
- A capability manifest is published at a predictable, linkable location.
- Every action lists its purpose, inputs, outputs, and required permissions.
- Resources (products, documents, records) have stable identifiers and canonical URLs.
- Human pages link to their machine-readable equivalents, and vice versa.
- Capabilities are versioned so agents can detect change.
Anti-patterns
- Capabilities that exist only as visual buttons with no semantic description.
- Undocumented endpoints that agents learn about by inspecting network traffic.
- Manifests that list actions the product no longer supports.
- Discovery that requires authentication before an agent can learn what is possible.
Evaluation checks
Use these questions when reviewing a task. They feed the AX evaluation.
- D1Is there a single, documented entry point that lists agent-facing capabilities?
- D2Does each capability state its purpose in one unambiguous sentence?
- D3Can an agent tell which capabilities need authentication before attempting them?
- D4Are capabilities versioned, with deprecations announced in-band?