Superseded by valuation-api on valuation.finance-tools.io (fresh connector with focused 12-tool set and current TDQS eval)
Deterministic valuation tools for AI agents — IRR, NPV, MOIC, DCF, WACC and sensitivity analysis for companies and assets via Model Context Protocol.
Scored across 14 tools
Each tool targets a distinct valuation formula or metric, and even the closely related cash-flow return tools (IRR, NPV, MOIC) are clearly differentiated by their use cases and cross-references. Inverse pairs like enterprise/equity value and unlever/relever beta are unambiguous because their inputs and outputs mirror each other explicitly.
All 14 tools follow the same calculate_<metric> snake_case pattern, making the entire surface predictable and easy to navigate. Even the longer names like calculate_equity_value_from_enterprise_value remain consistent and descriptive.
14 tools is well within the ideal range for a domain-specific calculation server, and each tool earns its place by covering a distinct valuation concept. The set is neither bloated nor thin for the stated valuation purpose.
The tool surface covers a broad valuation workflow: discount rates (CAPM, WACC), beta adjustment, DCF, EV/equity bridges, key multiples, and investment return metrics. Minor gaps exist, such as no standalone P/E ratio tool (though earnings yield returns it) and no additional multiples like P/B or EV/EBIT, but agents can work around these.
Calculate the cost of equity using the Capital Asset Pricing Model (CAPM): the risk-free rate plus beta times the market risk premium. Formula: Re = Rf + beta x (Rm - Rf). WHEN TO USE: Use to estimate the required return on equity — an input to WACC (calculate_wacc) and DCF discount rates, or as a standalone return hurdle. WHEN NOT TO USE: Do NOT use for companies where beta is a poor risk measure (private companies without a traded beta — consider building up from comparable betas via calculate_unlever_beta / calculate_relever_beta first). BEHAVIOUR: pure deterministic calculation — no side effects, no network or storage access; idempotent and non-destructive; identical inputs always produce identical outputs. Division by zero, non-finite inputs, or mathematically undefined combinations return an explicit error instead of a number. RETURNS: JSON object { cost_of_equity: decimal (e.g. 0.115 = 11.5%), cost_of_equity_pct: number (e.g. 11.5), inputs }. PARAMETERS: risk_free_rate (required): Risk-free rate as a decimal, e.g. 0.04 = 4% (typically the 10-year government bond yield; never pass percentage points). beta (required): Equity beta (levered, if the company has debt), e.g. 1.2. Use unlevered/relevered betas when comparing capital structures. market_return (required): Expected market return (Rm) as a decimal, e.g. 0.10 = 10% (never pass percentage points). The market risk premium is computed internally as Rm - Rf.
| Name | Required | Description | Default |
|---|---|---|---|
| beta | Yes | Equity beta (levered, if the company has debt), e.g. 1.2. Use unlevered/relevered betas when comparing capital structures. | |
| market_return | Yes | Expected market return (Rm) as a decimal, e.g. 0.10 = 10% (never pass percentage points). The market risk premium is computed internally as Rm - Rf. | |
| risk_free_rate | Yes | Risk-free rate as a decimal, e.g. 0.04 = 4% (typically the 10-year government bond yield; never pass percentage points). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes well beyond the readOnly/idempotent annotations by specifying deterministic calculation, no network or storage access, and explicit error behavior for division by zero or non-finite inputs. It also clarifies that the market risk premium is computed internally. This fully discloses the tool's runtime behavior with no contradictions.
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?
Though lengthy, the description is tightly structured with clear labels (formula, WHEN TO USE, WHEN NOT TO USE, BEHAVIOUR, RETURNS, PARAMETERS). Every section earns its place by addressing a distinct decision or execution need: purpose, routing, safety, output format, and unit pitfalls. No filler or redundancy.
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 3-parameter numeric tool with no output schema, the description covers everything an agent needs: formula, application context, unit conventions, error handling, return shape with examples, and sibling routing. Nothing essential 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 description coverage is 100%, so the baseline is 3. The description's PARAMETERS section essentially repeats the schema's already-detailed field descriptions (decimal format, 'never pass percentage points', beta examples), adding no new parameter-level meaning. The formula in the purpose section does add relational context, but not beyond what the schema fields already 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?
The description opens with a specific verb and resource ('Calculate the cost of equity using the Capital Asset Pricing Model'), provides the exact formula, and distinguishes itself from siblings by naming WACC as a downstream consumer and by flagging when CAPM is inappropriate. This gives an agent a precise, non-confusable understanding of the tool's role.
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 both the intended contexts (WACC input, DCF discount rate, standalone hurdle) and the exclusion case (private companies without a traded beta), with concrete alternative tools named (calculate_unlever_beta / calculate_relever_beta). This is exactly the decision guidance an agent needs.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Compute a Discounted Cash Flow (DCF) valuation: enterprise value from projected free cash flows plus a Gordon-growth terminal value. WHEN TO USE: to value a company or asset from its projected free cash flows, WACC and perpetual terminal growth rate (standard corporate/asset valuation). WHEN NOT TO USE: for a single-exit lump-sum investment (use calculate_irr), or when you need the discount rate itself (use calculate_wacc). BEHAVIOUR: pure deterministic calculation — no side effects, no network or storage access; idempotent and non-destructive. Terminal value uses the Gordon Growth Model; it is only defined when wacc is strictly greater than terminal_growth_rate. RETURNS: JSON object { inputs, results: { present_value, terminal_value, enterprise_value } }, each rounded to 2dp. present_value is the discounted explicit-period FCFs; enterprise_value = present_value + discounted terminal value (debt and cash are NOT netted — this is enterprise value, not equity value). PARAMETERS: free_cash_flows (array of per-period projected free cash flows, typically positive; the first element is discounted by one period), wacc (decimal, e.g. 0.10 = 10% — never pass percentage points; must be > terminal_growth_rate), terminal_growth_rate (decimal perpetual growth rate, e.g. 0.03 = 3% — never pass percentage points; must be < wacc).
| Name | Required | Description | Default |
|---|---|---|---|
| wacc | Yes | Weighted average cost of capital as a decimal, e.g. 0.10 = 10% (never pass percentage points). Must be strictly greater than terminal_growth_rate. | |
| free_cash_flows | Yes | Projected free cash flows per period, e.g. [5000000, 6000000, 7000000, 8000000, 9000000]. Typically positive; first element discounted one period. | |
| terminal_growth_rate | Yes | Perpetual terminal growth rate as a decimal, e.g. 0.03 = 3% (never pass percentage points). Must be strictly less than wacc, otherwise terminal value is undefined. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description states 'pure deterministic calculation — no side effects, no network or storage access; idempotent and non-destructive,' reinforcing the readOnlyHint and idempotentHint annotations. It also discloses the Gordon Growth Model constraint (wacc > terminal_growth_rate) and clarifies that debt and cash are not netted, adding meaningful behavioral context beyond 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 description is longer and structured with uppercase section headers, but every sentence carries substantive guidance: purpose, when to use/not use, behavior, return shape, and param semantics. It is front-loaded with the core purpose and not padded.
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?
This is a complex financial tool with three required parameters and no output schema, yet the description fully covers return structure, rounding, the mathematical constraint, and the distinction between enterprise and equity value. Combined with annotations, the agent has everything needed to invoke and interpret the result 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%, so the baseline is 3. The description's PARAMETERS section largely restates the schema: decimals not percentages, first FCF discounted one period, and the wacc/growth constraint. It adds no new meaning beyond what the schema already provides, so it stays at the baseline.
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.' It clearly distinguishes itself from siblings by naming calculate_irr and calculate_wacc as alternatives for different cases. The purpose is unambiguous and action-oriented.
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 with named alternative tools: calculate_irr for single-exit lump-sum investments and calculate_wacc for discount-rate needs. This gives the agent direct routing instructions, leaving nothing to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Calculate the earnings yield: earnings per share divided by share price — the inverse of the P/E ratio, expressing the earnings return on the share price as a percentage. Formula: Earnings Yield = EPS / Share Price. WHEN TO USE: Use to compare equity earnings returns directly against bond yields or the risk-free rate, or as a quick value screen — a high earnings yield can signal a cheap stock. WHEN NOT TO USE: Do NOT use when EPS is negative or zero (the yield is meaningless); use it as a complement to, not a replacement for, the P/E ratio (calculate_pe_ratio). BEHAVIOUR: pure deterministic calculation — no side effects, no network or storage access; idempotent and non-destructive; identical inputs always produce identical outputs. Division by zero or non-finite inputs returns an explicit error instead of a number. RETURNS: JSON object { earnings_yield: decimal (e.g. 0.05 = 5%), earnings_yield_pct: number (e.g. 5.0), pe_ratio: number (e.g. 20 = 20x), inputs }. The P/E ratio is the reciprocal of the earnings yield, returned so a client gets both figures from one call. PARAMETERS: earnings_per_share (required): Earnings per share (trailing or forward), e.g. 2.50. Must be > 0 for a meaningful yield. share_price (required): Current share price in currency units, e.g. 50.00. Must be > 0.
| Name | Required | Description | Default |
|---|---|---|---|
| share_price | Yes | Current share price in currency units, e.g. 50.00. Must be > 0. | |
| earnings_per_share | Yes | Earnings per share (trailing or forward), e.g. 2.50. Must be > 0 for a meaningful yield. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly/idempotent/non-destructive/openWorld=false, but the description goes further: it states the calculation is pure and deterministic with no side effects or network/storage access, and that division by zero or non-finite input returns an explicit error rather than a number. That error contract is genuinely useful behavior not covered by 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?
Well front-loaded and cleanly sectioned (definition, WHEN TO USE, WHEN NOT TO USE, BEHAVIOUR, RETURNS, PARAMETERS), so an agent can scan it quickly. It is longer than needed, though: the formula is expressed three times ('EPS / Share Price', 'earnings per share divided by share price', and the explicit formula line), which is mild redundancy.
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?
Although there is no output schema, the description fully documents the return object (earnings_yield, earnings_yield_pct, pe_ratio, inputs) including unit conventions and an example. For a two-parameter pure calculator, nothing needed to call or interpret it 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 description coverage is 100%, so both parameters (share_price, earnings_per_share) are already fully documented including the > 0 constraint, so baseline 3 applies. The description restates the same constraints and only marginally adds the 'trailing or forward' interpretation of EPS, which does not meaningfully exceed 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?
States a specific verb+resource ('Calculate the earnings yield') and defines it precisely as EPS / Share Price, explicitly framing it as the inverse of the P/E ratio. This is enough to distinguish it from the other calculate_* financial siblings without opening any 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?
Has explicit WHEN TO USE (compare against bond yields / risk-free rate, value screen) and WHEN NOT TO USE (negative or zero EPS, not a replacement for P/E). It names a complementary alternative, calculate_pe_ratio, and states the relationship rather than just pointing at it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Calculate enterprise value (EV): the total value of a business to all capital providers — equity value plus net debt (total debt minus cash and equivalents). Formula: EV = Equity Value + Total Debt - Cash & Equivalents. WHEN TO USE: Use as the capital-structure-neutral measure of a company’s total value — the standard starting point for valuation multiples (EV/EBITDA, EV/Revenue) and M&A transaction values. WHEN NOT TO USE: Do NOT confuse EV with equity value (market cap) — EV is what you would pay to own the whole enterprise including its debt; use equity value for per-share figures. BEHAVIOUR: pure deterministic calculation — no side effects, no network or storage access; idempotent and non-destructive; identical inputs always produce identical outputs. Division by zero, non-finite inputs, or mathematically undefined combinations return an explicit error instead of a number. RETURNS: JSON object { enterprise_value: number (currency), inputs }. PARAMETERS: equity_value (required): Equity value / market capitalisation, e.g. 5000000. Must be >= 0. total_debt (required): Total interest-bearing debt (short + long term), e.g. 2000000. Must be >= 0. cash_and_equivalents (required): Cash and cash equivalents to subtract, e.g. 500000. Must be >= 0.
| Name | Required | Description | Default |
|---|---|---|---|
| total_debt | Yes | Total interest-bearing debt (short + long term), e.g. 2000000. Must be >= 0. | |
| equity_value | Yes | Equity value / market capitalisation, e.g. 5000000. Must be >= 0. | |
| cash_and_equivalents | Yes | Cash and cash equivalents to subtract, e.g. 500000. Must be >= 0. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, but the description adds meaningful behavioral context: pure deterministic calculation, no side effects, no network/storage access, identical inputs yield identical outputs, and explicit error behavior for division by zero or non-finite inputs. This goes well beyond the annotations without contradicting 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-organized with labeled sections (BEHAVIOUR, WHEN TO USE, PARAMETERS) and front-loads the formula. It is somewhat verbose, with the formula stated twice and parameter descriptions nearly duplicating the schema, but each section serves a clear purpose and the length is justified by the completeness.
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 3-parameter deterministic calculation with no output schema, the description covers everything needed: formula, input meanings with examples, constraints, return shape ({ enterprise_value, inputs }), error behavior, and use-case guidance. Nothing required to call the 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%, so baseline is 3. The description adds value by embedding each parameter in the formula context, providing concrete examples (e.g., 5000000, 2000000, 500000), and restating the minimum-zero constraint in natural language. It does not introduce semantics absent from the schema, but the examples and formula linkage justify a score above baseline.
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 and resource ('Calculate enterprise value'), provides the formula (EV = Equity Value + Total Debt - Cash & Equivalents), and explicitly distinguishes EV from equity value, which is a key confusion point. Among siblings it clearly differentiates itself as the base EV calculation rather than EV/EBITDA or EV/Revenue multiples.
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' section identifies EV as the capital-structure-neutral measure and starting point for valuation multiples and M&A values. Explicit 'WHEN NOT TO USE' section warns against confusing EV with equity value and directs agents to use equity value for per-share figures. This gives clear selection guidance relative to alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Calculate equity value from enterprise value: the value attributable to common shareholders, derived by subtracting net debt (total debt minus cash) from enterprise value — the reverse of the EV bridge. Formula: Equity Value = Enterprise Value - Total Debt + Cash & Equivalents. WHEN TO USE: Use when you hold enterprise value (e.g. from a DCF or an EV multiple) and need the implied equity value / market capitalisation for per-share or acquisition-equity figures. WHEN NOT TO USE: Do NOT use when you already have market capitalisation directly; and do NOT net non-interest-bearing liabilities — only interest-bearing total debt is subtracted. BEHAVIOUR: pure deterministic calculation — no side effects, no network or storage access; idempotent and non-destructive; identical inputs always produce identical outputs. Division by zero, non-finite inputs, or mathematically undefined combinations return an explicit error instead of a number. RETURNS: JSON object { equity_value_from_enterprise_value: number (currency), inputs }. PARAMETERS: enterprise_value (required): Enterprise value in currency units, e.g. 10000000. Must be >= 0. total_debt (required): Total interest-bearing debt (short + long term), e.g. 2000000. Must be >= 0. cash_and_equivalents (required): Cash and cash equivalents to add back, e.g. 500000. Must be >= 0.
| Name | Required | Description | Default |
|---|---|---|---|
| total_debt | Yes | Total interest-bearing debt (short + long term), e.g. 2000000. Must be >= 0. | |
| enterprise_value | Yes | Enterprise value in currency units, e.g. 10000000. Must be >= 0. | |
| cash_and_equivalents | Yes | Cash and cash equivalents to add back, e.g. 500000. Must be >= 0. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent, non-destructive and closed-world, but the description adds genuinely new behavior: deterministic pure calculation with no side effects, and explicit error semantics ('division by zero, non-finite inputs, or mathematically undefined combinations return an explicit error instead of a number'). Those failure modes are not derivable from the annotations and materially change how an agent should handle results.
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?
Clearly front-loaded: purpose and formula first, then WHEN TO USE / WHEN NOT TO USE, BEHAVIOUR, RETURNS, PARAMETERS. Slightly verbose because the PARAMETERS block duplicates schema descriptions, but the sectioning keeps it scannable rather than rambling.
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 three-input deterministic calculator with no output schema, the description supplies everything needed: the formula, the sign conventions, input constraints, error behavior, and the exact return shape ({ equity_value_from_enterprise_value: number, inputs }). Nothing an agent needs to invoke or interpret it 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 parameter meanings are already documented; the description largely repeats them. It does add interpretive value by tying each parameter to the formula (what cash is 'added back', why only interest-bearing debt qualifies), making borderline cases like non-interest-bearing liabilities unambiguous.
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 (Calculate) and a precisely named resource (equity value from enterprise value), then defines it as 'the value attributable to common shareholders, derived by subtracting net debt ... from enterprise value — the reverse of the EV bridge.' This explicitly distinguishes it from the sibling calculate_enterprise_value, so an agent can route correctly without opening either 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?
Contains dedicated WHEN TO USE and WHEN NOT TO USE sections: use when holding EV from a DCF or EV multiple and needing implied equity value; do not use when market capitalisation is already known. It also excludes a common misuse ('do not net non-interest-bearing liabilities'), which is exactly the kind of routing guidance that selects among the many calculate_* siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Calculate the EV/EBITDA multiple: enterprise value divided by EBITDA — the most widely used valuation multiple for comparing companies independent of capital structure, tax and depreciation policy. Formula: EV/EBITDA = Enterprise Value / EBITDA. WHEN TO USE: Use for relative valuation of cash-generative businesses against peer multiples or transaction comps; a lower multiple may indicate relative undervaluation (or justified risk). WHEN NOT TO USE: Do NOT use when EBITDA is negative or near zero, or for early-stage companies with no meaningful EBITDA — the multiple is meaningless there (use EV/Revenue). BEHAVIOUR: pure deterministic calculation — no side effects, no network or storage access; idempotent and non-destructive; identical inputs always produce identical outputs. Division by zero, non-finite inputs, or mathematically undefined combinations return an explicit error instead of a number. RETURNS: JSON object { ev_to_ebitda: number (e.g. 8.5 = 8.5x), inputs }. PARAMETERS: enterprise_value (required): Enterprise value in currency units, e.g. 10000000. Must be > 0. ebitda (required): Earnings before interest, tax, depreciation and amortisation, e.g. 1200000. Must be > 0 for a meaningful multiple.
| Name | Required | Description | Default |
|---|---|---|---|
| ebitda | Yes | Earnings before interest, tax, depreciation and amortisation, e.g. 1200000. Must be > 0 for a meaningful multiple. | |
| enterprise_value | Yes | Enterprise value in currency units, e.g. 10000000. Must be > 0. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses behavior well beyond the annotations: pure deterministic calculation, no side effects, idempotent, non-destructive, and explicit error behavior for division by zero or non-finite inputs. This adds meaningful context on top of readOnlyHint and idempotentHint.
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 sections: definition, formula, use guidance, behavior, returns, and parameters. It is detailed but every section earns its place, and the core definition is front-loaded.
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 simple two-parameter deterministic calculation with no output schema, the description is complete: it defines the formula, states valid input conditions, describes error behavior, and specifies the return shape. Nothing needed to invoke the 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 description coverage is 100%, so the schema already documents both parameters with examples and constraints. The description restates the parameter meaning but does not add significant new semantics beyond the formula and the restriction that values must be positive for a meaningful multiple.
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 and resource: calculates EV/EBITDA, with the formula explicitly given. It also distinguishes the multiple from EV/Revenue, which is a sibling tool, making it clear what this one is for versus alternatives.
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?
Provides explicit WHEN TO USE and WHEN NOT TO USE sections, including the condition of negative or near-zero EBITDA and a direct pointer to EV/Revenue as the alternative. This fully routes the agent to the correct tool for the right situation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Calculate the EV/Revenue (EV/Sales) multiple: enterprise value divided by revenue — a valuation multiple usable for companies with thin, negative or zero EBITDA (e.g. high-growth or pre-profit businesses). Formula: EV/Revenue = Enterprise Value / Revenue. WHEN TO USE: Use for valuing pre-profit / high-growth companies, or as a cross-check alongside EV/EBITDA for mature ones. WHEN NOT TO USE: Do NOT use revenue multiples alone — they ignore profitability entirely (a company can have a low EV/S and still destroy value); pair with margin and growth context. BEHAVIOUR: pure deterministic calculation — no side effects, no network or storage access; idempotent and non-destructive; identical inputs always produce identical outputs. Division by zero, non-finite inputs, or mathematically undefined combinations return an explicit error instead of a number. RETURNS: JSON object { ev_to_revenue: number (e.g. 3.2 = 3.2x), inputs }. PARAMETERS: enterprise_value (required): Enterprise value in currency units, e.g. 10000000. Must be > 0. revenue (required): Revenue (net sales) over the trailing period, e.g. 3100000. Must be > 0.
| Name | Required | Description | Default |
|---|---|---|---|
| revenue | Yes | Revenue (net sales) over the trailing period, e.g. 3100000. Must be > 0. | |
| enterprise_value | Yes | Enterprise value in currency units, e.g. 10000000. Must be > 0. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations (readOnly, idempotent, non-destructive), the description adds concrete behavior: pure deterministic calculation, no side effects, no network or storage access, identical inputs produce identical outputs, and division-by-zero or non-finite inputs return explicit errors. This is exactly the kind of context annotations alone do not provide.
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 and is front-loaded with the core purpose. There is minor redundancy — the formula appears both in the opening sentence and again as 'Formula: EV/Revenue = Enterprise Value / Revenue' — but overall every section earns its place.
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 simple two-parameter calculation, the description covers the formula, use cases, exclusions, behavioral guarantees, error handling, and return format. Since there is no output schema, the explicit RETURNS section is valuable and leaves nothing an agent needs to know to call the 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%, so the schema already documents both parameters with examples and the 'Must be > 0' constraint. The description's PARAMETERS section mostly echoes the schema rather than adding new semantic meaning, so the baseline of 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 resource — 'Calculate the EV/Revenue (EV/Sales) multiple' — and immediately gives the formula. It also differentiates this from the sibling calculate_ev_to_ebitda by stating it is usable for companies with thin, negative, or zero EBITDA.
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 tell the agent to use this for pre-profit/high-growth companies and as a cross-check alongside EV/EBITDA, while warning against relying on revenue multiples alone. This fully routes the agent to and away from alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Calculate the Internal Rate of Return (IRR), MOIC and an IRR sensitivity table for a single lump-sum equity investment that returns one exit value after a whole-year hold period. WHEN TO USE: you have an upfront investment amount, a single exit value and a hold period in whole years (standard PE/VC single-exit scenario) and need the annualised return, the money multiple, or a return stress-test. The result also includes a plain-language interpretation benchmarked against VC/PE/public-market return hurdles. WHEN NOT TO USE: for cash-flow streams with multiple intermediate distributions (use calculate_npv or calculate_moic on the full cash-flow array), or when you only need the sensitivity grid (use calculate_irr_sensitivity). BEHAVIOUR: pure deterministic calculation — no side effects, no network or storage access, no randomness; idempotent and non-destructive; identical inputs always produce identical outputs. IRR is solved over the cash-flow schedule [-investment, 0, ..., exit_value] via Newton-Raphson with bisection fallback. RETURNS: JSON object with concept, definition, formula, calculation (irr as a percentage string, moic as a multiple, cash_flows array), interpretation, and sensitivity (byMultiple, byHoldPeriod). PARAMETERS: initial_investment (number > 0, currency units), exit_value (number > 0, same currency units), hold_period (integer >= 1 whole years), currency (optional string: GBP default, USD, EUR, JPY, CHF — display only, no conversion).
| Name | Required | Description | Default |
|---|---|---|---|
| currency | No | Optional display currency code. Defaults to GBP. Used only for formatting output labels — no FX conversion is performed. | GBP |
| exit_value | Yes | Value returned at exit, same currency units as initial_investment, e.g. 250000. Must be positive. | |
| hold_period | Yes | Holding period in whole years, e.g. 5. Must be a positive integer (1, 2, 3, ...). | |
| initial_investment | Yes | Amount invested up front, in currency units, e.g. 100000. Must be positive. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations that already mark it read-only, idempotent, and non-destructive, the description discloses that the tool performs a pure deterministic calculation with no side effects, network, storage, or randomness, and gives the exact cash-flow schedule and Newton-Raphson-with-bisection solution method. This gives an agent a concrete, trustworthy behavioral 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?
Well-structured with labelled sections and front-loaded purpose, but slightly verbose: 'idempotent and non-destructive; identical inputs always produce identical outputs' repeats the same idea, and the BEHAVIOUR line packs several near-synonymous claims. Still, every section earns its place.
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 is self-sufficient despite lacking an output schema: it enumerates the JSON return fields, explains the interpretation output, gives parameter constraints, and routes to siblings in edge cases. An agent has all needed context to select and invoke the 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?
Input schema covers 100% of parameters with descriptions, so the baseline is 3. The description's PARAMETERS block mostly restates schema constraints; it adds the 'same currency units' relationship and currency display-only nuance, but these are already present in 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?
States a precise verb and deliverable ('Calculate the Internal Rate of Return (IRR), MOIC and an IRR sensitivity table') and bounds the tool by the exact deal shape it accepts: single lump-sum investment, one exit value, whole-year hold. This directly differentiates it from calculate_irr_sensitivity, calculate_npv, and calculate_moic, which appear as 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?
Includes explicit WHEN TO USE and WHEN NOT TO USE sections naming sibling tools as alternatives: calculate_npv or calculate_moic for multi-distribution cash-flow streams, calculate_irr_sensitivity when only the grid is needed. This is the clearest possible routing guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Compute an IRR sensitivity grid across a range of exit multiples and hold periods for a single lump-sum investment. WHEN TO USE: to stress-test how the annualised return varies with exit multiple and holding period before committing to an investment. Complements calculate_irr. WHEN NOT TO USE: when you need one precise IRR for a known exit value (use calculate_irr), or a full valuation (use calculate_dcf). BEHAVIOUR: pure deterministic calculation — no side effects, no network or storage access; idempotent and non-destructive. NOTE ON GRID GEOMETRY: the byMultiple grid is computed at the SECOND hold period in hold_periods (default 5 years); the byHoldPeriod grid is computed at a 2.5x exit multiple. RETURNS: JSON object { byMultiple: { "2.0x": 14.9, ... } with IRR values as percentage numbers rounded to 1dp, byHoldPeriod: { "5y": 18.4, ... } }. PARAMETERS: initial_investment (number > 0), exit_multiples (optional array of numbers to test, default [1.5, 2.0, 2.5, 3.0, 3.5]), hold_periods (optional array of positive integers (years) to test, default [3, 5, 7, 10]).
| Name | Required | Description | Default |
|---|---|---|---|
| hold_periods | No | Hold periods in whole years to test, e.g. [3, 5, 7, 10]. Defaults to [3, 5, 7, 10]. | |
| exit_multiples | No | Exit multiples to test, e.g. [2.0, 2.5, 3.0, 4.0, 5.0]. Defaults to [1.5, 2.0, 2.5, 3.0, 3.5]. | |
| initial_investment | Yes | Amount invested up front, in currency units, e.g. 100000. Must be positive. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover readOnly, idempotent, and non-destructive, but the description adds specifics: 'pure deterministic calculation — no side effects, no network or storage access; idempotent and non-destructive.' It also discloses grid geometry ('byMultiple grid is computed at the SECOND hold period...'), which is not inferable from annotations or schema. This adds valuable behavioral context without contradicting 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?
Despite being lengthy, the description is well-structured with clear section labels (WHEN TO USE, WHEN NOT TO USE, BEHAVIOUR, NOTE ON GRID GEOMETRY, RETURNS, PARAMETERS) that allow quick scanning. Every section adds critical information for correct invocation. The purpose is front-loaded, and there is no filler language.
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's complexity (two-dimensional grid with defaults and anchor points) and no output schema, the description fully explains return structure ('RETURNS: JSON object { byMultiple: ... }') and parameters. It also covers usage context, safety (via annotations + description), and differentiates from siblings. Nothing an agent needs to call it 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%, so params are documented. The description adds context: 'single lump-sum investment' clarifies the investment model, and the note on grid geometry explains how hold_periods and exit_multiples affect the output (which grid uses which anchor). This enriches parameter semantics beyond the schema's basic descriptions, though the defaults are already stated in both.
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 for a single lump-sum investment.' This precisely states what the tool does and distinguishes it from siblings like calculate_irr (single IRR) and calculate_dcf (valuation). The purpose is unambiguous and the resource is clearly identified.
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 are provided. It states the use case ('to stress-test how the annualised return varies...') and names alternatives: 'use calculate_irr' for a precise IRR and 'use calculate_dcf' for full valuation. This gives an agent clear routing guidance with no ambiguity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Calculate the Multiple on Invested Capital (MOIC): total distributions divided by total invested, with no discounting and no time value. WHEN TO USE: for a quick money-multiple answer from a cash-flow schedule when you do not need a discount rate or annualised return. WHEN NOT TO USE: when time value of money matters (use calculate_irr for annualised return, or calculate_npv for discounted value). BEHAVIOUR: pure deterministic calculation — no side effects, no network or storage access; idempotent and non-destructive. MOIC is computed as sum of positive cash flows divided by sum of absolute negative cash flows; returns 0 if there is no invested capital. RETURNS: JSON object { moic: number rounded to 2dp (e.g. 2.5 = 2.5x), cash_flows }. PARAMETERS: cash_flows (ordered number array starting at time 0; negatives are investments, positives are distributions), e.g. [-100000, 0, 0, 0, 0, 250000].
| Name | Required | Description | Default |
|---|---|---|---|
| cash_flows | Yes | Ordered cash flows starting at time 0. Negative = invested capital, positive = distributions. Example: [-100000, 0, 0, 0, 0, 250000]. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses that the calculation is deterministic, side-effect-free, idempotent, and non-destructive, adding behavioral context beyond the annotations. It also documents the edge case of zero invested capital returning 0 and states the output format with rounding behavior.
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 labels for definition, usage, behavior, returns, and parameters. Every section carries distinct value and there is minimal redundancy despite the thorough coverage.
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 pure calculation tool with no output schema, the description fully covers what the agent needs: formula, sign conventions, edge case, output shape, rounding, and sibling distinctions. No important calling information 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?
Although the schema already documents cash_flows well, the description adds formula-level semantics: sum of positive cash flows divided by sum of absolute negative cash flows, explicit sign conventions, and a concrete example. This meaningfully supplements 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 clearly defines MOIC as total distributions divided by total invested, specifies no discounting and no time value, and distinguishes it from related financial metrics. The exact calculation formula makes the tool's purpose unambiguous.
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 that this tool is for quick money-multiple answers without a discount rate, and it names calculate_irr and calculate_npv as alternatives when time value of money matters. This fully guides tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Calculate the Net Present Value (NPV) of an ordered cash-flow series discounted at a given rate. The first cash flow is treated as time 0 and is NOT discounted (typically the negative initial investment). WHEN TO USE: to evaluate whether an investment creates or destroys value at a required discount rate, or to compare competing projects on a present-value basis when you have a full cash-flow schedule. WHEN NOT TO USE: for a single lump-sum investment with one exit value (use calculate_irr), or when you only need a money multiple with no time value (use calculate_moic). BEHAVIOUR: pure deterministic calculation — no side effects, no network or storage access; idempotent and non-destructive; identical inputs always produce identical outputs. RETURNS: JSON object { npv: number rounded to 2dp, rate, cash_flows }. A positive NPV means the investment clears the discount-rate hurdle. PARAMETERS: rate (decimal discount rate, e.g. 0.10 = 10% — express as a decimal, never as percentage points), cash_flows (ordered number array starting at time 0; negative values are investments/outflows, positive values are distributions/inflows), e.g. [-100000, 0, 0, 0, 0, 250000].
| Name | Required | Description | Default |
|---|---|---|---|
| rate | Yes | Discount rate as a decimal, e.g. 0.10 = 10%. Never pass percentage points (10 is invalid for 10%). | |
| cash_flows | Yes | Ordered cash flows starting at time 0 (first element is not discounted). Negative = investment/outflow, positive = distribution/inflow. Example: [-100000, 0, 0, 0, 0, 250000]. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes beyond the annotations by stating the calculation is 'pure deterministic' with 'no side effects, no network or storage access,' and that 'identical inputs always produce identical outputs.' It also discloses the return format and interpretation of positive NPV, adding real behavioral context beyond readOnlyHint and idempotentHint.
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: WHEN TO USE, WHEN NOT TO USE, BEHAVIOUR, RETURNS, and PARAMETERS. It front-loads the core definition and every section earns its place without filler or redundancy.
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?
Although there is no output schema, the description fully documents the return object shape and numeric rounding, plus the meaning of a positive NPV. Combined with full input schema coverage and safety annotations, nothing needed to invoke the 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%, so the baseline is 3, but the description adds meaningful reinforcement: it explains rate must be a decimal rather than percentage points, defines cash-flow sign conventions, notes the first cash flow is not discounted, and gives a concrete example. It largely mirrors the schema but adds the typical initial-investment framing.
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 Net Present Value (NPV) of an ordered cash-flow series discounted at a given rate.' It explains the time-0 non-discounting convention and distinguishes itself from siblings in the WHEN NOT TO USE section by naming calculate_irr and calculate_moic.
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?
WHEN TO USE explicitly describes investment evaluation and project comparison, while WHEN NOT TO USE names specific alternatives and the conditions that should route to them, such as single lump-sum investments going to calculate_irr. This is direct, actionable guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Relever an unlevered (asset) beta to a target capital structure using the Hamada formula — restoring financial risk for the specific debt/equity mix of the company or deal being valued. Formula: Beta(levered) = Beta(unlevered) x (1 + (1 - tax rate) x Debt/Equity). WHEN TO USE: Use AFTER unlevering comparable betas: apply the average unlevered beta to your target company’s (or transaction’s) capital structure to obtain the beta for WACC. WHEN NOT TO USE: Do NOT relever onto an unrealistic target structure — extreme leverage produces extreme betas that may overstate risk; sanity-check the resulting cost of equity. BEHAVIOUR: pure deterministic calculation — no side effects, no network or storage access; idempotent and non-destructive; identical inputs always produce identical outputs. Division by zero, non-finite inputs, or mathematically undefined combinations return an explicit error instead of a number. RETURNS: JSON object { levered_beta: number (e.g. 1.15), inputs }. PARAMETERS: unlevered_beta (required): Unlevered (asset) beta, e.g. 0.85. Must be > 0. tax_rate (required): Corporate tax rate as a decimal between 0 and 1, e.g. 0.25 = 25%. debt_to_equity (required): Target debt-to-equity ratio (market values preferred), e.g. 0.6 = 0.6x. Must be >= 0.
| Name | Required | Description | Default |
|---|---|---|---|
| tax_rate | Yes | Corporate tax rate as a decimal between 0 and 1, e.g. 0.25 = 25%. | |
| debt_to_equity | Yes | Target debt-to-equity ratio (market values preferred), e.g. 0.6 = 0.6x. Must be >= 0. | |
| unlevered_beta | Yes | Unlevered (asset) beta, e.g. 0.85. Must be > 0. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint and idempotentHint, but the description adds valuable detail beyond that: 'pure deterministic calculation — no side effects, no network or storage access; idempotent and non-destructive' and explicitly documents error behavior for division by zero or non-finite inputs. This goes well beyond the annotations without contradicting 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 uses clearly labeled sections (formula, when to use, when not to use, behavior, returns, parameters) and front-loads the core purpose and formula. Every sentence adds useful guidance; no filler or redundant restatement of the tool name.
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 calculation tool with 100% parameter schema coverage, readOnly/idempotent annotations, no output schema, and sibling tools covering related finance operations, the description is complete. It covers purpose, formula, usage timing, exclusion cases, return shape, error behavior, and parameter constraints.
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 fully documents each parameter. The description's Parameters section largely mirrors the schema with examples, and adds only minor context such as 'market values preferred' for debt_to_equity. This is adequate but not a substantial increment over 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?
States a specific verb ('Relever'), the resource (unlevered beta), the target state (target capital structure), and the exact formula (Hamada). It clearly differentiates from sibling calculate_unlever_beta, which performs the opposite operation.
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: 'AFTER unlevering comparable betas... apply the average unlevered beta to your target company’s capital structure to obtain the beta for WACC.' It also gives a WHEN NOT TO USE caution about unrealistic leverage, and the WACC mention connects it to calculate_wacc without needing to inspect siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Unlever a (levered) equity beta to its asset beta using the Hamada formula — removing the financial-risk effect of debt so betas of companies with different capital structures can be compared. Formula: Beta(unlevered) = Beta(levered) / (1 + (1 - tax rate) x Debt/Equity). WHEN TO USE: Use when valuing a private company or a deal with a different capital structure than the public comparable — unlever the comps’ betas, average them, then relever at your target structure. WHEN NOT TO USE: Do NOT unlever with an inconsistent tax rate or debt/equity ratio — the result is only as clean as its inputs; for companies with significant non-debt liabilities consider a more advanced formula. BEHAVIOUR: pure deterministic calculation — no side effects, no network or storage access; idempotent and non-destructive; identical inputs always produce identical outputs. Division by zero, non-finite inputs, or mathematically undefined combinations return an explicit error instead of a number. RETURNS: JSON object { unlevered_beta: number (e.g. 0.85), inputs }. PARAMETERS: levered_beta (required): The observed (levered) equity beta of the comparable company, e.g. 1.2. Must be > 0. tax_rate (required): Corporate tax rate as a decimal between 0 and 1, e.g. 0.25 = 25%. debt_to_equity (required): Debt-to-equity ratio of the company whose beta is being unlevered (market values preferred), e.g. 0.5 = 0.5x. Must be >= 0.
| Name | Required | Description | Default |
|---|---|---|---|
| tax_rate | Yes | Corporate tax rate as a decimal between 0 and 1, e.g. 0.25 = 25%. | |
| levered_beta | Yes | The observed (levered) equity beta of the comparable company, e.g. 1.2. Must be > 0. | |
| debt_to_equity | Yes | Debt-to-equity ratio of the company whose beta is being unlevered (market values preferred), e.g. 0.5 = 0.5x. Must be >= 0. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes well beyond the annotations by stating the calculation is 'pure deterministic,' with 'no side effects, no network or storage access,' idempotent, and non-destructive. It also discloses error behavior for division by zero, non-finite inputs, and undefined combinations, which is highly useful for an agent deciding how to invoke and handle results.
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 long but well-structured with labeled sections: Formula, WHEN TO USE, WHEN NOT TO USE, BEHAVIOUR, RETURNS, and PARAMETERS. Each section earns its place, and the core purpose and formula are front-loaded before usage and behavioral caveats.
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 calculation tool with no output schema, the description covers all necessary context: formula, parameter constraints, error semantics, return shape, and use cases. An agent has everything needed to select and correctly invoke the tool.
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 strong, but the description adds the Hamada formula tying the parameters together and clarifications like market values preferred for debt_to_equity. This provides relational meaning beyond the individual parameter schemas.
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 action and resource: 'Unlever a (levered) equity beta to its asset beta using the Hamada formula.' It also explains the purpose of the calculation—removing financial-risk effect so betas with different capital structures can be compared—and gives the exact formula, making the tool's role unambiguous and distinguishable from siblings like calculate_relever_beta.
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 valuation context and input-quality caveats. It mentions relevering at a target structure, which implicitly points to the alternative workflow, but it does not explicitly name calculate_relever_beta as the sibling tool to use for that step.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Calculate the Weighted Average Cost of Capital (WACC): the blended after-tax cost of a company's equity and debt capital, weighted by market values. WHEN TO USE: to determine the discount rate for a DCF valuation from equity market value, debt market value, costs of capital and corporate tax rate. WHEN NOT TO USE: when you already have the discount rate, or for the full valuation itself (use calculate_dcf). BEHAVIOUR: pure deterministic calculation — no side effects, no network or storage access; idempotent and non-destructive. Formula: (E/V) x Re + (D/V) x Rd x (1 - tax_rate), where V = equity_value + debt_value; returns 0 if total value is 0. RETURNS: JSON object { wacc: decimal rounded to 6dp (e.g. 0.105), wacc_percent: percentage rounded to 2dp (e.g. 10.5), inputs }. PARAMETERS: equity_value (market value of equity, >= 0), debt_value (market value of debt, >= 0), cost_of_equity (decimal, e.g. 0.12 = 12%), cost_of_debt (decimal, e.g. 0.06 = 6%), tax_rate (decimal 0-1, e.g. 0.25 = 25%). All rates are decimals, never percentage points.
| Name | Required | Description | Default |
|---|---|---|---|
| tax_rate | Yes | Corporate tax rate as a decimal between 0 and 1, e.g. 0.25 = 25%. | |
| debt_value | Yes | Market value of debt, >= 0, e.g. 5000000. | |
| cost_of_debt | Yes | Cost of debt as a decimal, e.g. 0.06 = 6%. Never pass percentage points. | |
| equity_value | Yes | Market value of equity, >= 0, e.g. 10000000. | |
| cost_of_equity | Yes | Cost of equity as a decimal, e.g. 0.12 = 12%. Never pass percentage points. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description goes further by stating 'pure deterministic calculation — no side effects, no network or storage access' and documents the zero-total-value edge case ('returns 0 if total value is 0'). This adds meaningful behavioral context beyond 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 description is longer than average but uses labeled sections (WHEN TO USE, BEHAVIOUR, RETURNS, PARAMETERS) that make it skimmable. Each sentence contributes either a usage rule, formula, or parameter clarification. Slight redundancy with schema parameter descriptions keeps it from a 5.
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 inputs, formula, edge case, and return object, so an agent can invoke and interpret results correctly. It references calculate_dcf as the alternative, but it does not mention calculate_capm_cost_of_equity, a sibling that could provide the cost_of_equity input. This is a minor gap given the input list is otherwise 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 coverage is 100% and each parameter already has a description. The description adds value by tying parameters to the formula (E/V x Re + D/V x Rd x (1 - tax_rate)) and by emphasizing the global rule 'All rates are decimals, never percentage points,' which prevents a common invocation error.
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 resource: 'Calculate the Weighted Average Cost of Capital (WACC)' and immediately defines what WACC is. It clearly distinguishes itself from calculate_dcf by noting the tool covers only the discount-rate step, not the full valuation.
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 give unambiguous selection criteria: use it to derive a DCF discount rate from the listed inputs, avoid it when the discount rate is already known, and defer to calculate_dcf for full valuation. This is model guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
calculate_irr_sensitivityirr_sensitivitycalculate_earnings_yieldcalculate_equity_value_from_enterprise_valuecalculate_annuity_present_valuecalculate_asset_turnovercalculate_cagrcalculate_cash_conversion_cyclecalculate_cash_ratiocalculate_current_ratiocalculate_days_inventory_outstandingcalculate_days_payables_outstandingcalculate_days_sales_outstandingcalculate_debt_to_assetscalculate_debt_to_equitycalculate_defensive_intervalcalculate_discounted_payback_periodcalculate_dividend_yieldcalculate_dpicalculate_epscalculate_equity_multipliercalculate_fixed_asset_turnovercalculate_future_valuecalculate_gross_margincalculate_interest_coveragecalculate_inventory_turnovercalculate_loan_paymentcalculate_net_margincalculate_operating_margincalculate_payables_turnovercalculate_payback_periodcalculate_payout_ratiocalculate_pb_ratiocalculate_pe_ratiocalculate_perpetuity_valuecalculate_present_valuecalculate_quick_ratiocalculate_receivables_turnovercalculate_return_on_assetscalculate_return_on_capital_employedcalculate_return_on_equitycalculate_return_on_invested_capitalcalculate_rvpicalculate_tvpicalculate_annuity_present_valuecalculate_cagrcalculate_capm_cost_of_equitycalculate_discounted_payback_periodcalculate_dpicalculate_enterprise_valuecalculate_ev_to_ebitdacalculate_ev_to_revenuecalculate_future_valuecalculate_loan_paymentcalculate_payback_periodcalculate_perpetuity_valuecalculate_present_valuecalculate_relever_betacalculate_rvpicalculate_tvpicalculate_unlever_betacalculate_asset_turnovercalculate_cash_conversion_cyclecalculate_cash_ratiocalculate_current_ratiocalculate_days_inventory_outstandingcalculate_days_payables_outstandingcalculate_days_sales_outstandingcalculate_dcfcalculate_debt_to_assetscalculate_debt_to_equitycalculate_defensive_intervalcalculate_dividend_yieldcalculate_epscalculate_equity_multipliercalculate_fixed_asset_turnovercalculate_gross_margincalculate_interest_coveragecalculate_inventory_turnovercalculate_irrcalculate_moiccalculate_net_margincalculate_npvcalculate_operating_margincalculate_payables_turnovercalculate_payout_ratiocalculate_pb_ratiocalculate_pe_ratiocalculate_quick_ratiocalculate_receivables_turnovercalculate_return_on_assetscalculate_return_on_capital_employedcalculate_return_on_equitycalculate_return_on_invested_capitalcalculate_waccirr_sensitivity
Add one secure layer between your agents and this server.