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

With no annotations, the description carries the full burden and does so well: it discloses deprecation/lag risk ('scores lag the catalogue and newer models may be unranked'), auth requirements ('Authorization: Bearer'), cost per call and credit pricing, and output semantics (shortlist vs verdict). It stops short of stating pagination/error behavior, keeping it below a perfect 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 deprecation warning and the 'use decide' routing are correctly front-loaded, and each sentence carries distinct information (routing, output caveats, auth, cost, presentation rules). It is dense and slightly sprawling across concerns, but no sentence is pure filler.

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?

For a deprecated, paid tool with no output schema, the description covers the return shape, safety/routing rules, and user-presentation obligations well. The remaining gap is the undocumented nested parameters, which is captured under parameter semantics rather than a missing description of the tool's behavior.

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 only 25%, so the description must compensate, but it never explains the parameters. The nested 'constraints' and 'environment' objects and 'limit' are undocumented in both schema and description, and only 'use_case' is even implicitly referenced via 'fixed use-case profile'.

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 states a specific verb and resource (a ranking of models against a fixed use-case profile) and qualifies the output ('a shortlist with evidence_basis and input provenance, not a quality verdict'). It distinguishes itself from siblings by leading with 'Legacy v1; use decide' and explaining the fixed-benchmark scope, so an agent can tell it apart from decide and compare_models without opening a schema.

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 explicit when-nots ('Don't call it as a fallback when decide has no single leader; report its tie') and names the preferred alternative (decide) by name. It also routes downstream behavior ('When next_move is present, offer it instead of a pick'), leaving little to inference.

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