Cal.com is Agent-Ready to agents.
Discry independently scored how well an AI agent can discover and understand the Cal.com 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 · 86/100Comprehension
55% of score · 96/100What we found
- An agent looking for Cal.com would find it immediately and orient fast: a well-structured root llms.txt with an explicit 'Instructions for AI Agents' section, a dedicated /docs/llms.txt index, an 'AI agents' guide, and an officially hosted MCP server (mcp.cal.com) all point agents straight at the v2 API.
- Endpoint docs are unusually agent-friendly — every page leads with method, URL, a realistic cURL example (John Doe / example.com values), and full request+response JSON, backed by clean per-page .md versions, so an agent parses them losslessly without fighting JS rendering.
- Capability boundaries are explicit throughout: documented rate limits, per-request caps (max 10 guests/request, 30 total; metadata 50 keys/40-char/500-char limits), which conferencing apps can be installed via API, and plan-gating (org-only endpoints return 403) — an agent learns limits from the docs rather than by failing.
- A publicly accessible OpenAPI 3.x spec (cal.com/docs/api-reference/v2/openapi.json + Swagger UI at api.cal.com/v2/docs) lets an agent machine-read the full surface, and a substantive AGENTS.md in calcom/cal.com gives coding agents real repo conventions.
- The main friction for an agent is versioning and error recovery: the required cal-api-version header differs per endpoint (bookings need 2026-02-25, event-types need 2024-06-14) and omitting it silently downgrades to an older version, while there is no centralized error-code reference with retry/recovery steps (e.g. 429 Retry-After handling) — guidance is scattered inline.
What to change
Prioritized by impact on discoverability. You (or your docs platform) deploy these — Discry never touches your API.
- 01Add a real llms-full.txt (and/or wire /llms-full.txt to the docs) — the current path resolves to a user booking page, a quick fix that would let agents pull the full corpus in one request.
- 02Publish a dedicated error-handling reference covering the top error scenarios (401, 403/scope, 404/missing cal-api-version, 429) with explicit recovery steps and rate-limit header names, so agents can self-correct instead of guessing.
- 03Standardize or clearly surface the cal-api-version header — a single current version (or a prominent per-endpoint callout) would stop agents from silently hitting deprecated endpoint behavior.
- 04Serve a .well-known/mcp.json describing the hosted MCP server's tools and auth, so MCP-aware agents can discover Cal.com's official server automatically rather than relying on third-party registry listings.
- 05Document idempotency-key support for write endpoints (create booking, create event type) so agents can safely retry on network failures without creating duplicates.
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 characteristics are well documented: four auth methods with explicit token lifecycle (60-min access tokens, 1-year refresh, force-refresh recovery), a consistent JSON envelope ({status: success|error, data}), explicit rate limits (120 req/min default, tighter per-endpoint caps like 5/min on add-guests), and offset (take/skip) pagination on list endpoints. No idempotency-key support is documented, so an agent cannot safely retry writes without risking duplicate bookings.