PuckAPI

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

Annotations already establish read-only, idempotent, non-destructive, closed-world behavior, and the description goes well beyond them: a 10-credit cost, historical coverage bounds (odds from 2019-20 on, part of the 2019 playoffs), and the derivation limit on goalie starts. The betting-policy sentence discloses a use restriction the agent could not 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 use condition is front-loaded, followed by prerequisite, coverage caveats, cost, and policy in that order. Every sentence carries distinct information an agent would otherwise lack; nothing is repeated 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?

An output schema exists, so return structure needn't be described, and the description covers the remaining burden: what's included, how to get the game ID, data availability limits by date and game state, and cost. Nothing an agent needs 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 100%, so both parameters are already documented, and the description still adds value by explaining where game_id comes from and implying the ID format ties to a specific game. It says nothing about the league parameter, but the schema's enum and default fully cover that.

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 and enumerates the payload: both teams' full info, all betting odds, and goalies with time on ice. That enumeration implicitly separates it from narrower siblings like get_odds or get_shifts, though 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?

Gives an explicit trigger ('Use when you need everything about one game'), a prerequisite with its source ('Requires a game ID (get one from get_games or get_schedule)'), and a when-not ('goalie starts ... available for played games, not upcoming ones'). The agent knows both when to call it and how to obtain the required input.

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 genuinely new behavioral context: a 5-credit cost and a cheaper rival path, plus the shape of the payload. It stops short of noting pagination or result ordering, which keeps it at 4.

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, zero filler, and the ordering is correct: what it does, what it returns, then the cheaper alternative and cost. Nothing could be cut without losing routing or pricing 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?

For an 8-parameter, optional-arg, multi-league list tool with full schema coverage, an output schema, and complete annotations, the description covers purpose, routing and cost adequately. Minor gaps remain around result volume/pagination and whether season is required for sensible queries, but nothing that would cause a mis-call.

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 every parameter — including the enum meanings for game_state and the season/date formats — is documented in the schema itself. The description contributes no additional parameter semantics, 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 and resource (querying games) plus scope (past or future, with filters) and even previews the returned fields (scores, teams, venue, metadata). It explicitly separates itself from the nearest sibling, get_schedule, so an agent can choose 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?

Gives an explicit use case, names the alternative (get_schedule) and the condition that selects it (upcoming-only games), and prices both options (2 vs 5 credits). That is a full when-to-use / when-to-use-something-else rule.

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 the safety profile (readOnly, idempotent, non-destructive, closed-world), and the description adds genuinely extra context: a 5-credit cost, the games-played filter behavior, and a caveat that goalie expected goals cover all strengths whereas team possession columns are 5v5-only. That strength-coverage caveat and the cost disclosure are exactly the beyond-schema traits that prevent misuse.

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 dense sentences that lead with the trigger and the sort/metric surface before the caveat and cost. Every sentence carries information, though the return-field enumeration is slightly list-heavy for a tool with an output 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?

An output schema exists, so return values needn't be spelled out, yet the description still summarizes the key metrics and flags the strength-coverage limitation. Combined with annotations and full schema coverage, an agent has everything needed to 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 coverage is 100%, so all six parameters are fully documented in the schema itself. The description alludes to the games-played filter and the sort metrics, but adds no syntax or formatting detail beyond what the enum and property descriptions already say. Baseline 3 applies when the schema carries the parameter burden.

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 concrete verb and resource ('returns a leaderboard' of goalie stats) and enumerates the sort dimensions, which clearly separates it from get_player_stats and get_skater_season_stats. An agent can tell this is the goalie-ranking endpoint without opening the 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?

Opens with an explicit trigger ('Use when ranking goalies or comparing goalie performance'), giving clear selection context against the sibling stat tools. It stops short of naming an alternative or stating when-not to use it, so it isn't 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 cover read-only, idempotent, non-destructive semantics, so the bar is lower. The description still adds genuinely new behavioral context: it discloses a cost of 10 credits and summarizes the return shape (recent matchups with win/loss record), neither of which appears in 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?

