An agent discovery file cannot be read
A file that agents look for under /.well-known/ answers, but cannot be read: agent-card.json (an A2A agent card), mcp.json (an MCP server descriptor), api-catalog (RFC 9727) or, on shops, ucp. It is not valid JSON, or it lacks a field it needs, such as the agent card's name or the API catalog's linkset.
What it means
A file under /.well-known/ that agents look for (the agent card, the MCP descriptor, the API catalog or the UCP profile) answers, but not with valid JSON, or without the fields it needs. Agents that find it stop there. Fix the file or remove it.
Why it matters for AI search
These files tell agents what a site offers: an agent to talk to, an MCP server, an API, a way to buy. An agent that finds one and cannot parse it gives up instead of guessing.
Most sites need none of them, so a missing file is never reported. A file that is there but broken usually comes from a test, a template or a plugin that was set up and forgotten.
How to fix it
- Open each file from the evidence and run it through a JSON validator.
- Fix the syntax and add the required fields, following the file's own specification.
- Serve it with
Content-Type: application/json(application/linkset+jsonfor the API catalog). - If the site does not offer what the file describes, delete the file. Run "Check again" on the page report to confirm the result.
Example
{
"name": "Example support agent",
"description": "Answers questions about orders",
"url": "https://example.com/a2a",
"version": "1.0.0",
"skills": []
} How to confirm the fix
After the change, press "Check again" on the report: it lists what was fixed and how the score changed.