Always-up-to-date agent experience checklist

• Agent experience is a distinct practice from SEO and AEO — finding the right host, reading your docs, authenticating, calling an API or MCP (Model Context Protocol) server, and recovering when a link is dead.
• Ten checks cover an agent's first session with your product. A true 404 on unknown URLs and one canonical docs host are two frequent silent failures behind that.
• The rest of the list tracks MCP registries, agent skills, machine payments, and emerging specs like WebMCP — where a missing item is informational until you claim it.
• Re-run this checklist on a schedule as the underlying standards evolve.

Your next visitor could be an IDE assistant checking for an OpenAPI spec on your API, or a ChatGPT session trying to call your MCP server. If that visitor hits a dead link or a vague auth error, the session ends.

Search engine optimization (SEO) gets Googlebot to find you. The AEO checklist — short for answer engine optimization — gets you cited inside AI answers. Agent experience is a third, separate job that sits next to both — finishing a task once the agent has arrived.

This checklist walks through the 10 checks for an agent's start, then the longer list of items that track fast-moving standards around skills, payments, and discovery.

The top 10 checks for an agent's start

These 10 separate a completed task from an abandoned one. Finish them before the later sections.

1. Unknown URLs return HTTP 404

Agents follow links the way you do, except they don't notice a redesign and give up — they read the response the URL returns. If an unknown path answers with a 200 status and a soft-404 page, or a client-side router shell that renders nothing useful, an agent assumes the page exists and quotes empty HTML back to the user who asked. Check this on both your marketing host and your docs host. A docs subdomain that answers every path with 200 is a hard fail.

2. One canonical docs host

Pick one docs host and stick with it. When you retire a host, it should send a true 301 redirect, with the original path preserved, to the matching page on the live one. A JavaScript redirect that dumps every old topic onto the docs homepage loses the specific page an agent, or a person, was sent to find.

3. MCP server or manifest exists

MCP, the Model Context Protocol, is a standard that lets AI agents call tools and pull in data from outside systems. If your product has an MCP server, say so on a public page and back the claim with either a hosted endpoint or an installable package. "We have MCP" in a blog post with no URL attached doesn't pass — an agent needs something to connect to.

4. OpenAPI spec discoverable from this host

A public OpenAPI file — the machine-readable description of your API's endpoints and parameters — should be linked from your docs and reachable without an account. Hide it behind a login wall and agents are left guessing endpoints from blog posts and screenshots, and they'll get some of them wrong.

5. Official SDK packages

Named SDK packages on npm, PyPI, or whatever registry your audience's language defaults to, published under your company's name, beat a zip file buried in a docs screenshot. Agents install packages they can resolve by name; they generally can't transcribe code out of an image.

6. MCP well-known discovery from this host

A file at /.well-known/mcp.json, or the current discovery convention, on your marketing domain lets an agent that started at your website find your MCP server. If discovery is limited to a changelog entry, most agents will miss it. If you publish a discovery file, point it at a live URL.

7. Agent-friendly 404 body

A 404 status code is necessary, and the body needs a next step. It should point the agent toward your docs, your search, or your llms.txt file — a plain-text index of your site built for language models — so it has somewhere to go next. A polished 404 page with nothing but a homepage link strands anyone, human or agent, who followed a dead /docs/... link.

8. OAuth 2.0 or an explicitly open API

Agents authenticate the way a protocol tells them to: OAuth 2.0 with published metadata, or a clearly documented API key. Mystery auth schemes and "email us for access" fail this check outright, since there's no documented path for an agent, or a developer, to follow. Authorization-server metadata (RFC 8414) and protected-resource metadata (RFC 9728) both belong on the API host.

9. Developer portal and self-serve keys

A person, or an agent acting on their behalf, following your docs should be able to create an API key or start a trial without booking a call with sales. If onboarding can't start without a human in the loop, write that down as a known limitation. Do not label the API "self-serve" if the claim would not survive an audit.

10. llms-full.txt for docs dumps

llms.txt is a short, indexed list of your docs pages, useful mainly for getting found and cited. llms-full.txt is the corpus: the full text of your docs. A sitemap copy with one-line descriptions does not qualify. Build it from your docs bodies at publish time, the same discipline as treating your docs like a system of connected pages, so an agent can read the docs in one pass.

Agent basics and discovery

