Skip to content
QAIL
Book a Demo Get Started
Agentic Web

What Is Agentic Resource Discovery? How to Implement ai-catalog.json Before Your Competitors

QAIL AI Team 7 min read

On June 17, 2026, Google published a new open specification alongside ten of the largest names in enterprise software: Cisco, Databricks, GitHub, GoDaddy, Hugging Face, Microsoft, Nvidia, Salesforce, ServiceNow, and Snowflake. The specification is called Agentic Resource Discovery, and its job is to solve a problem that has quietly become urgent: AI agents have no reliable way to find what they can do on your site.

As of this writing, adoption is near zero. A census of 39 major domains conducted the day after launch — including every one of the eleven working group members — found that none served a discoverable ai-catalog.json. The companies that wrote the standard hadn’t published it yet on their own sites.

That gap is a window. This post explains what ARD is, why it matters for your agentic visibility strategy, and how to implement it now — before your competitors get around to reading the press release.

The Discovery Problem Nobody Talks About

The conversation about the agentic web has mostly focused on access control: which bots to allow, which to block, how to structure your robots.txt directives. That conversation matters. But it assumes agents can find your capabilities in the first place.

Right now, they mostly can’t — not reliably. An AI agent trying to book a flight, purchase a product, or retrieve a data feed has to either guess where the relevant endpoint lives, rely on hardcoded URLs baked into its training data, or crawl your site the same way a search bot does and hope the page content is clear enough to infer what’s available. None of these work well at scale.

MCP (Model Context Protocol) reached 97 million monthly SDK downloads by late 2025. Thousands of tools and data sources are now accessible via MCP servers. But when an agent needs a capability it wasn’t pre-trained to know about, it has no standardized way to search for it. ARD is the answer to that problem: a discovery layer that sits above MCP, A2A, and plain APIs, letting agents find capabilities through a structured search rather than a crawl.

Think of it as the robots.txt moment for agent capability discovery — except this time, publishing your file makes you more visible to agents rather than restricting them. And unlike llms.txt, which tells AI models what your site is about, ARD tells agents what your site can do.

What ARD Actually Is

The Agentic Resource Discovery specification defines two primitives.

The first is a static manifest — ai-catalog.json — hosted at a predictable well-known path on your domain (/.well-known/ai-catalog.json). This file lists everything your domain exposes to agents: MCP servers, A2A interfaces, plain APIs, skills. Any agent or registry can find your manifest just by knowing your domain name.

The second is a registry API — a server that crawls published manifests, indexes their contents, and exposes a POST /search endpoint. An agent submits a natural-language query like “I need a tool that can verify a US business address in real time” and receives a ranked list of matching capabilities from across the web, along with enough metadata to evaluate and connect to them.

The spec is licensed under Apache 2.0, built on the AI Catalog data model from the Linux Foundation’s AI Catalog Working Group, and designed to layer over whatever protocol the underlying capability uses. An entry in your ai-catalog.json can point to an MCP server, an A2A agent card, or a plain REST API. The manifest is protocol-agnostic; the entries are not.

The Structure of ai-catalog.json

The manifest is straightforward. A minimal file has three top-level keys: specVersion, host, and entries.

specVersion identifies the ARD version you’re conforming to. At launch, that’s "0.9".

host identifies your organization with a displayName and a domain-anchored identifier.

entries is the array that matters. Each entry describes one capability and must include:

  • identifier — a domain-anchored URN like urn:ai:yourdomain.com:tool:capability-name
  • displayName — a human-readable label
  • type — the media type of the resource: application/mcp-server+json for MCP servers, application/a2a-agent-card+json for A2A interfaces, application/json for plain APIs
  • url — a link to the capability’s interface definition (or data to embed it inline)
  • description — what the capability does
  • representativeQueries — two to five natural-language questions describing which tasks your tool can handle; registries use these phrases as their primary ranking signal

That last field is where most of the SEO work lives. Registries rank matches primarily by how well an agent’s query semantically matches your representativeQueries. Write them the way your users would ask an AI for help — not “invoice processing API v2” but “can you extract line items from a PDF invoice and return them as structured data?”

Here is what a minimal entry looks like in practice:

