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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=true. The description adds behavioral context beyond that: it is 'research only — non-custodial', it can produce validation errors for unknown sourceChainKey and mentions it does not invent bridge fees, and it notes the output includes rationale for when the raw APY leader differs from the risk-adjusted winner. This is helpful extra transparency, though it doesn't fully describe all edge cases (e.g., what happens if an opportunity ID is invalid). The bar is lowered due to robust annotations, so 4 is fair.

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 concise—a few sentences—with a clear structure: purpose, parameter guidance, output summary, constraint note, and an example. It is front-loaded with the most important info (what it does, how many items), and every sentence adds value. No wasted words.

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?

Given the tool has no output schema, the description compensates by stating what the return contains (ranked list, comparison table fields, winnerId, rationale bullets). It also covers key constraints (2–5 items, SDK validation error for unknown sourceChainKey, aliases). The annotations cover safety (read-only, idempotent). It doesn't explicitly state what happens on invalid opportunity IDs or other error cases, but given the rich schema (with descriptions on every parameter) and clear output summary, it's quite complete. A 4 is appropriate; a 5 would require explicit error-handling for invalid IDs or other edge cases.

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 100%, so the baseline is 3. The description adds value by explaining the relationship between poolIds and opportunityIds (aliases) and telling the agent to use list_yields opportunities[].id values, which is not fully explicit in the schema. It also clarifies that sourceChainKey maps to the agent's current chain and that blank is a validation error, reinforcing the schema enum-like behavior. Since it adds meaningful context beyond the schema, a 4 is justified.

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 does a side-by-side comparison of 2–5 opportunities by risk-adjusted score, and returns a ranked list with comparison fields. It distinguishes itself from siblings like score_opportunity (single scoring) and list_yields (list fetching), and it explicitly mentions the raw APY vs risk-adjusted winner distinction, so an agent can differentiate it from related tools.

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 explicitly tells the agent when to use it: for comparing 2–5 opportunities. It provides guidance on parameter source (pass list_yields opportunities[].id values as poolIds or opportunityIds), and it names sibling tool list_yields as the source for the IDs. It also gives a concrete example. This is strong usage guidance that goes beyond generic 'how to call' and covers data sourcing.

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