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

The annotations already provide readOnlyHint, openWorldHint, and idempotentHint, which cover non-mutating and idempotent behavior. The description adds valuable context beyond annotations: it clarifies that the output is deterministic (not LLM-generated), includes specific Glicko-2 inputs (μ/φ), and tailors to Annex IV audit needs. It also discloses API key behavior differences between endpoints (public vs /mcp/mcp), which is behavioral transparency beyond annotations. This adds significant context about stability and authentication nuances.

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 compact, three short paragraphs, with front-loaded purpose. The first sentence immediately states the tool's purpose and contract. The second paragraph explains the output and use case, and the third gives a crucial API key nuance. Every sentence adds value: no fluff, no repetition of schema details. The structure is clear and efficient.

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 tool has an output schema, so the description needn't detail return values. The description covers purpose, behavioral traits (deterministic, non-LLM), and even authentication nuances (api_key). It mentions the target audience (Annex IV auditor) which aids in usage context. The only gap is that it doesn't explain what the narrative might contain or how to interpret the μ/φ inputs, but since the output schema likely covers that, it is relatively complete. The main missing piece is explicit guidance on when to use this vs similar tools like aimrank_predict_matchup_winner, but given the strong purpose clarity and output schema, it's adequate.

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?

The input schema has 0% description coverage, and the description does not explain any of the four parameters beyond their names. It does mention api_key is optional on the public endpoint, which adds some semantic insight into that parameter. However, for ranking_id, entity_a_id, entity_b_id, the description provides no meaning beyond what the schema provides (just field names). Given the schema is minimal and the description doesn't compensate, a score of 3 is appropriate, as it partially addresses api_key semantics but not the others.

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 that the tool explains a prediction in terms of features and narrative, specifically for the iCOMPLY contract. It mentions 'Glicko-2 μ/φ inputs' and 'deterministic narrative', which gives a clear sense of the tool's function. While the name 'aimrank_explain' suggests explanation, the description adds specificity by detailing the output nature and the absence of LLM-synthesised rationale, distinguishing it from generic explainability tools. However, it could be slightly more explicit about the context of 'prediction' (likely from aimrank_predict), but the intent is clear.

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 implies when to use this tool: when an auditor needs to trace the actual numbers behind a prediction via an Annex IV framework. It also contrasts with LLM-synthesised explanations, suggesting it is the alternative for deterministic, traceable output. However, it does not explicitly name sibling tools like aimrank_predict or aimrank_get_matchup that might be alternatives. The context of 'Annex IV auditor' provides a clear scenario, which is strong guidance, but lacking explicit exclusions or direct sibling comparisons.

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