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

Annotations already declare readOnly/idempotent/non-destructive, so the bar is lower, and the description still adds real behavioral detail: ambiguous symbols return every candidate by address rather than guessing, and unlisted tokens come back flagged with no name or symbol. It does not discuss pagination or result size, but for a two-parameter lookup the disclosed behavior is solid.

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?

Every sentence carries information — scope, return fields, ambiguity handling, unlisted-token behavior, and sibling placement — with no filler. The first sentence is long and packs the chain list and return shape together, which slightly hurts scannability but not correctness.

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?

There is no output schema, so the description takes on the burden and does: it names the returned fields and the edge-case shapes for ambiguous symbols and unlisted tokens. Combined with the read-only annotations, an agent has everything needed to call it and interpret the result.

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?

Only 50% schema coverage, but the description compensates: it spells out that `query` accepts either a symbol or a contract address, and its prose chain list (Ethereum, Arbitrum, Base, BNB Chain, Polygon, Optimism) supplies the meaning for the undescribed `chainId` enum. It also clarifies resolution behavior per input type, which the schema does not.

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?

States a specific verb (finds) and resource (token by symbol or contract address), enumerates the supported chains, and lists exactly what is returned (address, decimals, list status, similarity flag). An agent can distinguish this from the planning/tracking siblings without opening any 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?

Gives an explicit trigger: use it before cleave_plan_swap when the user names a token by symbol and the address is unknown, which directly routes the agent relative to a sibling. It stops short of stating when not to use it (e.g. when the address is already known, where plan_swap could be called directly).

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