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

Annotations already carry readOnlyHint=true, so the safety profile is covered. The description adds useful behavioral context about market coverage and Pinnacle as the reference source, but it doesn't address latency/freshness timing, pagination behavior, or whether results are limited by max_events beyond the schema. This is adequate but not rich.

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 purpose and each sentence has a role: source credibility, return contents, use cases, exclusions. The 'sharp bookmaker' phrase is slightly promotional but earns its place by explaining why Pinnacle specifically matters; overall compact and structured.

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 only 3 params, 100% schema coverage, and a read-only annotation, the description needs to carry the output/use-case burden, and it does by naming market types and typical applications. It could add a note on response shape or default pagination, but max_events already documents limits, so the definition is complete enough for an agent to invoke it 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?

Schema description coverage is 100%, so the baseline is 3: every parameter (sport_id, max_events, include_specials) is already documented clearly in the schema. The description's mention of 'optional props & specials' reinforces include_specials but adds no essential meaning 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 opens with a specific verb and resource: 'Current live (in-play) sports betting odds from Pinnacle' and enumerates the returned market types (moneylines, spreads, totals, team totals, specials). It distinguishes itself from siblings by emphasizing live/in-play and explicitly disclaiming historical archive and bet placement, so an agent can tell it apart from get_prematch_odds and similar tools.

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?

Use cases are explicitly listed — live odds displays, +EV screens, model features, Pinnacle leg of cross-book comparison — and exclusions are stated ('Not a multi-book aggregator, historical archive, or bet-placement tool'). It doesn't name sibling tools like get_prematch_odds as the alternative, relying on 'live' vs 'prematch', so it falls just short of a 5.

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