PuckAPI

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, but the description adds substantial context beyond them: a 10-credit cost, the historical coverage window for odds, the play-by-play derivation of goalie starts, and an explicit content policy forbidding stake/payout math or sportsbook referrals. These are behavioral traits the structured fields cannot express.

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 trigger is front-loaded, followed by prerequisite, coverage caveats, cost, and policy in descending order of importance. Every sentence carries distinct information — no restating of the name, title, or 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 need not explain return values, and it still covers everything an agent needs: trigger, prerequisite and its source, data availability windows, cost, and the domain policy constraint. Nothing material is left for the agent to infer.

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 above baseline by stating that game_id is required and specifying exactly which tools supply a valid value, which the schema does not say; the league parameter is 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 ('everything about one game') and enumerates the returned payload: both teams' info, all betting odds, and starting goalies with time on ice. This cleanly differentiates it from siblings like get_odds, get_goalie_stats, and get_shifts, which each cover only one slice of that payload.

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 when-to-use trigger, names the prerequisite (a game ID), and routes the agent to the correct sources for that ID (get_games or get_schedule). It also states availability boundaries — odds only from 2019-20 on, goalie starts only for played games — so the agent knows when the call is futile.

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=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds genuinely useful non-schema context: the credit cost of 5 and the shape of the payload (scores, teams, venue, metadata). It omits pagination/result-window behavior, which is the only notable 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?

Three short sentences, front-loaded with the use case, then the return shape, then the cheaper alternative and the cost. Nothing is redundant with the title or 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?

Output schema exists so return values need not be enumerated, yet the description still sketches them briefly. Combined with the explicit alternative and cost signal, an agent has everything needed to choose and invoke this tool over its 20 siblings.

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 one of the 8 parameters carries its own description and enum values, so the schema does the heavy lifting. The description adds no filter syntax or format detail beyond what the schema already states, which is the expected baseline here.

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 past or future games') plus the filterable scope, and immediately distinguishes itself from get_schedule by naming the upcoming-only alternative. An agent can separate it from get_game_detail, get_schedule, and the stats siblings 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?

Explicit when-to-use ('querying past or future games with filters'), explicit when-not ('upcoming-only games, prefer get_schedule'), and an explicit cost tradeoff (5 cr vs 2 cr). The routing decision is fully resolved in the description.

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=true, openWorldHint=false and destructiveHint=false, and the description goes beyond them by disclosing a cost (5 credits) and the output contents (GSAX, high-danger save%, rolling 10-game windows, rest days). It also flags a semantic caveat about goalie expected goals covering all strengths. Remaining gaps (rate limits, credit refunds) are minor.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Four sentences, front-loaded with the trigger condition and the return shape before cost. Every sentence carries content, though the listing of return columns is dense and slightly overlaps what the output schema covers.

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 annotations covering the safety profile and an output schema present, the description supplies the essentials: trigger, sort options, min-games behavior, credit cost and a caveat on expected-goal scope. Coverage of multi-league behavior is left to the schema, which is acceptable.

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 including the leagues enum and season format are already documented by the schema. The description restates the games-played filter and sort metrics (gsax already defined in the schema), adding little beyond the structured fields; 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 (returns a goalie leaderboard), names the ranking/comparison use case, and lists the exact sort metrics. It is clearly distinguishable from siblings like get_player_stats and get_skater_season_stats, which cover a different position group.

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 goalies or comparing goalie performance" gives clear positive usage context and the min-games filter is described. However, it never names an alternative tool or states when-not to use it (e.g., vs. get_player_stats for skaters, or league/team filtering routes), so routing guidance is incomplete.

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=true, openWorldHint=false, and destructiveHint=false, so safety is covered. The description adds genuinely useful material beyond that: the return payload shape (matchups with a win/loss record) and a non-obvious cost signal ("Costs 10 credits") that affects whether an agent should call it.

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 padding: the trigger condition leads, the return value follows, and the cost warning closes. Every sentence contributes 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?

