Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds detailed behavioral context: definitions of opening/closing snapshots, the 14-day pre-kickoff window, the archive start date (2026-04) and its implication for opening_age_seconds, and the warning to compare points as well as prices. It also mentions free tier redaction. This goes well beyond the annotations.

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?

The description is front-loaded with the core function and then provides definitions, use-case, and caveats. Each sentence adds value, but it is somewhat lengthy with multiple caveats. It is well-structured and readable, though not as tight as a two-sentence description.

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 and 5 parameters, the description covers the key return fields (opening/closing prices, points, timestamps, opening_age_seconds) and important caveats (archive start, free tier redaction). It doesn't explain the response structure or undocumented parameters like markets and event_id, but the core semantics are sufficiently covered for an agent to invoke the tool correctly.

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?

The schema description coverage is 40%, with only period and bookmakers documented. The description refers to output fields like opening_price/opening_point/opening_at and opening_age_seconds, adding some meaning, but it doesn't explain the input parameters such as markets, event_id, or sport_key beyond saying 'for an event' and mentioning 'spreads and totals.' Thus it only partially compensates for the schema's gaps.

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 explicitly states 'Returns the OPENING and CLOSING line per (book, market, outcome) for an event,' providing a specific verb and resource. It distinguishes from siblings by calling itself the 'Canonical CLV-tracking helper' and noting it returns both data points 'instead of fetching full history and post-processing,' differentiating it from history endpoints.

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?

The description gives clear context for when to use this tool: for CLV tracking, as it returns both opening and closing lines in one call. It contrasts with alternatives by saying 'instead of fetching full history and post-processing,' implying this is the simpler choice. It also notes the free tier limitation, but doesn't explicitly name alternative tools or provide exclusions for other cases like current odds.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.