Websites are becoming agent-discoverable capability surfaces

The public web was built around documents, links and forms. Search engines learned to crawl those structures, and browser automation learned to imitate clicks. Agents can do both, but neither approach gives them a reliable contract for consequential work.

A capability surface states what can be done, which arguments are accepted, what side effects may occur, how identity is established and what result proves success. It does not replace the page. The page remains the user’s review surface, explanation layer and recovery path.

This distinction matters because an agent can understand a page and still choose the wrong action. Better extraction is not the same as safe actuation.

robots.txt controls crawler access patterns. A sitemap lists important URLs. Structured data describes entities and relationships. llms.txt proposes a concise curated map for inference-time use. None of those mechanisms authorizes an account change or purchase.

A2A Agent Cards advertise remote agent services. MCP registry records describe MCP servers and installation metadata. OpenAPI describes HTTP operations. WebMCP proposes browser-mediated tools inside an active page. These are adjacent layers, not interchangeable files.

Teams should document which question each artifact answers: may it be fetched, where is it, what does it mean, what can be invoked, and who may invoke it? Ambiguity at this level becomes security debt.

A common shortcut is to build a separate agent API that bypasses validations, review screens or accessibility work embedded in the main application. The two paths then drift. A human sees one price, policy or state while the agent acts on another.

The stronger pattern shares domain services, policy checks and authoritative data. The page and agent surface may present different representations, but they should call the same controlled business operations and produce compatible receipts.

Parity also means that users can inspect what the agent intends to do. A machine-only action with no human explanation or reversal path weakens accountability even when the API is technically clean.

Agents benefit from the same qualities that help people and search engines: descriptive headings, labels, landmarks, stable links, valid forms and explicit relationships. Accessibility semantics reduce ambiguity and provide a durable representation when visual layout changes.

Schema.org, JSON-LD, RDFa and microdata can expose products, organizations, articles, events and actions. OpenAPI and JSON Schema describe typed server operations. These formats create useful structure, but only if values stay synchronized with the real system.

Machine-readable metadata should be generated from authoritative data or validated in release pipelines. Hand-maintained descriptions that drift from prices, permissions or side effects are worse than missing metadata because they create misplaced confidence.

WebMCP proposes an API for pages to register tools with natural-language descriptions and structured schemas. A browser-connected agent can discover those tools and invoke page logic instead of reverse-engineering the DOM. This can reuse the user’s current session, selected record and visible state.

That advantage is also the risk. Tool definitions are created by page scripts, can change during a session and may be influenced by third-party code. Chrome’s security guidance explicitly treats malicious manifests and contaminated outputs as prompt-injection vectors.

The specification remains a Community Group draft and states that it is not yet a W3C Standard or Standards Track document. Production teams should therefore isolate it behind a stable internal capability contract and expect API and security changes.

A2A Agent Cards describe an agent service’s identity, endpoints, skills, input and output modes, capabilities and authentication requirements. The current specification uses a well-known discovery location and also supports registries or direct configuration.

The MCP Registry provides standardized metadata for public MCP servers and uses namespace verification. MCP’s protocol surface then exposes tools, resources and prompts, while draft work explores explicit server discovery and version negotiation.

Discovery metadata should be treated as untrusted. A verified domain or namespace helps establish control of a name; it does not prove that the advertised capability is safe, truthful or suitable for a particular user.

A useful action contract identifies the business resource, accepted inputs, output, errors, side effects, reversibility, idempotency, required authority and expected postcondition. Natural-language descriptions help selection, but deterministic fields must carry the control burden.

Operation names should be stable and specific. “Manage order” is ambiguous; “create-order-draft,” “confirm-order” and “cancel-order” expose distinct effects. Read, draft, preview and commit should not be hidden behind one model-decided parameter.

Problem Details, rate-limit fields, idempotency keys and content digests make failure and retry behavior machine-readable. The same contract should tell a client when a human confirmation or step-up authentication is required.

A public capability description can say that an operation exists. It cannot establish which user is present, which agent represents them, or whether that user has authority over the target resource. Those decisions belong to authentication and authorization systems.

OAuth protected-resource metadata, authorization-server metadata, PKCE, DPoP, rich authorization requests and audience-bound tokens provide building blocks for scoped access. Browser tools may inherit session cookies, but possession of a session does not remove the need for server-side policy.

Consent should be proportional to consequence. Search and filtering may run silently. Sending a message, purchasing, publishing, deleting or changing identity data should produce a clear preview and an intentional confirmation or approval step.

Agents consume tool names, descriptions, schemas, page text and returned data as context. A malicious site can advertise a misleading tool. A trusted site can return hostile text from comments, product listings or external feeds. Third-party scripts can alter the available tool set after the page loads.

The model cannot reliably distinguish data from instruction on its own. Control must exist outside the model: origin allowlists, schema validation, capability risk labels, output sanitization, permission prompts, deterministic policy and transaction review.

Record the tool set and schema revision observed at selection time and again at invocation. Mid-session changes should invalidate or reapprove a plan for consequential work.

Agent descriptions are often cached by browsers, registries, gateways and model platforms. If a schema, endpoint or permission changes while old metadata remains available, clients may send invalid arguments or perform the wrong operation.

Every capability needs a version and compatibility policy. HTTP caching, ETags or explicit expiry can control freshness. Mutable aliases should resolve to immutable versions for execution. Breaking changes should coexist during migration or fail with structured upgrade guidance.

Withdrawal is as important as publication. Compromised or unsafe tools need a revocation path, and clients need a way to stop using stale registry or well-known records.

The browser may report that a tool callback completed. An API may return 200. A remote agent may say that the task is done. None proves that the authoritative business state changed as intended.

Consequential operations should return a receipt containing stable resource identifiers, state revision, idempotency key and status. A reconciliation step reads the authoritative system and confirms the expected postcondition. Ambiguous outcomes enter a recovery workflow rather than being narrated as success.

Trace context connects discovery, selection, policy, execution and verification. It supports investigation, but trace identifiers and agent-provided labels are not authorization evidence.

A demo that finds and calls a tool is not enough. Evaluation must include the wrong-tool rate, stale metadata, denied permissions, duplicate submissions, prompt injection, accessibility, recovery and final business outcome.

Start with read-only capabilities and reversible drafts. Add preview and confirmation before enabling commits. Test independent clients because one vendor’s parser or extension can hide portability defects.

The best first release is usually a small, carefully governed surface. Exposing dozens of low-value actions increases selection errors, review burden and attack area. Expand only when real tasks show that the next capability removes meaningful ambiguity or cost.