For a read-only, five-parameter tool with a full output schema, the description covers the trigger, the filter modes, the result shape, and the credit cost. Nothing material is missing, and return-value detail is appropriately 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 description coverage is 100%, so the schema already documents team abbreviations, the league enum, the 8-digit season format, and the limit default/range. The description only restates the season filtering option ("filter by season or get all-time"), which the schema's season description already conveys. 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?

The description states a specific verb+resource combination — comparing two teams' head-to-head history — and names the output (recent matchups with win/loss record). This is clearly distinct from siblings like get_games (all games) or get_team_stats (single-team aggregate), so an agent can select it 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 comparing two teams' history" gives explicit context for invocation, and "Can filter by season or get all-time" clarifies the two modes. There are no explicit exclusions or named alternatives, but no sibling provides head-to-head matchup data, so the routing risk is low.

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=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds non-obvious traits the annotations cannot convey: relative cost (25 cr), the grouping/shape of the result, and a policy boundary on what the agent must never compute from prices.

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 load-bearing: usage trigger, return shape, cost and cheaper alternative, policy constraint. The routing information is front-loaded before the cost comparison.

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 carry the safety profile. The description fills the remaining gaps an agent needs (when to call it, cost relative to the alternative, and the betting-advice prohibition).

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 (game_id, bookmaker) are documented there, so the baseline is 3. The description adds no format, casing, or defaulting guidance 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?

Specific verb+resource: it returns time-series snapshots of betting line movement grouped by bookmaker. It distinguishes itself from the sibling get_odds by naming that tool and the condition that selects it, so an agent can route correctly 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?

Explicit when-to-use ('when analyzing how betting lines moved over time'), an explicit cheaper alternative with its use case ('if you only need current lines, use get_odds'), and an explicit prohibition on downstream betting actions. Nothing is left 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 a safe read-only profile, yet the description adds substantial context: per-call credit costs (10 per game, ~13,700 for a season, ~820 for a team-season), estimate_only to price without being charged, per-season book coverage and the default four-book set, and the source-field semantics for opening/closing versus final lines. The market-information policy constraint is also disclosed.

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 opening sentence is well front-loaded, but the body is a dense run-on paragraph. It also repeats schema content verbatim, such as "100 games a page by default (up to 500)" and the book-count breakdown that already appears in all_books' schema description.

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?

Despite an output schema existing, the description supplies everything an agent needs: pricing model, pagination and next_offset workflow, snapshot defaults, book coverage by season, and the source field on each line. Nothing material is left for the agent to infer.

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 goes further: it ties cost and pagination behavior to the game_id-versus-season choice and explains that a season answer defaults to the four main books while an unserved season returns every book. It also documents array ordering by the columns field, none of which appears in 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 concrete resource (NHL betting lines) and enumerates the payload precisely: moneyline, puck line and total by bookmaker, opening and closing. It does not explicitly distinguish itself from adjacent siblings such as get_line_movement or get_player_props, but the game-level/season-level scope 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 checking betting lines" plus a clear branch on game_id (one game) versus season (optionally with team) tells the agent which mode to pick and when. There are no explicit exclusions pointing to competing tools, so it stops short of the top score.

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=true and destructiveHint=false, and the description goes well beyond that: it discloses the data lineage ('built from play-by-play'), the concrete consequence that time on ice and plus/minus come back null, the goalie-specific caveat that time on ice exists only for started games, and a cost signal ('Costs 5 credits'). This is exactly the kind of non-obvious behavior an agent needs 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?

