Best price

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

Annotations already cover read-only and open-world behavior, so the description only needs to add context, and it does: only currently-open prices count, suspended/expired prices are listed separately, line markets compare at a single line, and the call costs one object (billing). That is meaningful operational detail beyond the annotations, though return shape is only gestured at.

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?

Four sentences, front-loaded with the core purpose, and each sentence carries distinct information (scope, price eligibility, line semantics, billing). Slightly dense but nothing is redundant.

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?

No output schema exists, and the description compensates reasonably by indicating that non-best prices are also shown and that suspended/expired entries are listed separately. Coverage of parameters and behavior is solid for a 5-param read tool, though the exact return structure remains vague.

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 baseline is 3, but the description adds real meaning the schema lacks: the consensus-line default for line/total markets and the dependency that market+side is only needed when odd_id is absent. That goes beyond the enum/parameter descriptions without fully documenting every parameter.

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 opening sentence gives a precise verb and resource: it finds the best (highest) decimal price for one side of one market across bookmakers, and it states the secondary output ('show the rest of the field'). The reference to get_odds for odd_id helps separate it from that sibling.

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?

It clearly explains the two supported invocation routes ('Give market and side, or an exact odd_id from get_odds') and the fallback for line/total markets (your line, else the consensus line). It does not explicitly say when to prefer this over siblings like fair_odds, so it stops short of 5.

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