Compare selected Aerodrome pools

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds real behavioral value beyond that: deterministic output ordering ('Preserves input order'), explicit null semantics for missing data ('Unknown data stays null'), single-block snapshot semantics, and a disclaimer that no ranking is produced.

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 compact sentences, each carrying distinct information (what is compared, ordering/null behavior, what is excluded). Front-loaded with the core operation and free of 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?

An output schema exists, so return values need not be described, and annotations cover the safety profile. The description supplies the remaining essentials: input cardinality, uniqueness, ordering guarantees, null handling, and scope exclusions.

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?

With only one parameter at 0% schema description coverage, the description carries the semantic load and does so: it states the count bounds (2–16, matching minItems/maxItems), the 'distinct' uniqueness requirement the schema does not enforce, and that input order is preserved in output. Address format is left to the schema's regex.

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 names a specific verb (Compare), a bounded resource (2–16 distinct Aerodrome pool addresses), and enumerates exactly what is compared (Voter weights, protocol weight shares, gauge registration/liveness, reward contracts). This clearly separates it from the wallet- and protocol-oriented siblings, which none of them do.

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 sets explicit boundaries on what this tool is for ('no yield, liquidity or profitability ranking') and constrains the input shape ('2–16 distinct pool addresses ... at one Base block'), giving clear context for when it applies. It does not, however, point to an alternative tool for the excluded analyses, so it stops short of explicit when-not/alternative routing.

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