Published 2026-09-21 · Tested 2026-08-19

MotherDuck

A

MotherDuck received 12 PASS votes and passed 5 of five agent surface checks. The clearest finding came from the use the Python SDK task.

Panel: GPT 5.6 Sol, Opus 5, DeepSeek v4F Battery: v1 Read as markdown (opens in a new tab)

Three AI models, GPT 5.6 Sol, Claude Opus 5, and DeepSeek v4 Flash, each read MotherDuck’s public documentation independently and attempted five first-hour developer jobs: run the first query, find the exact limits, recover from a connection error, authenticate end to end, use the Python 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: T3: A documented connection error replaced 429 because it is the closest common product error. T4: Authentication end to end replaced webhooks because the public docs expose no native MotherDuck product-webhook interface.

Freshness

How rechecks work
Tested
Quotes verified
Surface rechecked

No change since the test.

5 of 5 quoted passages still appear on the live pages.

MotherDuck Docusaurus 3.10.2 · published
A

96.2% · 77/80 · AI Agent Readiness Score · reading 30 pts · surface 50 pts

llms.txt PASS
llms-full.txt PASS
markdown mirror PASS
MCP server PASS
docs AI PASS
Task GPT 5.6 SolOpus 5DeepSeek v4F Consensus
Run the first query PASSPASSPASS PASS
Find the exact limits PASSPASSPASS PASS
Recover from a connection error PASSPASSPASS PASS
Authenticate end to end PASSPARTIALPASS PASS
Use the Python SDK PARTIALPARTIALPASS PARTIAL

docs platform: Docusaurus 3.10.2 (unscored) · verified 2026-08-19

What to fix first

This fix could add up to 2 points to the AI Agent Readiness Score. The list ranks each fix by the points it would add. How the ranking works

  1. 1
    +2 points Use the Python SDK PARTIAL

    Found: GPT found that the Python install guide requires a database name, while the database-selection guide makes it optional. Opus 5 found the pip version unrendered in the Markdown mirror.

    Fix: State on both Python pages whether a database name is required, and render the pip version in the Markdown mirror.

    Evidence: motherduck.com/docs/getting-started/interfaces/client-apis/python/installation-authentication (opens in a new tab)

What the docs get right

  • Run the first query: 3 PASS votes. The tutorial links account signup, offers direct in-page execution, and supplies a complete query against the auto-attached sample_data database.
  • Find the exact limits: 3 PASS votes. One plan table gives compute, storage, user, and service-account quotas, while its Flight values agree with the detailed Flights table.
  • 5 of 5 agent surface checks. Present: llms.txt, llms-full.txt, markdown mirrors, an MCP server, docs AI.

Run the first query

PASS

PASS consensus from 3 PASS.

The tutorial links account signup, offers direct in-page execution, and supplies a complete query against the auto-attached sample_data database. Part 1 states prerequisites, names the auto-attached sample_data database, gives the exact SQL for the NYC 311 and taxi queries, and tells a DuckDB client user to run ATTACH 'md:'; first, so no step requires guessing; the only wart is the opening line "Before playing with the dataset we just downloaded", which refers to a download that never happens on the page. The tutorial page provides the exact SQL query against the auto-attached sample_data database and gives clear connection instructions for all clients.

Find the exact limits

PASS

PASS consensus from 3 PASS.

One plan table gives compute, storage, user, and service-account quotas, while its Flight values agree with the detailed Flights table. Every limit class is stated numerically and the four pages that repeat them agree: Lite is 10 CU hours and 10 GB per month, 3 active users, 2 service accounts, Pulse only, and Flights capped at 30 minutes of compute per day with one concurrent run and a 1-hour per-run maximum, while Business is $250 per month, pay-as-you-go compute and storage, 10 active users, unlimited service accounts, all five Duckling sizes, and Flights with unlimited concurrent runs and an 8-hour per-run maximum. All plan limits are in a single comparison table with consistent categories and expand into detailed sub-sections for compute, storage, and flights.

Recover from a connection error

PASS

PASS consensus from 3 PASS.

The error page identifies same-path connections with different configurations as the cause and links to exact TTL syntax for recovery. The page reproduces the error string verbatim, names the cause as MotherDuck's longer-lived database instance cache, and gives three concrete corrections (unify the configuration, set the instance TTL to zero and close prior connections, or add a session_name suffix for overlapping connections), each linked to working syntax on the connecting page; in the markdown mirror two of those three links point at /documentation/... and 404, though the rendered HTML resolves them correctly. The docs identify the error text, explain the cause (database instance cache with different config), and give three complete recovery paths with cross-references to the TTL and session_name documentation.

Authenticate end to end

PASS

PASS consensus from 2 PASS, 1 PARTIAL.

The authentication and Python guides cover token creation, environment storage, database connection, and SHOW DATABASES verification. The whole path exists (create a token in the UI, export it, connect with duckdb "md:my_db", and confirm with SHOW DATABASES), but two pages must be reconciled: the authentication page says the environment variable is motherduck_token while the service accounts page says to "set MOTHERDUCK_TOKEN in your environment" with neither page stating that the name is case-insensitive, and the UI route to the token screen is given as Settings then "+ Create token" on the authentication page but as Settings > Integrations > Access Token in the tutorial. The full path is covered across two linked pages: create token in UI settings, store as environment variable or connection string parameter, then connect and confirm with a SHOW DATABASES query.

Use the Python SDK

PARTIAL

PARTIAL consensus from 1 PASS, 2 PARTIAL.

The Python landing page extraction failed, while direct guides supplied the SDK path but disagreed on whether a database name is required. The Python path itself is correct and agrees with the rest of the interface guidance (duckdb.connect('md:') or 'md:?motherduck_token=<your_access_token>', then con.sql("SHOW DATABASES").show() to verify, on a client version range that matches cloud-regions and duckdb-versions.json), but the install command an agent needs is an unrendered MDX template literal in the markdown mirror and in the getting-started llms-full.txt bundle, so only the rendered HTML page actually shows pip install duckdb==1.5.5. The Python SDK page gives the install command (pip install duckdb==1.5.5), both browser and token auth patterns, and a verification query that agrees with the general connection guidance elsewhere.

The receipt

When connecting to MotherDuck, you need to specify a database name (like my_db in the example).

The Python landing page extraction failed, while direct guides supplied the SDK path but disagreed on whether a database name is required.

Agent surface notes

Initialize returned JSON-RPC error -32001 with an OAuth or bearer-token authentication requirement.

The live docs render a public Ask AI button backed by runllm.com.

Show the score

AI Agent Readiness Score 96.2%, grade A

Paste this into a readme:

[![AI Agent Readiness Score 96.2%](https://docsforagents.com/badge/motherduck.svg)](https://docsforagents.com/reports/motherduck-docs-ai-agent-readiness/)

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-08-19.

Read the full methodology

Put another docs site through the battery.

Nominate a docs site