Agent Interfaces
Check how your site describes forms, APIs and actions for AI tools. Each check includes its proof, limits and effect on the score.
agent-interfaces/agents-jsonGrade CAdvisoryagents.json at /.well-known/agents.json
agents.json (Wild Card AI, spec v0.1.0) layers agent-facing flows over OpenAPI at `/.well-known/agents.json`. No AI vendor documents consuming it, the spec never moved past v0.1.0, both of its project domains are offline and the path is absent from the IANA Well-Known URIs registry — so this check never asks a site to publish the file. It reports, with no score effect, whether what is served at that path is a real agents.json document or an HTML shell.
agent-interfaces/ai-catalog-existsGrade CAdvisoryAI Catalog exists
The AI catalog is the ARD discovery manifest that tells AI agents which MCP servers, agent cards, skills and API descriptions your site offers. Hugging Face's hf-discover resolves it at /.well-known/ai-catalog.json and reads its entries; without it, agents must probe endpoints to work out what your site can do.
agent-interfaces/ai-catalog-metadataGrade BScoredAI Catalog complete metadata
Consumers rank AI catalog entries on their metadata: Hugging Face's hf-discover builds its match text from each entry's description, tags, capabilities and representativeQueries. An entry with only an identifier and a type is legal ARD but is nearly unmatchable, so agents searching for what you offer will not surface it.
agent-interfaces/ai-catalog-urlsGrade BScoredAI Catalog entry URLs valid
Every AI catalog entry either embeds its artifact inline or points at one with a url. Consumers dereference those urls to load MCP server cards, agent cards and nested catalogs, so a dead url silently truncates a whole branch of discovery and breaks any agent that trusted the manifest.
agent-interfaces/cors-api-routesGrade CAdvisoryCORS on declared API routes
CORS matters for one class of AI consumer: agent code running inside a browser origin, such as an OpenAI Apps SDK widget in an isolated iframe under a strict CSP. Server-side crawlers and MCP clients are not browsers and are unaffected. This audit reads the endpoints out of your published OpenAPI document and probes those, and applies only to sites that publish one.
agent-interfaces/mcp-discoveryGrade CAdvisoryMCP server discovery file
Reports whether the site publishes an MCP discovery document at `/.well-known/mcp/servers.json` or `/.well-known/ucp`, and whether what it publishes can be parsed. Neither path is registered or specified, and no shipping MCP client is documented as fetching either, so this is reported rather than scored: a site with a working MCP server discovered by any other route is not less agent-ready for having no such file.
agent-interfaces/mcp-endpointGrade CAdvisoryMCP endpoint functional
One MCP endpoint audit: it finds the endpoint your site declares, speaks a spec-compliant JSON-RPC 2.0 initialize handshake to it, reports the capabilities the server negotiates on the wire, and checks that the tools it lists carry safety annotations.
agent-interfaces/mcp-modern-era-reachabilityGrade AScoredModern-Era Reachability Probe (server/discover)
Determine, with one unauthenticated stateless POST, whether the site's MCP endpoint can be used at all by a client built on the current protocol revision (2026-07-28). Classifies the endpoint into modern / dual-era / legacy-only / deprecated-HTTP+SSE / unreachable, and extracts supportedVersions, capabilities, instructions and serverInfo from the DiscoverResult.
agent-interfaces/mcp-oauth-discovery-chainGrade AScoredOAuth Discovery Chain Integrity (RFC 9728 → RFC 8414)
Walks the full credential-free authorization discovery path an MCP client must traverse — 401 challenge, WWW-Authenticate resource_metadata, Protected Resource Metadata document, authorization server metadata — and asserts every MUST-level validation gate the client will apply. Ends before any token is requested, so it needs no credentials.
agent-interfaces/mcp-origin-validation-corsGrade BScoredThe MCP endpoint validates Origin and its CORS policy matches its auth posture
Sends the discover call twice — once with a throwaway `Origin`, once without — and one CORS preflight, then compares. An endpoint that reflects an arbitrary Origin into `Access-Control-Allow-Origin` while also allowing credentials has authorized every page the user visits to call it on the user’s behalf. Permissive CORS on an endpoint with no auth surface is reported and not scored.
agent-interfaces/mcp-registry-listing-ownershipGrade BScoredThe MCP server is listed in the official registry under a namespace this domain owns
Searches the official MCP Registry for servers whose `remotes[].url` lives on this domain, classifies each listing by namespace — reverse-DNS of this domain, an individual’s GitHub account, or a third-party aggregator — and checks that the domain-control proof the reverse-DNS namespace requires is actually being served at `/.well-known/mcp-registry-auth`.
agent-interfaces/mcp-tool-contract-validityGrade AScoredTool Contract Validity and Silent-Drop Risk
Static validation of every tool definition returned by tools/list against the MUST/SHOULD-level structural rules in the 2026-07-28 tools spec — with special weight on x-mcp-header violations, which oblige conforming clients to silently remove the offending tool from the list they show the model.
agent-interfaces/mcp-tool-description-coverageGrade BScoredTool Self-Description Coverage
Counts, over the tool surface the endpoint already returned, what fraction of tools carry a description, what fraction of every input parameter carries one — walking `properties` recursively and into `items.properties` for arrays of objects — and reports the advisory ratios alongside: constrained string parameters, declared output schemas, titles and the server’s own `instructions`.
agent-interfaces/mcp-tools-list-determinismGrade AScoredtools/list Determinism and Cache-Hint Compliance
Repeatedly fetches tools/list and asserts three things the spec ties directly to agent cost and latency: caching hints are present and well-formed (ttlMs >= 0, cacheScope in {public, private}), tool ordering is stable across calls, and the tool set does not vary per connection.
agent-interfaces/mcp-version-downgradeGrade AScoredVersion Downgrade Recoverability
Negative-path probe that verifies the server fails correctly when handed a protocol version it does not support, and when the MCP-Protocol-Version header disagrees with the body's _meta. Both are MUST-level behaviors whose absence strands otherwise-compatible clients.
agent-interfaces/openapi-description-qualityGrade AScoredOpenAPI description quality for tool-calling
When an AI agent converts your OpenAPI spec into callable tools, the description fields become the prompt the LLM uses to decide when and how to call each function. A one-word description like "search" tells the model nothing about what the endpoint does, what the parameter means, or what values are valid — so the agent guesses, calls the wrong tool, or fills parameters with hallucinated values. Every operation and every parameter needs a verbose description (more than 15 characters) that explains purpose, expected input, and behavior.
agent-interfaces/openapi-endpointsGrade BScoredOpenAPI has endpoints
An OpenAPI spec without endpoints is like a menu with no items. AI agents need at least one path with an operation to know what actions they can perform on your site. Add your most important endpoints first.
agent-interfaces/openapi-existsGrade BAdvisoryAPI description discoverable
One discovery audit over the mechanisms that actually exist: the RFC 9727 /.well-known/api-catalog linkset, an OpenAPI document at a probed root path, and a <link rel="service-desc"> advertising one. A site with no API surface is not applicable rather than failing.
agent-interfaces/openapi-operation-idsGrade BScoredOpenAPI has operationIds
AI agents use operationIds as stable function names when calling your API. Without unique operationIds, agents must guess endpoint names from paths, leading to ambiguity and errors. An operationId that is not a legal function name (spaces, punctuation, or more than 64 characters) cannot be registered as a tool at all.
agent-interfaces/openapi-schemasGrade BScoredOpenAPI request/response schemas
Without request/response schemas, AI agents must guess the data format for your endpoints. This leads to malformed requests and failed API calls. Define JSON schemas for all request bodies and responses.
agent-interfaces/openapi-serversGrade BScoredOpenAPI servers array valid
Without a servers array, AI agents do not know the base URL for your API. They cannot construct valid request URLs, rendering the entire spec unusable. Add at least your production server URL.
agent-interfaces/search-endpointGrade CAdvisorySite search reachable by agents
A declared search endpoint lets an AI agent find specific content on your site without crawling every page. This audit covers both halves of that declaration: the Schema.org SearchAction URL template, and a GET search operation in your OpenAPI spec — and it probes the template rather than trusting it.
agent-interfaces/webmcp-declarative-formsGrade BScoredWebMCP declarative form tools
WebMCP's Declarative API turns an HTML <form> into an agent-callable tool: add toolname and tooldescription and the browser synthesizes a JSON Schema from the form's controls, which an in-browser agent can discover and invoke without any JavaScript. toolname is what registers the tool — a description on its own registers nothing.
agent-interfaces/webmcp-registered-toolsGrade BExperimentalWebMCP registered tools
WebMCP lets a page register agent-callable tools at runtime through navigator.modelContext, which is what Chrome exposes to an in-browser agent and what Lighthouse reports as "Registered WebMCP tools". This scanner has no JavaScript runtime, so it reports the registrations visible in the served document and treats silence as unknown rather than as absence — which is why it is experimental and never scores.