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

Goes well past the annotations by disclosing the solution method (1-point grid scan plus bisection on sign changes), a known correctness limit (two roots inside one grid step can be missed), the accepted rate window (-99.99% to 1000% per period), and error conditions for sign changes absent. That is the kind of caveat an agent needs to interpret results and warnings correctly.

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?

Purpose and output format are front-loaded and no sentence is filler, but the middle section is one long semicolon-chained clause that buries the error conditions and the missing-root caveat in dense prose. Slightly tighter sentence splitting would improve scanability.

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 still covers result format (decimal rates, annualized vs periodic), failure modes, and the multiplicity caveat, which is everything needed to call it and to report its output responsibly. Nothing material is missing for a two-parameter read-only calculation.

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 100% and the schema already documents sign convention, the 1200-item cap, and the annualization purpose of periods_per_year. The description adds only the decimal output convention and the root-search range, so the baseline 3 is appropriate.

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 computation ('Periodic and annualized IRR of periodic cash flows') with the output convention spelled out ('as decimals (0.085 = 8.5%)'), which unambiguously separates it from the NPV/rent-schedule siblings in the calc_* family. An agent can identify the operation and result type without opening 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?

Explicitly directs the agent to prefer this tool over computing IRR itself and specifies follow-on obligations (cite calc.irr@2, cite returned steps, surface warnings). It gives clear context but never contrasts with calc_npv or other siblings where an agent might mis-route.

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