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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered; the description adds the row-grain contract and the mandatory scoping rule, which materially change how an agent calls it. It omits any note on result size or pagination for a potentially large per-shot result set, which is the main remaining behavioral 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?

Two sentences, front-loaded with the purpose and followed by the field inventory and the constraint. The field list is dense but each item is informative rather than filler; a small trim of the coordinate and zone parentheticals would tighten it without losing meaning.

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 schema coverage, the description only needs to carry purpose, grain and call constraints — all of which it does. The one thing an agent might still wonder about is how to source team_id/player_id and how large the result can get, both of which are left to the schema or unaddressed.

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 season format, the team_id/player_id pairing, league_id, season_type and context_measure. The description only restates the player-or-team scoping requirement and adds no format, default, or valid-value detail beyond the schema. Baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Get NBA shot chart') and then pins down the grain: one row per shot with game, player, team, period, action type, zone, distance, coordinates and made flag. That is enough for an agent to know it is not a box score or an aggregate shot-location tool. It stops short of naming the close siblings (nba_lineup_shot_chart, nba_player_pt_shot, nba_team_shot_locations) to route between 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?

The description gives one hard constraint — 'Scoping to one player or one team is required' — which tells the agent it must pass an id rather than call it bare. It does not say when to prefer this over the lineup or team shot-location variants, nor what happens if both ids are supplied, so the routing guidance is implied rather than explicit.

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