get_sports_eventsRetrieve event sections for a sport series, including trending or general sections, with pagination and event exclusion filters.
Retrieve events sections for a sport series (optional trending, optional live, and sport section). Same structure as home page.
| Name | Required | Description | Default |
|---|---|---|---|
| query | No | Query parameters and pagination; use the exact field names shown. | |
| seriesId | Yes | Series ID (path) |
Changes observed during successful MCP inspections.
v0.1.0Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the safety profile (readOnly, idempotent, non-destructive, openWorld), so the description's burden is lighter, but it adds almost nothing beyond them. 'Same structure as home page' references an undefined baseline and does not disclose pagination behavior, response shape, or what 'trending' vs 'live' actually changes in the result.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
It is a single short sentence, which is appropriately sized and front-loaded with the verb and resource. However, the trailing clause 'Same structure as home page' is unresolvable filler that consumes attention without conveying usable information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description is the only place an agent could learn what comes back, and the vague 'same structure as home page' does not deliver that. The input side is fully covered by a rich nested schema, which keeps this from being inadequate, but the return-side gap is real given the tool's openWorld read nature.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents seriesId, type, limit, offset, section, and excludeEventId, making 3 the baseline. The description gestures at 'trending/live/sport section' but does not map these terms to the `section` and `type` fields or clarify the interaction between them, so it adds little beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a verb and resource ('Retrieve events sections for a sport series'), which is clear enough at a high level, but 'sections' and 'same structure as home page' are undefined, and nothing distinguishes this from sibling tools like get_events or get_events_by_sport_slug. An agent still has to guess whether this returns events, markets, or layout blocks.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No when-to-use or when-not-to-use guidance is given, and no alternative is named despite get_events, get_events_by_sport_slug, and get_series_by_id appearing in the sibling list. The parenthetical '(optional trending, optional live, and sport section)' hints at available modes but does not explain when an agent should prefer one over the other.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.