Four short, front-loaded sentences — usage trigger first, then return content, then filtering mode, then cost. The telegraphic phrasing wastes nothing, though it borders on terse rather than explanatory.

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 detailed, and annotations carry the safety profile. With cost, scope, filtering modes and the two required teams covered, an agent has enough to call it correctly; only cross-tool routing guidance 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 description coverage is 100%, including team abbreviations, league enum, limit default and the season format, so the baseline is 3. The description's 'filter by season or get all-time' corroborates the season parameter's omit-for-all-time behavior but adds no format or edge-case detail 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 — comparing two teams' history and returning recent matchups with a win/loss record — which is distinct from sibling list tools like get_games or get_team_stats. It does not explicitly name those siblings as alternatives, but the purpose is unambiguous.

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 when comparing two teams' history' gives a clear trigger condition, and 'Can filter by season or get all-time' frames the two modes of use. However, it never names an alternative tool (e.g. get_games or get_team_stats) or states when this tool is the wrong choice, so routing is left partly 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 cover the safety profile (readOnly, idempotent, non-destructive). The description adds genuinely useful behavior beyond them: it discloses that this is the most expensive tool at 25 credits, that results are grouped by bookmaker, and it carries an important compliance constraint about not computing stakes or recommending bets. It stops short of richer details like pagination or result caps, so 4 rather than 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?

Four short sentences, each earning its place: purpose, return shape, cost/alternative routing, and the compliance guardrail. The routing information is front-loaded where an agent will see it before committing to the 25-credit call.

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 read-only two-parameter tool with full schema coverage and an output schema, this is complete: it covers purpose, cost, alternative routing, and the responsible-gambling constraint. Nothing an agent needs in order to call 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 100%, so both parameters are already documented, including the lowercase bookmaker note. The description's mention of grouping by bookmaker loosely reinforces the filter but adds no syntax or format detail beyond the schema, so the baseline of 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 and resource ('analyzing how betting lines moved over time') and describes the return shape (time-series snapshots grouped by bookmaker). It explicitly names the sibling get_odds and the distinction, so an agent can tell the two apart 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?

Gives an explicit when-to-use trigger ('analyzing how betting lines moved over time') and a when-to-use-the-alternative rule ('If you only need current lines, use get_odds (10 cr) instead'), complete with the cost trade-off. Nothing is left to inference about routing.

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 a safe read-only, idempotent operation. The description adds important context beyond that: credit costs, season cost estimates, pagination limits, data coverage by season, book counts, source-field behavior, and a clear restriction 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 description is dense but front-loads the primary usage decision before covering costs, coverage, and constraints. Some book-count and cost detail is lengthy, but it is relevant for a complex, priced, multi-mode 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 nine-parameter tool with an output schema, the description covers the important operational context: mode selection, costs, pagination, defaults, data availability, source fields, and ethical constraints. Nothing essential 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?

