◎ Discry Score
ably.io.com
infrastructure · API
B
0 / 100
DISCOVERY0
COMPREHENSION0
Category leader: 98 (A)
Discry your API →
INFRASTRUCTURE · RANK #26 OF 68

ably.io is Good to agents.

Discry independently scored how well an AI agent can discover and understand the ably.io 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 · 62/100
OpenAPI specA machine-readable OpenAPI/Swagger spec agents can parse.Partial
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.Partial
.well-known/mcp.jsonA discoverable MCP manifest at a well-known path.Fail
MCP registryThe API is listed in a public MCP registry.Fail
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 · 91/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.Pass
Naming consistencyConsistent, predictable naming across endpoints.Partial
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.Pass

What we found

  • Every documentation page ships a parallel .md version (e.g. ably.com/docs/pub-sub.md) and llms.txt links straight to them — an agent can read the entire platform's docs as clean markdown without HTML parsing.
  • llms.txt exists and is genuinely API-focused with ~35 structured, described sections, but at ~445KB it is roughly 10x the size an agent can comfortably load as an index — right-sizing it would turn a good signal into a great one.
  • An agent hunting for a machine-readable spec hits a dead end: the ably/open-specs GitHub repo declares itself deprecated 'in favor of the docs repository' (Aug 2024), and no OpenAPI spec is discoverable at any ably.com URL.
  • There is no Ably presence in the MCP ecosystem — no server listed on Glama/Smithery/PulseMCP and no .well-known/mcp.json — so agents get documentation but no ready-made tools.
  • Comprehension quality is excellent: endpoint docs lead with method + URL + purpose, the pub/sub guide shows an end-to-end connect→subscribe→publish workflow in 12 languages, and a dedicated limits page states concrete per-plan numbers.

What to change

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

  1. 01Publish a current OpenAPI spec at a stable ably.com URL (e.g. ably.com/openapi.json) and link it from the REST API reference; redirect or clearly supersede the deprecated ably/open-specs files.
  2. 02Slim llms.txt to under 50KB (or split it per product: Pub/Sub, Chat, Spaces, LiveObjects) and add an llms-full.txt for agents that want the full corpus in one fetch.
  3. 03Ship an official Ably MCP server and list it on Glama, Smithery, and PulseMCP; add .well-known/mcp.json so agents can discover it programmatically.
  4. 04Add AGENTS.md to the primary SDK repos (ably-js first) with API-usage context for coding agents — the existing ably-cli AGENTS.md only covers contributor conventions.
  5. 05Extend the errors page so the top API errors (401 token expiry, 429 rate limit, 40160 capability mismatch) carry explicit recovery steps, matching the quality of the existing SSL troubleshooting guidance.

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 key (basic auth)Ably TokenToken RequestJWT✓ Error format documented✓ Rate limits documented✓ Pagination documented✓ Idempotency documented

Execution characteristics are unusually well documented: a structured ErrorInfo object (code, statusCode, cause, nonfatal, href) is specified, per-plan rate limits carry concrete numbers, history endpoints document paginated results, and idempotent REST publishing is explicitly supported.

See your own Discry Score.

Drop your API docs URL. See what an agent sees — in 60 seconds, free.

Discry your API — free