◎ Discry Score
github.com
devtools · API
B
0 / 100
DISCOVERY0
COMPREHENSION0
Category leader: 96 (A)
Discry your API →
DEVTOOLS · RANK #10 OF 39

GitHub is Good to agents.

Discry independently scored how well an AI agent can discover and understand the GitHub API from what’s public — not whether it’s usable. Below: every signal we checked, what’s costing the score, and what to change.

Discry your API — freeView the docs ↗

SCORED UNDER RUBRIC 1.2 · A full re-launch under Discry Score 2.5 — a new behavioral instrument, not comparable to these scores — is in progress.

Discovery

45% of score · 81/100
OpenAPI specA machine-readable OpenAPI/Swagger spec agents can parse.Pass
llms.txtAn llms.txt index that points agents to the docs that matter.Pass
llms.txt qualityThe llms.txt is focused, current, and well under the size budget.Pass
llms-full.txtA full-text bundle agents can load in one request.Fail
AGENTS.mdAn AGENTS.md that tells coding agents how to build on the API.Pass
.well-known/mcp.jsonA discoverable MCP manifest at a well-known path.Fail
MCP registryThe API is listed in a public MCP registry.Pass
robots.txt AI directivesrobots.txt allows (or explicitly guides) AI crawlers.Pass
SitemapA sitemap so agents can enumerate the docs surface.Fail

Comprehension

55% of score · 93/100
Task-oriented descriptionsEndpoints described by what they accomplish, not just their shape.Pass
Realistic examplesRunnable, real-world request/response examples.Partial
Multi-step workflowsDocs that chain calls into complete jobs an agent can follow.Pass
Error-recovery guidanceDocumented failure modes and how to recover from them.Pass
Answer-first formatThe answer leads; preamble does not bury it.Pass
Capability boundariesClear limits — what the API can and cannot do.Pass
Naming consistencyConsistent, predictable naming across endpoints.Pass
Heading hierarchyClean heading structure agents can navigate.Pass
Markdown docsDocs available as clean markdown, not JS-rendered HTML only.Pass
Token efficiencyDocs are concise enough to fit an agent context window.Pass

What we found

  • GitHub's comprehension quality is near-perfect (93/100): the Article API at /api/article/body returns clean markdown for any docs page, dedicated troubleshooting page provides error recovery guidance, and multi-step workflow guides cover core use cases
  • The llms.txt is a best-in-class example — API-focused, right-sized (2.6KB), with structured sections explaining programmatic APIs for page listing, search, and article retrieval. Passes the new llmsTxtQuality check with full marks
  • Discovery improved from v1.0 thanks to AGENTS.md at github/awesome-copilot providing useful coding agent context, but sitemap.xml and .well-known/mcp.json remain missing
  • Error recovery guidance is strong: a dedicated troubleshooting page explains timeouts, 404s vs permission issues, and rate limiting with specific remediation steps
  • The OpenAPI spec is comprehensive (26,000+ lines, 76 endpoints, 284 schemas) publicly hosted at github/rest-api-description

What to change

Prioritized by impact on discoverability. You (or your docs platform) deploy these — Discry never touches your API.

  1. 01Add .well-known/mcp.json to docs.github.com with tool declarations for the official GitHub MCP server — enables automated agent discovery
  2. 02Add llms-full.txt at docs.github.com containing the complete REST API reference in markdown — the Article API already serves this content
  3. 03Add sitemap.xml to docs.github.com listing API documentation pages — the Page List API already provides this data
  4. 04Upgrade code examples to use realistic values instead of OWNER/REPO placeholders — response examples are good (octocat/Hello-World) but request examples use generic placeholders
  5. 05Add AGENTS.md to github/rest-api-description repo (the awesome-copilot one is good but not in the primary API repo)

Execution coverage · INFORMATIONAL, UNSCORED

Whether an agent can actually complete a call and recover from errors is the deeper Audit layer — documented here, but not part of the Discry Score.

personal_access_tokengithub_appoauth_appgithub_actions_tokenfine_grained_pat✓ Error format documented✓ Rate limits documented✓ Pagination documented✕ Idempotency documented

Multiple auth methods (PAT, GitHub Apps, OAuth, GITHUB_TOKEN, fine-grained PATs). JSON error responses with messages and documentation_url. Comprehensive rate limit docs (primary + secondary) with header names. Link-header pagination. No idempotency key support.

See your own Discry Score.

Drop your API docs URL. See what an agent sees — in 60 seconds, free.

Discry your API — free