# SurrealDB docs: AI Agent Readiness Score 82.5% (B-)

**82.5% · 66/80 · AI Agent Readiness Score · 26/30 reading points · 40/50 agent surface points**

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

- Tested: 2026-08-19
- Published: 2026-09-21
- Battery: v1
- Scoring: reading 30 pts · surface 50 pts
- Docs: https://surrealdb.com/docs

Three AI models, GPT 5.6 Sol, Claude Opus 5, and DeepSeek v4 Flash, each read SurrealDB’s public documentation independently and attempted five first-hour developer jobs: create the first record, find the exact limits, recover from a 429, authenticate end to end, 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. Preflight substitutions: T4: Authentication end to end replaced webhooks because http::post is an outbound query function, not a SurrealDB product-webhook interface.

## Freshness

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

- Category: [Databases & analytics](https://docsforagents.com/grades/?category=databases)
- Tested: 2026-08-19
- Quotes verified: 2026-08-19
- Surface rechecked: 2026-09-21

No change since the test.

4 of 5 quoted passages still appear on the live pages. The quoted page changed for Recover from a 429.

## Agent surface checks · 40/50

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

## The Reading Test · 26/30

| Task | GPT 5.6 Sol | Opus 5 | DeepSeek v4F | Consensus |
| --- | --- | --- | --- | --- |
| Create the first record | PASS | PASS | PASS | PASS |
| Find the exact limits | PARTIAL | PARTIAL | PASS | PARTIAL |
| Recover from a 429 | PASS | PASS | PASS | PASS |
| Authenticate end to end | PASS | PARTIAL | PASS | PASS |
| Use the JavaScript SDK | PASS | PARTIAL | PASS | PASS |

Docs platform: Custom Vike and React (unscored) · verified 2026-08-19

## What to fix first

These 2 fixes could add up to 12 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. **+10 points · Docs AI · check failed**

   **Found:** The live docs expose search but no Ask AI control.

   **Fix:** Add an assistant to the docs site that answers questions from the docs and links to its sources.

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

   **Found:** Instance docs call Free storage a small allowance and show 512 MB memory, while pricing lists 1 GB for each.

   **Fix:** State Free instance memory and storage as numbers in the instance docs that match the pricing page.

   **Evidence:** [surrealdb.com/docs/manage/instances/create](https://surrealdb.com/docs/manage/instances/create)

## What the docs get right

- **Create the first record: 3 PASS votes.** The Linux install, authenticated start, credentialed CLI, CREATE, and SELECT pages form a complete path without undocumented steps.
- **Recover from a 429: 3 PASS votes.** The reference gives Retry-After handling, a five-second fallback, a two-minute credit cap, and exit code 8.
- **4 of 5 agent surface checks.** Present: llms.txt, llms-full.txt, markdown mirrors, an MCP server. Missing: docs AI.

## Create the first record

**PASS**

PASS consensus from 3 PASS.

The Linux install, authenticated start, credentialed CLI, CREATE, and SELECT pages form a complete path without undocumented steps. One page carries the whole path end to end: install pointer, surreal start --user root --pass secret, surreal sql --username root --password secret --pretty, then CREATE person SET age = 20; and SELECT * FROM person WHERE age > 25; with the expected output printed, and the file-backed page confirms authentication is on by default. Install, start with root credentials, and create-via-HTTP are each shown with exact commands; a GET on the returned record id retrieves it in a single documented step.

## Find the exact limits

**PARTIAL**

PARTIAL consensus from 1 PASS, 2 PARTIAL.

HTTP limits agree, but Free memory conflicts: 512 MB in instance docs versus 1 GB on pricing. The per-endpoint body limits are exact and agree byte for byte across three independent pages, but the Cloud plan quotas are not stated as numbers in docs prose: the instances page defers to the off-docs pricing page and the Free instance type is described only as "a small storage allowance". All nine endpoint-specific limits are tabulated with their environment variable overrides; WebSocket per-message ceiling is 128 MiB. Plan quotas are not documented because SurrealDB Cloud charges by compute-hour and storage, not by request count.

## Recover from a 429

**PASS**

PASS consensus from 3 PASS.

The reference gives Retry-After handling, a five-second fallback, a two-minute credit cap, and exit code 8. All three asks are answered explicitly on one page, Retry-After is honoured, the fallback wait is five seconds, and the credit is "capped at a cumulative two minutes", with the retry budget (--retries, default 3), the rate_limited error kind, the retry_after_secs field, and exit code 8 documented alongside. The docs explain Retry-After honouring, a 5-second fallback when the header is absent, a cumulative 2-minute cap, and an exit code 8 when the retry budget is exhausted.

## Authenticate end to end

**PASS**

PASS consensus from 2 PASS, 1 PARTIAL.

The docs define database users, scope credentials with namespace and database flags, and verify identity through $session. The full path is documented (DEFINE USER, sign-in over the SDK and over HTTP, namespace and database selection, and a verifying query), but the security guide sends the sign-in body keys as NS and DB while the HTTP reference documents and demonstrates only lowercase ns and db. DEFINE USER, sign-in via HTTP and SDK, namespace/database selection headers, and verification through $session/$auth are each documented with concrete examples forming a single unambiguous path.

## Use the JavaScript SDK

**PASS**

PASS consensus from 2 PASS, 1 PARTIAL.

The HTML guide completes authenticated create-and-select and matches SDK transport docs; its advertised .md twin returned 404. The official SDK (npm install --save surrealdb) and a complete authenticated connect-create-select example are both present, but the example's own output contradicts its input, new Table('users') returns id: user:w6xb3izpgvz4n0gow6q7 and the follow-up query reads FROM product, and the connection URL disagrees with the security page, which uses ws://localhost:8000/rpc. The official npm package surrealdb is identified with import, connect, create, and select shown in a single coherent example; the WebSocket connection and authentication patterns match the HTTP/RPC protocol documentation.

## The receipt

> A request over the cap is rejected with 413 Payload Too Large. The 1 MiB cap on /sql is the one large queries tend to reach first.

HTTP limits agree, but Free memory conflicts: 512 MB in instance docs versus 1 GB on pricing.

- [surrealdb.com/docs/manage/instances/connect/via-http](https://surrealdb.com/docs/manage/instances/connect/via-http)

## Agent surface notes

Initialize returned a valid OAuth-protected MCP authentication challenge.

The live docs expose search but no Ask AI control.

## 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 3 of five tasks. Quotes shown here were re-fetched and confirmed verbatim on 2026-08-19.

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

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