> ## Documentation Index
> Fetch the complete guide index at: https://www.synscribe.com/agentic-discovery/llms.txt
> Use this file to discover all pages before exploring further.

---
title: "Agentic Resource Discovery (ARD) & ai-catalog.json: The Complete Guide"
description: "Google's new ARD spec, explained: the ai-catalog.json schema, the .well-known path, URN identifiers, registries, and trust. Plus our day-one census: 0 of 39 top sites publish one yet."
slug: /agentic-discovery/agentic-resource-discovery
series: The Agentic Discovery Playbook · Play 12 of 12
last_verified: 2026-06-18
---

# Agentic Resource Discovery (ARD): The Complete Guide to ai-catalog.json

> **In short:** Agentic Resource Discovery (ARD) is a new open spec, announced by Google and a Linux Foundation working group in late May 2026, that lets a site publish a machine-readable `/.well-known/ai-catalog.json` listing the agents, MCP servers, skills, and APIs it offers, so registries can index them and agents can find them by capability. It sits *before* invocation: it helps an agent find the right resource, which is then called through its own protocol (MCP, A2A, an API). It is real, backed, and Apache-2.0 licensed, but it is **v0.9 draft** and adoption is currently near zero: in our 2026-06-18 census of 39 major sites, including all eleven named working-group members, **none served a discoverable ai-catalog.json.** That makes this a first-mover bet, not a proven channel. Treat the file as a cheap option to write today and the protocol as a forecast to watch.

![Left-to-right flow of Agentic Resource Discovery. A publisher box marked "live today" hosts /.well-known/ai-catalog.json; a dashed registry box marked "forecast, no agent-queried one yet" crawls catalogs and exposes POST /search; a dark agent box asks "what can send email?" and queries the registry; a dashed invoke box marked "out of ARD scope" calls the resource via MCP, A2A, or API. A bracket labels the first three boxes "discovery, before invocation, ARD's scope." A footer states our day-one census: 0 of 39 top sites publish a catalog.](/agentic-discovery/images/diagram-ard-flow.svg "ARD covers discovery only: publish a catalog, a registry indexes it, the agent finds you, then invokes through the resource's own protocol. As of 2026-06-18, 0 of 39 top sites publish one.")

**Works in:** Find. ARD is the would-be open standard for the same job Play 2's registries do today: it sits at the **find** step as the standardized, self-hosted way agents resolve "what capability exists for this task." Unlike the other eleven plays, it is **frontier, not yet evidence-backed**, which is why it is sequenced last.

> **What's a forecast, not a finding.** Every other page in this playbook is backed by data we collected on live agents. This one is different: ARD is three weeks old. We have read the spec closely and run our own adoption census, but we cannot yet show you an agent choosing a product *because* of an ai-catalog.json, because there is almost nothing in the wild to choose from. We mark below what is true today, what is plausible later, and what is pure spec text that may never ship.

## Do this now

