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

Annotations already declare readOnly/idempotent/closed-world, and the description adds real context beyond them: pure arithmetic with no I/O or external calls, results rounded to 2 decimals, no auth or rate limits, and explicit failure behavior (unknown method or missing required param returns an error rather than a value). It also states the decimal/fraction convention and that lists must be in [0,1] and sum to 1.

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 routing before the dense per-method parameter rules, and every clause carries information. It is somewhat long and packs several distinct ideas into single sentences, which slightly reduces scannability, but nothing is redundant.

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?

For a 14-parameter, method-dispatching tool this is complete: it covers method selection, per-method inputs, unit conventions, error behavior, and the downstream hand-off, and an output schema exists so return-value detail (value, method, inputs, assumptions, formula_number, steps) need not be elaborated further.

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, but the description goes further by mapping methods to their required parameter sets (capm → risk_free_rate+beta+market_return; startup_capm adds the premiums; portfolio_beta needs equal-length weights+betas; wacc needs equity/debt/cost/tax), which the schema does not express. It clarifies cross-parameter constraints (equal length, sum to 1) that a per-field schema cannot 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 verb+resource ("Estimate the cost of capital") and enumerates the four supported formulas (standard CAPM, startup-adjusted CAPM, portfolio beta, WACC), so the agent knows exactly what computation is performed. It also names the sibling tools it feeds (valuation_time_value, valuation_international), which separates it from the other valuation_* tools.

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 says when to use it ("derive the discount rate that feeds valuation_time_value and DCF models") and when to supplement it ("for cross-border rates add valuation_international"). It also gives per-method usage rules — which parameter set each method requires and that only method is mandatory — leaving little to inference.

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