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

Paragon is Agent-Ready to agents.

Discry independently scored how well an AI agent can discover and understand the Paragon 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 · 93/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.Pass
AGENTS.mdAn AGENTS.md that tells coding agents how to build on the API.Pass
.well-known/mcp.jsonA discoverable MCP manifest at a well-known path.Partial
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.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

  • An agent can consume nearly the entire documentation surface without HTML scraping: every docs page is served as native markdown (.md, text/markdown), backed by llms.txt, a 2MB llms-full.txt, a .well-known/mcp.json, and a hosted 2.5MB OpenAPI 3.0 spec (docs.useparagon.com/actionkit/openapi.json) covering the full tool catalog.
  • The docs robots.txt explicitly opts INTO AI consumption with Content-Signal: ai-train=yes, search=yes, ai-input=yes — an agent crawler is affirmatively welcomed rather than merely tolerated.
  • Paragon ships first-party agent tooling beyond docs: an official paragon-mcp MCP server (listed on mcp.so, LobeHub, PulseMCP) and a paragon-ai-skills repo with AGENTS.md providing setup skills for agentic IDEs.
  • Rate limits are completely undocumented — the words 'rate' and 'limit' do not appear in the docs index, so an agent discovers throttling only by failing at runtime. Idempotency is also unmentioned.
  • Error responses are machine-parseable with requestIds and sample payloads, but recovery guidance is dashboard-oriented (Monitoring page log traces) — an agent hitting a common error gets no explicit 'do X to fix it' instructions.

What to change

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

  1. 01Publish a rate limits page documenting per-endpoint limits, 429 behavior, and retry/Retry-After header semantics — the single biggest capability-boundary gap.
  2. 02Add actionable recovery guidance for the top 5-10 error scenarios (e.g., expired Paragon User Token, missing actionkit JWT permission, integration OAuth failures) instead of pointing only to dashboard log traces.
  3. 03Slim llms.txt below 50KB and add one-line descriptions per link — it is currently a ~100KB flat link list, so an agent burns tokens navigating it.
  4. 04Add tool declarations to .well-known/mcp.json and host the MCP endpoint on a first-party domain (it currently points to a paragon.main-kill-isr.mintlify.me URL).
  5. 05Unify casing conventions across the API surface — query params are snake_case (limit_to_available) while body fields are camelCase (paginationParameters, pageCursor).

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.

Paragon User Token (JWT) Bearer authentication✓ Error format documented✕ Rate limits documented✓ Pagination documented✕ Idempotency documented

Auth (JWT Bearer via Paragon User Token), a machine-parseable JSON error format with message/code/status/requestId, and cursor-based pagination (paginationParameters/pageCursor) are all documented. Rate limits and idempotency support are not documented anywhere in the docs index.

See your own Discry Score.

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

Discry your API — free