PuckAPI

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

Annotations only declare readOnlyHint and openWorldHint, so the description adds real value beyond them: a 10-credit cost, the 2019-20+ odds coverage window, and the fact that goalie starts are derived from play-by-play and therefore absent for unplayed games. These are exactly the behavioral traits an agent needs before invoking.

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

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

Three dense sentences, front-loaded with the use case and followed by prerequisites, coverage caveats, and cost. Nothing is wasted, though the 'with their time on ice' clause slightly restates what the return content already implies.

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 covers the remaining gaps an agent faces: ID sourcing, credit cost, and data-availability limits by date and game status. Complete for this tool's complexity.

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; the description still adds meaning by explaining where game_id comes from (get_games or get_schedule) and implying its scope. The league parameter is left 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 the specific resource ('one game') and enumerates exactly what it returns: both teams' full info, all betting odds, and starting goalies with time on ice. That enumeration distinguishes it from siblings like get_odds and get_goalie_stats without needing to name them 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?

Opens with an explicit when-to-use ('Use when you need everything about one game'), tells the agent where to obtain the required ID (get_games or get_schedule), and gives a when-not: goalie starts are unavailable for upcoming games. This is close to ideal 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 readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds real value beyond them: the cost (5 credits) and the comparative cost of the alternative, which affects tool selection. It stops short of noting rate limits or pagination behavior, but this is a filtered-read tool where that gap is 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?

Three tight sentences with no waste: purpose, return shape, routing alternative plus its cost, and own cost. The routing guidance is front-loaded where an agent will see it before committing to the 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?

An output schema exists, so return values need not be detailed, yet the description still hints at the payload (scores, teams, venue, metadata). Combined with full schema coverage and clear routing guidance, an agent has everything needed to select and invoke it correctly.

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

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

Schema description coverage is 100%, with all 8 parameters documented in the schema including enum meanings and date formats, so the schema does the heavy lifting. The description adds no parameter-level detail beyond pointing at 'filters' generically, so the baseline 3 is appropriate.

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 with filters') and enumerates what comes back (scores, teams, venue, game metadata). It clearly distinguishes itself from the sibling get_schedule by scope (past/future vs upcoming-only).

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 querying past or future games with filters') and names the alternative with the condition that selects it ('For upcoming-only games, prefer get_schedule (2 cr) instead'). The when-to-use and when-to-prefer-something-else are both 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 only cover the read-only, closed-world safety profile; the description adds genuinely new behavioral facts: a cost of 5 credits, the exact metrics returned (GSAX, high-danger save%, rolling 10-game save%/GSAX, form trend, rest days), and a data-coverage nuance that goalie xG spans all strengths unlike the 5v5-only team possession columns.

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 in the first clause, followed by a dense but tightly packed enumeration of outputs and the cost line. It is run-on in places but nearly every phrase carries 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 six-parameter, zero-required leaderboard tool with an output schema and read-only annotations, the description covers when to call it, what it returns, the nuance around xG coverage, and the credit cost. Nothing needed for correct invocation is missing.

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

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

Schema description coverage is 100%, so the schema already documents all six parameters including defaults and enum values. The description's 'sorted by save%, GAA, GSAX, or wins, with a games-played filter' largely restates sort_by and min_games rather than adding syntax or edge-case guidance, 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?

The description names a specific verb and resource ('ranking goalies', 'goalie leaderboard') and states the sort metrics, which cleanly separates it from the skater-oriented siblings (get_player_stats, get_skater_season_stats). 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?

It gives a clear trigger condition ('Use when ranking goalies or comparing goalie performance') and implies the games-played filter context. It does not explicitly name an alternative tool or a when-not-to-use case, so it falls short of a 5.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds valuable behavioral context: the credit cost (10 credits) and the ability to filter or get all-time, which goes beyond annotations. However, it doesn't detail pagination or return format, but output schema exists.

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 usage, then output, then filtering and cost. Every sentence earns its place with zero 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?