Even though schema coverage is 100%, the description adds substantial meaning about how parameters interact and what they imply: one-game vs season mode, per-game credit pricing, default page size and maximum, all_books effects, snapshot defaults, and estimate_only pricing behavior.

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 ('checking betting lines') and immediately distinguishes two operational modes: one game via game_id or a whole season via season. An agent can tell this is the odds-lines tool and not a scores, props, or line-movement tool.

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 explicit conditions for the two main modes, including optional team filtering, pagination defaults, all_books behavior, and estimate_only. It does not explicitly compare against sibling tools such as get_line_movement, so it stops just short of full alternative routing guidance.

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 the description adds substantive context beyond them: the data source (play-by-play), the resulting null fields (time on ice, plus/minus), the goalie-TOI caveat, the credit cost, and that the season used is echoed back. These are exactly the behaviors an agent needs before committing.

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 the use condition, then scoped detail; every sentence carries information. The enumerated field lists for skaters and goalies are somewhat redundant given an output schema exists, which keeps it from a 5.

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 6-parameter read tool with an output schema, the description covers selection criteria, prerequisite, data provenance, known null-value gaps, and cost. Nothing an agent needs to call 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 description coverage is 100%, so the baseline is 3; the description adds value by explaining where player_id must come from (search_players) and by tying the null-field caveats to what game_type/season actually yield. It does not restate defaults redundantly enough to be penalized.

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 (game-by-game stat lines per season) and immediately distinguishes it from the season-total siblings: 'not a season total'. The per-position breakdown (skater vs goalie fields) makes the output scope unambiguous without opening the 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 when you need a player's game-by-game stat lines for a season, not a season total' gives a clear selection rule against get_player_stats/get_skater_season_stats, and it names search_players as the prerequisite for the player ID. It stops short of naming the alternative tool explicitly or stating when-not conditions beyond the season-total contrast.

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 read-only/idempotent/non-destructive, and the description goes far beyond that with credit pricing (10 vs 20 per game, legacy-account pricing), default snapshot semantics, and precise row-capture semantics including the negative minutes_before_scheduled_start case. It also discloses a use policy (never compute stakes/payouts or recommend bets), which is exactly the kind of context structured fields cannot carry.

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 the purpose, then access modes, then cost and row semantics, then policy — a defensible order with essentially no filler sentences. It is a dense single paragraph of roughly 200 words, and the capture-timing detail ('in the NBA usually about 10 minutes after the scheduled one') could be split out for scanability, 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?

Output schema exists so return values need no explanation, and the description still covers cost, default snapshot, capture-time filtering, and the market-information policy. For an 8-parameter, credit-metered data tool, an agent has everything needed to call it correctly and to interpret the rows.

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 cross-parameter semantics the schema states only piecewise: the game_id vs player_id+from_date modes as mutually exclusive access patterns, the 100-row cap, and the real-world meaning of opening vs closing captures. It does not clarify bookmaker-key formatting beyond the schema examples or how market interacts with game_id/player_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?

States a specific verb+resource ('player prop lines by sportsbook') and enumerates the exact markets and books covered, plus the archive start date (May 2023). It does not explicitly distinguish itself from siblings like get_prop_history or get_prop_projections, so the agent must infer that this is the current/consensus line tool rather than the historical or projected one.

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 invocation modes: 'Pass game_id for every player's props in one game, or player_id with from_date (and to_date) for one player across games (up to 100)', plus the estimate_only shortcut for pricing. It also tells the agent how to filter for a clean backtest. It never names a sibling tool as the alternative for history or projections, so routing between prop tools is still on the agent.

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 context the annotations cannot: a concrete cost of 5 credits and an upstream dependency on search_players. It does not discuss error behavior for invalid player IDs, which keeps it below 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?

Three tight sentences: trigger condition first, then return contents split by position, then prerequisites and cost. Every sentence carries information an agent needs, with no filler or repetition of the title.

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 need not enumerate return fields, yet it still summarizes the notable skater and goalie metrics. Combined with the credit cost and the prerequisite tool call, an agent has everything needed to decide and invoke 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 both parameters are already documented and the baseline is 3. The description earns a bump by specifying the provenance of player_id via search_players, adding meaning the schema text ('NHL player ID') does not convey; the league parameter and its default are left entirely 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 (full details for one player) and enumerates exactly what is returned for skaters versus goalies, which lets an agent predict the payload shape. It never explicitly distinguishes itself from the closely overlapping siblings get_skater_season_stats and get_goalie_stats, so it stops short of a top score.

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 when you need full details for one player' sets a clear triggering condition, and 'Requires player ID from search_players' names the prerequisite tool that produces the required input. It gives no when-not-to-use guidance or comparison against the per-league stats siblings, so the routing is incomplete rather than ambiguous.

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 read-only, idempotent, non-destructive, closed-world behavior, so the safety profile is covered. The description adds genuinely non-structured context: a credit cost (10 credits), the at-least-one-filter constraint, and pagination via offset. It does not mention page-size defaults or rate limiting, which keeps it off 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?