Three tight sentences, no filler: the use condition and the skater/goalie field lists come first, the null caveats follow, and the prerequisite plus cost land last. Each sentence carries distinct information an agent would otherwise have to infer.

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 spelled out, yet the description still flags which fields will be null and why, which is the one thing the output schema cannot express. For a read-only, six-parameter tool with full schema coverage, nothing needed 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 description coverage is 100%, with limit, league, offset, season and game_type all self-documented including defaults, so the schema carries the parameter burden and baseline 3 applies. The description only adds a prerequisite for player_id (from search_players) and notes the resolved season is echoed back, without adding format or syntax detail for the remaining parameters.

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 ('a player's game-by-game stat lines for a season') and immediately contrasts with what it is not ('not a season total'), which cleanly separates it from get_player_stats/get_skater_season_stats. It also enumerates the exact fields returned for skaters vs goalies, so an agent knows the granularity 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 an explicit use condition ('Use when you need a player's game-by-game stat lines for a season') and an implicit exclusion ('not a season total'), plus the prerequisite 'Requires player ID from search_players'. It stops short of naming the alternative tool (e.g. get_player_stats) outright, so routing relies on the agent recognizing the season-total counterpart by description.

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 cover read-only safety, and the description adds substantial behavior beyond that: exact credit pricing (10 per game, capped at 100), the closing-vs-opening capture semantics, the fact that outside football opening and closing are usually identical, the meaning of minutes_before_scheduled_start and when rows are retained, and a hard policy on not computing stakes or recommending bets. It also warns that estimate_only avoids charges.

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-loads purpose, then usage branching, then capture/backtest caveats, then policy, and nearly every sentence carries information. It is a dense single block with minor redundancy (credit cost restated) and could be broken into clearer segments, but no sentence is pure 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 8 optional parameters, an output schema, and non-obvious time-capture semantics, the description supplies everything an agent needs: which parameter combination to use, what it costs, how to filter for a clean backtest, and what the returned rows contain. 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 the baseline is 3, but the description adds real semantics on top: the game_id vs player_id+from_date branching, snapshot_type defaults and why opening often equals closing, and the cost implications of each path. It leaves bookmaker keys and market enum details to the schema, which is acceptable given full coverage.

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 with scope: player prop lines by sportsbook, and enumerates the markets (points, goals, assists, shots on goal, blocked shots, saves, anytime scorer) plus coverage start date and book list. This clearly distinguishes it from siblings like get_odds, get_prop_history and get_prop_projections.

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 call patterns: game_id for a whole game's props, or player_id + from_date (+ to_date) for one player across games, and names estimate_only as the free dry run. It does not explicitly route the agent away from sibling tools such as get_prop_history or get_prop_projections, so it stops short of full when/when-not 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 readOnlyHint=true, openWorldHint=false, destructiveHint=false, so the safety profile is covered. The description adds genuinely new context: a cross-tool dependency on search_players and a 5-credit cost, which is exactly the kind of pre-call constraint annotations cannot express.

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?

Five short sentences, front-loaded with the use condition, then the two return branches, then the dependency and cost. No filler and no repetition of the title; each sentence carries distinct 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 a read-only single-entity lookup with a full output schema, 100% parameter coverage, and explicit annotations, the description is nearly complete: trigger, prerequisite, cost, and return shape are all present. The only unaddressed item is the multi-league scope supported by the league enum.

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% (2 params, one enum), so the baseline is 3. The description earns above baseline by tying player_id to its source tool ("from search_players"), giving the agent an acquisition path the schema does not state, though it says nothing about 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?

The description opens with a specific verb and resource ("full details for one player") and enumerates exactly what comes back for skaters vs. goalies, which is more informative than the title. It stops short of explicitly differentiating itself from close siblings like get_skater_season_stats or get_goalie_stats, so the agent must infer that this is the combined per-player view.

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" gives a clear trigger, and "Requires player ID from search_players" states the prerequisite and the tool that supplies it. It offers no when-not guidance, e.g. when to prefer get_goalie_stats or get_player_game_log instead, so the sibling boundary is left implicit.

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 and non-destructive behavior. The description adds valuable operational details: a cross-parameter requirement (at least one of game_id, season, or player_id), pagination via offset, and a 10-credit cost. It does not cover auth or rate limits beyond 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?

