# Discry — full-text bundle for agents > This is llms-full.txt: everything in llms.txt, expanded into full text, for agents that want the whole picture in one fetch instead of following links. Prefer /llms.txt if you just need the map. # Corpus, right now - Total indexed: 395 (scored: 324, insufficient-coverage: 1, docs-unreachable: 59) - Index contract version: 2.3.0 · generated 2026-09-07T01:01:40.335Z - Median scores across scored APIs: overall 67.7, discovery 47.4, comprehension 75.25 - Full data: https://discry.ai/api/index.json (JSON, filter: ?category=) or https://discry.ai/api/index.csv (CSV, same filter); decomposed per-row detail (capability floor, discovery/comprehension breakdown) at https://discry.ai/api/v1/index.json and https://discry.ai/api/v1/(.md) - Pricing: https://discry.ai/pricing — free scan; one-time Fix Kit (every failed task with its trace, discovery + comprehension artifacts, engineering brief, one confirmation re-run); "Discry on your repo" GitHub app (in development, waitlist); design-partner engagements # Discry MCP server - Endpoint: https://discry.ai/api/mcp (Streamable HTTP, stateless — no session setup required) - Tools: discry_find(need, category?) — search the Index; discry_profile(slug) — full score + evidence for one API; discry_compare(slugs) — head-to-head; discry_methodology() — how scores are measured + corpus stats. - No inference happens server-side: every tool is a direct read of the same data that backs the site, zero marginal cost. - Manifest: https://discry.ai/.well-known/mcp.json # Methodology, in full # Methodology: how the Discry Score works > The Discry Score is a behavioral measurement of API agent-readiness, taken from your public documentation surface: real models are quizzed on your live docs, and a pass requires a correct answer backed by a verbatim citation from those docs. Mechanically graded, Familiarity-disclosed, plain-fetch, fully published. Canonical: https://discry.ai/methodology · Markdown mirror: https://discry.ai/methodology.md # How the Discry Score works. AI agents are becoming a primary consumer of APIs. When a developer asks an agent to build something, the agent reads public documentation, works out which API it can operate, and quietly picks one. There is no sales call and no evaluation spreadsheet. There is just your documentation, read by a model, in seconds. The Discry Score measures how ready your API is for that moment. It looks only at your public documentation: the pages, specs, and entry-point files an agent actually fetches. What an agent can find and understand there is what decides whether it chooses you. There are two ways to lose that moment, and they happen in order. The first is that the agent never finds a usable version of your docs at all. There may be no machine-readable entry point, or the pages may render as empty for anything that is not a browser. A surprising share of APIs lose right here, before the quality of their documentation is ever tested. The second is that the agent finds your docs but cannot work from them. It misreads your authentication, guesses at your endpoints, or invents features you do not offer. The score measures both, in that order: discovery first, then comprehension. All of it happens before a single API call. ## The score at a glance - Discovery is graded first: can an agent find a usable, machine-readable version of your API at all? We look for signals like llms.txt, AGENTS.md, OpenAPI, and MCP presence, fetched the plain way agents actually arrive. - Comprehension is graded by experiment: real models are quizzed on your live docs. The questions cover facts, request construction, and traps that check whether a model invents features you do not have. - Grading is mechanical, never a matter of human opinion. A comprehension task passes only when the model gives the correct answer and backs it with a word-for-word quote from the docs we fetched. - Because a pass needs a quote from your live docs, a model cannot earn one from memory alone. Fame earns nothing. How much a model already knew is published separately, as Familiarity. - The score measures readiness on your public surface, before any code runs. Authentication, live calls, reliability, and SDK behavior are outside what it tests. - Every profile publishes its receipts: coverage, invalid runs, the URLs we fetched, and the tasks that failed. ## Two dimensions, one grade Every published grade breaks down into the same two dimensions, so you can see exactly where an API wins or loses: - **DISCOVERY: Can an agent find you?** The machine-readable surface of your API: llms.txt, AGENTS.md, an OpenAPI spec, MCP manifests and registry presence, crawlable sitemaps. We fetch all of it over plain HTTP, the way agents actually do. This is the gate. Fail it and nothing else about your docs matters. - **COMPREHENSION: Can an agent operate you?** The experiment: models across a range of capability tiers answer quizzes using your fetched docs as their only source. They find the facts, build correct requests, and refuse what you do not support. Everything is graded mechanically against ground truth cited to your own pages. ## Discovery: the failure that happens first Agents fetch over plain HTTP, without running JavaScript, and they navigate by machine-readable entry points. Discovery measures whether that path exists for your API. Is there an llms.txt that actually routes to your reference? An AGENTS.md that briefs a coding agent? A spec it can parse, or an MCP surface it can wire up? Serving these well earns credit directly. This is where a striking share of APIs lose outright, well-known ones included. Some documentation renders almost nothing without JavaScript. Some llms.txt files point agents at marketing pages instead of the API reference. When that happens, the profile says so plainly, with the reason and the URLs we tried. A discovery failure is a checkable fact about your public surface, and it is usually the cheapest thing on the page to fix. ### Isn’t MCP the answer? The Model Context Protocol is the clearest bet on how agents will consume APIs next, and the score credits it. Shipping a working MCP surface earns discovery credit today. MCP changes how a finished integration calls your API at runtime. It does not change how integrations get chosen and built in the first place. The coding agents that scaffold software on top of APIs still have to understand your endpoints, your auth, and your request shapes from your documentation, before any tool surface enters the picture. An MCP server is also a public surface an agent has to discover and understand. The discovery problem does not disappear behind a manifest; it just moves into one. Across the corpus, MCP servers remain rare, and a meaningful share of those that ship do not validate. The receipts are in the State of Agent-Readiness report. MCP quality is where the next edition of this measurement is headed, and every artifact is stamped with the surface it graded. ## Comprehension: the test you get to take if you’re found Once an agent has your docs, the question turns practical: can it actually operate your API? We answer that with an experiment, not a checklist. Models are quizzed from published task banks. The questions cover the facts an integration depends on (auth, errors, pagination, limits), requests to construct, and traps that ask for things your API does not support. On a trap, the right answer is to refuse, not to invent something with confidence. Grading is mechanical and grounded. A comprehension task passes only when two things are both true. The answer is correct against ground truth traced to a specific place in your docs. And the model backs that answer with a word-for-word quote, pulled from the documentation we actually fetched and checked against it. An answer with no quote from your pages does not pass, however confident it sounds. Trap tasks, where the correct move is to refuse, do not need a quote. ## Two boundaries, both deliberate Unlike docs platforms and checklist scanners, Discry independently tests real models against your public documentation and benchmarks the results across APIs. Holding that position means being clear about where the measurement stops: - **THE COMPETITIVE BOUNDARY: Discoverability, not usability** Discry measures whether agents can discover and understand your API, because that is what determines whether they choose it. We do not write or host documentation, and we grade every docs stack the same way, whether it is platform-hosted or hand-rolled. Usability matters, but it sits downstream and is not ours to claim. Staying out of the docs business is what keeps the grade neutral. - **THE MEASUREMENT BOUNDARY: Public-surface readiness, not runtime API quality** The score grades what an agent can find and understand on your public documentation surface, before anything executes. We do not test authentication, successful calls, reliability, SDK behavior, or end-to-end task completion. No Discry product tests execution, and nothing outside the canonical docs-surface path can reach the published Index. That separation is enforced in code, not by policy, by two independent guards. ## See the results The methodology is one page. The data is the product. Explore it wherever you work: - [The Discry Index](https://discry.ai/index): every scored API, ranked, with per-profile receipts - [Scan your API free](https://discry.ai/scan): probe your own discovery signals in seconds - [Machine-readable](https://discry.ai/api/index.json): the full index as JSON (CSV at /api/index.csv, this page at /methodology.md) # The instrument in depth ## How a score is produced 1. **Plain fetch**: We fetch your docs surface the way most agents do: plain HTTP, no JavaScript execution. What renders is what gets graded. 2. **Published task banks**: Every API is quizzed from versioned, published task banks: factual questions about auth, errors, pagination and limits; request-construction tasks; and trap tasks probing whether a model invents capabilities your API does not have. 3. **Models answer from your docs alone**: Models across capability tiers answer with your fetched docs as their only source. A separate closed-book pass runs the same questions with no docs, to establish what the models already knew. That result is published as the Familiarity metric. 4. **Grounded mechanical grading**: Answers are graded mechanically against ground truth traced to a specific location in your own documentation. A pass also requires the model to cite that location with a verbatim quote from the docs we fetched, checked against them. No quote, no pass, so a correct guess from memory does not count. Trap tasks, where refusal is correct, are exempt. 5. **Decomposition and receipts**: The result publishes as discovery + comprehension, with the profile’s coverage, invalid-run count, fetched URLs, and failed tasks alongside it. ## The plain-fetch policy The corpus is fetched over plain HTTP with no JavaScript execution, because that is how most agents fetch. If your documentation only renders with JavaScript, an agent on a plain fetch sees almost nothing, and we grade what it sees. Serving llms.txt or markdown mirrors is rewarded, because those are exactly the surfaces that make an API legible to agents. When a docs surface yields essentially nothing readable on plain fetch, the profile publishes as docs-unreachable. That is a rule-based failing grade, and it ships with the specific reason and the URLs we tried, so the result is verifiable and fixable. When an API publishes an llms.txt, that file is treated as its declared agent-facing entry point. If it routes agents to marketing pages instead of the reference, the grade reflects the surface the API itself chose to present. ## Familiarity: what a model already knew Frontier models have read a lot of API documentation in training, and for well-known APIs they can answer many questions from memory alone. We measure that directly. Alongside the open-book quiz, every task also runs closed-book: the same questions, with no access to your docs. The rate at which models answer correctly from memory is published as the Familiarity metric. Familiarity is a disclosure, not part of the score. It tells you how much of your API models already carry from training, and it does not raise or lower the grade. A high Familiarity earns no points, because a graded pass requires a verbatim quote from your live docs, and memory cannot produce one (see below). A low Familiarity costs nothing. In the rare case where a docs surface adds nothing an experiment can measure, the profile publishes as insufficient-coverage instead of being handed an unearned grade. ## Why fame doesn’t move the score The score measures your documentation, not your brand, and the mechanism that keeps it that way is the grounding requirement itself. The quiz harness holds your docs, and a graded pass requires the model to quote them verbatim. A model running on memory can often reproduce a fact, but it cannot produce a citation to text it was never shown. So prior knowledge, however deep, does not convert into a passing grade. It can only surface in Familiarity, which is disclosed and kept separate. The consequence is that every API is scored on the same basis, whether it is a household name or one you have never heard of: what its live documentation lets a model find, understand, and quote. A famous API earns nothing from being famous, and an obscure one loses nothing for being obscure. ## The capability floor: cost of comprehension Not every agent runs on a frontier model. Routing routine work to lower-cost models is standard industry practice, and the implication for an API producer follows directly: if only frontier models can understand your API from its docs, you are invisible where the volume is. The capability floor measures the piece of that we can measure: the lowest tested model tier that reliably operates the API from its documentation. Profiles carry a vendor-neutral label: small-model ready, advanced-model required, or frontier required, plus not-agent-ready and indeterminate where coverage cannot support a floor. The exact models and versions tested at each tier are disclosed in each artifact’s provenance. ## Run validity and coverage, disclosed Errored or aborted runs never fold into a published score, and profiles disclose their invalid-run count. Each profile also reports request-task coverage: how many of its five request-construction tasks produced gradeable capability extractions. When coverage is too thin to support a conclusion, the profile says indeterminate instead of guessing. The closed-book control is held to the same bar: if a majority of a profile’s closed-book runs fail to produce a clean answer, the scan fails loud rather than quietly reporting a score with no Familiarity check behind it. All published scores are produced in one canonical execution environment, and every artifact is stamped with the exact instrument version and the environment it ran under. We disclose that environment rather than claim scores transfer unchanged to a different one. Equivalence across environments is an open question, and we report it honestly instead of assuming it. ## Before publication, we audited ourselves Before we publish, two layers of self-audit run. The first is a census: mechanical validity checks across every artifact in the corpus, confirming that no errored run folds into a published median and no correct request is graded as wrong. The second is depth: on a stratified sample of APIs, every failed answer is re-ruled by hand at the trace level, to decide whether each failure is a genuine property of the documentation or an instrument error. The most recent full audit of this kind, run on the prior generation of the instrument, reached the conclusion quoted here in full, with 25 failed cells re-ruled by hand: > Before publication we audited a stratified 8-API sample of the corrected instrument (2.4.x) at the trace level — every failed task in each API’s reference run was independently ruled as a genuine documentation failure or an instrument error, with the API’s live agent-facing surface (llms.txt) fetched as a receipt where it drove the result. No sampled grade was overturned. One failed cell in 25 (4%) traced to an instrument error (a ground-truth extraction miss on one API’s auth-scheme fact), down from 84% before the correction round. Every low grade in the sample decodes to a verifiable property of the API’s own documentation surface. Separately, mechanical checks across all 196 artifacts confirmed zero errored runs folded into published medians and zero remaining cases of a correct request graded as wrong. > Source: Widened post-fix sample audit, 2026-07-18 The shipped instrument gets the same trace-level audit, at a wider sample, before the Index launches, and every edition of the Index thereafter. ## Known limitations, and the fix path for each - **GraphQL paradigm fit**: The request-construction task banks are REST-shaped, so GraphQL APIs fit the paradigm imperfectly today. Paradigm-aware task banks are on the instrument roadmap. - **Residual request sparsity**: Some docs yield few gradeable request-construction tasks, which leaves the capability floor thinly supported. This is disclosed per profile via the request-coverage line, and improved request targeting is on the instrument roadmap. ## Think your grade is wrong? The appeals path is a rescan, not an argument. Request an on-demand rescan of your API and the published profile updates from the fresh artifact. On-demand rescans land with the Index launch. Until then, start from the free scan. [Scan your API free](https://discry.ai/scan) ## An independent measurement, published in full Discry helps teams get agent-ready. That is the business, and we are not neutral about wanting every API on the Index to improve. So the measurement is built to be independent of us. Grading is mechanical, the task banks are versioned and published, every profile carries its receipts, and the same instrument grades every API. That includes this site, which ships its own llms.txt, AGENTS.md, and markdown mirrors to the standard it grades others on. The only thing that moves a grade is the documentation itself, verified by rescan. We publish everything: methodology, task banks, receipts, and the data itself in machine-readable form. We do it because agent-readiness is an industry-wide problem, and an open benchmark moves it faster than a private one. ## The independence charter Discry both grades APIs and sells fix artifacts. These commitments keep the two from ever touching: - Fixed, published scoring methodology. - Versioned instruments and reproducible receipts. - Identical scoring regardless of payment: no pay-for-grade, no vendor favoritism, honest Fs with receipts. - Fix purchases never guarantee grade movement. Artifacts are derived from what we measured, and the next scan judges them like anyone else’s. - Scoring and artifact generation are separate functions; the instrument never knows who is a customer. - Only canonical docs-surface scans enter the Index. A two-layer mechanical firewall keeps product-path and API-environment runs out of the published benchmark, enforced in code at scan time and again at index build. Paid work never buys a different instrument: a Fix Kit’s confirmation re-run is an ordinary Discry-run scan, judged like anyone else’s. # Guides ## What is llms.txt — and why your API needs one > The single highest-leverage file for making your API discoverable to AI agents. ### The one-paragraph version llms.txt is a plain-text index, placed at the root of your docs domain, that tells AI agents exactly which pages matter and in what order. Think of it as robots.txt for comprehension instead of crawling: not “what you may read,” but “here is the map.” Agents have small context windows. A good llms.txt is the difference between an agent loading your three canonical guides and an agent giving up on a 400-page docs site. ### What a good one contains A short description of the API, then a curated list of links grouped by task — auth, core resources, webhooks, errors — each with a one-line summary. Keep it focused and well under the size budget; a bloated llms.txt scores worse than a tight one. Pair it with llms-full.txt (the full text agents can load in a single request) when your core docs fit in a reasonable bundle. ### How Discry scores it Discry checks both presence (does llms.txt exist?) and quality (is it focused, current, and the right size?), and the behavioral scan follows your llms.txt as your declared agent-facing surface — if it routes agents to marketing pages, that is what gets graded. See the methodology page. --- ## AGENTS.md for APIs: the file coding agents look for > How to tell an AI coding agent how to build on your API — in the file it already checks. ### Why AGENTS.md Coding agents increasingly look for an AGENTS.md at a project or docs root: a concise brief on how to work with your system — conventions, auth setup, the golden-path example, gotchas. For an API producer, it’s where you hand an agent the “start here” it would otherwise reconstruct by trial and error. ### What to put in it The minimal viable integration (get a key → make one authenticated call → read the response), your naming conventions, rate-limit and pagination rules, and the two or three mistakes agents most commonly make against your API. ### How Discry scores it A usable AGENTS.md is one of the discovery signals Discry credits. It’s low-effort, high-signal — one of the most common quick wins in our recommendations. --- ## How to make your API agent-ready (a prioritized checklist) > The fixes that move your Discry Score the most, in order. ### Start with discovery Most APIs lose more points on Discovery than Comprehension — the signature finding across the Index. Ship an OpenAPI spec, a focused llms.txt, and an AGENTS.md first; add an MCP manifest at .well-known/mcp.json if you expose tools. ### Then tighten comprehension Rewrite endpoint descriptions to be task-oriented (“charge a customer,” not “POST /charges”), add realistic runnable examples, document multi-step workflows end to end, and write real error-recovery guidance. ### Then keep it passing Discoverability regresses silently on every deploy. Re-scan after any docs change so a refactor that drops your llms.txt doesn’t quietly cost you the agent channel. The free scan is unlimited; a Fix Kit includes one official confirmation re-run, and the Discry on your repo GitHub app (in development) will check each docs PR before it ships. Want the prioritized list for your API specifically? Run a free scan. # Notes for agents - Slugs are lowercase; unknown slugs 404, not an error object. - Scores carry a rubricVersion/harnessVersion stamp — v1.2 and the current behavioral instrument are different instruments, never mixed or trended together. - The full corpus is scored under the locked behavioral instrument, and band edges are ratified (no longer provisional). Rows without a score are labeled with their reason (docs unreachable, blocked, or insufficient coverage) rather than a fabricated tier. The Index grows continuously as new APIs are scanned under the same locked instrument. - Everything above is generated from the same data and copy that renders the HTML pages — nothing here is hand-duplicated or stale by design (methodology and resource text share source modules with the site; corpus stats are read live).