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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so safety is covered. The description adds genuinely non-structured facts: data only goes back to 2018 for the score/win-probability fields, league defaults to NBA, and each call costs 10 credits. It stops short of describing pagination behavior or how scoring fields behave for pre-2018 seasons beyond the parenthetical.

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

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

Two sentences, front-loaded with the use case, then the payload, then filters, then league defaults and cost. Every clause carries distinct information with no restatement of the tool name or annotations. Dense but readable given 13 parameters.

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 not be explained, and the description covers the remaining unknowns: temporal coverage, league switching, cost, and default season. Pagination via offset/limit and the meaning of season_type are left entirely to the schema and are the only meaningful omissions for a 13-parameter 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 77%, so several fields (offset, period, season_type) carry no description. The prose compensates by explaining the league switch and its default ('Pass league for the WNBA (wnba) or college (ncaam, ncaaw); default NBA') and by grouping the filter parameters into a readable set of choices. It does not clarify the offset/limit paging pair, leaving one gap against the remaining 23%.

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 up front ('Use for play-by-play') and defines scope precisely: every event of a game, or a player's/team's plays across a season. The listed payload (shot location in feet, zone, expected points, score and home win probability after each play) makes it unmistakably a play-level feed. It never names the nearest sibling, get_shot_chart, so an agent must infer the boundary between an aggregated chart and event-level 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?

Gives explicit selection criteria: pass game_id for one game, player_id plus season for a player, team for a team, and a full set of filter conditions (shots/makes/misses, zone, period, clutch). This is a clear usage context. However, it offers no exclusions or named alternatives (get_shot_chart, get_player_games, get_game) for the cases where this tool is the wrong choice.

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