Why AI Agents Pick One API Over Another

When a developer asks a coding agent to add a capability to an app — send a receipt email, take a payment, sync a calendar — the agent picks the API. It reads public documentation, assembles a short list of candidates, and builds against the one it can operate. The whole evaluation takes seconds, happens without a sales call or a comparison spreadsheet, and leaves no trace beyond the dependency that lands in the pull request.

The selection runs through three gates, in a fixed order: discovery, comprehension, construction. An API the agent cannot find never enters the candidate set. One it cannot understand drops out. One it cannot call correctly gets swapped for the candidate whose docs worked. Understanding how AI agents choose APIs means watching those gates operate on real documentation — so that is what this article does.

The three gates

Discovery is whether the agent can find a machine-legible version of your API at all. Agents fetch over plain HTTP, without executing JavaScript, and they navigate by machine-readable entry points: an llms.txt index at the docs root, an OpenAPI spec it can parse, an AGENTS.md brief, an MCP manifest at a well-known path. Discoverability is the gate that decides whether anything else about your documentation ever gets read.

Comprehension is whether the agent can operate your API from what it fetched: work out the auth scheme, build correct request shapes, recover from documented errors, respect your limits. Comprehension is where documentation that looks fine to a human reader either holds up under a model's reading or quietly falls apart.

Construction is the moment of commitment — the agent writes the integration and the first request either works or it fails. A failed first request against candidate A is rarely debugged with patience. It is the moment the agent tries candidate B.

This sequence is what agent-readiness names, and it is the sequence the Discry methodology measures: discovery, then comprehension, taken from the public documentation surface — the pages, specs, and entry-point files an agent actually fetches — before a single API call. What an agent can find and understand there determines what it chooses.

Watching a selection: "add transactional email"

Take the concrete case. A developer types "add transactional email for password resets" into a coding agent. The agent's first moves are fetches, and the transactional-email category shows how differently three real candidates answer them.

An agent that reaches Resend finds a compact llms.txt — about 2.3KB, structured into sections that route to the MCP server, the OpenAPI spec, SDKs, and the core docs. A fetch of /.well-known/mcp.json returns a manifest with tool declarations. Error documentation pairs every error code with a suggested recovery action, which is exactly the material an agent needs to handle a 422 without human help. The surface has gaps too — no AGENTS.md in the public repos, no llms-full.txt bundle — but the path from "first fetch" to "correct request" is short and machine-legible at every step.

Postmark answers differently. Its llms.txt exists and does something genuinely useful: it documents key limitations — message size, recipient caps, batch limits — which gives an agent the capability boundaries it would otherwise discover at runtime. But the file is large (around 62KB), and the deeper machine surface thins out from there: no publicly accessible OpenAPI spec, no AGENTS.md, no MCP manifest, no MCP registry presence. The endpoint docs themselves are clear and example-rich. An agent that arrives finds readable prose; an agent that navigates by machine-readable entry points finds fewer of them to follow.

SendGrid splits the difference in an instructive way. Its complete OpenAPI spec is findable through a public GitHub repo, and every docs page offers a "view as markdown" option — content a model can consume without scraping rendered HTML. But its llms.txt lives at the Twilio parent level: a 292KB file spanning every Twilio product, which an agent hunting specifically for the email API has to wade through on a fixed context budget.

None of this involves a score, and that is the point of the walkthrough: the selection pressure is visible at the level of individual fetches. Each answered or unanswered fetch moves a candidate up or down before any code is written.

Gate one: the candidate set is built from what is findable

Discovery failures are the quietest kind, because the API's producer never sees them — the agent simply builds the shortlist without you. Across the APIs the Discry Index scans, 64% publish an llms.txt and 54% expose a parseable OpenAPI spec . AGENTS.md adoption sits at 30% , and a discoverable MCP manifest at .well-known/mcp.json remains rare at 5% . Meanwhile 80% of scanned APIs already allow AI crawlers in robots.txt . Access is mostly granted; the missing layer is the index files that tell an arriving agent where to go.

The scan corpus surfaces the same recurring patterns behind those numbers:

