How It Works

What callable() scores

callable() produces a single overall score (0–100) and grade (A+ through F). It’s driven mostly by agent-readability across 6 documentation categories, and also includes a smaller Agent Discoverability (AEO) component.

Supported formats

  • OpenAPI (JSON or YAML)
  • MCP manifests (/.well-known/mcp.json)
  • SKILL.md (structured markdown)
  • HTML docs (developer documentation pages)

Machine-readable formats (OpenAPI, MCP) score higher than unstructured HTML.

The 6 categories

Schema & Structure (25 pts)

Documentation format, number of endpoints documented, request/response schemas, and metadata (title, description, base URL). Machine-readable specs earn the most points here.

Error Documentation (20 pts)

Error status codes, structured error response format, recovery guidance, and breadth of HTTP status codes. Agents need to know what went wrong and how to fix it.

Auth Clarity (20 pts)

Authentication type, simplicity (API keys and bearer tokens are agent-friendly; OAuth is harder), usage examples, and security guidance.

Rate Limits (12 pts)

Whether limits are documented, specific numeric limits, rate limit response headers, and retry/backoff guidance.

Response Quality (13 pts)

Request/response examples, pagination documentation, and consistent response structure (shared envelopes, reused schemas).

MCP Readiness (10 pts)

MCP endpoint or manifest, MCP URL, OpenAPI auto-conversion potential, and tool/function patterns. Native MCP manifests earn full marks.

Agent Discoverability (AEO)

AEO contributes 10% of the overall score. It checks for high-signal discovery primitives that agents and answer engines rely on.

  • llms.txt at /llms.txt or /.well-known/llms.txt
  • Well-known OpenAPI at /.well-known/openapi.json (or YAML)
  • Well-known MCP manifest at /.well-known/mcp.json
  • robots.txt that allows crawling and references a sitemap
  • sitemap.xml listing your key docs/spec pages

Grading scale

A+95 – 100%A80 – 94%B65 – 79%C50 – 64%D30 – 49%FBelow 30%

How to improve your score

  • Publish an OpenAPI spec (JSON or YAML)
  • Document errors with structured schemas and recovery hints
  • Make auth obvious — type, headers, and a curl example
  • Add request/response examples to every endpoint
  • Document rate limits, headers, and retry behaviour
  • Expose an MCP manifest at /.well-known/mcp.json
  • Add /llms.txt (or /.well-known/llms.txt) and link your OpenAPI + MCP endpoints
  • Ensure robots.txt allows crawling and references sitemap.xml