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

Beyond the annotations (readOnly, idempotent, non-destructive), the description discloses the de-vigging algorithm, the model source (same Elo/Poisson path as football_match_predictor), the limitation that events_analysed only includes model-comparable events, and that meta.estimated is true with meta.is_stale reflecting odds freshness. This gives an agent a realistic picture of the tool's behavior and edge cases. There is no contradiction with 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 a one-sentence purpose, followed by a concise algorithm explanation and structured Args/Returns sections. Every sentence earns its place, covering the key behavioral nuance, filter semantics, and return shape without repetition or padding.

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?

Given the read-only annotations and an output schema, the description provides the essential invocation context: filter semantics, threshold behavior, return fields, sort order, model provenance, and the staleness flag. An agent has enough information to decide whether to call this tool and how to interpret its results.

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 fully documents team and min_edge. The description's Args section largely restates the schema, adding little new parameter-level meaning beyond reinforcing the default and the WC 2026 scope. With the schema doing the heavy lifting, the baseline of 3 is appropriate.

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 first sentence states a specific verb and resource: it surfaces gaps between the model's win probability and the market. The rest of the description makes the purpose concrete by defining the de-vigging process, the edge threshold, and the comparison to the server's own probabilities. It also distinguishes itself from football_match_predictor by clarifying it is the market-comparison layer, and its football scope separates it from cricket_find_value_bets.

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 invoke the tool: to find football value bets where model probability exceeds de-vigged market probability by at least min_edge. It explains how to narrow to a team or scan all WC 2026 odds events. It does not explicitly state when-not-to-use it or name alternatives like football_get_odds or football_match_predictor, so it stops 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.