get_match_player_stats

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

With no annotations, the description carries the full burden and adds substantial context: it strips UI metadata, recalculates hitting percentage, returns a formatted box score or compact JSON, and explains that force_refresh bypasses a 7-day disk cache. It does not mention authentication, permissions, or error behavior, which keeps it from a higher score.

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 is front-loaded and the Args/Returns structure is easy to scan. The long list of statistical fields is useful but somewhat verbose given that an output schema exists, so the description is not maximally concise.

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?

The description covers all four parameters, output formats, cache behavior, and how to obtain the required match_id. Since an output schema exists, it need not fully define return values, and the remaining gap around auth or error handling is minor for a read-only stats 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 description coverage is 0%, so the description must compensate, and it does: match_id is tied to a Hudl match identifier obtainable through list_volleyball_matches, team_id is an optional filter, output_format distinguishes markdown from compact JSON, and force_refresh is explained as bypassing the local 7-day disk cache.

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: 'Fetch individual athlete box scores and volleyball statistics for a match.' It clearly distinguishes this from sibling tools like get_rotation_breakdown and get_game_actions by focusing on per-player box scores, not rotation summaries or play-by-play actions.

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 clear context for obtaining the required match_id via list_volleyball_matches and explains optional filtering by team_id. However, it stops short of explicitly stating when to prefer this tool over siblings such as get_rotation_breakdown or get_game_actions, leaving that inference to the agent.

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