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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds disclaimers ('Read-only public research data', 'Not investment advice') and discloses edge-case behavior in the sort_order parameter: 'When CEX + sort_by volume_perps_* uses the HF derivatives sub-index only... response echoes the normalized value.' This goes beyond annotations, though it doesn't fully describe output shape or error handling.

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 three crisp lines with no filler. It front-loads the core purpose (ranked list with filter/sort) and then supplies routing and safety caveats. Every sentence earns its place—no redundancy with schema or annotations.

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 search tool with 5 optional parameters and an output schema, the description covers purpose, usage, safety, and parameter quirks. It doesn't mention pagination details or response format, but the output schema handles that. The routing to siblings and platform_type mapping are well-specified. A small gap: it doesn't explicitly state that the result is sorted by default but that's implied by sort_by default in schema.

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 coverage is 100%, so the baseline is 3. The description adds meaningful extra semantics: for sort_order it explains the CEX + volume_perps sub-index behavior and response echo, and for platform_type it already provides mapping in the schema but the description's parenthetical notes (e.g., 'any other value is passed through to the index') add context beyond the raw property definition.

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 returns a 'Ranked multi-protocol list with filter and sort', which is a specific verb (search) on a resource (platforms). It explicitly differentiates from siblings by pointing to get_platform_info and get_platform_history for other use cases, leaving no ambiguity about scope.

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?

Usage guidance is explicit: 'One-shot profile→get_platform_info. One named protocol daily series→get_platform_history.' tells exactly when to use this tool vs others. It also states the read-only, public-data nature and constraints (no account access, no order placement), giving clear context for appropriate invocation.

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