◎ Discry Score
notion.com
productivity · API
B
0 / 100
DISCOVERY0
COMPREHENSION0
Category leader: 92 (A)
Discry your API →
PRODUCTIVITY · RANK #3 OF 24

Notion is Good to agents.

Discry independently scored how well an AI agent can discover and understand the Notion 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 · 83/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.Pass
AGENTS.mdAn AGENTS.md that tells coding agents how to build on the API.Fail
.well-known/mcp.jsonA discoverable MCP manifest at a well-known path.Partial
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.Pass

Comprehension

55% of score · 88/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.Partial
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

  • Notion achieves strong scores across both dimensions (87/90) with llms.txt that is API-focused and right-sized, llms-full.txt (1.4MB), OpenAPI 3.1.0 spec, and multi-step workflow guides for building integrations
  • The status codes page lists errors with example messages and context (e.g., object_not_found includes the connection name) but lacks explicit recovery steps beyond 'try again' — earning partial on errorRecoveryGuidance
  • Multi-step workflow documentation is solid: guides cover building full integrations from auth setup through database queries and page manipulation end-to-end
  • Response examples still use generic placeholders (<string>) rather than realistic values, which impacts agent comprehension of expected output shapes
  • No AGENTS.md in makenotion repos despite having an official MCP server, agents SDK, and skills repo

What to change

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

  1. 01Add AGENTS.md to makenotion/notion-sdk-js or makenotion/notion-mcp-server with coding agent context
  2. 02Enhance error documentation with explicit recovery steps: what to DO on rate_limited (check Retry-After), object_not_found (verify sharing permissions), validation_error (check which field failed)
  3. 03Serve .well-known/mcp.json from developers.notion.com (not just notion.so)
  4. 04Replace <string> placeholders in response examples with realistic values
  5. 05Add idempotency key documentation for write operations

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.

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

Bearer token auth for internal connections and full OAuth 2.0 for public connections. JSON error responses with structured codes and messages. Rate limit of 3 req/s with Retry-After header. Cursor-based pagination with start_cursor and page_size. 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