• Good human docs, no machine surface. Documentation that reads well in a browser while llms.txt, llms-full.txt, .well-known/mcp.json, and the OpenAPI spec all return 404 — so an agent doing machine discovery comes up empty on an API a human would rate highly.
• Stale pointers. Lucinity's docs sitemap lists documentation URLs that now return 404 because the live reference moved — an agent following the declared map lands on dead pages. The signal exists; it points at the past.
• Manifests that reference the wrong environment. Firecrawl publishes a .well-known/mcp.json, but it points at a staging preview host and declares no tool list, so an agent trusting the manifest cannot enumerate capabilities from it. A present signal still has to be a correct one.
• JavaScript-only rendering. Docs pages that return only a loading shell on a plain HTTP fetch. Whatever the page shows a browser, the agent's copy is close to empty. See the llms.txt signal and OpenAPI signal pages for what a passing surface looks like.

Every one of these is fixable, and most are cheap to fix. That is a consistent property of discovery failures: they are verifiable facts about a public surface, and the remedies are files.

Gate two: comprehension is where lookalike docs diverge

Once an agent has your docs, the question becomes operational. Can it identify the auth scheme without guessing? Do endpoint descriptions say what an operation accomplishes, or only its shape? Are there realistic request and response examples it can adapt? When a call fails, does the documentation say what to do next?

The Discry methodology measures this behaviorally: real models are quizzed against the fetched docs — factual questions, request construction, and trap tasks that ask for capabilities the API does not support, where the correct answer is a refusal rather than a confident invention — and answers are graded mechanically against ground truth cited to the API's own pages. Producers have started designing for exactly this reader. Zapier's AGENTS.md gives coding agents explicit rules, including an instruction not to hallucinate method names and to discover capabilities at runtime through the SDK's own listing calls. Resend's per-error suggested actions are the same idea applied to failure paths. Both are documentation written for a reader that executes instead of skims.

Comprehension also carries a cost dimension. Routing routine work to cheaper models is standard industry practice, so the model reading your docs is frequently a small one. Documentation only a frontier model can operate loses the agents running where the volume is. That is what the capability floor describes: whether an API is small-model ready, or requires an advanced or frontier model before the docs become operable.

Gate three: the first failed request is the swap moment

Construction is where selection becomes final. The agent assembles the call — auth header, request body, the right endpoint — and runs it. When the docs supported comprehension, this step is uneventful. When they did not, the builder pays for it in the currency they actually budget: an afternoon of trial and error, a burned token budget, and an integration that "should have been simple" turning into archaeology.

The failure has a recognizable shape: docs that looked straightforward, a model producing plausible-but-wrong requests, and a fix that is either hours of manual spelunking or a switch to the candidate whose spec and examples let the first request succeed. The swap is rational. From the builder's side of the table, an API that costs a day of debugging has a real price that never appears on a pricing page.

Both sides lose the same failure

The shared stake is what makes this worth measuring. When an API fails a gate, two parties eat the cost at once. The producer loses an integration — silently, with no signal in any dashboard, because the agent that dropped them never filed a ticket. The builder loses the day, or ships on a second-choice API that fit the agent's reading rather than the team's actual preference. Agents assembling integrations are becoming a front door to the API market, and when your public docs fail the gates, the build proceeds with whichever candidate's docs worked.

Every pre-flight check an agent builder runs is an integration a producer wins or loses. That symmetry is why an independent measurement serves both sides at once: the builder gets ground truth before committing, and the producer gets to see the exact fetches and failures that shaped the choice.

Where to start

Discry measures discoverability, and discoverability is where the fixes concentrate: they are files you ship, not rewrites of the docs you host. Publish and verify a focused llms.txt, expose your OpenAPI spec where an agent can fetch it, add an AGENTS.md brief, and if you expose tools, put a correct MCP manifest at .well-known/mcp.json. The prioritized version of that list is in How to make your API agent-ready — and the fastest way to see which gates your API currently passes is to run the scan.

What grade does an AI agent give your API? Discry your API — free — 60 seconds, no signup.