valuation-api

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, but the description adds non-redundant behavioral detail: pure deterministic calculation, no network or storage access, identical inputs always produce identical outputs, and explicit error handling for undefined mathematical combinations. This goes well beyond the annotation bits, and it does not contradict them.

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?

The description is well-structured with scannable sections (formula, when to use, when not, behavior, returns, parameters) and front-loads the core formula. It earns most of its sentences, but the parameters section duplicates the schema descriptions almost word-for-word, which adds length without additional value. Still, overall information density is high and no fluff is present.

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 explicitly documents the return shape (JSON with cost_of_equity, cost_of_equity_pct, inputs) and gives examples. Combined with the formula, usage guidance, and error behavior, an agent has everything needed to call this tool correctly. The description is fully self-contained.

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 parameter text in the description is nearly verbatim identical to the schema property descriptions (e.g., beta's 'levered, if the company has debt' and unit examples). It reinforces the decimal-vs-percentage warning, but adds no new information beyond what the schema already provides. The baseline 3 applies.

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 opens with a specific verb and resource ('Calculate the cost of equity using CAPM') and includes the exact formula, leaving no ambiguity about what the tool computes. It also differentiates from siblings by explicitly naming its role as an input to WACC and DCF, making it clear this is not one of the valuation multiples or cash-flow 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?

The 'WHEN TO USE' section gives concrete applications (WACC input, DCF discount rate, standalone hurdle), and the 'WHEN NOT TO USE' section names the exact alternative tools (calculate_unlever_beta / calculate_relever_beta) and the condition (private companies without a traded beta) that should route the agent elsewhere. This is explicit and actionable.

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

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

The description explicitly discloses that the tool is a 'pure deterministic calculation — no side effects, no network or storage access; idempotent and non-destructive,' which aligns with and expands on the annotations. It also reveals important behavioral constraints: terminal value is only defined when wacc is strictly greater than terminal_growth_rate, debt and cash are not netted, and results are rounded to 2dp. This goes well beyond the annotations and helps an agent set correct expectations.

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?

The description is organized with clear labeled sections: purpose, when to use, when not to use, behaviour, returns, and parameters. It is detailed but every sentence adds value, and the most important scoping information is front-loaded in the first sentence.

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, so the description correctly explains the return shape: a JSON object with inputs and results including present_value, terminal_value, and enterprise_value. It also covers the critical model constraints, rounding behavior, and the distinction between enterprise and equity value, making the tool safe to invoke without further information.

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 every parameter already has a thorough schema description including decimal format, constraints, and the discounting convention. The description's PARAMETERS section largely restates this information rather than adding new meaning, so the high-coverage baseline of 3 applies.

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 opens with a specific verb and resource: 'Compute a Discounted Cash Flow (DCF) valuation: enterprise value from projected free cash flows plus a Gordon-growth terminal value.' This precisely identifies what the tool does and clearly separates it from valuation siblings. It also explicitly names alternatives in the WHEN NOT TO USE section, so an agent can disambiguate it from calculate_irr and calculate_wacc.

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?

The description contains a dedicated WHEN TO USE section that states the intended scenario: valuing a company or asset from projected free cash flows, WACC, and perpetual terminal growth rate. It also provides explicit WHEN NOT TO USE guidance, naming calculate_irr for single-exit lump-sum investments and calculate_wacc when the discount rate itself is needed.

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

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

Annotations already cover read-only, idempotent, and non-destructive behavior, and the description adds deterministic behavior and explicit error handling for invalid or non-finite inputs. The mention of division by zero is slightly irrelevant since the formula has no division, but it does not contradict the annotations.

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?

The structured sections make the description scannable, and the core formula is front-loaded. Some redundancy exists in the BEHAVIOUR section, where annotation facts are repeated and the division-by-zero note is irrelevant, but overall the text is efficient.

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 pure calculation tool with three fully documented parameters and strong annotations, the description includes the formula, usage boundaries, return shape, and error behavior. Since there is no output schema, the explicit RETURNS line adds necessary context, and nothing important 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?

The schema already describes all three parameters fully with constraints and examples (100% coverage), so the description does not need to add much. The formula maps equity_value, total_debt, and cash_and_equivalents to the calculation, but adds no new semantic detail beyond 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?

The description opens with a specific verb and resource ('Calculate enterprise value') and provides the exact formula, distinguishing EV from equity value. It also clearly separates this from sibling valuation-multiple tools by focusing on the base EV calculation.

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?

The WHEN TO USE section names valuation multiples and M&A transaction values, while WHEN NOT TO USE explicitly warns against confusing EV with equity value and directs per-share use to equity value. This gives an agent both inclusion and exclusion criteria.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, but the description meaningfully goes beyond them by stating the calculation is pure and deterministic, has no network or storage access, and returns an explicit error for division by zero, non-finite inputs, or mathematically undefined combinations. This gives the agent a clear failure-mode model.

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?

The description is well organized with capitalized section headers and front-loads the formula and purpose. It is slightly longer than strictly necessary because the parameter section largely mirrors the input schema, but each section still serves a clear operational purpose.

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 two-parameter pure calculation with no output schema, the description completely specifies inputs, formula, output shape ({ ev_to_ebitda, inputs }), and error behavior. Nothing an agent needs to correctly select and invoke the tool 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?

The input schema already documents both parameters with descriptions, examples, and exclusiveMinimum constraints, so schema coverage is 100%. The description repeats this content and adds formula-level rationale for why EBITDA must be positive, but it does not materially extend parameter semantics beyond what the schema provides.

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 names the exact verb and resource ('calculate the EV/EBITDA multiple') and gives the formula: EV/EBITDA = Enterprise Value / EBITDA. It also distinguishes this tool from calculate_ev_to_revenue by explicitly noting that EV/Revenue is the correct alternative when EBITDA is negative or near zero.

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?

Explicit 'WHEN TO USE' and 'WHEN NOT TO USE' sections state the intended context (relative valuation against peer multiples or transaction comps) and exclude cases with negative/near-zero EBITDA or early-stage companies. The description directly names the alternative tool, calculate_ev_to_revenue, leaving no ambiguity about routing.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, and the description reinforces these by stating 'pure deterministic calculation,' 'no side effects,' 'idempotent and non-destructive,' and 'identical inputs always produce identical outputs.' It goes beyond the annotations by disclosing error behavior for division by zero and non-finite inputs, which is valuable operational context, though some redundancy with annotations exists.

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?

The description is well-organized with clear labeled sections: formula, when to use, when not to use, behavior, returns, and parameters, and it front-loads the core formula. It is somewhat repetitive around idempotence and non-destructiveness already covered by annotations, but every section still adds practical value and no unnecessary fluff.

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 two-parameter deterministic calculator with no output schema, the description is complete: it defines the formula, return shape, error behavior, parameter constraints, and usage boundaries. The explicit JSON return example ('{ ev_to_revenue: number, inputs }') compensates for the absent output schema, so an agent has everything needed to call and interpret the result.

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% and the parameter descriptions in the schema already explain enterprise_value and revenue, their units, examples, and the >0 constraint. The tool description repeats these rather than adding materially new meaning, so it meets the baseline expected when the schema carries the parameter documentation weight.

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 ('Calculate'), a precise resource (EV/Revenue multiple), and gives the formula plus a clear characterization of when the metric is relevant (thin/negative/zero EBITDA, high-growth or pre-profit companies). It differentiates itself from sibling EV/EBITDA by explicitly scoping to pre-profit companies and framing EV/EBITDA as the mature-company counterpart.

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?

The description includes explicit 'WHEN TO USE' and 'WHEN NOT TO USE' guidance, naming the alternative (EV/EBITDA) and warning against relying on revenue multiples alone. It even instructs pairing with margin and growth context, which is actionable and unambiguous.

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

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

Annotations already mark read-only and idempotent, and the description strengthens this by detailing determinism, no side effects/network/storage/randomness, and the Newton-Raphson-with-bisection solution method. No contradiction with annotations.

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?

The description is organized into labeled sections (WHEN, WHEN NOT, BEHAVIOUR, RETURNS, PARAMETERS) and every sentence contributes a distinct fact. It is detailed but efficiently front-loaded with the core scope, then alternatives, then behavior.

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 tool with no output schema, the RETURNS section lists the full JSON shape including sensitivity keys, and the parameter constraints are fully covered. Usage conditions, behavior, and return contract are all present, making safe invocation fully specified.

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% with field descriptions already explaining constraints and currency semantics, so the baseline is 3. The description's PARAMETERS section mostly mirrors the schema plus the display-only currency note; it adds little beyond the structured 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?

Opens with a specific verb and resource: 'Calculate the Internal Rate of Return (IRR), MOIC and an IRR sensitivity table' for a precisely scoped single-exit scenario. The scope sentence and WHEN NOT TO USE references to calculate_npv/calculate_moic/irr_sensitivity distinguish it from siblings.

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?

Explicit WHEN TO USE block gives concrete preconditions (upfront amount, single exit value, whole-year hold) and expected outputs. WHEN NOT TO USE names alternatives and their trigger conditions, so an agent can route correctly.

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

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

Beyond the annotations, the 'BEHAVIOUR' section states it is a pure deterministic calculation with no side effects, network, or storage access, and idempotent/non-destructive. It also discloses the edge case: returns 0 when there is no invested capital. This adds value beyond the readOnlyHint and idempotentHint annotations.

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?

The description is well-structured with labeled sections, front-loaded with the core purpose. Although longer than many tool descriptions, every sentence adds useful operational guidance — usage conditions, behavior, return format, and parameter semantics — with no filler or redundant restatement.

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 single-parameter calculation tool with fully annotated safety hints, the description covers everything needed to invoke it correctly: formula, input semantics, edge case, return shape, and differentiation from siblings. The absence of an output schema is compensated by the explicit RETURNS section describing { moic, cash_flows }.

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% for the single cash_flows parameter, so the baseline is 3. The description adds the computational formula (sum of positive cash flows divided by sum of absolute negative cash flows) and clarifies the ordered nature starting at time 0, which is more explicit than the schema. It mostly reinforces the schema but adds the formula and edge-case behavior.

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 opens with a specific verb and resource: 'Calculate the Multiple on Invested Capital (MOIC): total distributions divided by total invested, with no discounting and no time value.' It clearly defines what the tool computes and the key formula, distinguishing it from financial metrics like IRR and NPV by stating it ignores time value.

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?

The description explicitly provides 'WHEN TO USE' and 'WHEN NOT TO USE' sections, naming the alternative tools (calculate_irr, calculate_npv) and the exact conditions that should route an agent to them. This leaves no ambiguity about when the tool is appropriate.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds valuable context: 'pure deterministic calculation — no side effects, no network or storage access; identical inputs always produce identical outputs.' This goes beyond the structured annotations and helps the agent understand the tool's operational profile.

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?

The description is well-structured with labeled sections (WHEN TO USE, WHEN NOT TO USE, BEHAVIOUR, RETURNS, PARAMETERS). Every sentence serves a purpose, and the key definition is front-loaded. Length is justified by the tool's complexity and the need to disambiguate from multiple siblings.

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?

The description covers the computation rule, parameter semantics, return shape, decimal format, sign conventions, and sibling alternatives. Since there is no output schema, the explicit 'RETURNS' section is especially valuable. Nothing critical is missing for an agent to call this tool 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 100%, and the schema already explains both parameters in detail, including the decimal-rate warning and the time-zero treatment. The description repeats these semantics and adds an example, but does not add substantial meaning beyond 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?

The description states a specific verb and resource: 'Calculate the Net Present Value (NPV) of an ordered cash-flow series discounted at a given rate.' It also clarifies the time-zero treatment of the first cash flow. It clearly distinguishes itself from siblings like calculate_irr and calculate_moic by naming those alternatives for different use cases.

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?

The description provides explicit 'WHEN TO USE' and 'WHEN NOT TO USE' sections with named alternatives (calculate_irr, calculate_moic), making it unambiguous when an agent should select this tool over its siblings.

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

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

Beyond the annotations (readOnlyHint, idempotentHint, destructiveHint), the description discloses additional useful behavior: the calculation is deterministic with no side effects, and invalid inputs such as division by zero or non-finite values return explicit errors rather than numbers. This goes well beyond what annotations already state and prepares the agent for error handling.

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?

The description is well-structured with clear headings (formula, WHEN TO USE, WHEN NOT TO USE, BEHAVIOUR, RETURNS, PARAMETERS) and is front-loaded with the key formula and purpose. It is somewhat lengthy, and the PARAMETERS section repeats information already present in the schema, which is slightly redundant. Overall it earns its length with actionable guidance, just not perfect conciseness.

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?

The description fully covers the tool's purpose, formula, usage conditions, error behavior, and return format. Since there is no output schema, the RETURNS section specifying the JSON object structure is especially valuable. All necessary information for an agent to correctly select and invoke this tool is present.

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%, so the baseline is 3. The description's PARAMETERS section largely duplicates the schema text rather than adding new meaning. It does reinforce the constraints and gives examples, but the formula and the relationship between parameters are already evident from the description's opening. No significant semantic value is added beyond 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?

The description opens with a precise verb and object: 'Relever an unlevered (asset) beta to a target capital structure using the Hamada formula.' It also states the exact formula and the role of the tool in restoring financial risk for a specific debt/equity mix. This clearly distinguishes it from its sibling calculator, calculate_unlever_beta, by focusing on the relevering direction.

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?

The description contains explicit WHEN TO USE and WHEN NOT TO USE sections. It instructs the agent to apply this tool after unlevering comparable betas and warns against relevering onto unrealistic capital structures. This gives clear operational guidance and a boundary condition, leaving no ambiguity about when to invoke this tool versus an alternative.

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

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

The description adds substantial detail beyond the annotations: 'pure deterministic calculation — no side effects, no network or storage access; idempotent and non-destructive; identical inputs always produce identical outputs'. It also discloses error handling for edge cases like division by zero and non-finite inputs, which is important for a calculation tool.

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?

The description is well-structured with clear labeled sections: formula, WHEN TO USE, WHEN NOT TO USE, BEHAVIOUR, RETURNS, PARAMETERS. While longer than the minimal examples, every section earns its place and the core purpose is front-loaded in the first sentence.

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 deterministic 3-parameter calculation, the description covers the formula, use cases, exclusions, parameter constraints, return format, and edge-case behavior. It also differentiates from the relever_beta sibling. Nothing an agent needs to invoke this tool correctly 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% and the parameter section largely repeats the schema, so the baseline is 3. However, the description adds practical context such as 'market values preferred' for debt_to_equity and ties each parameter to the Hamada formula with concrete examples, which enhances semantic understanding.

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 opens with a specific verb and resource: 'Unlever a (levered) equity beta to its asset beta using the Hamada formula'. It clearly distinguishes the tool from its siblings, especially calculate_relever_beta, by explaining the direction of the transformation and the goal of comparability across capital structures.

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?

Explicit WHEN TO USE and WHEN NOT TO USE sections provide direct guidance. The description explains the typical workflow ('unlever the comps’ betas, average them, then relever at your target structure') and gives an exclusion condition with an alternative ('for companies with significant non-debt liabilities consider a more advanced formula').

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

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

Beyond the annotations, the description adds valuable behavioral context: it is a pure deterministic calculation with no side effects, no network/storage access, and returns 0 if total value is 0. It also discloses the exact formula and output rounding behavior, which the annotations do not cover.

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?

The description is well-structured with labeled sections for usage, behavior, formula, returns, and parameters. Every section adds necessary operational information, and the purpose is front-loaded in the first sentence.

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 present, the description fully specifies the return shape including field names, rounding precision, and example values. It also covers the edge case of zero total value, making the tool safe to invoke without external documentation.

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?

Although the schema already covers all five parameters, the description adds crucial usage meaning such as 'all rates are decimals, never percentage points' and concrete examples like '0.12 = 12%'. This reduces the risk of misinterpreting the numeric format for cost_of_equity and cost_of_debt.

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 ('Calculate') and resource ('Weighted Average Cost of Capital') with a clear definition and formula. It also explicitly distinguishes this tool from calculate_dcf by saying it is not for the full valuation itself, making it easy for an agent to select correctly among siblings.

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?

The description provides explicit 'WHEN TO USE' and 'WHEN NOT TO USE' guidance, including the condition for using calculate_dcf instead. This leaves no ambiguity about when the tool is appropriate and names the key alternative.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds value by explicitly stating 'pure deterministic calculation — no side effects, no network or storage access' and clarifies grid geometry (byMultiple uses second hold period, byHoldPeriod uses 2.5x), which is key behavioral information not in the schema. Minor redundancy with annotations but no contradiction.

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?

The description is organized into clear labeled sections, front-loads purpose, and every section earns its place. While it is longer than average, the complexity of the tool (grid geometry, return format, usage boundaries) justifies the length. The WHEN/WHEN NOT structure and RETURNS section make it highly scannable for an agent.

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?

Given the tool has no output schema, the description fully compensates by documenting the return shape, rounding behavior, grid geometry, defaults, and side-effect profile. An agent has everything needed to call this tool correctly: parameters, defaults, output structure, and usage conditions. No critical gap remains.

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%, so the schema already documents each parameter, including defaults and constraints. The description's PARAMETERS section mostly repeats what the schema provides (types, defaults, positivity). It adds no meaningful new parameter semantics beyond the schema, 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?

The description opens with a specific verb and object: 'Compute an IRR sensitivity grid across a range of exit multiples and hold periods.' It immediately establishes the tool's scope (sensitivity analysis, single lump-sum investment) and clearly distinguishes it from calculate_irr, which computes a single IRR. This makes sibling differentiation trivial.

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?

The description explicitly states WHEN TO USE ('stress-test how the annualised return varies... before committing to an investment'), WHEN NOT TO USE ('when you need one precise IRR'), and names the exact alternatives (calculate_irr, calculate_dcf). This is textbook usage guidance.

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