Given the tool complexity, annotations, and output schema, the description is nearly complete. It covers when to use, what it returns, filtering options, and cost. Only minor gap is absence of explicit alternatives, but overall sufficient.

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 fully documents all parameters including defaults and formatting. The description mentions filtering by season or all-time, which aligns with the schema's season parameter, but adds no new semantic detail. Baseline 3 is appropriate.

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 (comparing) and resource (two teams' history), and clearly distinguishes from siblings like get_games or get_team_stats. The output focus on recent matchups with win/loss record is 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?

Provides clear 'when to use' context: comparing two teams' history. It also distinguishes filtering by season vs all-time. Missing explicit when-not-to-use or alternative sibling names, but the context is strong.

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 openWorldHint=false, so safety is covered. The description adds two traits not present in structured fields: cost (25 cr, the most expensive tool) and the result organization (time-series grouped by bookmaker). It stops short of stating time range, snapshot density, or pagination limits, which would matter for an expensive analytics call.

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: purpose, return shape, cost, and alternative all front-loaded with zero 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 still summarizes the grouping. Purpose, cost, and sibling routing are all covered for a low-complexity two-parameter read tool.

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 documented there including the lowercase bookmaker key convention. The description adds no syntax or format 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 ('how betting lines moved over time') and specifies the return shape ('time-series snapshots grouped by bookmaker'). The sibling get_odds is explicitly named as the contrasting tool, so an agent can route between them 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 ('analyzing how betting lines moved over time'), explicit when-not plus alternative ('If you only need current lines, use get_odds (10 cr) instead'), and cost differentials to support the choice. This is textbook 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 only declare readOnlyHint=true and openWorldHint=false; the description adds substantial non-obvious behavior: credit pricing (10/game, ~13,700 for a season), that estimate_only avoids charging, per-season book coverage counts, and provenance tagging (the_odds_api vs espn). This is exactly the cost/quota/disclosure context annotations 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 correctly with when-to-use and cost, but the middle is a dense run-on of parenthetical figures (cost totals, per-season book counts) and the book-count figures are duplicated verbatim in the all_books schema description. The provenance sentence at the end is also clipped and hard to parse.

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 9-parameter tool with two operating modes and an output schema already covering return values, the description supplies mode routing, pricing, pagination defaults, and data-coverage caveats. Only the error behavior when neither game_id nor season is supplied is left 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 coverage is 100%, so the baseline is 3, but the description adds cross-parameter semantics the schema only hints at: game_id and season are alternatives ('used when game_id is not set'), team/all_books/snapshot_type only apply in season mode, and each book's line array follows the columns order.

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 clear verb+resource (retrieve betting lines/odds) and goes further by spelling out the two retrieval modes and what each returns. It never distinguishes itself from the sibling get_line_movement, which an agent could easily confuse with odds retrieval, so it stops short of a 5.

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

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

Gives explicit mode-selection guidance ('Pass game_id for one game ... Or pass season ... for a whole season'), plus the cost-saving estimate_only path. It does not name or exclude any sibling (e.g. get_line_movement for movement over time), so usage is clear but has no explicit alternatives.

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

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

Annotations only declare readOnlyHint and openWorldHint, so the description carries real weight and does: it discloses the data provenance ('built from play-by-play') and the resulting gaps ('time on ice and plus/minus ... come back null; goalie time on ice is available only for games the goalie started'). It also notes the season actually used is echoed in the response, which sets expectations about return content and 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?

Front-loaded with the use condition and the key exclusion, then the field lists, then caveats and prerequisites. The two stat enumerations are long but earn their place by letting an agent verify the tool returns the metric it needs. Slightly dense, 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?

An output schema exists, so return-shape explanation is not owed, yet the description still preempts the most likely support question (missing TOI/plus-minus) that an output schema alone would not explain. Combined with prerequisites, cost, and the season-echo behavior, nothing needed 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 description coverage is already 100%, with league, game_type, season, limit and offset all documented in-schema including defaults and formats. The description adds no syntax or constraint detail beyond that, so the baseline 3 applies; its value is in describing output content rather than parameter 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?

Opens with a specific trigger and resource: 'a player's game-by-game stat lines for a season, not a season total.' That negative clause immediately separates it from the season-total siblings (get_player_stats, get_skater_season_stats). It then enumerates the exact stat columns returned for skaters and goalies, so the agent knows precisely what this tool produces.

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?

States the when ('game-by-game stat lines for a season'), the when-not ('not a season total'), and the prerequisite ('Requires player ID from search_players'), which chains it to the correct sibling for ID lookup. It also surfaces the cost ('Costs 5 credits'), which is decision-relevant for an agent weighing alternatives.

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, openWorldHint=false), so the bar is lower. The description adds genuinely useful non-schema context: a 5-credit cost and the dependency on search_players for the ID. No access/permission or rate details, but the cost disclosure is real behavioral value.

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 trigger first, then a tight enumeration of returned fields, then prerequisites and cost. Three sentences, all earning their place, 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?

