Scoring Methodology
How we calculate the Clarvia Score. Weights are based on real-world agent failure frequencies and developer pain points — not marketing narratives.
This methodology is also available as structured JSON at GET /api/v1/methodology
API Accessibility
25 ptsPublicly reachable endpoint returning 2xx
Median response time, target <200ms
OpenAPI security schemes documented
#1 cause of agent failures — X-RateLimit-* headers
API version in URL path or header
Official SDKs on PyPI/npm
Free tier or trial available
Data Structuring
25 ptsOpenAPI/JSON Schema published with typed models
Machine-readable pricing information
Structured JSON errors (RFC 7807 or equivalent)
Webhook endpoints or documented webhook system
Batch/bulk endpoints for efficient agent operations
JSON Schema or TypeScript type definitions published
Agent Compatibility
25 ptsRegistered on mcp.so, Smithery, or Glama
Agent-friendly robots.txt with AI agent rules
Sitemap, ai-plugin.json, .well-known configs
Idempotency-Key header for safe retries
Consistent cursor/offset pagination
SSE/streaming endpoints for real-time data
Trust Signals
25 ptsPublic status page with uptime metrics and history
API reference, guides, code examples, changelogs
Active changelog, recent updates within 30-90 days
Identical responses across repeated requests
Error includes code, message, and documentation link
Explicit deprecation/versioning policy documented
Published SLA or uptime commitment
v1.1 Weight Changes
Rate Limit Info: 3 → 6 pts
#1 cause of agent failures in production (429 errors)
MCP Server: 10 → 7 pts
Important but APIs work fine without MCP via OpenAPI specs
NEW: Idempotency Support (3 pts)
Critical for agent retry safety
NEW: Streaming Support (3 pts)
Essential for LLM-based API services
NEW: Pagination Pattern (2 pts)
Agents need to handle large datasets reliably
Trust Signals: restructured to 7 sub-factors
Response consistency, error quality, deprecation policy, and SLA now scored separately
Data Structuring: restructured to 6 sub-factors
Added webhook support, batch API, type definitions; removed CORS (moved to informational)
Scoring Philosophy
Clarvia Score measures how easily AI agents can discover and use your service. It does not measure company size, product quality, or business viability.
Weights are derived from agent-builder pain frequency: we prioritize factors that cause the most agent failures in production. Rate limit headers (6pts) outweigh SDK availability (1pt) because missing rate limits crash agents, while missing SDKs merely slow integration.
MCP support was reduced from 10 to 7 points because well-documented OpenAPI specs enable agent integration without MCP. We want to reward all paths to agent compatibility, not just one protocol.