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

Goes well beyond the annotations (readOnly/openWorld/destructive already covered) by disclosing the paid-call model: $0.0055 USDC per call via x402, accepted chains, and that compliant clients pay automatically. It also discloses outlier exclusion behavior and offers a free sample invocation. This is exactly the auth/payment and data-filtering context annotations cannot carry.

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?

Front-loaded with purpose and dense but largely non-wasteful, with each clause adding a filter, default, or behavioral rule. It is somewhat run-on across three long sentences, but the information density is justified by the payment model and eight parameters.

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?

With no output schema, the description fully carries the return-value burden by enumerating the fields returned (APY split, 30-day mean, 7-day change, TVL, stablecoin flag, IL risk). Combined with filter/sort semantics, outlier handling, and payment info, an agent has everything needed to invoke and interpret the call.

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 schema coverage at only 38% across 8 params, the description compensates by illustrating chain, project, and symbol values and restating the min_tvl_usd and sort defaults. It adds interpretive meaning tbut much of the default/enum information is already present in the schema, so the marginal value is real but partly redundant; limit's ceiling is left to the schema.

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 and resource ('Find DeFi yield pools') with scope (400+ protocols, 100+ chains) and the data source (DefiLlama). An agent can immediately distinguish this from the sibling defi_tvl, which covers TVL rather than yield/APY data. The enumerated return fields (base/reward APY, 30-day mean, 7-day change, TVL, stablecoin flag, IL risk) further pin down what the tool produces.

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 clear practical context for use: which filters exist, their defaults (min_tvl_usd 1,000,000, sort 'apy'), and the outlier exclusion rule. However, it never names an alternative tool or states when NOT to use this one (e.g. the sibling defi_tvl for pure TVL queries), so routing guidance is implied rather than explicit.

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