An output schema exists, so return values need not be described, yet listing them helps an agent pick this tool over the specialized stat tools. Combined with the cost and ID-source notes, the definition is complete enough to invoke correctly; only sibling differentiation is missing.

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

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

Schema description coverage is 100% and both parameters (league enum, player_id) are fully documented in the schema. The description only adds that the ID comes from search_players; it does not explain the league parameter's impact on results, so baseline 3 is right.

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, split by skater vs goalie. It is clearly distinguishable from generic stat lists, though it never names the sibling tools (get_goalie_stats, get_skater_season_stats) that overlap with its output.

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 a clear trigger ('Use when you need full details for one player') and a hard prerequisite ('Requires player ID from search_players'), which routes the agent through the correct lookup first. It offers no when-not guidance or comparison to the specialized stats siblings.

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 openWorldHint=false, so the safety profile is covered. The description adds real non-obvious context: the 10-credit cost, the at-least-one-identifier precondition, and offset-based pagination. Return-format detail is largely redundant since an output schema exists, keeping 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?

Three dense sentences, front-loaded with purpose then filters then preconditions then cost. Every clause carries information (event inventory, filter list, gating rule, pagination, price) 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?

For a 12-parameter, mostly-optional query tool with full schema coverage and an output schema, the description supplies exactly the missing pieces: what the tool is for, the required-identifier rule, and cost. Nothing an agent needs to invoke it correctly is omitted.

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 a semantic constraint absent from the schema (which declares zero required params): at least one of game_id, season, or player_id must be supplied, plus 'player (any role)' and 'offset' pagination semantics. That is meaningful meaning beyond the field-level docs.

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+resource ('play-by-play events') and then enumerates the concrete payload (goals, shots, faceoffs, hits, rink coordinates, strength state, zone, players), which lets an agent distinguish it from siblings like 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 states the triggering condition clearly ('Use for play-by-play events') and gives a hard gating rule ('Requires at least one of game_id, season or player_id') plus pagination guidance. It stops short of naming an alternative tool or saying when *not* to use it, so it earns 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 cover the safety profile (readOnlyHint=true, openWorldHint=false), so the description's main added value is the credit cost and the 'unplayed future games only' filtering behavior, which are not in the annotations. It stops short of describing pagination or result limits, so it is strong but 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?

Three short sentences, each earning its place: trigger, core behavior, routing alternative, plus a cost note. The most decision-relevant information (upcoming-games scope) 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?

