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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the description doesn't need to repeat those. It adds meaningful behavioral context: the tool 'names no winner, no margin and no recommendation' – clarifying it's neutral and not a prediction/ranking tool. It also states that invalid metrics are 'refused with the nearest ones,' revealing a fallback behavior. This goes beyond the annotations and helps the agent set expectations.

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 description is dense but well-structured. It opens with the core purpose, then adds a key behavioral trait (no winner), and then details the metrics parameter. Every sentence adds value; there's no fluff. It's slightly longer than necessary but remains focused. Front-loading the purpose and key behavior helps the agent quickly understand the tool's essence.

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 no output schema, the description must explain the return behavior. It states 'shown side by side,' 'Each side carries its source rank,' and 'States both figures and stops' – giving some idea of output structure. However, it does not clarify the response format (e.g., JSON shape), nor does it explain all parameters (a, b, season, entity_kind). For a tool with 6 parameters and no output schema, the description is moderately complete but leaves gaps that could affect 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 description coverage is 0%, so the description must compensate. It explains 'metrics' in detail (accepted keys, plain-English names, refusal of non-panel metrics) and mentions 'all:true' for the full set. However, it does not explain 'a', 'b', 'season', or 'entity_kind'. While 'a' and 'b' are presumably entity identifiers and 'entity_kind' is implied by 'two players or two teams', the description leaves these to inference. For a 6-parameter tool with zero schema coverage, this partial coverage is inadequate.

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 clearly states the tool compares two players or teams side by side, with a default focus on position-relevant metrics and an explicit option for the full set. It distinguishes itself from sibling tools like get_entity_metrics (single entity) and run_stat_query (derived stats) by emphasizing it shows both figures without declaring a winner, margin, or recommendation. The verb 'compare' and resource 'players/teams' make the purpose specific and 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?

The description provides clear context on when to use the tool: when you need a side-by-side comparison. It gives explicit guidance on the 'metrics' parameter, stating it accepts verified panel metric keys from list_metrics or plain-English names, and warns that measures only run_stat_query computes are refused. While it doesn't name sibling alternatives like get_entity_metrics or query_stat_leaders directly, the implied contrast (comparison vs single entity vs derived stats) is sufficient. It could improve by explicitly saying 'use this for comparing two entities, not for single-entity metrics.'

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