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

Annotations already declare this a read-only, idempotent, non-destructive closed-world tool, so the description only needed to add operational context — and it does: cost of 25 credits, the scope of the data searched ('every finished game we hold prices for that fits your filters'), and the aggregation grain ('one result per player per game at the median closing line'). It also adds a scope disclaimer ('describes the past and recommends nothing'), which is useful for an agent that might otherwise treat output as a forecast.

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 and return contents, then the example, then the grain, the disclaimer, the alternative, and finally cost — a sensible order with essentially no filler sentences. It is dense but readable; the cost note sits at the very end where an agent skimming the first sentence could miss it.

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?

For a 14-parameter aggregation tool with full schema coverage, an output schema, and explicit annotations, the description supplies the remaining decision-relevant facts: what gets counted, the unit of a result, the date/price coverage, and relative cost. Nothing an agent needs to call it correctly or interpret the response is missing.

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 coverage is 100%, so the schema already carries the meaning of all 14 parameters and a baseline 3 would be defensible. The description still contributes beyond that by explaining that filtering happens at the median closing line (which gives line_min/line_max real semantics) and by the example that maps market plus team_role plus home_away onto a query the agent can imitate.

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?

Opens with a specific verb and resource ('test an idea about player props') and immediately narrows the shape of the answer: hit rate versus market-implied probability over finished games matching the filters. It explicitly distinguishes itself from the closest sibling, get_prop_history, which covers one player game by game, so an agent can pick between them without reading either schema.

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?

States the use case ('test an idea about player props without pulling every row'), gives a concrete worked example of a hypothesis ('anytime goalscorer prices for players whose team was the home favorite'), and routes the agent to the alternative tool when the need is per-player history. The only unstated piece is an explicit when-not condition, which is effectively covered by the named alternative.

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