• Wikipedia or Wikidata entity. Covered in depth on the AEO checklist. For agent experience, a name collision with something else sends routing agents to the wrong tool.
• Listed in MCP registries. Publish both the hosted server and the local package in the official MCP registry so registry-aware clients can find you by name.
• NPM or PyPI SDK and CLI entry points. This overlaps with official SDK packages, but also covers the CLI commands agents will try on their own, like npx or pip install.
• Agent platform configs in the repo. CLAUDE.md, a .cursor/ folder, a VS Code MCP config, or the equivalent belongs in the public repo so an agent cloning it can start without extra instructions.
• Listed on skills.sh. Relevant if you publish agent skills. Absence here is informational until you ship skills.
• Agent-readable catalog at /.well-known. An optional catalog of agent-readable resources. Record it without blocking the audit.

Files and identity

• llms.txt exists, is a usable job index, and its links resolve. The index-quality question is an AEO item. Here, the test is narrower: an agent starting from /llms.txt should reach your API docs, MCP details, and getting-started page.
• Markdown copies of important pages. Optional per-page .md files are a reasonable stand-in when you haven't shipped llms-full.txt yet.
• Agent discovery file or "front desk." A start-here file for agents, separate from llms.txt, if you maintain one.
• Agent instruction or "when to use" file. Tells an agent when to reach for your product — as long as it's a file an agent will load.
• Product story matches the live company. Docs, MCP tool descriptions, and the homepage should all name the same product the same way.

OpenAPI

• Public API and docs linked from the homepage. Put them in the global nav. A footer link three clicks deep does not count.
• API catalog, the RFC 9727 .well-known/api-catalog convention. Still rare, and its absence is informational.
• Public API with reachable endpoints. Even an auth-required API needs a documented, unauthenticated error response so an agent can recognize an unauthenticated error.
• JSON error responses. 401, 403, and 429 responses should be JSON objects. A JSON content type wrapping a plain-text string does not pass.
• Rate limit headers. RateLimit and Retry-After, or a vendor equivalent, let an agent back off on 429s. Confirm this with an authenticated call, since many APIs send those headers after you log in.

MCP

• Modern transport. Hosted MCP servers should speak the current Streamable HTTP transport; local packages can reasonably use stdio instead.
• Auth matches the job. Hosted servers should use the user's OAuth; local packages, an API key. Mixing the two by accident confuses both agents and your own support team.
• MCP OAuth metadata (RFC 8414 / RFC 9728). Protected-resource metadata lives on the MCP host; authorization-server metadata lives on the API host.
• Product and docs coverage. Your MCP tools should cover the jobs your product sells. A docs-lookup tool is a nice extra; missing tools for your core product fails this check.
• Clear tool names, descriptions, and schemas. Plain descriptions and required parameters spelled out. A tool called do_stuff fails this check regardless of its behavior.

CLI and skills

• Official CLI. Optional if MCP and your SDKs already cover the jobs an agent would need to do. Be clear in your docs about which surface — CLI, MCP, or SDK — handles which task.
• Agent-skills index. A machine-readable index of SKILL.md files, needed if you publish skills.
• User-facing SKILL.md. At least one skill an agent can load, if skills are part of your product description.

Auth and tasks

• Unauthenticated install or "hello world." Something an agent can do without an account: a public spec, a mock server, or a documented trial. If nothing runs until someone signs up, say so plainly.
• auth.md walkthrough. A dedicated authentication walkthrough, or a clearly linked docs page that plays the same role.
• OAuth protected-resource metadata. Same family as the MCP OAuth metadata check, but it belongs on the API host.
• Onboarding without a human. Follows directly from having self-serve keys. If it isn't true yet, record it as a limitation.
• One end-to-end task. A documented path from authentication to one successful product action, whether that's a cloud task or a core workflow. Grading this needs an account, but it still belongs on the list.
• Human-gated steps are written down. Legal review, billing setup, seat invites — anything that needs a person should be in your docs. A surprise 403 should not be the first mention.
• Sandbox or test environment. A trial, sandbox, or test tenant. If your trial already functions as the sandbox, that's fine; note it.

Agent ops

• Community sitemaps. If your community is a product surface, it needs a crawlable sitemap. A Slack-only community is invisible to agents entirely.
• Agent vs. human logs. Separating agent traffic from human traffic in analytics or server logs gives support and rate-limiting a usable signal.
• Rate limits sized for agents. Hosted MCP and API limits should account for many users sitting behind a handful of platform IP addresses.

Payments

• Machine-payable APIs. Protocols like x402, MPP, ACP, and UCP are still optional for most B2B products, which bill through sales anyway — most don't yet have one settled spec page to point to. Record the absence.

Emerging standards

These are informational unless you've claimed them:

