Skip to content
AX Framework
Discovery pattern

Capability Manifest

Publish a single machine-readable document that lists what agents can do with your product.

AX proposalDiscoverability

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.

  1. 01Inventory the tasks agents should be able to perform.
  2. 02Describe each as a capability with typed input and output.
  3. 03Serve the manifest at a stable URL and reference it with a <link> element.
  4. 04Generate it from the same definitions your handlers use.
  5. 05Version the manifest and announce deprecations inside it.

Interaction diagram

Interaction diagram for Capability Manifest. 1. AI agent to Product · AX layer: GET /. 2. Product · AX layer to AI agent: <link rel="ax-manifest">. 3. AI agent to Product · AX layer: GET /ax.json. 4. Product · AX layer to AI agent: capabilities[], version. 5. AI agent to AI agent: Plan using declared capabilities.AI agentProduct · AX layerGET /1<link rel="ax-manifest">2GET /ax.json3capabilities[], version4Plan using declared capabilities
request response internal step

Example implementation

Illustrative example

Examples use a fictional store and illustrative field names. Adapt the shape to your stack; the qualities matter more than the exact format.

ax.jsonjson
{
  "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
    }
  ]
}
app/layout.tsxhtml
<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.

Applies the principles Explicit Capabilities.