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

Annotations already cover read-only, idempotent, and open-world traits, and the description adds substantial non-obvious context: access/delay/metered usage follow the connected account, empty results do not imply lack of coverage, affiliate 27 is excluded, and no wagers or account changes occur. This is genuinely useful behavioral disclosure beyond the structured hints, though it stops short of describing pagination or result shape.

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?

Front-loaded with purpose, then constraints; sentences are short and each carries a distinct constraint. Slight fragmentation ('Read-only Product data or price calculation.') and boilerplate-sounding clauses ('No wagers, account changes or guarantee of returns') keep it from a 5.

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?

An output schema and rich annotations are present, so return values and safety are covered elsewhere. The description fills in the account/access model and empty-result caveat, but leaves the sibling-differentiation and parameter semantics gaps unaddressed, making it minimally viable for a tool with ten effective query parameters.

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 effectively 0% — only affiliate_ids carries an inline description, while sort, type, limit, offset, event_id, market_id, min_percent, include_live, and include_closed are undocumented. The description only echoes the affiliate-27 exclusion and mentions 'by edge' for sorting, so it fails to compensate for the large documentation gap.

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?

States a specific verb (List) plus resource (Top Hedge Opportunities) and adds the ranking key ('by edge'), which is meaningful. However, it does not distinguish itself from the sibling v2GetHedgeOpportunities, so an agent cannot tell from the description alone why it should prefer this 'Top' variant over the plain one.

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?

Offers operational constraints ('One bounded request, no background polling or automatic retry', 'Use returned canonical IDs') but gives no guidance on when to choose this tool over v2GetHedgeOpportunities, v2GetHedgeOpportunitiesByEvent, or v2GetHedgeOpportunityByID. There is no explicit when-to-use or when-not-to-use statement.

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