Calendly is Needs Work to agents.
Discry independently scored how well an AI agent can discover and understand the Calendly 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 · 40/100Comprehension
55% of score · 85/100What we found
- An agent that finds the docs gets near-production-grade endpoint reference: every operation leads with method, URL, purpose and required OAuth scopes, response bodies enumerate 400/401/403/404/500, and examples use realistic values (test@example.com, John Doe, America/New_York, real ISO-8601 timestamps) with full copy-pasteable JSON — comprehension scores a B (85).
- Calendly is unusually agent-forward for its category: it ships an official Calendly MCP server (dedicated /calendly-mcp-server and /schedule-events-with-ai-agents docs pages, listed on Smithery) and a new Scheduling API explicitly pitched for 'AI assistants and automation tools' — so an agent looking to book meetings has a first-class path.
- Discovery is the weak link (D, 40): an agent probing for machine-readable entry points finds no llms.txt, no llms-full.txt, and no .well-known/mcp.json — all return the styled 404 page — so there is no curated, token-efficient map of the API.
- No clean, single-file OpenAPI spec is publicly downloadable. The reference is OpenAPI-backed and rendered through Stoplight (with a public Postman collection), but an agent cannot grab a canonical openapi.json/yaml to generate a typed client without scraping the SPA.
- No AGENTS.md exists in Calendly's own GitHub org; the only AGENTS.md surfaced is in a third-party community CLI (bcharleson/calendly-cli), so coding agents get no first-party repo guidance.
What to change
Prioritized by impact on discoverability. You (or your docs platform) deploy these — Discry never touches your API.
- 01Publish an llms.txt at developer.calendly.com/llms.txt that summarizes the core scheduling workflow (authenticate → list event types → check availability → create invitee/booking → subscribe to webhooks) and links the key reference and recipe pages — the single highest-leverage discovery fix.
- 02Expose a downloadable OpenAPI spec (e.g. developer.calendly.com/openapi.json) so agents can generate typed clients directly instead of scraping the Stoplight SPA; the spec already exists behind the reference.
- 03Add an llms-full.txt with the full API reference as clean markdown so agents can ingest endpoint detail without rendering the JavaScript-heavy Stoplight/Gatsby pages.
- 04Add an AGENTS.md to the primary Calendly GitHub repo (and/or the official MCP server repo) with auth setup, scopes, and common task recipes for coding agents.
- 05Strengthen error-recovery guidance beyond rate limiting: for the top REST errors (400/403/404) give explicit 'what to do' steps (which parameter was invalid, which scope is missing) rather than just listing the status codes per endpoint.
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 execution documentation. Per-endpoint responses enumerate 400/401/403/404/500 with a machine-parseable JSON error schema, a dedicated Rate Limits page specifies 60 req/min (Free/Standard/Teams) and 120 req/min (Enterprise) with a Retry-After header plus X-RateLimit-Limit/Remaining/Reset, and cursor (page_token) pagination is documented per endpoint with next_page/previous_page URIs. Idempotency keys are not documented, including for the new Create Event Invitee (Scheduling API) write endpoint.