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

Annotations already carry readOnly/idempotent/openWorld/non-destructive hints, and the description adds genuinely new behavioral context: it is a paid resource with an exact per-call price ($0.002 USD), and its results are explicitly flagged as unverifiable. The prohibition list also discloses where the tool's output is untrustworthy. No contradiction with annotations exists.

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?

Three sentences, each earning its place: core function, intended/forbidden usage, and cost. The primary function is front-loaded, and the disclaimers and pricing are compact. Zero 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 tool with nested objects, up to 500 candidates, and no output schema, the description should explain what the caller gets back (a ranked list of ids? with scores?) and how constraint violations affect ranking (disqualify vs. penalize). The cost and scope are well covered, but the missing return-value contract and implicit permission/payment semantics leave real gaps for safe 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 carries the burden, and it only maps the top-level parameter groups (weights, constraints, and the five signals) without explaining field-level semantics: the 0–1 normalization of trust/quality/reliability, the role of boolean fields (permission_ok, payment_supported, require_payment, require_permission), or how weights and constraints interact. Self-explanatory parameter names and schema min/max bounds partially compensate, but the boolean semantics and weight/constraint interplay remain ambiguous.

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 ('Ranks') with a clear resource ('caller-supplied candidates') and enumerates the ranking dimensions (price, reliability, latency, trust, quality) plus the weighting/constraint mechanism. This distinguishes it from the many selection_routing_router and selection_routing_control_plane siblings, whose roles (routing vs. ranking vs. control) are structurally different.

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 an explicit intended use ('Intended for selection routing') and an explicit when-not-to-use list ('Do not use for legal, identity, sanctions, fraud, contractual, or regulatory adjudication'), plus the 'result unverifiable' caveat that tells an agent to treat output cautiously. It stops short of naming a specific sibling alternative (e.g., which of the three ranking_api variants to prefer), so it earns a 4 rather than a 5.

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