- [ ] Read the spec at its source: [agenticresourcediscovery.org/spec](https://agenticresourcediscovery.org/spec/) and the repo at [github.com/ards-project/ard-spec](https://github.com/ards-project/ard-spec). It is short. Do not take our word for any field name.
- [ ] Check whether you already 404 the path: `curl -sL -o /dev/null -w "%{http_code}\n" https://yourdomain.com/.well-known/ai-catalog.json`. As of today, almost everyone does.
- [ ] If you ship an MCP server, an A2A agent, a skills repo, or a public API, draft a minimal `ai-catalog.json` (template below). It is ~20 lines and costs nothing to host.
- [ ] Pick your URN namespace now: `urn:ai:<your-domain>:<area>:<name>`. Anchor it to a domain you control, because domain ownership is the spec's entire trust model.
- [ ] Add a backlog ticket, not a quarter of work. Until a registry or an agent client actually reads catalogs, this is an option you hold, not a program you run.
- [ ] Subscribe to the [update digest](/agentic-discovery#updates). We re-run the adoption census and will publish the moment the first real registry goes live.

> 📥 **Free resource:** validate your file against our copy of the schema in the [Registry Submission Runbook](/agentic-discovery/resources/registry-submission-runbook).

## Who needs this play?

Anyone who ships a **callable agentic resource**: an MCP server ([Play 3](/agentic-discovery/mcp-server-distribution)), an A2A agent, a public skills repo ([Play 4](/agentic-discovery/agent-skills-and-agents-md)), or an integrable API. If that's you, this is a ~1-hour first-mover option. If you have no such resource yet, ARD has nothing to advertise; skip it and revisit when you ship one.

This is the one play in the guide we tell you **not** to prioritize. The other eleven are backed by data on live agents; ARD is a three-week-old draft spec with zero measured adoption. Run Plays 1–11 first. Treat this as the frontier hedge: cheap to take, no regret if it fades, genuinely early if it lands. The rest of the page is the complete reference so you can ship a correct catalog in the hour you spend on it.

## What is Agentic Resource Discovery?

ARD is a protocol for one question an agent asks before it does anything: **"What capability exists for this task, and can I trust it?"** Today there is no standard answer across organizations. An agent that needs to "send a transactional email" has no uniform way to discover that your company ships an MCP server, an A2A agent, or an API that does exactly that. ARD proposes the missing layer.

It has two roles:

- **Catalogs** — a publisher hosts a static `ai-catalog.json` at a well-known path describing the agentic resources it offers. This is the part you own and can ship today.
- **Registries** — search services that crawl catalogs across the web and expose a REST search API, so an agent can ask one endpoint "what's available for X" instead of crawling the whole internet. This is the part that does not exist for you yet.

The single most important thing to understand: **ARD sits entirely before invocation.** It helps a client *find* a resource. The resource is then invoked through its own native mechanism. ARD is explicitly *not* a runtime (that's MCP, A2A, Skills), *not* a central catalog (many registries will exist with different trust policies), and *not* a replacement for anything you already publish.

```mermaid
flowchart LR
    P["PUBLISHER<br/>hosts /.well-known/ai-catalog.json<br/><i>(you can do this today)</i>"] -->|crawled by| R["REGISTRY<br/>indexes catalogs · exposes POST /search<br/><i>(does not exist for you yet)</i>"]
    A["AGENT<br/>'what can send email?'"] -->|queries| R
    R -->|returns ranked entries + trust| A
    A -->|invokes via its own protocol| I["MCP · A2A · API<br/><i>(ARD's job ends here)</i>"]
```

### Who is behind it, and does that matter?

ARD comes out of a working group with participants named as Microsoft, Google, Hugging Face, GoDaddy, Cisco, Databricks, GitHub, Nvidia, Salesforce, ServiceNow, and Snowflake, building on the Linux Foundation's AI Catalog data model. Google has said native ARD support is coming to its Cloud Agent Platform "in the coming months." The license is Apache-2.0.

That backing is the strongest reason to take ARD seriously, and the reason not to over-index on it. A heavyweight consortium can make a standard real (see: MCP). A heavyweight consortium can also publish a spec that quietly stalls (the standards graveyard is large, and not every announced spec gets adopted). The honest read: the sponsor list buys ARD a real shot, not a guarantee.

## What's true today vs what's a later bet

This is the section to read twice. ARD is a single spec, but its pieces have very different odds and very different costs.

| Layer | Status today (2026-06-18) | Our read on "later" | What it costs you now |
|---|---|---|---|
| `ai-catalog.json` at `/.well-known/` | Spec is stable enough to write against; **~0% of sites publish one** (our census below) | Most likely piece to stick; it's just a static file, like robots.txt or llms.txt | ~20 lines, ~1 hour |
| Domain-anchored URN identity | Defined; nothing consumes it yet | Sensible and low-risk to adopt; mirrors how the web already does trust (you own the domain) | Pick a naming scheme |
| Registries (`POST /search`) | **No public, agent-queried ARD registry we can find** | The make-or-break piece. ARD is inert until a registry an agent actually uses indexes catalogs | $0 — you can't act on this yet |
| Agent clients reading catalogs | None observed in the wild | Depends entirely on registries + a client wiring it in (à la how clients wired in MCP) | $0 — watch only |
| Trust manifest / attestations | Fully specified; aspirational | Enterprise-driven; will matter for high-trust use long before it matters for indie devs | Skip unless you already have SOC2/attestations to point at |

The practical takeaway: **the file is a cheap option; the protocol is a forecast.** Writing `ai-catalog.json` now is like having shipped `llms.txt` in early 2024, low cost, possible upside, no regret if it fades. Re-architecting around ARD registries now would be building on a road that has not been poured.

## The ai-catalog.json schema, field by field

This is the reference. We reproduce the structure from the v0.9 draft so you can write a valid file without round-tripping to the spec, but **the spec is the source of truth** — field names can move before v1.0 freezes. (Note the version quirk: the repo is tagged v0.9 draft, while the manifest's own `specVersion` value is `"1.0"`.)

### Root object

```json
{
  "specVersion": "1.0",
  "host": { /* Host Info object */ },
  "entries": [ /* array of Catalog Entry objects */ ]
}
```

| Field | Type | Required | Notes |
|---|---|---|---|
| `specVersion` | string | yes | `"1.0"` in the current draft |
| `host` | object | yes | Who publishes this catalog |
| `entries` | array | yes | The resources you're advertising |

### Host Info object

| Field | Type | Required | Notes |
|---|---|---|---|
| `displayName` | string | **MUST** | Human-readable publisher name |
| `identifier` | string | optional | Your DID or domain |
| `documentationUrl` | string | optional | Where humans read about you |
| `logoUrl` | string | optional | For registry UIs |
| `trustManifest` | object | optional | Identity/compliance at the host level |

### Catalog Entry object

Each entry describes one agentic resource. The rule that trips people up: **exactly one of `url` or `data` must be present** (the spec calls this "Strict Value-or-Reference"). Use `url` to point at a remote artifact; use `data` to inline the artifact document. Never both.

| Field | Type | Required | Notes |
|---|---|---|---|
| `identifier` | string | **MUST** | URN: `urn:ai:<publisher>:<namespace>:<name>` |
| `displayName` | string | **MUST** | Human-readable name |
| `type` | string | **MUST** | IANA media type, e.g. `application/mcp-server+json`, `application/a2a-agent-card+json` |
| `url` | string | conditional | Remote artifact URL (XOR `data`) |
| `data` | object | conditional | Inline artifact document (XOR `url`) |
| `description` | string | optional | Short, task-phrased |
| `tags` | array | optional | Keywords for filtering |
| `capabilities` | array | optional | Tool/skill identifiers |
| `representativeQueries` | array | optional (SHOULD, 2–5) | Natural-language queries you want to match |
| `version` | string | optional | Artifact version |
| `updatedAt` | string | optional | ISO 8601 timestamp |
| `metadata` | object | optional | Custom key-value pairs (filterable as `metadata.*`) |
| `trustManifest` | object | optional | Identity + attestations for this entry |

The field worth your attention is `representativeQueries`. It is the same mechanic we document throughout this playbook: agents and indexes match on natural-language need, so 2–5 queries phrased the way a developer actually asks ("send a transactional email", "get the 5-day forecast for Seattle") is your ranking surface. Marketing copy matches nothing. This is [llms.txt description engineering](/agentic-discovery/llms-txt) and [Context7 description engineering](/agentic-discovery/ai-agent-registries-and-directories), in a new envelope.

### Trust Manifest object

| Field | Type | Required | Notes |
|---|---|---|---|
| `identity` | string | **MUST** | Cryptographic workload ID (SPIFFE, DID, or HTTPS URI) |
| `identityType` | string | optional | Hint: `"spiffe"`, `"did"`, `"https"` |
| `attestations` | array | optional | Each: `type` (e.g. `"SOC2-Type2"`), `uri`, optional `digest` |
| `provenance` | array | optional | Lineage: `relation`, `sourceId`, optional `sourceDigest` |
| `signature` | string | optional | Detached JWS signature |

The trust model's foundation is plain: **you prove you own the domain in your URN, and that domain anchors your identity.** Attestations and signatures layer cryptographic verification on top for enterprise use. For day-one adoption, the `identity` is the only required field here, and you can skip the whole object until you have something real to attest.

## A complete, valid example

A minimal catalog for a fictional payments company, "PayKit," advertising one MCP server:

```json
{
  "specVersion": "1.0",
  "host": {
    "displayName": "PayKit",
    "identifier": "paykit.dev",
    "documentationUrl": "https://paykit.dev/docs",
    "logoUrl": "https://paykit.dev/logo.png"
  },
  "entries": [
    {
      "identifier": "urn:ai:paykit.dev:payments:mcp",
      "displayName": "PayKit Payments MCP",
      "type": "application/mcp-server+json",
      "url": "https://paykit.dev/.well-known/mcp/server.json",
      "description": "Create checkout sessions, capture and refund payments, and verify webhooks.",
      "tags": ["payments", "checkout", "refunds", "webhooks"],
      "capabilities": ["create_checkout", "capture_payment", "refund", "verify_webhook"],
      "representativeQueries": [
        "accept a card payment",
        "refund a charge",
        "verify a payment webhook signature"
      ],
      "version": "3.4.1",
      "updatedAt": "2026-06-18T00:00:00Z"
    }
  ]
}
```

That file, hosted at `https://paykit.dev/.well-known/ai-catalog.json`, is a conformant ARD catalog. Note what it does *not* contain: no auth, no runtime, no endpoint logic. It points at the MCP server's own descriptor (`url`) and lets the MCP protocol handle the rest. That separation is the whole design.

## How do agents find your catalog?

The spec defines four discovery mechanisms. The first is the baseline; the rest are belt-and-suspenders.

| Mechanism | Form | Status |
|---|---|---|
| **Well-known URI** (baseline) | `https://{domain}/.well-known/ai-catalog.json` | SHOULD host here; this is what to do |
| robots.txt directive | `Agentmap: https://example.com/ai-catalog.json` | Optional; mirrors `Sitemap:` |
| HTML link tag | `<link rel="ai-catalog" href="...">` in `<head>` | Optional |
| DNS service binding | records under `_catalog._agents.example.com` | Optional, infra-heavy |

Ship the well-known file. Add the `Agentmap` line and the `<link>` tag if they're cheap in your stack; they're free redundancy that helps a crawler that hasn't guessed the well-known path.

## The registry side (what you can't act on yet)

You publish a catalog; a registry consumes it. You will not run a registry, but understanding its API tells you what your catalog needs to be good at. The spec mandates one endpoint and defines two more:

- **`POST /search` (MUST).** Body carries `query.text` (natural-language need), an optional `query.filter` (structured constraints using dot-notation paths like `trustManifest.attestations.type`), and a `federation` mode (`auto` | `referrals` | `none`). Returns ranked entries each with a `score` (0–100 semantic relevance — explicitly **not** a trust or safety rating) and a `source` registry URL.
- **`POST /explore` (SHOULD).** Faceted aggregation, e.g. "how many MCP servers vs A2A agents match this."
- **`GET /agents` (MAY).** Deterministic, cacheable listing with strict filtering.

Two design facts that should shape your catalog:

1. **Federation.** Registries forward queries to each other (`auto` merges upstream results; `referrals` hands back pointers to other registries; `none` stays local). This is meant to prevent the single-winner-takes-all directory problem we document in [Play 2](/agentic-discovery/ai-agent-registries-and-directories). Whether it works in practice is unknown until multiple registries exist.
2. **Filter semantics.** Within one key, multiple values are OR'd; across keys, AND'd; arrays match if any element qualifies; and *any* field you put in the entry, including `metadata.*` and Schema.org vocabulary, becomes filterable. That is the technical reason to put real, specific `tags`, `capabilities`, and `metadata` in your entry: each one is a query you can win.

The scalability pitch behind all this: move resource selection *out* of the LLM's context window and into a dedicated search service. Instead of stuffing 500 tool descriptions into a prompt, the agent asks a registry. It's a clean idea. It needs a registry the agent trusts to be real.

## Our independent experiment: who actually publishes a catalog?

We could not find anyone writing about ARD adoption with real numbers, so we measured it ourselves.

**Method.** On 2026-06-18 we probed 39 domains for all three of ARD's HTTP discovery surfaces: a `GET` of `/.well-known/ai-catalog.json` (following redirects, recording the final status and content type), the site's `robots.txt` for an `Agentmap`/`ai-catalog` directive, and the homepage `<head>` for a `<link rel="ai-catalog">`. The sample was deliberately friendly to ARD: all eleven named working-group members (Google, Microsoft, Hugging Face, GoDaddy, Cisco, Databricks, GitHub, Nvidia, Salesforce, ServiceNow, Snowflake) plus the developer-tool companies who lead every other adoption curve in this guide (Stripe, Vercel, Next.js, Supabase, Prisma, Clerk, Resend, Better Auth, and more). If anyone had shipped one, this sample would catch it.

**Result.** Zero. **0 of 39** domains served a discoverable `ai-catalog.json`, an `Agentmap` directive, or a `link rel="ai-catalog"`.

| Probe surface | Sites with it | Notes |
|---|---|---|
| `/.well-known/ai-catalog.json` (HTTP 200 + JSON) | **0 / 39** | 33 returned 404; the rest returned SPA HTML, CDN "Access Denied", or redirect loops, never a catalog |
| `robots.txt` `Agentmap:` directive | **0 / 39** | Not one site, including Google's |
| `<link rel="ai-catalog">` | **0 / 39** | None |

The non-404 responses are worth a line, because they're the trap in any adoption census: `azure.microsoft.com` and `huggingface.co` returned `200`, but the body was their normal HTML app shell (a catch-all route), not JSON. `nvidia.com`, `godaddy.com`, and `servicenow.com` returned `403 Access Denied` from their CDN edge. `tailwindcss.com` returned a `308` redirect loop. We verified each by reading the response body and content type; none was a catalog. The lesson for your own monitoring: a `200` is not adoption. Check the content type and parse the JSON.

**What this means.** Three weeks after a launch backed by eleven of the largest names in software, the real-world adoption of ARD's publisher side is indistinguishable from zero, *including among the companies that wrote the spec.* Read that two ways at once. The skeptic's read: specs that the authors themselves haven't shipped are a coin-flip to matter. The operator's read: the first-mover window is wide open, and shipping a valid catalog this month makes you genuinely early, not late. Both are true. We re-run this census on a cadence and publish every dated snapshot, plus the per-company results and the implementers table, in the live [ARD / ai-catalog.json Adoption Tracker](/agentic-discovery/ard-adoption-tracker).

## We practice what we preach: our own catalog

Per the dogfooding principle behind this whole guide, Synscribe now serves a valid ARD catalog at [`/.well-known/ai-catalog.json`](https://www.synscribe.com/.well-known/ai-catalog.json). It is honest about what it lists (a documentation/knowledge resource, not a callable runtime we don't ship), and it exists so we can say we did the thing on the day we told you to. Validate it yourself; copy the shape.

## The ARD adoption playbook

If you decide to take the option, here's the whole thing, in order:

1. **Inventory your agentic resources.** MCP servers, A2A agents, public skills repos, callable APIs. If you have none, ARD has nothing to advertise yet, stop here and revisit when you ship one.
2. **Choose your URN scheme.** `urn:ai:<your-domain>:<area>:<name>`, anchored to a domain you control. Write it down so every future entry is consistent.
3. **Write `ai-catalog.json`.** Start from the example above. One entry per resource. `type` is the IANA media type of the artifact; `url` points at the artifact's own descriptor.
4. **Engineer `representativeQueries` and `tags`.** This is the only part with real craft. Phrase 2–5 queries as the tasks a user actually asks. Put your category nouns in `tags`. These are your filter surfaces.
5. **Host it static** at `/.well-known/ai-catalog.json`: HTTP 200, `application/json`, no auth wall, no bot challenge, no redirect. Same hygiene as [llms.txt](/agentic-discovery/llms-txt).
6. **Add the optional signals** if cheap: the `Agentmap:` line in robots.txt and the `<link rel="ai-catalog">` tag.
7. **Validate** against the spec's JSON Schema (`spec/schemas/ai-catalog.schema.json` in the repo). A malformed catalog is worse than none.
8. **Monitor.** Add a one-line CI check that your catalog still returns 200 + valid JSON, and set a calendar reminder to re-read the spec at v1.0. Watch for the first agent-queried registry; that is the signal that this option is going live.

Total cost: an afternoon, once. That's the right size of bet for a v0.9 spec with zero adoption and serious backing.

## How ARD relates to everything else

ARD does not replace a single play in this guide; it potentially standardizes the *find* step.

| You already have | ARD's relationship |
|---|---|
| [llms.txt](/agentic-discovery/llms-txt) | Complementary. llms.txt is a doc index for reading; ai-catalog.json is a capability index for invoking. Ship both. |
| [MCP server](/agentic-discovery/mcp-server-distribution) | ARD *points at* your MCP server; it doesn't replace it. Your catalog entry's `url` is the MCP descriptor. |
| [Registries (Play 2)](/agentic-discovery/ai-agent-registries-and-directories) | ARD is the would-be open standard for the same job today's registries do ad hoc. If it wins, Play 2's tier table gets an open, self-hosted column. |
| robots.txt / sitemap.xml | Same family: a well-known, machine-readable file that tells automated clients what exists. ARD is "sitemap for capabilities." |

If you internalize one mapping: **ai-catalog.json is to agent capabilities what sitemap.xml is to web pages.** Whether agents come to depend on it the way crawlers depend on sitemaps is the open question. The file is cheap enough that you don't need the answer to justify writing it.

## FAQ

**What is Agentic Resource Discovery (ARD)?**
ARD is an open specification, announced by Google and a Linux Foundation working group in late May 2026, for discovering agentic resources (agents, MCP servers, skills, APIs) across the web. Publishers describe their resources in a `/.well-known/ai-catalog.json` file; registries crawl those files and expose a search API so agents can find capabilities by natural-language need. It handles discovery only, not invocation.

**What is ai-catalog.json?**
It's the file at the center of ARD: a JSON document at `https://yourdomain.com/.well-known/ai-catalog.json` with a `specVersion`, a `host` block, and an `entries` array. Each entry has a domain-anchored URN `identifier`, a `displayName`, an IANA-media-`type`, and either a `url` to the resource or inline `data`. Optional fields like `representativeQueries`, `tags`, and `trustManifest` make the entry findable and trustworthy.

**Should I publish an ai-catalog.json today?**
If you ship an MCP server, an A2A agent, a public skills repo, or a callable API, yes, it's a cheap option (~1 hour) and you'll be genuinely early; our 2026-06-18 census found 0 of 39 major sites publishing one. If you have no agentic resource to advertise, wait. Either way, treat it as a low-cost bet, not a program, until an agent-queried registry actually exists.

**Is ARD adopted yet? Does it work?**
Not yet, by any measure we can find. We probed 39 leading domains, including all eleven named working-group members, on 2026-06-18 and found zero discoverable catalogs, zero `Agentmap` directives, and zero `link rel="ai-catalog"` tags. There is no public ARD registry an agent queries today. The spec is real and well-backed, but as a working channel it is a forecast, not a finding.

**How is ARD different from llms.txt and MCP?**
llms.txt is a curated index of your *documentation*, for an agent to read. MCP is a *runtime* protocol for an agent to call your tools. ARD is a *discovery* layer that sits before both: it tells a registry that your MCP server (or A2A agent, or API) exists and what it's for, so an agent can find it in the first place. They stack; ARD doesn't replace either.

**Will ARD actually get adopted?**
Unknown, and anyone who tells you otherwise is guessing. The Apache-2.0 license and the eleven-company working group give it a real shot, and Google has signaled native support in its Cloud Agent Platform. But announced specs stall all the time, and right now even the authors haven't shipped catalogs. The make-or-break milestone to watch is the first registry that a major agent client actually queries by default. We track it in the [Data Room](/agentic-discovery/data).

---

*Last verified 2026-06-18. This is a fast-moving frontier topic; we re-read the spec and re-run our adoption census quarterly, and changes are logged in the [Data Room](/agentic-discovery/data).*

**Part of [The Complete Playbook to Agentic Discovery](/agentic-discovery).**

← Previous: [Play 11: AI Evals & Public Leaderboards](/agentic-discovery/ai-evals-and-leaderboards) · Next: [Measuring Agentic Visibility](/agentic-discovery/measure-ai-visibility) →

> **Stay ahead of the agents.** We re-test this playbook quarterly and publish what changed: new data, busted myths, ranking shifts. [Get the update digest →](/agentic-discovery#updates)
>
> **Want this done for you?** Synscribe runs agentic-discovery programs for B2B SaaS and developer platforms. [Talk to us →](/contact)