◎ Discry Score
twilio.com
communication · API
B
0 / 100
DISCOVERY0
COMPREHENSION0
Category leader: 98 (A)
Discry your API →
COMMUNICATION · RANK #12 OF 24

Twilio is Good to agents.

Discry independently scored how well an AI agent can discover and understand the Twilio 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 · 71/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.Partial
llms-full.txtA full-text bundle agents can load in one request.Fail
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.Fail
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 · 87/100
Task-oriented descriptionsEndpoints described by what they accomplish, not just their shape.Pass
Realistic examplesRunnable, real-world request/response examples.Pass
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.Partial
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.Partial

What we found

  • Twilio's documentation is exceptionally agent-friendly for comprehension: every page offers a native 'View as Markdown' link, code examples span 8+ languages, and endpoint descriptions are task-oriented with multi-step quickstart guides
  • The llms.txt file is massive (2,100+ KB, 497 sections) covering every product page — useful for discovery but too large for efficient agent consumption, earning only a partial on the new llmsTxtQuality check
  • An agent looking for workflow guidance would find dedicated multi-step tutorials (e.g., SMS quickstart, TaskRouter end-to-end, workflow automation) that chain operations together with error handling
  • Error recovery guidance is split between a help center article listing top 5 error codes with solutions and a large error dictionary that lists codes without actionable fix steps — partial coverage
  • Discovery gaps persist: no llms-full.txt, no .well-known/mcp.json, and no AGENTS.md in any Twilio GitHub repo despite having an official MCP server at twilio-labs/mcp

What to change

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

  1. 01Create a right-sized llms.txt (<50KB) focused on API capabilities and core endpoints rather than the current 2.1MB site-wide link index — this would convert the llmsTxtQuality check from partial to pass
  2. 02Add .well-known/mcp.json at twilio.com pointing to the official twilio-labs/mcp server with tool declarations for AI coding tools
  3. 03Add AGENTS.md to twilio/twilio-node or twilio-labs/mcp with SDK patterns, environment variable conventions, and common agent workflows
  4. 04Consolidate error recovery guidance into API docs — the current split between help center and error dictionary means agents cannot find actionable fix steps in a single location
  5. 05Create llms-full.txt with consolidated API reference markdown for core products (Messaging, Voice, Verify) to improve comprehension for agents that need full context

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_keybasic_auth✓ Error format documented✓ Rate limits documented✓ Pagination documented✕ Idempotency documented

HTTP Basic Auth with Account SID + Auth Token. JSON error responses with status, message, code, and more_info URL. Pagination via next_page_uri. Rate limits documented per product. No general 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