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

Annotations only declare read-only/idempotent/open-world, but the description discloses behavior annotations cannot: the $0.001 x402 charge, the two-call 402 challenge flow, that failures are not charged, and that statistical outliers are dropped unless includeOutliers is true. That is rich, non-redundant operational context.

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 paid/402 caveat is front-loaded and every clause carries information, but the second sentence crams filters, output fields, and outlier behavior into a single dense run-on. It is appropriately sized for an 8-param paid tool yet could be parsed more easily.

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 an output schema exists, return values need not be enumerated, yet the description covers the fields, defaults, outlier handling, payment/error semantics (>=400 not charged), and the auto-paying client. An agent has everything needed to call and pay correctly.

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 already 100%, so the schema carries the parameter burden. The description still adds value beyond it by restating defaults (Base, $1M TVL) and by explaining the payment/retry lifecycle and the outlier-exclusion default, which are semantics the enum and type fields alone would not convey.

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 resource (DeFi yield pools) and the exact question it answers ("Where a token earns the most"), names DefiLlama as the source, and its scope is clearly distinct from siblings like token_price or stablecoin_intel. An agent can select it without reading the 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?

The description gives concrete selection context — filter by chain, symbol, stablecoin-only, min TVL, sort by APY/TVL — and notes the default chain and TVL floor, which tells the agent what it gets without arguments. It stops short of naming a sibling alternative or an explicit when-not-to-use condition, so it falls short of a 5.

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