Problem
Agents have no reliable way to learn what a product supports. They crawl pages, read help articles, or probe endpoints, and still miss capabilities or invent ones that do not exist.
Context
Use this pattern when:
- Your product has tasks that people would plausibly delegate to an agent: searching, booking, ordering, filing, reporting.
- You already have an API, server actions, or an MCP server, but agents arriving at your website have no pointer to them.
Recommended solution
Publish a capability manifest at a stable, well-known URL and link to it from your HTML head. The manifest lists each capability with a name, a one-sentence purpose, input and output schemas, authentication requirements, and a risk level.
Treat the manifest as a product surface, not an export. Generate it from the same source as your action handlers so it cannot drift, and version it so agents can detect change.
- 01Inventory the tasks agents should be able to perform.
- 02Describe each as a capability with typed input and output.
- 03Serve the manifest at a stable URL and reference it with a <link> element.
- 04Generate it from the same definitions your handlers use.
- 05Version the manifest and announce deprecations inside it.
Interaction diagram
Example implementation
Illustrative exampleExamples use a fictional store and illustrative field names. Adapt the shape to your stack; the qualities matter more than the exact format.
{
"ax": "0.1",
"name": "Northwind Outfitters",
"description": "Outdoor apparel and footwear store shipping within the EU.",
"version": "2026-10-01",
"auth": { "type": "oauth2", "authorizationUrl": "https://northwind.example/oauth/authorize" },
"capabilities": [
{
"name": "search_products",
"description": "Search the catalog by keyword, category, size, and price range.",
"risk": "read",
"auth": "none",
"input": { "$ref": "https://northwind.example/schemas/search.json" }
},
{
"name": "add_to_cart",
"description": "Add a product variant to the active cart.",
"risk": "low",
"auth": "session",
"idempotent": true
},
{
"name": "place_order",
"description": "Place an order for the current cart using a saved payment method.",
"risk": "high",
"auth": "user",
"requiresApproval": true
}
]
}<head>
<link rel="alternate" type="application/json" href="/ax.json" title="Agent capability manifest" />
</head>Accessibility and security
Accessibility
- Write capability descriptions in plain language. They are often relayed verbatim to the person the agent is working for.
- Keep human-facing help pages and the manifest consistent so people and agents learn the same model of the product.
Security
- A manifest describes capabilities; it does not grant them. Enforce authorization on every action regardless of what the manifest says.
- Do not list internal or administrative capabilities in a public manifest.
- Treat agents' claims about the manifest version as untrusted input.
Related patterns
Applies the principles Explicit Capabilities.