Descope is Good to agents.
Discry independently scored how well an AI agent can discover and understand the Descope 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 · 83/100Comprehension
55% of score · 88/100What we found
- An agent looking for Descope's API can fully discover and consume it: a complete OpenAPI 3.0.3 spec (902KB, every public endpoint with request/response schemas) is one click away at /examples/Descope_API.yaml, robots.txt blocks no AI crawlers, and the MCP server is listed on Glama.
- Descope is unusually agent-native — in-docs 'Rules files' for Cursor/Claude Code/Copilot, an official descope/skills repo, a hosted docs MCP server, and a dedicated Agentic Identity Hub — but there is no canonical AGENTS.md in the primary repos, so an agent relying on that convention misses the (richer) equivalents.
- Comprehension is strong: endpoint pages lead with method and URL, descriptions are task-oriented ('Add roles to an existing user granularly without updating all user details'), and multi-step flows (the OTP two-phase initiate/verify flow, a full Next.js integration) are documented end-to-end.
- The biggest discovery drag is sizing: llms.txt is 268KB and llms-full.txt is 4.1MB — both far over an agent-friendly budget — so an agent that naively loads either burns context instead of getting a tight overview.
- Raw API-reference code samples are skeletal — multi-language tabs (cURL, JS, Go, Python, Java, C#) exist, but the cURL examples ship an empty 'Bearer ' header and `-d '{}'` bodies with 'string'/0 placeholder values, so an agent can't copy-paste a working call without filling in the blanks.
What to change
Prioritized by impact on discoverability. You (or your docs platform) deploy these — Discry never touches your API.
- 01Trim llms.txt to an API-focused index under ~50KB (link out to pages rather than inlining the full doc tree) and keep llms-full.txt as the deep resource — this would flip both llms.txt quality and token efficiency to pass.
- 02Populate the auto-generated API-reference examples with realistic values: a sample loginId/email, a non-empty request body, and a real-looking bearer token, so agents get copy-pasteable working calls instead of empty skeletons.
- 03Add an AGENTS.md to the primary repos (descope/ai and the key SDKs) pointing at the existing skills and .mdc rules — meeting the convention agents check first, even though the underlying content already exists.
- 04Publish /.well-known/mcp.json advertising the existing hosted docs MCP server (docs-mcp.descope.com) so agents can auto-discover it without a web search.
- 05Quick win: add the Retry-After and rate-limit header names to the Rate Limits page so agents have explicit, programmatic backoff guidance rather than just a 429 description.
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.
Strong, machine-parseable execution documentation: a dedicated Common Errors catalog with E-prefixed codes plus an 'Additional Context' column of causes and fixes, an explicit 429 rate-limiting page with best practices, and multiple documented auth methods (Bearer Management Key, OAuth2/OIDC, SAML, JWT). Pagination is not clearly specified in the scanned reference pages and idempotency keys are not documented. These are documented claims only — live behavior requires a full Discry Audit.