{
  "specVersion": "0.9",
  "host": {
    "displayName": "Acme Corp",
    "identifier": "acme.com"
  },
  "entries": [
    {
      "identifier": "urn:ai:acme.com:tool:address-verify",
      "displayName": "US Address Verification",
      "type": "application/mcp-server+json",
      "url": "https://acme.com/.well-known/mcp/address-verify.json",
      "description": "Validates and standardizes US postal addresses against USPS data in real time.",
      "representativeQueries": [
        "Verify a US mailing address before shipping an order",
        "Check whether an address is deliverable",
        "Standardize a customer address to USPS format"
      ]
    }
  ]
}

How This Connects to What You’ve Already Built

If you’ve followed QAIL’s guide to implementing MCP endpoints for AI-ready commerce, you’re already most of the way there. Each MCP server you’ve deployed becomes an entry in your ai-catalog.json. The url field points to the MCP server descriptor you’ve already published; ARD adds the discoverability layer on top.

Think of it as a stack: llms.txt tells AI models what your site is about. Your agent access control policies govern which agents can use your capabilities and how. MCP or A2A provides the protocol layer for the actual interaction. ARD is the index that makes all of it findable without requiring agents to know about your site in advance.

Missing any layer means agents that could use your capabilities won’t find them. ARD without MCP means agents discover you but can’t connect. MCP without ARD means agents can only use your tools if they already know your domain.

The Adoption Gap Is an Opportunity

The fact that none of the specification’s own authors had published ai-catalog.json on their domains within 24 hours of launch tells you something important: early adoption here is genuinely early.

Search engines rewarded early adopters of structured data markup for years before compliance became standard. The same dynamic applies here. Registries that index ai-catalog.json files will surface compliant domains first and most prominently. Agents that use those registries will route queries toward discoverable capabilities.

QAIL’s analysis of 30M+ website visits found that AI bot traffic now constitutes 38–52% of total web traffic. The agents driving that traffic are increasingly capable of autonomous action — booking, purchasing, retrieving, synthesizing. The sites those agents visit first are the ones they can find. Right now, that’s a short list. Publishing ai-catalog.json puts you on it.

Implementation: What to Do This Week

Getting a baseline ai-catalog.json live is less than a day’s work for most teams. Here’s the sequence.

Audit your existing capabilities. List every endpoint, API, or tool your site exposes that an agent could reasonably use: product search, checkout APIs, content retrieval, account management, booking flows. If you’ve already deployed MCP endpoints, start there.

Write your entries. For each capability, draft three to five representative queries. Think about what an AI assistant would ask to find this tool. Be specific — vague queries produce poor ranking.

Choose between url and data. If your capability already has a machine-readable descriptor (an MCP server JSON, an OpenAPI spec, an A2A agent card), link to it with url. If not, embed a summary directly using data. The spec requires exactly one — not both.

Publish at the well-known path. Your file goes at https://yourdomain.com/.well-known/ai-catalog.json. Serve it with Content-Type: application/json and make sure it’s reachable without authentication.

Submit to registries. Hugging Face launched the first ARD-compliant registry at launch, indexing thousands of Spaces, Skills, and MCP servers. Submit your catalog URL there, and monitor agenticresourcediscovery.org for additional registries as the ecosystem develops.

Keep it current. An ai-catalog.json that describes capabilities you’ve deprecated is worse than no file at all — agents will attempt to use endpoints that no longer work and develop negative priors about your domain’s reliability. Treat updates as part of your deployment checklist.

What ARD Doesn’t Do (Yet)

The specification is a v0.9 draft. The gap between “published standard” and “operating ecosystem” is real.

There is no mandatory validator. There are no official registry certification requirements. The representativeQuery ranking behavior is defined at the semantic level but implemented differently by each registry. None of this disqualifies ARD — the same was true of structured data markup in 2009, and schema.org became table stakes within a few years. But it means you should implement ARD as infrastructure, not as an immediate traffic driver. The traffic comes as registries proliferate and agents start routing against them at scale.

ARD also doesn’t replace your agent access control policy. Discoverable doesn’t mean open. Your ai-catalog.json can surface a capability while your backend enforces authentication and authorization on the actual requests. The two systems are independent and complementary.

Act Now, While the Field Is Empty

The ARD specification is backed by the companies that build the platforms your buyers use. Registries will crawl it. Agents will query those registries. The sites already in the index will have a head start that compounds over time.

Publishing ai-catalog.json this week costs a few hours. Waiting six months means catching up to a field that’s no longer empty.

Want to know how your site scores on agent readiness before you implement? QAIL’s free Agent Readiness Score shows you exactly where you stand across structured discoverability, agent access policy, and AI traffic performance — in under 30 seconds.