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

No annotations exist, so the description carries the full behavioral burden. It does disclose a real behavioral trait beyond structured fields: the monetization model with 5 free trial calls per signed wallet, implying paid usage after that. It says nothing, though, about output format, rounding, or how conflicting input pairs are resolved.

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?

Two short sentences with the purpose front-loaded and no rambling. The emoji-laden trial-call line is marketing noise but brief and does convey a real constraint, so the cost is small.

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 8 undocumented parameters, no required fields, no annotations, and no output schema, the description would need to explain which inputs combine to form the ROI and what happens when years is supplied. It covers only 2 of 8 parameters and omits the ambiguity that makes this tool hard to call 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 0% across 8 string parameters and no parameter is required. The description names only 2 of them (invested, returned) and never explains the alternative input pairs (cost/gain, initial/final) or the role of years/current, leaving most of the schema undocumented in both places.

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 states a specific verb and resource: 'Calculate Return on Investment from invested and returned amounts.' An agent can identify the function without opening the schema. However, it does not differentiate itself from the near-identical sibling x402-roi, nor from x402-annualized-return or x402-irr-calc, which matters given the enormous sibling list.

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?

'Provide invested and returned values' is a parameter instruction, not usage guidance. There is no statement of when this tool should be chosen over x402-roi, x402-annualized-return, or x402-holding-period-return, and no exclusions or prerequisites. The only added context is a promo line about free trial calls.

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