Doist is Needs Work to agents.
Discry independently scored how well an AI agent can discover and understand the Doist API from what’s public — not whether it’s usable. Below: every signal we checked, what’s costing the score, and what to change.
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 · 62/100Comprehension
55% of score · 82/100What we found
- An agent that already knows about Todoist is well served: the unified API v1 reference is generated from an OpenAPI spec (downloadable, and mirrored on apis.io), and Doist ships an official MCP server listed on Glama, PulseMCP, and the GitHub MCP registry — so an agent can connect through a maintained, first-party tool rather than reverse-engineering endpoints.
- Comprehension is the standout dimension (82/B): the docs go beyond endpoint listings with dedicated conceptual guides for authorization, sync, pagination, and webhooks, plus consistent snake_case naming and realistic example values (real-looking UUIDs and cursors).
- Error recovery is genuinely agent-usable — error tables pair codes with explicit 'Solution:' steps (e.g. 'use a limit value of 200 or less', 'use the cursor exactly as returned', treat 400 command errors as terminal and do not retry), which is what separates self-correcting agents from ones that fail silently.
- Discovery is the weak spot (62/C): there is no llms.txt, no llms-full.txt, and no .well-known/mcp.json anywhere on doist.com or developer.todoist.com, so an agent that doesn't already know the API exists has no machine-readable on-ramp to discover it.
- The entire reference is one ~500KB single-page Redoc app (~125K tokens) with no concise overview or llms.txt, so an agent must ingest a massive JS-rendered page to grasp core capabilities — a real token-efficiency and markdown-cleanliness tax.
What to change
Prioritized by impact on discoverability. You (or your docs platform) deploy these — Discry never touches your API.
- 01Add an llms.txt at developer.todoist.com (and/or doist.com) with a titled, sectioned index linking to the auth, sync, tasks, pagination, and webhooks sections — this is the single highest-leverage discovery fix and would lift multiple discovery checks at once.
- 02Publish the OpenAPI spec at a stable, unauthenticated URL (e.g. developer.todoist.com/api/v1/openapi.json) and link it visibly from the reference, so agents and tooling can fetch it directly instead of relying on the JS-embedded copy or third-party mirrors.
- 03Add a concise 'overview' or quickstart page (<5K tokens) summarizing core resources and the minimal auth-to-first-call path, so agents aren't forced to parse the full single-page reference to understand capabilities.
- 04Serve a clean markdown representation of the docs (content negotiation or an llms-full.txt) so LLMs get structured headings instead of a flattened 500KB HTML-to-markdown blob.
- 05Publish a .well-known/mcp.json advertising the official Todoist MCP server so MCP-aware agents can auto-discover the first-party tool from the domain itself.
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.
Execution characteristics are documented unusually well: errors return machine-parseable JSON (error, error_code, http_code, error_extra), rate limits are spelled out with distinct full/partial sync budgets and server-provided Retry-After backoff, pagination is cursor-based with a dedicated guide (next_cursor, 'use the cursor exactly as returned'), and the Sync API documents command idempotency via client-generated UUIDs. Verification of actual runtime behavior requires a full Discry Audit.