# Notion docs: AI Agent Readiness Score 95.0% (A)

**95.0% · 76/80 · AI Agent Readiness Score · 26/30 reading points · 50/50 agent surface points**

Notion received 11 PASS votes and passed 5 of five agent surface checks. The clearest finding came from the find the exact limits task.

- Tested: 2026-09-22
- Published: 2026-09-22
- Battery: v1
- Scoring: reading 30 pts · surface 50 pts
- Docs: https://developers.notion.com/guides/get-started/overview

Three AI models, GPT 5.6 Sol, Claude Opus 5, and DeepSeek v4 Flash, each read Notion’s public documentation independently and attempted five first-hour developer jobs: create the first page, find the exact limits, recover from a 429, verify a webhook, use the JavaScript SDK.

No accounts, API calls, or code execution were used. Every verdict came from public pages and every published quotation passed a live verification check.

## Freshness

[How rechecks work](https://docsforagents.com/methodology/#freshness)

- Category: [Productivity & collaboration](https://docsforagents.com/grades/?category=productivity)
- Tested: 2026-09-22
- Quotes verified: 2026-09-22
- Surface rechecked: Not yet rechecked

## Agent surface checks · 50/50

| Check | Verdict | Points |
| --- | --- | --- |
| llms.txt | PASS | 10 |
| llms-full.txt | PASS | 10 |
| Markdown mirror | PASS | 10 |
| MCP server | PASS | 10 |
| Docs AI | PASS | 10 |

## The Reading Test · 26/30

| Task | GPT 5.6 Sol | Opus 5 | DeepSeek v4F | Consensus |
| --- | --- | --- | --- | --- |
| Create the first page | PASS | PASS | PASS | PASS |
| Find the exact limits | PARTIAL | PARTIAL | PASS | PARTIAL |
| Recover from a 429 | PASS | PASS | PASS | PASS |
| Verify a webhook | PARTIAL | PARTIAL | PASS | PARTIAL |
| Use the JavaScript SDK | PASS | PASS | PASS | PASS |

Docs platform: Mintlify (unscored) · verified 2026-09-22

## What to fix first

These 2 fixes could add up to 4 points to the AI Agent Readiness Score. The list ranks each fix by the points it would add. [How the ranking works](https://docsforagents.com/methodology/#what-to-fix-first)

1. **+2 points · Find the exact limits · PARTIAL**

   **Found:** The request limits page gives no number for the shared workspace limit, though it states 600 and 180 requests per minute per connection by plan.

   **Fix:** State the shared workspace request limit as a number for each plan on the request limits page, next to the per-connection rates.

   **Evidence:** [developers.notion.com/reference/request-limits](https://developers.notion.com/reference/request-limits)

2. **+2 points · Verify a webhook · PARTIAL**

   **Found:** The webhooks page warns that re-serialized JSON fails verification, then its manual sample signs JSON.stringify(body) over a parsed object.

   **Fix:** Rewrite the manual verification samples on the webhooks page to hash the raw request body, matching the warning that re-serialized JSON fails verification.

   **Evidence:** [developers.notion.com/reference/webhooks](https://developers.notion.com/reference/webhooks)

## What the docs get right

- **Create the first page: 3 PASS votes.** The quickstart covers PAT creation and a parentless POST /v1/pages request on one page.
- **Recover from a 429: 3 PASS votes.** The response reason identifies the limit, and the retry sequence covers Retry-After, retry, backoff with jitter, and a retry cap.
- **5 of 5 agent surface checks.** Present: llms.txt, llms-full.txt, markdown mirrors, an MCP server, docs AI.

## Create the first page

**PASS**

PASS consensus from 3 PASS.

The quickstart covers PAT creation and a parentless POST /v1/pages request on one page. The quickstart runs token creation to a created page in two steps, and the POST /v1/pages example needs no parent and no properties object because the markdown field supplies the title. One clear path from PAT creation in the Developer portal through env-var setup to a curl or SDK request that creates a workspace-private page.

## Find the exact limits

**PARTIAL**

PARTIAL consensus from 1 PASS, 2 PARTIAL.

The page gives exact per-connection and listed size limits, but omits numeric shared-workspace and child-depth limits. Per-connection rates are exact by plan (600/min for Business and Enterprise, 180/min for all other plans) and the size limits are a complete table, but the per-workspace limit that can independently reject a compliant client is never given a number for any plan. Per-connection rate limits are exact by plan and size limits have exact character, element, and byte counts in a clear table.

## Recover from a 429

**PASS**

PASS consensus from 3 PASS.

The response reason identifies the limit, and the retry sequence covers Retry-After, retry, backoff with jitter, and a retry cap. The page names the field that identifies which limit was hit, defines Retry-After as an integer number of seconds, gives a four-step recovery procedure with backoff, jitter and a retry cap, and ships working implementations in JavaScript, Python, Go and Java. Complete four-step recovery path documented with Retry-After header, rate_limit_reason to identify which limit was hit, exponential backoff, and retry limits.

## Verify a webhook

**PARTIAL**

PARTIAL consensus from 1 PASS, 2 PARTIAL.

The page completes setup and offers a correct SDK helper, but its manual snippets re-serialize parsed JSON before hashing. Subscription creation, the verification_token handshake and signature checking are all documented on one page, but the same page contradicts itself: the SDK tip warns that re-serialized JSON fails verification while the hand-rolled sample immediately below signs JSON.stringify(body) over a parsed object. Full end-to-end path: create subscription, receive verification_token, echo it back, compute HMAC-SHA256 on subsequent events to verify X-Notion-Signature, with sample validation code.

## Use the JavaScript SDK

**PASS**

PASS consensus from 3 PASS.

The quickstart names @notionhq/client and gives REST and SDK create-page examples with matching icon and markdown bodies. The quickstart shows the curl, raw HTTP and @notionhq/client forms as tabs of one example, so notion.pages.create({ icon, markdown }) is visibly the same request body as the POST /v1/pages reference, which documents markdown as a body parameter. The Quickstart provides matching curl and JavaScript SDK examples using the same API parameters (icon, markdown). The SDK's notion.pages.create() maps to POST /v1/pages shown in the curl form.

## The receipt

> A separate limit is shared across all of the workspace's connections and scaled to the workspace's plan.

The page gives exact per-connection and listed size limits, but omits numeric shared-workspace and child-depth limits.

- [developers.notion.com/reference/request-limits](https://developers.notion.com/reference/request-limits)

## Agent surface notes

Initialize returned HTTP 401 with a Bearer OAuth challenge naming resource metadata at mcp.notion.com/.well-known/oauth-protected-resource/mcp.

The hydrated docs home exposes a Mintlify Ask Assistant control and an assistant panel with a send-message input and an AI-generated response disclaimer.

## Method note

This is a reading test of public documentation, not an execution test. No accounts were created and no API calls were run. The AI Agent Readiness Score counts fifteen reading votes at PASS 2, PARTIAL 1, and FAIL 0, for 30 possible points. Five agent surface checks add 10 points each. The total is 80. Consensus chips show each row majority and do not affect scoring. The panel split on 2 of five tasks. Quotes shown here were re-fetched and confirmed verbatim on 2026-09-22.

Methodology: https://docsforagents.com/methodology/

Canonical URL: https://docsforagents.com/reports/notion-docs-ai-agent-readiness/