The discovery problem
HTML is written for humans: navigation labels, marketing copy, and screenshots. Nothing in a typical homepage reliably tells an automated client that a JSON API exists, which operations it offers, what each one costs, or how access and payment work. Scraping navigation text to reconstruct that picture is brittle, lossy, and indistinguishable from guesswork at exactly the moment an agent needs certainty.
What a capability manifest is
A capability manifest is a JSON document at a well-known location that enumerates invocable operations with stable identifiers, prices, typed input and output schemas, worked examples, and stated limitations. Santos publishes one at /.well-known/agent-capabilities.json: it lists eleven capabilities, from Safe Fetch at 0.002 USDC to Batch Audit at 0.50 USDC flat, each with its endpoint, schemas, examples, and the payment protocol it accepts.
Structure in practice
A useful entry carries a stable capability id, a plain description, the invocation endpoint, a price with amount and asset, request and response schemas an agent can validate against before calling, at least one worked example, and explicit limitations such as rate limits, blocked network ranges, or unsupported inputs. Service-level metadata covers the provider identity, supported payment protocols such as x402-v2, and settlement behavior so the agent knows payment finalizes only on success.
An index, not a replacement
The manifest does not compete with the documents it points to. OpenAPI remains the canonical contract for HTTP operations, MCP remains the agent-native invocation protocol, and llms.txt remains the orientation file for readers both human and machine. The manifest is the routing layer above them: it helps an agent decide that Structured Extraction, not raw fetch, is the right tool, then hands off to the contract that governs the actual call.
Publishing one
Start by inventorying the operations an agent may legitimately invoke, and assign each a stable id. Describe inputs and outputs with the same schemas your OpenAPI document or MCP server already uses rather than inventing a parallel description. State prices and limitations honestly, serve the file at /.well-known/agent-capabilities.json with a content type of application/json and a predictable cache policy, and link it from llms.txt and your documentation so discovery does not depend on one convention alone.
Keeping it honest
A manifest is a claim, and claims are audited. Prices must match what the 402 challenge actually quotes, endpoints must resolve, and stated limitations must match observed behavior. Santos compares manifest claims against live evidence during an audit, and discrepancies surface as findings that lower the Callable and Trustworthy dimensions. The manifest that helps your score is the one your service can keep.