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

Annotations only say readOnly/non-destructive/closed-world; the description adds substantial beyond that: the ln(1+rate) search grid from -99% to +9,900% at 0.2% steps, the ~1e13 upper limit, and that touching-zero roots can be missed. That disclosure of algorithmic limits and possible misses is exactly what a numerical tool needs. It stops short of describing the return payload's shape in depth, but 'Returns:' enumerates the fields, so a 4 rather than a 5.

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 and logically ordered (definition, sign-change behavior, search limits, edge cases, exclusions, return fields), but it repeats itself: 'Several sign changes can give several rates or none, then irr is null (see reason)' restates the earlier multi-root paragraph almost verbatim, and 'The rate is per period' appears twice. For a two-parameter tool the text is heavier than it needs to be.

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, yet the description names every returned field (irr, irrs, unique, signChanges, reason, annualEffectiveRate, periods) and explains when each reason value fires (unverified, multiple_roots, none_found). Combined with the input bounds and exclusions, nothing an agent needs to call this correctly or interpret the result is missing.

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 coverage is 100%, so the baseline is 3; the description still adds interpretation the schema does not — that periods must be equal, flows finite, first flow at time 0, and that periodsPerYear is a whole number 1–365 used to derive the annual effective rate. The 'rate is per period' framing is the key semantic the schema cannot convey, though it is restated more than once.

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 precise verb-plus-resource definition: 'Internal rate of return: the rate per period at which the NPV of a list of cash flows is zero (first flow at time 0).' It also names adjacent-but-different tools (XIRR for irregular dates, MIRR for different reinvestment) and the sibling family includes run_npv/run_present_value, so an agent can route correctly without opening a 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 explicit trigger phrases ('what is the IRR of these cash flows?', 'what return does this project earn?') plus an explicit 'Not covered' list routing XIRR, MIRR, and out-of-range rates elsewhere. It even warns not to quote a single rate when sign changes exceed one, which is a usage rule, not just behavior.

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