Skip to content
AX Framework

Architecture

Capability Discovery

Publishing what your product can do so agents can find it.

An agent arriving at your product needs to answer one question before anything else: what can I do here? Capability discovery is how your product answers it. This page covers where to publish capabilities, what to include, and how to keep the description honest.

AX proposal

Discovery entry points

Agents arrive in different ways, so publish more than one path to the same information:

Entry pointWho uses itWhat to provide
HTML headAgents that browse pagesA link element pointing to the manifest
Well-known pathAgents that know the conventionThe manifest itself, e.g. /ax.json
llms.txtLanguage models reading a site summaryA short Markdown overview that links onward
MCP serverAgents in MCP-capable clientsThe same capabilities as MCP tools
OpenAPI documentAgents and developer tools calling HTTPOperations, schemas, auth

llms.txt is a community proposal and MCP is an open protocol; the /ax.json manifest is an AX Framework proposal. None is required, and none replaces the others.

html
<link rel="alternate" type="application/json" href="/ax.json" title="Agent capability manifest" />
<link rel="alternate" type="text/plain" href="/llms.txt" title="Site summary for language models" />

Manifest anatomy

A manifest is a product-level index. Keep it small enough to read in one request, and link to detailed schemas rather than inlining them.

json
{
  "ax": "0.1",
  "name": "Northwind Outfitters",
  "description": "Outdoor apparel and footwear store shipping within the EU.",
  "version": "2026-10-01",
  "docs": "https://northwind.example/developers",
  "auth": {
    "type": "oauth2",
    "authorizationUrl": "https://northwind.example/oauth/authorize",
    "scopesUrl": "https://northwind.example/oauth/scopes"
  },
  "channels": {
    "http": "https://northwind.example/api/ax",
    "openapi": "https://northwind.example/openapi.json",
    "mcp": "https://northwind.example/mcp"
  },
  "capabilities": [
    {
      "name": "search_products",
      "description": "Search the catalog by keyword, category, size, and price range.",
      "risk": "read",
      "auth": "none",
      "input": "https://northwind.example/schemas/search_products.input.json"
    },
    {
      "name": "place_order",
      "description": "Place an order for the current cart using a saved payment method.",
      "risk": "high",
      "auth": "user",
      "scopes": ["orders:create"],
      "requiresApproval": true,
      "idempotent": true
    }
  ],
  "deprecated": [
    { "name": "checkout", "replacedBy": "place_order", "removalDate": "2027-01-01" }
  ]
}

Field guidance

  • description — one sentence, plain language, written so it can be relayed to a person unchanged.
  • risk — read, low, medium, or high. See the Sensitive Actions pattern.
  • auth — none, session, or user (requires a delegated grant).
  • requiresApproval — tells the agent to expect an approval step before it plans.
  • deprecated — announce removals in-band, with a replacement and a date.

Describing capabilities well

The quality of a description decides whether an agent picks the right capability. Compare:

WeakStrong
"Cart endpoint""Add a product variant to the active cart."
"Process order""Place an order for the current cart using a saved payment method."
"Search""Search the catalog by keyword, category, size, and price range. Returns at most 50 results."

Name capabilities with a verb and an object (start_return, list_orders). Avoid names that only make sense inside your codebase.

Keeping it honest

A manifest that lists capabilities that no longer work is worse than none. Generate it from the same definitions your handlers use, and add a test that every listed capability resolves to a handler.

ts
import { buildManifest } from "@/lib/ax/manifest";
import { handlers } from "@/lib/ax/handlers";

test("every manifest capability has a handler", () => {
  for (const c of buildManifest().capabilities) {
    expect(handlers).toHaveProperty(c.name);
  }
});

Last updated 2026-10-06. AX Framework documentation describes proposals unless a section is marked as an established standard.