Three tightly packed sentences: purpose first, filterable dimensions second, hard constraint and cost last. No filler, and the most decision-relevant facts (what it returns, what it requires, what it costs) are front-loaded.

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 it already covers the two things an agent cannot infer: the mandatory filter constraint and the credit cost. For a 12-parameter, all-optional read tool with full schema coverage, nothing essential to a correct call 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 every one of the 12 parameters is already documented with types, enums, defaults and examples. The description restates the filterable dimensions (game, season, team, player, event type, strength, zone, period) but adds no syntax, format or edge-case detail beyond the schema, so the baseline of 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?

The description opens with a specific verb and resource ('Use for play-by-play events') and then enumerates the exact event kinds returned (goals, shots, blocks, faceoffs, penalties) plus the attributes attached to each (rink coordinates, strength state, zone, players). An agent can distinguish this from get_shot_map or get_game_detail 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 gives a clear usage context ('use for play-by-play events') and an explicit precondition ('Requires at least one of game_id, season or player_id'), which is real routing guidance. It stops short of naming a sibling alternative or stating when not to use it — nothing points an agent to get_shot_map or get_shifts instead for narrower needs.

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?

Adds substantial context beyond annotations: costs 5 credits, an empty slate costs nothing with an explanatory note, a failed call is free, and it clarifies the accuracy/backtest note is not a live record. This is exactly the kind of cost and failure-mode detail annotations cannot convey.

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 scope, then cost/failure behavior. Dense but each clause carries useful information; slightly long but no filler sentences.

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 values need no explanation. The description covers cost, empty/failure behavior, exclusions, and staleness notes, leaving no gaps for correct invocation.

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?

Zero parameters, so baseline is 4. The description reinforces this with 'Takes no arguments (current slate only)', removing ambiguity about scope.

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 ('win probability for each NHL game on the current slate') and enumerates the returned fields (home/away probability, A/B/C grade, start time, model version, generation time). Explicitly distinguishes itself from odds-based siblings by stating no odds, prices, or goalie/injury notes are included.

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?

Clear context: use for the model's own win probabilities on the current slate, no arguments, current slate only. It implicitly routes away from odds/pricing tools by naming what it does not contain, though it does not name a specific sibling 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 the description adds substantial context beyond them: a precise cost model (10 credits per 25 games played, 10-credit minimum, legacy pricing), a 200-game per-call ceiling, pagination continuation via next_from_date, and a compliance constraint forbidding stake, payout or profit calculations. These are behavioral facts the agent could not infer from annotations or schema.

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 is front-loaded in the first clause and every sentence carries real information (markets, row contents, cost, estimate_only, compliance). It is dense to the point of being a single run-on sentence, which slightly hurts scanability, but there is no filler to cut.

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 an output schema already documents the return shape, the description covers what remains: cost mechanics, credit-minimizing estimate_only, the 200-game cap and pagination, which markets are valid, and the downstream usage restriction. An agent has everything needed to invoke and price the call 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%, so baseline is 3, and the description earns above it by clarifying semantics the schema only gestures at: the closing line is the median across books unless one bookmaker is given, the opening line mirrors the close where only one capture exists, and 'over rate' is part of the response. It still does not spell out how from_date/to_date interact with limit and paging order beyond what the schema says.

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 markets covered plus the per-game row contents (closing line, opening line, prices, actual result, over rate). It does not name sibling tools such as get_player_props or get_prop_projections, so differentiation is implicit rather than explicit, but the historical 'against the line' framing is distinctive enough to separate it from current-line tools.

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 an explicit use case ('Use to see how a player did against his prop line over time') and explains when to set estimate_only (to get the price without being charged). It gives no explicit when-not-to-use guidance and never names the alternative to pick when the agent wants current or projected lines instead of history.

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 and idempotency, and the description adds substantial context beyond them: paid-plan gating, a concrete 25-credit cost, that an empty slate and a failed call are free, and a hard 'tonight's slate only' scope. That is exactly the operational detail an agent needs before spending credits.

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 the gating constraint and purpose, and nearly every sentence carries information (scope, cost, exclusions). It runs long and the per-line distribution methodology (Poisson vs. model goal distribution) is more detail than most callers need, which keeps it off a 5.

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 not required. Given the two optional filters, the credit cost, the plan gating and the slate restriction, an agent has everything needed to decide and call 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%, so both filters are already documented with examples and semantics. The description restates them ('team either side of the game', 'player name fragment') and adds the explicit 'optional' framing, but contributes no format or edge-case detail beyond the schema. 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 and resource: model-projected stat lines for tonight's NHL skaters and goalies, with named fields (goals, assists, points, shots, saves). It also draws a clear boundary against get_player_props/get_odds by declaring 'Numbers only: no odds, prices or injury notes.' An agent can pick this over its siblings without opening a 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?