Five tight sentences, front-loaded with purpose, then filters, requirement, pagination, and cost. Every sentence carries actionable information; no waste.

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 12-parameter read-only tool with an output schema and full annotation coverage, the description supplies the essential calling constraints: required filter, pagination, cost, and event scope. Nothing critical 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 a critical cross-parameter constraint not expressed in the schema (at least one of game_id, season, or player_id) and maps filters to parameters. It does not add syntax or format details for individual parameters, but the constraint is meaningful.

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 (play-by-play events) and enumerates event types with attributes like rink coordinates and strength state, giving a clear sense of what the tool returns. It does not explicitly differentiate itself from siblings such as get_shot_map or get_shifts, so 4 rather than 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?

Provides clear context 'Use for play-by-play events' and lists filterable dimensions, but offers no when-not guidance or named alternatives for related tools. Clear enough but lacks exclusion criteria.

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, non-destructive, openWorld), but the description adds genuinely new operational facts: the call costs 5 credits, an empty slate is free and returns a note explaining why, and a failed call is also free. Cost and failure semantics are exactly the kind of behavior an agent cannot infer from annotations alone.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Purpose and scope are front-loaded in the first clause, and the sentences are information-dense rather than padded. The empty-slate sentence is slightly knotty in phrasing ('An empty slate costs nothing, and a note says why...; so does a failed call'), but every sentence carries load-bearing 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-field detail is already covered, so the description rightly spends its budget on scope, cost, empty-state and failure behavior. An agent has everything needed to decide whether to call it and what to expect.

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 the baseline is 4 and there is nothing for the schema to document. The description confirms 'takes no arguments' and clarifies the implicit scope (current slate only), which is the only semantic worth adding here.

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 ('the model's win probability for each NHL game on the current slate') and enumerates exactly which fields come back (home/away probability, A/B/C grade, start time, model version, generation time). It distinguishes itself from siblings like get_odds by explicitly saying no odds or prices 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 about the operative constraint ('takes no arguments, current slate only') and about what is not covered (odds, prices, goalie/injury notes), which implicitly routes the agent to get_odds or get_game_detail for those. It never names an alternative tool explicitly, so it falls short of a full when-to-use/alternative mapping.

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 (readOnlyHint=true, destructiveHint=false, openWorldHint=false), so the bar is lower. The description nonetheless adds genuinely useful operational context the annotations lack: a concrete cost ('10 credits for up to 200 games'), the shape of each returned row, and a compliance constraint on how the price data may be used. It omits auth/error behavior, 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?

Purpose and scope are front-loaded in the first clause, and the compliance warning lands at the end where it belongs. The main inefficiency is re-listing all seven market values that the schema enum already declares, which is duplicated text.

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, a full annotation set and 100% schema coverage, the description supplies everything the schema cannot: purpose, cost, row semantics, and the usage restriction on price data. 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 3 is the baseline. The description still adds meaning beyond the schema: it enumerates the human-readable market names matching the enum, explains bookmaker as 'one book's closing line instead of the median across books', and ties the 200-game ceiling to the credit cost.

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 pins the scope precisely: one market, one row per game, closing/opening line, prices, actual result and over rate. That is distinguishable at a glance from get_player_game_log (raw stats) and get_player_props (current lines), 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?

Opens with an explicit 'Use to...' condition and adds a hard usage constraint (prices are market information; never compute stakes or recommend bets). It does not name alternative siblings or state when not to use it (e.g. for upcoming lines use get_player_props), so it stops short of full 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 cover the safety profile (readOnly, non-destructive, openWorld), and the description layers on non-obvious behavior: a 25-credit cost, free empty slate, free failed call, a hard paid-plan requirement, and the odd/no-date scoping. It even discloses the modeling methodology behind the over-probabilities (goal distribution vs. Poisson), which no structured field provides.

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 paywall and scope constraints are front-loaded, and every clause carries information (credits, plan tier, date scope, output shape). It is dense with stacked parentheticals and runs long, but there is no filler sentence to remove.

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 exists, return values need not be spelled out, yet the description still surfaces the key business constraints an agent needs: plan eligibility, credit cost, no-date scope, and the exclusion of odds/injury data. Nothing required to decide whether and how to call it 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% and both parameters are already fully documented in the schema, including the team-abbreviation example and the name-fragment/accent behavior. The description only restates them as 'Optional team (either side of the game) and player (name fragment) filters', adding no syntax 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?

States a precise verb and resource: the model's projected stat lines for tonight's NHL players, enumerating each skater's goals/assists/points/shots with ranges and each goalie's saves. It also carves out its niche against siblings by declaring 'Numbers only: no odds, prices or injury notes', which separates it from get_odds and get_player_props.

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 clear usage context: 'Paid plans only (not available on the free plan)' and 'Tonight's slate only; no date argument', plus the note that empty slates and failed calls are free. It stops short of explicitly naming an alternative tool for odds-bearing props or historical props, so selection between siblings still requires some 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 readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds a cost disclosure ('Costs 2 credits') and reiterates the future-only filtering constraint, which is genuinely useful context not present in structured fields. It does not, however, describe the returned shape or ordering, so it stops short of full behavioral disclosure.

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, and the primary use case is front-loaded before the alternative and the cost note. Every sentence carries information the 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?

With an output schema present, the description need not explain return values, and annotations cover safety. Scope, default, alternative routing, and cost are all stated, leaving nothing an agent needs in order to call this correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% and all three parameters (days, team, league) are documented with defaults and an enum in the schema itself. The description only restates the default of 7 days, adding no format, syntax, or constraint detail beyond the schema. Baseline 3 applies when the schema does the heavy lifting.

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 ('checking what games are coming up') and immediately narrows scope to 'only unplayed future games for the next N days (default 7)'. It explicitly distinguishes itself from get_games for past games, so an agent can separate it from its closest sibling without reading either schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives an explicit trigger ('Use when checking what games are coming up') and an explicit alternative with its selecting condition ('For past games, use get_games instead'). The when-to-use and when-not-to-use are both stated rather than inferred.

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 the safe read-only, non-destructive, closed-world profile. The description adds genuinely new operational context: a cost of 10 credits and the historical coverage window (2010-11 onward), which an agent needs for planning but cannot get 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?

Three front-loaded sentences with no filler; the purpose leads and filtering, coverage, and cost follow. The field enumeration sentence is dense but each clause carries real information, so it stays efficient rather than padded.

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 explain return values, yet it adds the cost and the historical cutoff that the structured fields omit. Complete enough for correct invocation, though it could mention the absence of pre-2010-11 data as a routing signal to other tools.

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 three parameters are already documented in the schema. The description only echoes the filtering intent ('Filter to one team or player') without adding format or semantics beyond what the schema provides, matching the baseline for fully-covered schemas.

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 scope ('every player's shifts in one NHL game') and enumerates the returned fields (period, start/end, duration, boxscore TOI, plus/minus). This clearly distinguishes it from sibling tools like get_plays and get_situation_time, which cover different slices of game data.

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 for who was on the ice and when') and states the narrowing options ('Filter to one team or player') plus a data-availability boundary ('NHL games from 2010-11 on'). It does not name a specific alternative tool, so it stops short of explicit when-not 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 read-only, non-destructive, closed-world. The description adds real behavioral context beyond them: pages are chronological, a season exceeds one page so next_offset must be followed, and each call costs 10 credits. Lacks only auth/error semantics, so a 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?

Three tight sentences: trigger first, filter modes second, pagination and cost last. No filler, and the most decision-relevant information (when to use this vs. an event list) is 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, return values need no explanation. The description covers the remaining decision-critical gaps for this tool: filter combinations, pagination depth and ordering, and the credit 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 baseline is 3. The description adds the useful combination logic the schema only hints at – 'filter by game, OR by season plus a team or player' – clarifying which parameters pair with which. Strength and league filters aren't elaborated, keeping it at 4.

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 ('every shot attempt with rink coordinates') and explicitly contrasts with the sibling that returns 'a list of events' (get_plays). An agent can distinguish this from get_plays 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?

Opens with an explicit when-to-use trigger ('shot locations rather than a list of events') and enumerates the valid filter modes: by game, or by season plus team or player. The alternative (event list) is named, so routing is unambiguous.

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 cover the safety profile (readOnlyHint=true, destructiveHint=false, openWorldHint=false), and the description adds genuinely useful context beyond them: the shift-chart data source, a completeness check against play-by-play, cost (10 credits per game, 10 per game for a date query), and the 2010-11 onward data boundary. It stops short of describing response shape or failure behavior.

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 primary output list are front-loaded in the first sentence, and cost/coverage details are pushed to the end. It is dense and the middle clause runs long, but almost 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?

With an output schema present, return values need no further explanation, and the description still covers provenance, credit cost, data-range limits, and the optional per-player expansion. 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 description coverage is 100%, so game_id, date, and include_players are already documented. The description reinforces that include_players adds per-skater time by strength and that date and game_id are alternatives, but adds no syntax or constraint detail the schema lacks, 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?

The description opens with a specific verb and resource ('exact time at each strength') and enumerates the concrete outputs — 5v5, 5v4, 4v5, 4v4, 6v5, even/PP/SH totals, period lengths — so an agent can distinguish it from get_shifts, get_plays, and 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 states the calling context ('Use for exact time at each strength') and gives the two mutually exclusive invocation modes: one game by game_id or every game on a date. It does not explicitly name a sibling to prefer or exclude, but the scope and the 'from the shift charts' provenance make the appropriate use clear.

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

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

Annotations already establish readOnlyHint=true, destructiveHint=false, so the safety profile is covered. The description adds genuinely useful non-schema behavior: the 5-credit cost and the historical coverage boundary (seasons from 2010-11 on), both of which affect whether an agent should call it.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Four tight sentences, front-loaded with the trigger condition, then output contents, then the two operational constraints (season range, cost). No sentence is redundant with another, and nothing is 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?

With an output schema present, the description needn't enumerate return fields, yet it usefully previews the stat categories available. Combined with the cost and season-range notes, an agent has everything needed to decide and call correctly; only the fallback routing to a sibling for non-leaderboard queries is unstated.

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 every parameter (team, league, season, sort_by, min_games, limit) is already documented with defaults and formats. The description echoes the sort metrics and the games-played filter without adding syntax or semantics beyond the schema, 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?

States a concrete verb+resource pair: returns a ranked skater leaderboard with sortable metrics and filters. It implicitly differentiates from get_player_stats (single-player) and get_goalie_stats by framing itself as a leaderboard, but never names those siblings, so differentiation is inferred rather than explicit.

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 selection context, which is exactly the scenario where a leaderboard tool beats a per-player tool like get_player_stats. It stops short of explicit exclusions or naming the alternative tool, so it clears the bar for clear context but not full when/when-not 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 cover the read-only/non-destructive safety profile, and the description adds real operational context beyond them: a 2-credit cost, the default to the most recent season with standings, and a caveat that possession columns are 5v5-only and will not reconcile with a goalie's all-situations expected goals.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences, front-loaded with the usage trigger, then the returned metrics, then the possession caveat and credit cost. Every sentence earns its place, though enumerating return columns overlaps with the 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 need not be explained, yet the description still covers the key semantics an agent needs: defaults, filtering intent, cost, and a subtle correctness caveat. Nothing needed 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 league, season, division, and conference are already fully documented, including the enum values and accepted season formats. The description adds only the season-default behavior, which the schema also states, 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?

The description states a clear resource and scope: team rankings within a division or conference, with the specific stats returned. It is distinguishable from get_team_stats in intent, though it never names or contrasts with 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 when checking where teams rank in their division or conference" gives a concrete triggering condition and the default-season behavior. It stops short of naming alternatives or stating when not to use it (e.g. vs get_team_stats).

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=true and destructiveHint=false, so the safety profile is covered. The description adds value beyond them by disclosing the 5-credit cost and the non-obvious 'possession is 5v5 only' scope caveat, which an agent could otherwise misread as all-situations 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?

Four short sentences, front-loaded with the usage trigger, and each carries distinct information: payload contents, the 5v5 scope caveat, the required parameter plus fallback, and the credit cost. 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. With all three parameters documented, the safety profile in annotations, and the description adding cost and scope caveats, an agent has everything needed to invoke this correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so team, league, and season are fully documented in the schema itself. The description restates the required 'team' abbreviation and the list_teams fallback but adds no format or default detail beyond the schema, 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?

States a specific verb+resource ('full details for one team') and enumerates the exact payload: record, goals for/against, league rank, and 5v5 possession metrics. An agent can separate this from 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?

Opens with an explicit 'Use when you need full details for one team' trigger and routes the agent to list_teams if the abbreviation is unknown. It stops short of naming when to prefer a sibling (e.g. get_standings for league-wide tables), so it is strong but not fully 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 establish readOnly/openWorld=false/destructive=false, so the safety profile is covered. The description adds non-obvious behavioral context the annotations cannot convey: the cost signal ('cheapest tool at 1 credit') and the negative scope of historical franchises.

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 use condition, then scope, then exclusions and cost. No filler; the only mild redundancy is restating 'list teams' from 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?

An output schema exists, so return values need not be described, and the description covers use case, scope, exclusions, and cost. The one gap is that multi-league support (pwhl, ohl, whl, etc.) is never mentioned, leaving an agent to discover it only from 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 100% with two enums, so the schema fully documents league/conference/division. The description only indirectly implies the NHL default via '32 active NHL teams' and adds no syntax or filtering semantics beyond the schema, 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 (list) and resource (teams) plus the actual return fields (city, conference, division, arena) and meaningfully distinguishes itself from get_team_stats/get_standings. The only weakness is that it frames the tool as NHL-only ('all 32 active NHL teams') while the schema accepts eight leagues, which slightly narrows the perceived scope.

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 ('when you need team abbreviations') and an explicit exclusion ('Excludes historical franchises (ATL, ARI)'). It does not name a sibling alternative, but the use case is unambiguous without one.

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=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description usefully adds non-annotation context: the dataset's date range (2010-11 onward), the default active-only behavior, and a 2-credit cost. Return format and pagination behavior are left unstated, but the output schema covers returns.

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?

Five short sentences, each with a distinct job: trigger, scope, default behavior, next step, cost. The most decision-relevant information (what it does, when to use it) is front-loaded 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?

With an output schema present, the description needn't explain return values, and it doesn't. For a read-only search tool it covers the trigger, defaults, cost, and the handoff to a sibling, leaving no gap an agent needs to fill 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 description coverage is 100%, so every parameter (team, limit, query, active, league, position) is already documented in the schema. The description only restates the `active` default, adding no syntax or format meaning beyond the structured fields. 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 (search/look up) and resource (players by name) with concrete scope: 4,900+ players since 2010-11. It clearly distinguishes itself from get_player_stats, which it names as the follow-up detail tool rather than a competitor.

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 looking up a player by name' gives an explicit trigger, and it routes the agent onward to get_player_stats for full details. It lacks an explicit 'when not to use' (e.g., resolving IDs vs. bulk season stats), so it stops 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.