An output schema exists, so the description needn't explain return values, and it covers the key behavioral facts an agent needs (future-only scope, default window, credit cost, alternative tool). Complete for this tool's complexity.

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%, with the days parameter (default 7, max 30), team abbreviation, and league enum all documented in the schema. The description restates the default-7 window but adds no format or syntax detail beyond what the schema already provides, so baseline 3 is appropriate.

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 upcoming games) plus exact scope: only unplayed future games for the next N days. It explicitly names the sibling it is not (get_games for past games), so an agent can differentiate without opening schemas.

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

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

Gives an explicit trigger ('Use when checking what games are coming up'), an explicit exclusion/alternative ('For past games, use get_games instead'), and a cost caveat ('Costs 2 credits'). Nothing about when to select this tool 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 only declare readOnlyHint and openWorldHint, so the description adds real behavioral context a caller needs: pagination mechanics ('follow next_offset'), the fact that pages are chronological, that a season exceeds one page, and the 10-credit cost. It stops short of describing failure modes or rate limits, but this is well beyond the annotation baseline.

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 selection condition, then filter options, then pagination and cost. Every clause carries information an agent needs; 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?

Output schema exists so return values are covered elsewhere; the description supplies the operational details an agent needs to actually page through a season and budget credits. No meaningful gap remains for an 8-parameter, zero-required read tool.

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 the combination logic the schema only hints at ('game, or by season plus a team or player') plus the chronological page ordering, which tells the agent how offset behaves in practice. It does not explain strength or league semantics 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?

States a specific verb and resource ('every shot attempt with rink coordinates, shot type, strength, shooter and goalie') and explicitly positions it against an alternative ('rather than a list of events'), which cleanly separates it from siblings like get_plays and get_line_movement.

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 the when-to-use condition up front ('Use when you want shot locations rather than a list of events') and spells out the two valid filter shapes: by game, or by season plus team or player. Nothing about selection 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 readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds genuinely new behavioral context: a 5-credit cost, the 2010-11 season floor, and the fact that the returned stat set includes power play/shorthanded production, shooting%, faceoff%, and TOI. No pagination or defaulting caveats beyond the schema, which is the only 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?

Front-loaded with the trigger condition, then answers question, then contents, then constraints and cost. Every sentence carries information, though the stat-category enumeration is somewhat redundant against the existing 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?