Gives explicit when-to-use (projected stat lines for tonight's slate) and when-not (no odds, no injury notes, no date argument, paid plans only). It does not name the alternative sibling tools such as get_player_props or get_predictions directly, so the routing is inferred rather than spelled out.

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, but the description adds two traits they don't cover: results are filtered to unplayed future games only, and each call costs 2 credits. Return shape is left to the output schema, and no pagination or rate-limit detail is given.

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, zero filler, and the primary trigger ('Use when checking what games are coming up') is front-loaded ahead of scope, alternative, and cost.

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 describing returns, full annotation coverage of the safety profile, and complete parameter documentation, the remaining things an agent needs — the future-games filter, the sibling to use for history, and the credit cost — are all stated. Nothing material 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% — all three parameters (days, team, league) are documented including the enum values and default. The description's only parameter-adjacent note is the 7-day default, which the schema already states, so it adds no meaning beyond the structured fields.

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 (games schedule) and a precise scope constraint: 'only unplayed future games for the next N days (default 7)'. It also names the sibling it is not (get_games for past games), so the agent can distinguish it 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?

'Use when checking what games are coming up' gives a clear use context, and 'For past games, use get_games instead' supplies an explicit alternative with its selecting condition. It does not address the boundary with get_game_detail (single-game detail), so the routing is strong but not exhaustive.

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, closed-world behavior, so the description's added value is the credit cost (10) and the historical coverage floor (2010-11 on) — both operationally useful facts absent from the structured fields. It doesn't address result size or pagination, which keeps it below 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?

Front-loaded with the use case, then scope, then filters, then constraints and cost — no filler. The enumeration of return fields is somewhat redundant given an output schema exists, which is the only wasted space.

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 three-parameter filtered read with an output schema, the description supplies everything an agent needs to decide and call correctly: what it returns, what can be filtered, the historical boundary, and the cost.

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 all three parameters (game_id, team, player_id) are already documented with formats and examples. The description only restates that filtering by one team or player is possible, adding no syntax or edge-case semantics beyond the schema; 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 and resource — every player's shifts in one NHL game — and enumerates the returned fields (period, start/end, duration, boxscore TOI, plus/minus). This distinguishes it clearly from siblings like get_plays, get_situation_time, and get_player_game_log.

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 who was on the ice and when" frames the selection context, and the description states narrowing options (team or player) plus a data-coverage limit (2010-11 on). It stops short of naming an explicit alternative or a when-not-to-use condition.

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 the description goes well beyond them: it discloses pagination behavior (pages are chronological, follow next_offset, a season exceeds one page) and a concrete cost of 10 credits. These are exactly the operational traits an agent needs before calling a large paginated endpoint.

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 short sentences, each doing distinct work: purpose+contrast, return fields, filtering modes, then pagination and cost. Front-loaded with the selection cue, 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?

With an output schema present, the description needn't explain return shape — yet it still summarizes the key fields, and it covers pagination and cost, the two things an agent could otherwise get wrong on a season-length query. Nothing material is missing for correct invocation.

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 baseline is 3; the description adds that game_id is an alternative to the season+team/player combination, which conveys the mutual-exclusivity and pairing rules an agent would otherwise have to infer. It doesn't document limit/offset/strength syntax beyond what the schema already says.

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 (shot attempts with rink coordinates) and explicitly contrasts it with the alternative output shape ('rather than a list of events'), which cleanly separates it from get_plays and get_game_detail. The enumerated return fields (shot type, strength, shooter, goalie) further pin down what 'shot map' means.

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 when you want shot locations rather than a list of events' gives a clear selection condition, and 'Filter by game, or by season plus a team or player' shows the two valid calling modes. It stops short of naming a specific sibling tool as the fallback, so the routing is implied rather than fully explicit.

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 the safety profile (readOnly, idempotent, non-destructive, closed-world), so the description's job is added context — and it delivers: data provenance (shift charts), a cross-validation against play-by-play, a season coverage window (2010-11 onward), and a concrete cost model (10 credits per game, multiplied when using date).

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 the core use case and packed with substantive detail — strength states, splits, provenance, cost, coverage window. It is a single long run-on sentence with mild redundancy ("every other on-ice state" after the exhaustive list), but nearly every clause carries information an agent needs.

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 derived-aggregate tool with an output schema and three optional params, this covers everything that matters: what is measured, where it comes from, how far back the data goes, what the optional flag adds, and what it costs. Return-value shape is correctly left to the output 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 coverage is 100%, so date, game_id, and include_players are already fully documented in the schema, including the default for include_players. The description mostly restates those semantics; the only genuine addition is the cost implication of the date parameter fanning out across every game that day.

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 with unusual precision: seconds per team by on-ice strength state (5v5, 5v4, 4v5, 4v4, 6v5, plus all other states), split regulation/overtime, sourced from shift charts. The enumeration makes it unmistakable against siblings like get_shifts (raw shifts) or get_game_detail (game-level summary), even without naming them.

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 exact time at each strength" plus "from the shift charts" gives clear selection context, and it states the game_id-vs-date choice with per-call credit costs. It stops short of naming an alternative tool or an explicit when-not-to-use case (e.g. use get_shifts for raw shift rows), so it lands at 4 rather than 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 readOnlyHint, idempotentHint, and destructiveHint=false, so safety is covered. The description adds value the annotations cannot: a 5-credit cost and the 2010-11 season floor, both of which affect whether an agent should call this at all.

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 short sentences, each carrying a distinct fact (trigger, output shape, contents, constraints, cost), with the use case front-loaded. Dense and free of filler, though the mid-sentence metric list is slightly list-like.

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 the description still summarizes what is included (power play, shorthanded, shooting%, faceoff%, TOI). Combined with the cost and season-range notes, an agent has enough to call it correctly; only explicit sibling routing 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 description coverage is 100%, so all six parameters (team, limit, league, season, sort_by, min_games) are already documented with defaults and constraints. The description only echoes the sort metrics and games-played filter, adding nothing beyond the schema except the historical season range.

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 ('Returns a leaderboard sorted by points, goals, assists...'), making it distinguishable from get_player_stats and get_goalie_stats by its ranking/leaderboard framing. It stops short of explicitly naming the sibling it is not, which keeps it below 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 when ranking skaters or comparing scoring' gives a clear positive trigger condition, which is unusually direct. It does not state when NOT to use it or name the alternative to pick instead for single-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 a safe, idempotent read, so the lower bar applies, and the description clears it: it discloses the 2-credit cost, the default-season behavior, and a genuine analytical caveat that 5v5 possession columns will not match a goalie's all-situations expected goals. That caveat prevents a real misinterpretation of the data.

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 usage condition is front-loaded, followed by the returned metrics and then the caveat and cost. The metric enumeration is dense but each item is informative; 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?

An output schema exists, so the description needn't document return structure, and it covers usage context, defaults, cost, and a data-interpretation caveat. What's missing is only a sibling comparison, which is a modest gap given 21 tools in the family.

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 enums documented for league and conference, so the schema carries the load. The description only adds the default-season behavior ('most recent season with standings'), which is a slight refinement of the schema's 'Defaults to current season' rather than new parameter guidance.

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 the question it answers: team rankings within a division or conference. It enumerates the returned metrics, so the agent knows precisely what data it gets. It stops short of naming how it differs from sibling tools like get_team_stats, which is likely to be the main ambiguity.

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 when checking where teams rank in their division or conference' gives a clear triggering context and implies the league/division/conference scoping via the schema. There is no explicit 'not for X, use Y instead' guidance against the many sibling stats tools.

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 read-only, idempotent, closed-world behavior, so the description is free to add the two things annotations cannot convey: the cost ('5 credits') and the interpretive constraint that possession stats are 5v5 only. Only gap is nothing about output shape beyond the metric list, which the output schema covers.

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, each earning its place: content scope first, the caveat about possession second, then the prerequisite and cost. Front-loaded with the trigger condition and 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?

With an output schema present, the description does not need to explain return values, yet still names the key metrics. For a 3-parameter read tool with full annotation and schema coverage, nothing an agent needs in order to call it correctly is missing, including cost awareness.

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%, including the enum for league and season format examples, so the schema carries parameter semantics. The description only reinforces the required `team` parameter and points to list_teams for discovery; it adds nothing about league or season defaults.

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 ('full details for one team') and enumerates the contents: record, goals for/against, league rank, and 5v5 possession metrics (Corsi%, Fenwick%, xG for/against). That level of enumeration distinguishes it from siblings like get_standings or get_skater_season_stats 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?

'Use when you need full details for one team' gives a clear trigger, and 'use list_teams if unsure' names the fallback sibling for resolving an abbreviation. It does not explicitly say when to prefer get_standings or get_game_detail instead, so it stops just short of full alternative routing.

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/closed-world, so the bar is lower; the description still adds real value by disclosing the historical-franchise exclusion and the credit cost. It doesn't say whether results are paginated or ordered, but that is minor for a small fixed list.

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 tight sentences, front-loaded with the usage trigger, then scope, exclusions and cost — 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?

An output schema exists so return values need no explanation, and annotations plus the description cover safety and scope. The remaining gap is that multi-league support and filter behavior are never acknowledged in prose.

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% and both enums are documented inline, so the schema carries parameter meaning. The description adds nothing about league/division/conference filtering beyond the word 'active', and its '32 NHL teams' phrasing could mislead an agent into ignoring the league 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 ('see all 32 active NHL teams') and enumerates the returned fields (city, conference, division, arena), which clearly separates it from stat/game-oriented siblings. The framing is narrowed to NHL even though the schema supports eight leagues, so the scope statement is slightly narrower than the tool actually is.

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 when you need team abbreviations' gives a concrete triggering condition, and 'Excludes historical franchises (ATL, ARI)' pre-empts a likely user request. It also flags cost ('Cheapest tool at 1 credit'), which helps routing decisions, though no sibling alternative is named.

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 this as a safe, read-only, idempotent, non-destructive operation. The description adds useful behavioral context beyond annotations: default active-only results, historical scope via active=false, and a concrete cost of 2 credits. It does not describe pagination or result-shape behavior, so it is not exhaustive.

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 four tight sentences with no wasted wording. The primary use case is front-loaded, followed by scope, default behavior, next-step routing, and cost.

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 the description need not explain return values. Given the 100% schema coverage, clear annotations, and the description's coverage of use case, defaults, next tool, and cost, an agent has enough information to select and invoke this 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 description coverage is 100%, so all six parameters are already documented in the schema. The description reinforces the important active-status default and clarifies that query is a name search, but it does not add syntax or meaning beyond what the schema already provides.

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 ('looking up a player by name') and adds scope ('4,900+ players across every season since 2010-11'). It also distinguishes this lookup tool from get_player_stats by explaining that the returned player ID should be used there for full details.

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 usage context ('Use when looking up a player by name') and names the follow-up tool get_player_stats for full details. It also explains the default active-player behavior and how to include retired/historical players, though it does not explicitly state when not to use this tool.

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