Read-only MCP server for the Handigraphs Stats API v1
Three well-structured read-only tools with complete input schemas, proper Zod validation, and tool annotations. Descriptions are clear and action-oriented (avg ~80 chars). All parameters have type constraints and descriptions. query_stats is complex but well-documented with 15 optional parameters, each with min/max bounds. Error handling distinguishes ToolInputError from UpstreamError with safe redaction. Main gaps: output schemas are not formally documented (only visible via structuredContent in code), and no pagination guidance in descriptions despite cursor support.
Return live resource, metric, split, unit, and filter discovery.
List live sports and stats resources from public Handigraphs discovery.
Query one live Handigraphs Stats API resource. Use describe_resource first; pagination remains in this tool via cursor.
Output schemas not documented in tool descriptions. LLMs cannot predict response structure (fields, types, pagination behavior) without explicit schema documentation.
query_stats description lacks pagination guidance. Mentions 'cursor' in description but does not explain when/how to use it or what 'notModified' response means.
No dependency hints in tool descriptions. LLMs should be told to call describe_resource before query_stats, but this is only mentioned in query_stats description, not in discover_resource.
Error handling returns SafeProblem objects with status/code/detail, but descriptions do not explain error categories (retryable vs user-fixable vs fatal) or recovery actions.
| Scored | Grade | Overall | Spec posture | Rubric |
|---|---|---|---|---|
| 2026-09-23 | C | 67 | 2025-06-18+ | v2 |
metrics parameter in query_stats accepts array but no guidance on what happens if metrics do not exist for the resource. Should reference describe_resource discovery output.