For automated discovery, an AI catalog matters only to software that knows how to read it. Its practical job is to provide a typed inventory of artifacts that a publisher has listed (Agent Card Working Group, "AI Catalog"). It is not evidence that a registry indexed those artifacts, that a client selected them, or that any tool call succeeded.
The specifications around ai-catalog.json are still moving (Agent Card Working Group, "Common AI Catalog"; Bu, Guha, and Smith). The file can be worthwhile as publisher-maintained documentation, but its presence should not be promoted as a general discovery guarantee.
Two documents, two jobs
The AI Catalog specification defines a typed, nestable JSON container. Each entry identifies an artifact, states its type, and either links to the artifact document or embeds its data. The catalog does not replace formats such as an MCP Server Card or an A2A Agent Card. It provides an envelope around those native descriptions (Agent Card Working Group, "AI Catalog").
The ARD v0.9 draft proposes a broader search and registry layer around that catalog. Its current document marks its status as "Proposal" (Bu, Guha, and Smith). The AI Catalog repository also calls itself a working repository under temporary governance. It says possible adoption votes by the MCP and A2A steering committees would follow finalization of the specification, not precede it (Agent Card Working Group, "Common AI Catalog").
Those are primary-source status statements. They support calling the work an emerging specification. They do not support claims of broad implementation or adoption.
The path can cause another kind of confusion. RFC 8615 reserves /.well-known/ as a path prefix for registered well-known locations, but it does not define the format found at every name under that prefix (Nottingham, sec. 3). The AI Catalog specification makes /.well-known/ai-catalog.json an optional discovery location and permits catalogs at other URLs or in other distribution forms (Agent Card Working Group, "AI Catalog"). The RFC status of the prefix does not make the AI Catalog specification an IETF standard, and the familiar path does not establish client support.
What the document can describe
In the current AI Catalog specification, the top-level document has a specVersion and an entries array. An entry has an identifier and type, plus exactly one of url or data; host information and trust metadata are separate, optional layers (Agent Card Working Group, "AI Catalog"). The ARD v0.9 proposal adds discovery-oriented fields and describes registry behavior (Bu, Guha, and Smith).
The version field is important in a changing format. A publisher should validate against the version it actually implements rather than copy fields from a newer example into an older document. A small catalog with two accurate entries is easier to inspect than a long inventory assembled from stale deployment records.
The core fields are publisher-supplied statements. A description says what a resource is intended to do. A URL says where its native document is supposed to live. Optional trust material provides inputs for further checks, but its presence is not verification. The specification says that even a verified signature without an independently anchored identity establishes integrity and internal consistency only, not publisher authenticity (Agent Card Working Group, "AI Catalog"). At the Trusted Catalog level, a consumer must verify the signature, anchor the identity, and confirm the subject digest before relying on a claim (Agent Card Working Group, "AI Catalog"). MachineRead does not perform those trust checks. Syntax alone cannot establish availability, authorization, safety, or fitness for a task.
How to maintain a useful catalog
Start with resources that are already public and documented. Give each one a stable identifier, identify its artifact format with the type field, and point to the canonical resource document. Update or remove retired entries rather than leave stale URLs and descriptions.
Then test the catalog as an independent client would see it:
- Request the published URL without a browser session.
- Confirm that the response is JSON and declares the version you intend to support.
- Validate every required field against that version of the specification.
- Fetch each referenced public URL and compare its name, purpose, and version, where those fields exist, with the catalog entry.
- Keep credentials, internal hostnames, and private operational details out of the public file.
When protocol checks are selected, MachineRead treats the catalog as one optional discovery signal within its broader machine-surface check. The audit can report whether it received parseable JSON and whether selected fields meet MachineRead's limited structural expectations. It does not query an ARD registry, connect to a listed resource, verify catalog signatures or publisher identity, or infer that a provider consumes the file.
What this check can and cannot establish
The check can establish that the audited origin returned a candidate catalog at the checked path under the audit's request conditions. It can inspect JSON parsing, the declared version shape, selected host and entry fields, and whether a trustManifest key appears. Presence is reported as metadata, not verified.
It cannot establish that a registry has indexed the catalog, that a named client supports the specification, or that a listed resource is safe and usable. It also cannot predict search ranking, referral traffic, model citations, resource selection, or successful execution. Those later outcomes are not properties of the catalog response.
Works Cited
Agent Card Working Group. "AI Catalog." AI Catalog, Linux Foundation, https://ai-catalog.io/spec/. Accessed 7 Aug. 2026.
Agent Card Working Group. "Common AI Catalog and Registry Standard." GitHub, Linux Foundation, https://github.com/Agent-Card/ai-catalog. Accessed 7 Aug. 2026.
Bu, Junjie, R. V. Guha, and Shaun Smith. "Agentic Resource Discovery Specification." AgenticResourceDiscovery.org, version 0.9, 28 May 2026, https://agenticresourcediscovery.org/spec/. Accessed 7 Aug. 2026.
Nottingham, Mark. "Well-Known Uniform Resource Identifiers (URIs)." RFC 8615, Internet Engineering Task Force, May 2019, RFC Editor, https://www.rfc-editor.org/rfc/rfc8615.html. Accessed 7 Aug. 2026.
See also
- Methodology reference - documents the ai-catalog probe and the machine_surfaces check group
- Launch post - explains the audit's evidence boundaries
- Related: api-catalog.json and llms.txt