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.

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

Annotations only declare readOnlyHint and openWorldHint=false, and the description adds substantial context beyond that: the full calculation method, the fact that no API call occurs when prices are passed, what is reported (per-bookmaker margin and combined margin of best prices), and the important caveat that the result 'estimates the chance; it is not a prediction or a tip.'

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 purpose is front-loaded in the first sentence and the method, modes, and caveat follow in an orderly way. It is on the longer side and the method walkthrough is dense, but nearly every sentence carries information an agent needs, so little is wasted.

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 four-parameter tool with a nested prices object, no output schema, and only safety annotations, the description supplies what's missing: the algorithm, the two invocation modes, the reported outputs, and the interpretive caveat. Nothing an agent needs to call it correctly is absent.

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: it ties 'two- or three-way market' to the market enum, clarifies that event_id is used together with market, and frames prices as the by-hand alternative to the API path. It does not add further detail on the line parameter 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 names a specific verb and resource ('work out the no-vig (margin-free) fair price') and scopes it to two- or three-way markets, then details the exact proportional method used. An agent can tell this is a derived-metric calculator rather than a raw price lookup like get_odds or best_price without opening any 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?

It clearly states the two operating modes: 'Use event_id and market for live prices, or pass prices to calculate by hand with no API call.' That is explicit when-to-use guidance for each path, but it never names or excludes the sibling tools (get_odds, best_price), so the agent must infer the boundary itself.

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

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

Annotations already declare readOnlyHint and openWorldHint, and the description adds real value beyond them: it discloses the quota cost model ('every event returned counts as one object against the key's monthly allowance') and the practical effect of omitting league_id. It stops short of disclosing pagination or result ordering beyond the name-free fallback.

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?

Purpose and example queries are front-loaded, followed by return contents and then cost/parameter guidance; every sentence carries information. It is slightly dense but no sentence 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?

With no output schema, the description compensates by enumerating what is returned (start times in local and UTC, event IDs, best head-to-head price per side), plus quota mechanics and the no-team fallback. An agent has enough to call and interpret the tool 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 coverage is 100%, so the schema documents defaults for limit and days_ahead; baseline would be 3. The description adds rationale the schema lacks, explaining that passing league_id 'keeps the search small' and what happens with an empty team query, which meaningfully clarifies why the optional parameters matter.

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 (find) and resource (upcoming events/games) and clarifies the input style ('from a plain question such as...'). It is clearly distinguishable from siblings like get_odds, best_price, and list_leagues, which serve different retrieval purposes.

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?

Gives concrete when-to-use context: pass league_id whenever the league is known, and it explains the fallback behavior when no team is named. It does not explicitly name the sibling tools or state when to prefer them over find_event, so it stops short of a full when/when-not/alternatives treatment.

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

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

Annotations already declare readOnlyHint and openWorldHint, so safety is covered; the description adds real value beyond them by disclosing data freshness ('when it was last seen') and a consumption cost ('Costs one object'). It stops short of describing pagination, response size, or what happens when no bookmaker prices exist.

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 tight sentences, front-loaded with the core purpose, then the default market scope, then the all_markets expansion, then the cost. Every sentence carries information an agent needs; 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?

With no output schema, the description carries the return-shape burden and does so: prices are decimal, per bookmaker, with a last-seen timestamp. Combined with annotations covering the safety profile and full schema coverage on parameters, an agent has what it needs to call this 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 coverage is 100%, so the baseline is 3, but the description adds meaning the schema lacks: it defines the default market set and clarifies that all_markets pulls in 'every priced market, such as halves and props'. It says nothing extra about the bookmakers filter or the event_id format, which the schema already documents well.

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 gives a specific verb and resource ('Get every bookmaker's current decimal prices for one event') and enumerates the exact market set covered (head to head, line, total). It implicitly separates itself from siblings like best_price and fair_odds by scoping to all bookmakers and raw prices, but it never names or contrasts those siblings explicitly.

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 tells the agent when to flip all_markets to true (halves and props) and notes the cost ('Costs one object'), which is genuine usage guidance. However it never says when to prefer best_price or fair_odds over this tool, so tool-selection guidance is only implied by scope.

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

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

Annotations already establish readOnlyHint and openWorldHint, so the safety profile is covered. The description adds genuinely useful context beyond them: the tool is plan-gated and the free Developer plan only covers MLB, NFL, AFL and NRL, which matters for interpreting results. It says nothing about pagination or ordering, which is a minor gap for a small enumeration.

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?

Three sentences, front-loaded with the core purpose and free of filler; the plan-coverage detail earns its place as gating information. The trailing 'leagueID' reference slightly muddies the message since leagueID is not a parameter of this tool.

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 one-optional-parameter enumeration tool with no output schema, the description covers purpose, usage trigger, and the plan-access behavior an agent needs to interpret results. Only return-shape details (fields, ordering) are omitted, which is acceptable given no output schema exists.

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% for the single optional sport_id parameter, including an example value, so baseline is 3. The description mentions 'leagueID' but does not clarify sport_id's filtering semantics beyond what the schema already documents.

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 states a specific verb and resource ('List the leagues SockOdds carries') and adds what the response conveys (plan read-access per league). It is clearly distinct from odds-oriented siblings like get_odds and best_price, though it never names a sibling explicitly.

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 gives a clear triggering condition: 'Use it when you are unsure of a leagueID.' That tells the agent when this tool is the right entry point, though it does not state when not to use it or name an alternative lookup path.

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