agentic‑readiness docs
/
Scan at scale Blog Build one › Run a scan ›

Scan at scaleSites with a broken Agentic Resource Discovery file

Sites with a broken Agentic Resource Discovery file

A site-wide report: one row per host, over the ard rows the crawl emitted.

What this report returns

Agentic Resource Discovery (ARD) is a file at /.well-known/ard.json, or the older /.well-known/ai-catalog.json, listing the agents, MCP servers and APIs a site offers, each with a stable name, so an agent or a registry can find them from one address. Google's Lighthouse audits it.

A row appears here when any of these is wrong, worst first:

  • Malformed DocumentThe file is served as application/ai-catalog+json but has no entries list, so a consumer finds nothing in it.Fix Shape it as {"entries": [{"identifier": "urn:air:example.com:assistant", "displayName": "Assistant", "type": "application/mcp-server-card+json", "url": "https://example.com/mcp/card.json"}]}.
  • Entry Missing IdentifierAn entry has no identifier, the stable handle registries index it by, so it can't be listed or found.Fix Add "identifier": "urn:air:example.com:assistant" (your domain, then a name).
  • Entry Missing TypeAn entry has no type, so an agent can't tell whether it points at an MCP server, an agent card or an API.Fix Add the media type, e.g. "type": "application/mcp-server-card+json".
  • Entry URL And DataAn entry carries both url and data, or neither, but must carry exactly one, so a consumer can't tell where its content is.Fix Keep one: "url" pointing at the document, or "data" with it inline.
  • Entry Missing Display NameAn entry has no displayName, which every entry must carry, so it is rejected by validators such as Lighthouse and shows no name to people.Fix Add "displayName": "Example Assistant".
  • Entry Invalid IdentifierAn identifier isn't in the urn:air: form with your domain as publisher (e.g. urn:ai: or a plain URL), so registries can't anchor it to your site.Fix Use "urn:air:example.com:assistant", with your full domain after urn:air:.
  • Entry Type Not Media TypeAn entry's type is a word such as "documentation" rather than a media type, so an agent can't tell how to read what it points at.Fix Use a media type, e.g. "type": "application/openapi+json".
  • Invalid Trust ManifestAn entry's trustManifest has no identity, or gives it as an object rather than a string, so a registry can't verify who publishes the entry.Fix Set "identity": "did:web:example.com" or "spiffe://example.com/agent".
  • Trust Identity MismatchAn entry's trustManifest.identity names a different domain from the publisher in its identifier, which the specification forbids because it is how one site could pose as another; verifying registries reject the entry.Fix Issue the identity from the domain in the identifier, e.g. did:web:example.com for urn:air:example.com:assistant.

A note, not a fault: we also mention when the file is only at the older address. It never fails the site.

Spec: ARD v0.91, sections 4.1, 4.3, 4.5.1 and Appendix C. Sites that publish no ARD file don't appear here, because absence is not a failure.

The columns it shows

Every defect this technology can carry is a column in the grid, worst first, so nothing is hidden behind a filter you have to know to apply.

  • Hosthost
  • ARD ValidardValid
  • ARD FindingsardFindings
  • ARD PathardPath
  • ARD Entry CountardEntryCount
  • ARD Faulty IdentifiersardFaultyEntries
  • ARD Malformed DocumentardMalformedDocument
  • ARD Entry Missing IdentifierardEntryMissingIdentifier
  • ARD Entry Missing TypeardEntryMissingType
  • ARD Entry URL And DataardEntryUrlAndData
  • ARD Entry Missing Display NameardEntryMissingDisplayName
  • ARD Entry Invalid IdentifierardEntryInvalidIdentifier
  • ARD Entry Type Not Media TypeardEntryTypeNotMediaType
  • ARD Invalid Trust ManifestardInvalidTrustManifest
  • ARD Trust Identity MismatchardTrustIdentityMismatch
  • ARD Predecessor Path OnlyardPredecessorPathOnly

About Agentic Resource Discovery (ARD)

A file at /.well-known/ard.json listing the agents, tools and APIs a site offers, each with a stable name.

Read how Agentic Resource Discovery (ARD) is checked, including the specification it is validated against and a worked correct and broken example.

Running it

This report comes with Agentic Readiness in Lumar and appears on every crawl of any project that has it turned on. See the whole set, or check a single URL with the scanner on this site, which runs the same code with no account.

Get Lumar pricing