For a fully-defaulted, zero-required-parameter list endpoint with an output schema and readOnly annotations, the description supplies everything else an agent needs: when to use it, cost, season coverage, and the shape of the leaderboard. 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%, including enum values and the nuanced default-season behavior, so the baseline is 3. The description restates the sort metrics ('points, goals, assists, plus/minus, or shots') and the games-played filter but adds no syntax, units, or edge-case meaning the schema does not already carry.

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 leaderboard' of skater scoring stats) and scopes it to ranking/comparison use, which cleanly separates it from get_player_stats (individual lookups) and get_goalie_stats (different population). An agent can pick it correctly 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 ranking skaters or comparing scoring' gives a clear positive trigger condition. It does not, however, name the sibling it is not (e.g. get_player_stats for a single player's line) or state exclusions, so it falls short of the explicit when/when-not bar.

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 this is a read-only, closed-world call. The description goes beyond them by disclosing the credit cost (2 credits), the default season behavior, and a data-scope caveat that 5v5 possession metrics will not match a goalie's all-strength expected goals against.

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, followed by returns, then the caveat and cost. Every sentence is informative, though the long enumeration of stat columns is dense relative to what the output schema likely already conveys.

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 and full parameter coverage, the description needs only to frame the scenario, defaults, and cost, all of which it does. Nothing an agent needs to invoke 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 description coverage is 100%, so league, season, division, and conference are all self-documented with formats, enums, and defaults. The description adds no parameter-level detail, 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 opening sentence ('Use when checking where teams rank in their division or conference') gives a specific verb-like action and resource, and immediately enumerates the returned fields. An agent can distinguish it from get_team_stats or get_goalie_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?

It states the scenario that should trigger the tool and notes that it defaults to the most recent season with standings. It does not name an alternative tool or state when not to use it, 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 declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds a useful scoping note that possession is 5v5 only and states a cost (5 credits), which is real behavioral context. However, it doesn't mention caching, rate limits, or season/league default behavior beyond what the schema says.

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 primary use case, followed by metric scope and the cost note. Every sentence is short and carries actionable information 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 a rich output schema already defined, the description needn't explain return structure. It covers usage, prerequisites (abbreviation, list_teams fallback), scoping granularity, and cost – everything an agent needs 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 three parameters are already documented. The description adds a partial hint ('Requires a team abbreviation') and a referral to list_teams, but does not clarify league/season format beyond what the schema provides. Baseline 3 is appropriate.

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 ('get full details for one team') and enumerates the exact metrics returned (record, goals for/against, league rank, 5v5 possession). Clearly distinguishable from siblings like get_player_stats or get_standings.

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

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

Explicitly says 'Use when you need full details for one team' and routes to list_teams when the abbreviation is unknown. Provides a clear activation condition and an alternative for disambiguation.

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 openWorldHint=false, so safety is covered. The description adds behavior the annotations do not: historical franchises are excluded from results, and the call costs 1 credit. Return format is not described, but an output schema exists to cover that.

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

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

A single compact sentence front-loads the usage condition, then appends the scope exclusions and the cost note. Every clause carries information an agent can act on; there is 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?

For a zero-required-parameter list tool with a 100%-covered schema and an output schema, the description supplies the essentials: purpose, cost, and data-scope exclusions. The one notable omission is any hint that the tool spans eight leagues rather than just the NHL, which matters for cross-league questions.

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 league, division, and conference all documented and two enum-backed, so the baseline is 3. The description never mentions filtering by league, division, or conference; the fields it lists (city, conference, division, arena) are result fields, not parameters, so it adds no parameter meaning 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?

States a concrete resource (team list) with its return fields (city, conference, division, arena) and names the excluded historical franchises (ATL, ARI). It is clearly distinguishable from every sibling, none of which list teams. However, it frames the tool as 'all 32 active NHL teams' while the schema accepts eight leagues (pwhl, ohl, whl, qmjhl, echl, ahl, ushl), so the stated scope under-describes the 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?

'Use when you need team abbreviations' gives a clear triggering condition, and 'Cheapest tool at 1 credit' adds cost context useful for tool selection. It stops short of naming an alternative or stating when not to use it, but no sibling overlaps enough for that to be a serious gap.

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 openWorldHint=false, so safety is covered. The description adds genuinely non-structured context: dataset size and temporal coverage (4,800+ players since 2010-11), the default filtering behavior (active only, active=false for retired/historical), and a cost signal ('Costs 2 credits'). It doesn't discuss rate limits or result-shape, but with an output schema present that is 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?

Five short sentences, each earning its place: trigger, scope, default behavior, next-step workflow, and cost. The most important information (when to use it) is front-loaded and there is 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?

For a 6-parameter search tool with an output schema and safety annotations, the description covers triggers, defaults, dataset scope, cost, and the chained workflow, so an agent has enough to call it correctly. Minor gaps remain around pagination/limit behavior and empty-result handling, but nothing critical 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 6 documented parameters (including enum lists for league and position), so the schema carries the parameter burden. The description only re-states the active default and partial-match searching for query, adding no syntax or format detail beyond the schema; baseline 3 is correct 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 ('looking up a player by name', 'Searches 4,800+ players across every season since 2010-11') and implicitly separates the discovery role from retrieval tools by directing the agent to get_player_stats for details. An agent can distinguish it from get_player_stats without opening either schema.

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

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

'Use when looking up a player by name' is a clear trigger, and the follow-up instruction ('Use the returned player ID with get_player_stats') gives explicit workflow routing to the sibling tool. It lacks an explicit when-not (e.g., 'if you already have a player ID, call get_player_stats directly'), so it stops just 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.