• WebMCP — in-page MCP for the browser.
• Agent2Agent (A2A) agent card at /.well-known/agent-card.json, from the A2A protocol.
• MCP Apps or generative UI, a proposed MCP extension for interface elements rendered inside the client itself.
• ChatGPT app directory listing, relevant if you've built a ChatGPT app.
• NLWeb /ask — a natural-language query endpoint.
• Agent mode view (?mode=agent) — a dedicated, agent-oriented HTML view of a page.
• Pricing.md or another parseable pricing file. A human-readable /pricing page is still the usual stand-in.

Keeping this checklist current

Items on this checklist will keep changing. MCP transports, OAuth metadata conventions, and agent-skill formats are all still being drafted somewhere, so the top 10 checks deserve a re-run after any doc migration, host change, or API redesign — a true 404 today can disappear in your next deploy.

Agent experience sits next to the SEO and GEO work you're probably already doing, applied to a different kind of visitor. If you've already run SEO and AEO checklists against your site, this one continues from those checks, testing an agent's ability to act on content it already found and was cited for.

Frequently asked questions

What is agent experience, and how is it different from SEO and AEO?

SEO gets a crawler like Googlebot to find and index your pages. AEO, the subject of the getting-started AEO checklist, is about getting cited inside AI answers. Agent experience is a third job: finishing a task against your product — finding the right host, reading your docs, authenticating, calling an API or MCP server, and recovering when a URL turns out to be wrong. It's a separate set of checks because a page can rank well and get cited often while still failing every agent that tries to act on it.

If we can only fix a few things first, which checks matter most?

Start with the three that strand an agent before it even reaches your API: a true HTTP 404 on unknown paths, one canonical docs host with real 301 redirects from anything you retire, and a 404 body that points somewhere useful (docs, search, or llms.txt). Those three are hard fails because a soft-404 or a dead redirect makes an agent think a page exists when it doesn't — everything downstream, from OpenAPI discovery to OAuth, assumes the agent reached the right page first.

Do we have to ship an MCP server to pass this checklist?

No. The MCP checks are conditional on an MCP server you already ship. If you have an MCP server, it needs to be stated on a public page with a real hosted endpoint or installable package — "we have MCP" in a blog post with no URL doesn't count. If you don't have one yet, skip those rows. Most of the MCP-specific and emerging-standard items on this list are informational until a team makes the claim.

What does "information, not a fail" mean on this checklist?

A chunk of the list — skills.sh listings, machine-payable APIs, WebMCP, an A2A agent card, and similar emerging items — applies once you've shipped the thing. Not having a machine-payable API is expected if your product bills through sales like most B2B software does. Record that fact. A docs host that returns HTTP 200 for every path actively misleads an agent.

How often should we re-run this checklist?

Re-run it after any doc migration, host change, or API redesign — more often than once a year. A canonical-docs-host check that passed last quarter can break the next time someone ships a new JavaScript router, and a 404 that worked correctly can regress silently in the same deploy that fixes something else. The standards this checklist tracks — MCP transports, OAuth metadata, llms.txt conventions — are also still moving, so an item that was information-only six months ago may be worth a real check today.

What's the difference between llms.txt and llms-full.txt?

llms.txt indexes your docs pages in a short, linked list, which is why it shows up on the AEO checklist too. llms-full.txt is the corpus itself: the full text of your docs, built from your docs bodies at publish time. A sitemap copy with one-line descriptions does not qualify. An agent limited to llms.txt still has to fetch every page one at a time; llms-full.txt lets it read the docs in one pass. See the llms.txt specification for the current convention.

Do we need OAuth if our API is public and unauthenticated?

If your API is genuinely open, say so clearly and document it as a plain API key or no-auth-required path — that's a pass. The check fails on ambiguous auth: no documentation, "email us for access," or an undocumented scheme. If you do use OAuth 2.0, publish the metadata agents expect, including authorization-server metadata (RFC 8414) and protected-resource metadata (RFC 9728), on the API host itself.

Where do payments and emerging standards like WebMCP fit in?

They sit at the edge of the checklist. Machine-payable APIs (x402, MPP, ACP, UCP), WebMCP, an A2A agent card, MCP Apps, a ChatGPT app directory listing, NLWeb's /ask endpoint, and a dedicated agent mode view are all still emerging. Most B2B products don't need them yet. Record the absence, and revisit the list as these specs (and your product) mature.

Related reading

• Technical SEO audit: how-to and template — a practical template for running a technical SEO audit alongside this agent-experience one.
• Getting started with AEO — the companion checklist for getting cited inside AI answers, distinct from the "can an agent finish a job" focus here.
• SEO and GEO services — where agent experience sits next to the broader SEO and GEO work this checklist assumes you're already doing.