FastballAPI

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

Annotations only cover read-only/idempotent/closed-world, so the description adds real value: a concrete cost ('5 credits') and hard policy constraints on what the agent may do with the odds data (no staking, payout math, bet recommendations, or sportsbook referrals). What it doesn't disclose is failure modes (unknown game_id, league default behavior beyond the schema default).

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 compact sentences, front-loaded with the primary use case, then the sibling routing, then the cost and compliance guardrail. No filler and nothing important buried.

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 exists, so return-value explanation is unnecessary, and the description covers purpose, sibling routing, cost, and data-use guardrails. For a two-parameter read tool with full schema coverage, an agent has everything needed to select and call it 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 description coverage is 100% and both game_id (source of ids) and the league enum are already documented in the schema. The description adds no syntax or format detail beyond that, so baseline 3 applies.

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?

Names a specific verb+resource ('one game in full') and enumerates the payload at a level no sibling offers: line score, every batter/pitcher line, each sportsbook's opening and closing line, win-probability range. This is clearly distinguishable from get_games (list) and get_plate_appearances (granular), which the description explicitly routes to.

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 an explicit alternative with a condition: 'For every plate appearance use get_plate_appearances.' Absence of when-not guidance versus get_games or get_odds is the only gap; scope ('one game in full') implies the rest.

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 carry the read-only/idempotent/non-destructive profile, but the description adds two things they cannot: the 'newest first' ordering and the 'Costs 2 credits' cost signal. It does not discuss pagination behavior despite offset/limit params, which keeps it from a 5.

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?

Two routing sentences plus a trailing cost note, with the primary purpose front-loaded and zero filler. Every clause carries either scope, routing, or cost information.

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 an output schema present, return-shape explanation is unnecessary, and the description covers scope, ordering, sibling routing and cost for a 10-param tool. The only gap is that pagination semantics for offset/limit are left entirely to the schema.

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 80%, so the schema already documents date, range, team, season, status, league and limits. The description's 'by season, date, date range or team' phrase confirms which axes are combinable but adds no format or default detail (e.g. limit 50, league default mlb) beyond what the schema provides. Baseline 3.

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 and resource ('list games') plus the returned content ('runs, hits and errors') and the filter axes ('by season, date, date range or team'). It is immediately distinguishable from get_schedule and get_game, which it names 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?

Gives an explicit routing rule: use get_schedule for upcoming games with lines, use get_game for a single box score. When-to-use and when-to-use-something-else are both spelled out with the condition that selects each alternative.

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 readOnly, idempotent, non-destructive, and closed-world, so safety is covered. The description adds two things annotations cannot: the 2-credit cost and the snapshot semantics (latest day, or latest on/before the supplied date), which materially affects how results should be interpreted.

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?

Two sentences, zero filler: purpose and payload first, then the date-resolution rule and cost. Every clause carries information an agent needs before calling.

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 exists, so return structure need not be described, and cost plus snapshot behavior are covered. However, for a 2-parameter tool, leaving the team filter completely undefined is a real completeness gap.

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 50%: date is documented in the schema and reinforced in the description with the on-or-before fallback rule. The team parameter is bare in the schema and unexplained in the description — it is unclear whether it filters players by team or selects a team-specific report.

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 resource and the exact payload: player status, injury, and expected return, as of a snapshot date. No sibling covers injuries, so it is easy to place, though it never explicitly contrasts with get_player, which may also expose injury fields.

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?

"Use for the injury report" implies the trigger, and the parenthetical clarifies date defaulting to the latest snapshot on or before the given date. There is no when-not guidance and no mention of an alternative tool for historical injury data or per-player lookups.

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 read-only, idempotent, non-destructive, and closed-world behavior. The description adds useful behavior beyond that: it states the cost (5 credits) and defines qualification thresholds for batting and pitching stats, which affect which players appear.

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 "Use for" and packs the stat list, qualification thresholds, and credit cost into one dense but efficient sentence. Every clause carries operational information.

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 exists, so return values need not be described. The description covers purpose, stat categories, qualification defaults, and cost; the only notable gap is that it does not explain the limit parameter or how results are ranked/limited.

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 67%, and the description adds meaningful semantics beyond the schema by grouping stats into batting and pitching and specifying the default qualification thresholds for each. It also clarifies what min_pa and min_ip are overriding, though it does not explain the limit 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 description clearly states a specific verb/resource: a season's leaders among qualified players. It enumerates the exact batting and pitching stats supported, making the tool's scope concrete. It does not explicitly contrast itself with sibling tools, so it falls short of a 5.

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?

