Paddle is Agent-Ready to agents.
Discry independently scored how well an AI agent can discover and understand the Paddle 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 · 88/100Comprehension
55% of score · 100/100What we found
- An agent that crawls developer.paddle.com finds best-in-class discovery scaffolding: a structured, API-focused llms.txt that splits into per-section files to dodge truncation limits, a 1.1MB llms-full.txt, an LLM-specific sitemap (sitemap-llm.xml), and a .md sibling reachable by appending '.md' to any documentation URL — so the agent never has to parse JS-rendered HTML.
- robots.txt uses the Content-Signal standard (search=yes, ai-input=yes) to explicitly invite AI agents to read and reason over the docs, while still opting out of training — a deliberate, agent-aware policy rather than a default allow.
- Paddle ships agent execution surfaces well beyond documentation: two hosted MCP servers (one for account actions, one for up-to-date knowledge), a loadable paddle-agent-skills repo for Claude Code/Codex/Cursor/Gemini, and an official OpenAPI 3.1 spec — an agent can go from reading to acting with no glue code.
- Endpoint pages are answer-first and task-oriented: 'POST /customers — Create a customer' leads with purpose and required permissions, then realistic copy-pasteable examples (jo@example.com, ctm_-prefixed IDs). Error pages add 'Common causes' and 'Common solutions' so an agent can self-correct after a failure.
- The one gap is the legacy .well-known/mcp.json discovery file (404) — but Paddle's two MCP servers are surfaced through PulseMCP and its own /sdks/ai docs instead, so agents still discover them; the missing well-known file is a near-cosmetic miss.
What to change
Prioritized by impact on discoverability. You (or your docs platform) deploy these — Discry never touches your API.
- 01Add a /.well-known/mcp.json manifest declaring the two hosted MCP servers and their auth so MCP-aware agents can auto-discover Paddle's tools without a web search — the only failing discovery check.
- 02Publish a top-level AGENTS.md in the primary SDK and MCP repos (paddle-node-sdk, paddle-mcp-server). Paddle already teaches users to add one for Codex; mirroring it in its own repos would turn the current partial into a full pass and guide coding agents working against the SDKs.
- 03Keep the llms.txt split structure but consider a short 'capabilities at a glance' block at the very top so an agent can confirm scope (subscriptions, checkout, payments, webhooks, merchant-of-record tax) in under a few hundred tokens before fetching section files.
- 04Surface the MCP servers and OpenAPI spec inside llms.txt itself (not just the docs nav), so an agent reading the index immediately knows action surfaces exist alongside the reference.
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 documentation is exemplary. Errors return machine-parseable JSON (type, code, detail, documentation_url, and a field-level errors array with request_id); rate limits are stated explicitly (240 rpm platform, 1,000 rpm for preview endpoints, 429 with a Retry-After header); pagination, idempotency keys, and retry patterns are documented as shared SDK behaviors.