"Use for a season's leaders..." gives a clear usage context and maps stat choices to batting or pitching categories. It does not name alternatives or state when not to use this tool, so there are no explicit exclusions.

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?

With annotations already covering read-only/idempotent safety, the description adds genuinely new operational facts: snapshot cadence (daily, then hourly for games within four days) and a 10-credit cost per call. It also discloses a policy constraint (never compute stakes/payouts, recommend bets, or route to a sportsbook) that no structured field conveys.

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?

Two sentences, no filler: purpose and data scope first, then cost and policy limits. Every clause carries information an agent cannot get from the schema or annotations.

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?

Output schema exists, so return values need no explanation, and annotations cover safety; the description fills the remaining gaps (cost, cadence, use limits). Minor omissions: no hint about behavior when no pre-game snapshots exist and no explicit pointer to get_odds for current lines.

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 75%, so the baseline is the schema itself; the description still adds meaning by explaining the capture cadence, which is what makes all_snapshots' 'every hourly capture' interpretable. game_id remains undocumented in prose, so it is not fully compensatory.

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 and resource ('see how a game's line moved before first pitch') and enumerates the data returned: per-book snapshots of moneyline, run line and total. The phrase 'moved' and the snapshot framing implicitly separate it from get_odds, but no sibling is named 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?

'Use to see how a game's line moved before first pitch' gives clear use context, and the credit cost plus the prohibition on stake/payout/bet-recommendation work sets a firm boundary on legitimate use. No explicit when-not condition or named alternative (e.g. get_odds for current prices) is provided.

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?

Goes well beyond the readOnly/idempotent annotations by disclosing data coverage rules (opening and closing per book from July 2020; final pregame line only before that), credit costs per call shape, and derived fields (implied probabilities, favourite-won and over/under flags against the median close). It also states a policy constraint on how the data may be used, which no annotation conveys.

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 dense sentences, front-loaded with the payload then the invocation modes then the usage policy; nearly every clause carries information. The mid-sentence parenthetical about pre-July-2020 coverage is slightly awkward but earns its place.

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 exists so return shape need not be explained, and the description still covers coverage window, cost, derived fields and usage policy. Nothing an agent needs in order to call this correctly 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 67%, so the description usefully adds that game_id is single-game and date is a whole day, along with the differing credit cost of each path. The league parameter (enum, default mlb) is left entirely to the schema, so it does not compensate for the remaining coverage 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?

Names a specific resource (betting lines) and enumerates exactly what is returned: each book's moneyline, run line and total, opening and closing, with implied probabilities. This clearly separates it from siblings such as get_line_movement (movement over time) and get_player_props (player-level markets).

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?

Explicitly routes the two retrieval modes: game_id for one game (5 credits) or date for a day's games (10 credits), and states a hard usage boundary (no stake/payout math, no bet recommendations, no sportsbook referral). It does not name a sibling alternative for cases where historical line movement is wanted, which keeps it from a 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 already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is fully covered. The description's one genuine contribution is the cost disclosure ('Costs 10 credits'), which an agent cannot get from annotations or schema. It says nothing about result volume, pagination strategy, or how cost scales with seasons versus single games.

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?

A single dense sentence, front-loaded with 'Use for' and the data type, then the scopes, then the payload fields, then cost. No filler; every clause carries information. It is slightly compressed — it could split the cost note out for readability.

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 exists, so return shape need not be explained, and annotations cover safety. The remaining gap is the undocumented identifier parameters and the absence of any guidance on the 10-credit cost versus result size (up to 2000 pitches per call), which an agent budgeting requests would want.

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 only 43%: game_id, batter_id, pitcher_id and offset have no schema descriptions at all. The description partially compensates by implying the three access modes (game / pitcher / batter), which is the key modeling decision for these undocumented IDs. It adds nothing about offset pagination, limit defaults, or how season interacts with game_id.

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 phrase 'Use for pitch-by-pitch data' names a specific resource and enumerates the three scopes it supports (single game, pitcher season, batter season) plus the fields returned (count, pitch type, velocity, location, result). That distinguishes it from coarser siblings such as get_plate_appearances, though it never names 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?

'Use for pitch-by-pitch data' is an implied usage cue, and the enumerated scopes hint at when the tool applies. However, it gives no exclusions or routing guidance against the many adjacent siblings — get_plate_appearances, get_pitch_mix, get_spray_chart, get_game — which overlap heavily with this data.

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 cover read-only, idempotent, non-destructive and closed-world, so the description does not need to restate safety. It adds genuinely new operational context: the 5-credit cost, which matters for tool selection under budget constraints. It does not describe caching or latency, but that is a minor gap.

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?

A single front-loaded sentence with the usage cue first, the returned fields second and the cost last. Every clause carries information; nothing 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?

With an output schema, annotations and fully described parameters, the description only needs to add the return-content summary and cost, which it does. A brief note on the credit cost being per call and on granularity versus get_pitches would close the remaining gap.

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 both parameters (pitcher_id, season with its default and game_id interaction) are already documented. The description only echoes season scoping at a high level and adds no syntax or format detail beyond the schema, which is the baseline case.

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 resource (a pitcher's arsenal for a season) and enumerates the returned metrics, so an agent knows this is an aggregated per-pitch-type breakdown rather than raw pitch data. It does not explicitly name the pitch-level sibling get_pitches, which would have made the distinction unmistakable.

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?

"Use for a pitcher's arsenal in a season" gives an implied usage cue and scoping condition, but there is no when-not guidance or named alternative (e.g. get_pitches for individual pitches). The agent must infer that this is the season-aggregate option.

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 readOnly/idempotent/non-destructive, so the description's job is to add context — and it does: explicit 10-credit cost, and the fact that win probability is only available from 2019 onward. It does not disclose default row counts or pagination behavior, but the cost and data-availability caveats are genuinely useful additions.

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?

Two dense sentences, front-loaded with the use case, then the returned fields, then filters, then cost. Every clause carries information; nothing is repeated from the schema.

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 an output schema present, the description needn't explain return values, yet it usefully previews the key ones (base-out state, batted ball, WPA, RE24). Cost and data-era caveats are included. Only pagination/default-limit behavior is left uncovered.

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?

Despite 50% schema coverage over 12 params, the description maps most of them semantically: risp, result, inning, batter/pitcher/team scopes and season. It adds the useful note that season is ignored with game_id. Limit/offset pagination params remain unexplained in the description.

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?

Names a specific resource (plate-appearance play-by-play) and enumerates its scopes: a full game in order, or a batter's/pitcher's/team's season. This clearly separates it from pitch-level siblings like get_pitches and aggregated ones like get_team_stats.

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?

"Use for plate-appearance play-by-play" plus the enumerated scopes gives a clear selection context. It never names a competing sibling or states when not to use it (e.g., pitch-level detail → get_pitches), so it falls short of a full when/when-not 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 readOnly, idempotent, non-destructive, and closed-world, so safety is covered. The description adds two pieces of genuinely new behavioral context: the credit cost of the call and the fact that stats are derived from every plate appearance (a data-granularity claim the annotations cannot convey). Pagination and season-range behavior remain unstated.

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?

A single front-loaded sentence with the use case first and the cost last; nothing is wasted. The long metric enumeration is dense but each group (batting vs pitching) does real work distinguishing the tool's coverage, though it crowds out room for usage guidance.

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 exists, so return-value explanation is correctly omitted, and the cost is disclosed. The remaining gap is scope: nothing says which seasons are returned or how far back the data goes, which matters for a season-by-season stats tool with only a player_id input.

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% and both parameters are documented in-schema, including the enum for league and the 'from search_players' provenance hint for player_id. The description adds no parameter-level meaning beyond that, so the baseline 3 applies.

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-resource pair ('a player's season-by-season batting ... and pitching') and enumerates the exact metrics returned, which clearly separates it from aggregate siblings like get_team_stats and from per-event siblings like get_plate_appearances or get_player_games. It does not name a sibling explicitly, so it stops short of a 5.

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?

'Use for...' establishes the intended context, and the cost note ('Costs 5 credits') gives the agent a budget signal before calling. However, there is no when-not guidance, no stated alternative for per-game or per-pitch granularity, and no mention of season scoping, leaving the choice against get_player_games/get_plate_appearances to inference.

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 readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds value beyond that: per-game batting AND pitching lines, newest-first ordering, season scoping, and a concrete 5-credit cost.

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?

A single dense sentence, front-loaded with the use case, then content, ordering, scoping and cost. No filler whatsoever.

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 exists so return values need no explanation, and cost plus ordering are disclosed. However, missing pagination and league behavior leaves an agent without enough to call a 6-parameter endpoint confidently at scale.

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 only 33% across 6 parameters, so the description needs to compensate and largely does not. It only hints at season scoping and says nothing about limit/offset pagination (important given 'every game' with a 200-row cap), league (mlb vs ncaabase), or season_type.

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-and-resource: a player's game log with every game's batting line and pitching line, newest first. This is clearly distinct from get_games (games) and get_player (profile), 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?

'Use for a player's game log' signals the intended case, and 'optionally one season' implies a season-scoped variant. There is no explicit when-not guidance or routing to alternatives such as get_plate_appearances or get_player.

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?

Beyond the read-only annotations, it discloses credit costs, estimate_only behavior, default closing-line snapshot semantics, capture-timing fields, the archive's limited multi-capture coverage, and a backtest filtering rule. It also includes an explicit compliance constraint against calculating stakes or recommending bets.

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 and access modes are front-loaded, and most of the long paragraph earns its place by explaining cost, snapshot behavior, and capture timing. It is dense and would benefit from bullets or shorter sentences, but it is not padded with empty filler.

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 output schema, the description does not need to explain return fields, yet it still covers the subtle cases an agent must know: opening vs closing lines, capture timing, archive limitations, billing, and estimate mode. Nothing material for correct invocation 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 parameter definitions are already documented. The description still adds meaningful relational semantics by emphasizing the two mutually exclusive access patterns, the 100-row limit, and how estimate_only interacts with billing.

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?

It states a specific resource (player prop lines by sportsbook) and enumerates the covered markets, so the agent knows exactly what data is returned. It does not distinguish itself from nearby siblings such as get_prop_history or get_odds, which leaves some ambiguity at the selection stage.

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 operational modes: pass game_id for a whole game, or player_id with from_date/to_date for one player across games, plus the 100-row cap. It does not state when not to use this tool or name the alternative sibling to use instead.

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?

Goes well beyond the readOnly/idempotent annotations: discloses credit pricing (10 per 25 games, 10 minimum, legacy-account exception), the free estimate_only path, the 200-game cap, and a compliance constraint against computing stakes or recommending bets. Those are exactly the operational facts an agent cannot infer from structured fields.

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 critical framing and the row layout come first, but the opening sentence is a long run-on carrying a six-item market list and several parentheticals. Dense and mostly earning its place, though it could be split for scanability.

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 an output schema present, 100% schema coverage, and rich annotations, the remaining burden was cost, limits, and policy — all addressed. An agent knows what it gets, what it costs, and what it must not do with the data.

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 already 100%, so the baseline is 3; the description earns extra by explaining that bookmaker swaps the median-across-books close for one book's line, and that opening equals closing where only one capture exists. It still doesn't cover from_date/to_date or limit default behavior in prose, leaving that to 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?

States a specific verb and resource — see how a player did against his prop line over time — and enumerates the exact per-game row contents (closing line, opening line, prices, actual result, over rate). This clearly separates it from siblings like get_player_props (current odds) and get_player_games (raw game logs).

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?

Opens with 'Use to see...' and explains the estimate_only flow for pricing before being charged, plus the 200-game-per-call ceiling with next_from_date-style continuation. It never names an alternative sibling or states an explicit exclusion (e.g., 'for a single upcoming line, use get_player_props'), so it falls 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.

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

Annotations already declare readOnly, idempotent, non-open-world, non-destructive, so the safety profile is covered. The description adds genuinely new behavioral context: the underlying methodology (Elo from every final game) and, importantly, a cost of 2 credits, which an agent should know before calling.

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?

Two compact sentences with zero filler; the purpose leads and the cost caveat is appended as a short, high-value note.

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 an output schema present, the description needn't explain return values, and annotations cover safety. It just falls short on season format and on how ratings differ from standings, but the core invocation requirements are present.

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 only 50%, with the 'season' parameter undocumented in the schema. The phrase 'as of the end of a season or today' compensates by implying that omitting season yields current ratings, adding meaning beyond the raw schema. It still doesn't specify the accepted season format (e.g. '2023' vs '2023-24'), which is a real remaining 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 the specific resource (team power ratings, Elo-derived from final games) and the temporal framing (end of a season or today, ranked). This clearly separates it from statistical siblings like get_team_stats or get_standings, though it never names an alternative 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?

'Use for our team power ratings' tells the agent the intended domain, and the mention of 'end of a season or today' implies the two usage modes. However, there are no exclusions or guidance on when to prefer get_standings/get_team_stats instead.

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 readOnly/idempotent/non-destructive/openWorld=false, and the description adds non-schema behavior: a 2-credit cost and a policy that prices are market information only, forbidding bet recommendations or stake math. Return-value shape is covered by the output schema, so these additions are exactly the extra context needed.

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 tight sentences, front-loaded with purpose and scope, then the alternative, then cost/policy. Every clause carries information (scope, cost, forbidden actions) with no filler.

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?

Complete for a read-only query tool: purpose, scope, default window, sibling routing, credit cost, policy constraints, and an output schema to describe return values. Nothing an agent needs to invoke it correctly 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 67%; team and league are already documented in the schema, but the description adds the missing semantics for days — the 1-30 range and the default of 7, which the schema does not state. That directly compensates for the one under-documented 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?

States a specific verb and resource ('upcoming games') plus the exact scope (next 1-30 days, default 7) and the data returned (median line: moneylines, run line, total). It names the sibling it is not — 'For every book's line use get_odds' — so an agent can distinguish it from get_odds and get_games 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?

Explicitly states when to use it (upcoming games within a 1-30 day window) and names the alternative (get_odds) with the condition that selects it (per-book lines). It also states a hard usage constraint: never compute stakes/payouts, recommend a bet, or refer to a sportsbook.

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 safe read-only, idempotent, non-destructive behavior, and the description adds valuable context beyond them: the 10-credit cost, regular-plus-postseason aggregation default, and how season_type changes that. There is no contradiction with 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 the use case and output dimensions, then adds only essential behavioral details about aggregation and cost. There is no filler, and the parenthetical comparison to get_player is useful rather than distracting.

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 an output schema and rich annotations present, the description covers the key invocation context: purpose, output dimensions, include_balls behavior, season aggregation, and credit cost. The main remaining gap is that it does not clarify whether team and batter_id are alternatives, whether either is required, or what happens if both are supplied.

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 60%, so the description must add meaning, and it does: include_balls is explained as adding each ball's location for drawing, and season_type is tied to regular/postseason/all aggregation. It still leaves team and batter_id with little semantic clarification beyond "batter or team."

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 resource and output: balls in play for a batter or team, broken down by trajectory and field with hit rates. It also distinguishes the tool from get_player's regular-season-only batting line, so an agent can identify its role among siblings.

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 use case ("Use for where a batter or team hits the ball") and explains the include_balls drawing option and season aggregation. It names get_player as a contrast for season scope, but does not explicitly rule out adjacent sibling tools such as get_pitches or get_plate_appearances.

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, idempotentHint, and openWorldHint=false, so safety is covered. The description adds two genuinely useful behavioral facts not in the structured fields: the cost ("Costs 2 credits") and the data provenance ("computed from every final game"), which tells the agent the numbers are final-game aggregates only.

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?

Two compact clauses with the usage trigger front-loaded and no filler. The metric list is long but each item is a concrete returned field rather than prose 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?

Output schema exists and annotations cover safety, so the description only needs to add cost and scope, which it does. Minor gaps remain: it does not say whether playoff games are excluded from the aggregates, or whether all listed metrics apply to both leagues.

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% with defaults and an enum on league, so the schema carries the parameter burden. The description adds nothing beyond the schema about league/season semantics (e.g., how NCAA baseball standings differ). Baseline 3 applies.

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 resource (a season's regular-season standings) and enumerates exactly which metrics are returned (record, home/away, last 10, runs scored/allowed, run differential, Pythagorean win %), which separates it from generic siblings like get_team_stats. It stops short of naming a sibling it is not, so an agent still has to infer the boundary with get_team_stats and get_ratings.

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?

"Use for a season's regular-season standings" is an explicit use trigger and "computed from every final game" implies the source scope. However, there is no when-not guidance, no named alternative among the ~20 siblings, and no guidance on choosing league or season values.

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 cover read-only/idempotent/no-destruction, so the description correctly spends its words elsewhere: it discloses the credit cost (5 credits) and the data provenance ('from every plate appearance'), which explains why rates are computed from raw events. It omits any note on latency or caching, which is minor given the annotation coverage.

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?

One sentence, zero filler, purpose front-loaded and cost disclosed at the tail where it belongs. The parenthetical metric list is dense but scannable.

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 exists, so return-shape explanation isn't needed, and the annotations cover semantics. The remaining hole is the undocumented required-ish 'team' input and the absence of any routing to list_teams or get_standings, which is exactly what an agent needs before calling.

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 67%; league and season are documented in the schema, but the bare 'team' string has no description and the description doesn't clarify whether it expects a name, abbreviation, or ID, nor point to list_teams for resolution. With no compensating detail in the description, this sits at the baseline rather than above it.

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+resource (team stats for a season) and enumerates the exact metrics returned — runs per game for/against, differential, AVG/OBP/SLG/OPS, K%, BB%, HR. It never names the adjacent siblings (get_standings, get_ratings) so an agent must infer the boundary, but the metric inventory is distinctive enough to be actionable.

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?

'Use for team offence and run prevention for a season' implies the use case but gives no when-not guidance and no alternative tools. An agent choosing between this, get_standings, and get_ratings gets no disambiguation from the description alone.

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, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds two pieces of context the annotations cannot convey: the credit cost ('Costs 1 credit') and the default season behavior (latest), both of which affect invocation decisions.

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 short sentences with zero filler. The purpose and the default are front-loaded, and the prerequisite note follows as supporting rationale in sequence an agent reads.

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?

The tool is simple (2 optional params, output schema present, rich annotations), and the description covers the three things structured fields don't: why to call it, its role as a prerequisite for siblings, and its credit cost. Nothing needed for correct invocation 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 description coverage is 100% and both parameters (league enum, season) are fully documented in the schema, so the baseline is 3. The description only restates the season default ('default: the latest'), which duplicates the schema and adds no meaning about the league parameter or accepted season formats.

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 ('find team ids and abbreviations') scoped to a season, and immediately distinguishes this tool from all 19 siblings by noting 'Every other tool takes a team as an id or abbreviation.' An agent can identify this as the team-id lookup without inspecting schemas.

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 makes the usage context explicit: call this first to obtain team ids/abbreviations that the other tools require. It doesn't name a specific alternative or an exclusion case, but the prerequisite framing is enough to route the agent correctly in nearly all cases.

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 readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds genuinely non-structured context: a credit cost and the fact that partial-name matching is supported. It stops short of saying whether multiple matches are returned or how ties are ordered.

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?

One sentence, zero waste, with the matching behavior front-loaded and the cost disclosure appended. Nothing redundant with the title or annotations.

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 exists, so return values needn't be explained, and the credit cost is a nice addition. But for a search tool the crucial missing piece is result-set behavior — multiple matches, limit default, league scope — which the description leaves to the schema alone.

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?

With 67% schema coverage, the baseline is 3. The description reinforces the name parameter (partial names work), which is useful, but adds nothing about the limit cap of 50 or how the league enum interacts with name matching.

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?

Names a specific verb and resource (find a player's id), plus the key affordance that partial names work. This separates it from sibling get_player, which clearly implies lookup by known identifier. An agent can pick the right tool without opening 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?

"Use to find a player's id by name" gives the triggering condition, so usage is implied rather than spelled out. It never states when not to use it or routes the agent to get_player once an id is known, nor does it mention the league/limit trade-offs between results.

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