calculate_actuarial_pv

Actuarial present value engine. Discount expected cash flows with mortality, survival, and risk adjustment for insurance and benefit obligations, generalising IFRS 17 (fulfilment cash flows), IAS 19 (employee benefits), IFRS 2 (share-based payments), and IAS 37 (provisions). Use this for regulated IFRS/HKFRS obligations only; it does NOT do generic project or scenario probability weighting (use calculate_expected_value). Methods: ifrs17_gmm: cash_flows, discount_rate, risk_adjustment; ifrs17_paa: premiums, claims_cash, acquisition_cash_flows, coverage_periods; ifrs17_vfa: cash_flows, discount_rate, underlying_items_return, risk_adjustment; ias19_puc: projected_benefits, discount_rate, attribution_years; ias37_provision: outcomes, probabilities, discount_rate, periods. Supply exactly one method with its declared inputs (no defaults). An unknown method, a missing input, or an extra field returns an error envelope (code INVALID_ARGUMENT) instead of raising.

read-only

Argument	Type	Description
method*	string	Formula to apply; the tool description lists the exact inputs each value requires.
periods	any	Number of periods n (>=1).
outcomes	any	Outcome values aligned with probabilities.
premiums	any	Premiums in reporting currency.
cash_flows	any	Projected cash flows in reporting currency, indexed t=1..n.
claims_cash	any	Expected claims in reporting currency.
discount_rate	any	Discount rate as a decimal (0.10 = 10%); pre-tax when method=viu_pre_tax.
probabilities	any	Cumulative success probability per period in [0,1], aligned with cash_flows.
risk_adjustment	any	Explicit risk adjustment for non-financial risk.
coverage_periods	any	Coverage periods for the PAA (>=1).
attribution_years	any	Years of service for attribution (>=1).
projected_benefits	any	Projected benefits per service year.
acquisition_cash_flows	any	Acquisition cash flows in reporting currency.
underlying_items_return	any	Return on underlying items (decimal).

Input schema (JSON)

{
  "type": "object",
  "required": [
    "method"
  ],
  "properties": {
    "method": {
      "enum": [
        "ifrs17_gmm",
        "ifrs17_paa",
        "ifrs17_vfa",
        "ias19_puc",
        "ias37_provision"
      ],
      "type": "string",
      "description": "Formula to apply; the tool description lists the exact inputs each value requires."
    },
    "periods": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Number of periods n (>=1)."
    },
    "outcomes": {
      "anyOf": [
        {
          "type": "array",
          "items": {}
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Outcome values aligned with probabilities."
    },
    "premiums": {
      "anyOf": [
        {
          "type": "number"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Premiums in reporting currency."
    },
    "cash_flows": {
      "anyOf": [
        {
          "type": "array",
          "items": {}
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Projected cash flows in reporting currency, indexed t=1..n."
    },
    "claims_cash": {
      "anyOf": [
        {
          "type": "number"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Expected claims in reporting currency."
    },
    "discount_rate": {
      "anyOf": [
        {
          "type": "number"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Discount rate as a decimal (0.10 = 10%); pre-tax when method=viu_pre_tax."
    },
    "probabilities": {
      "anyOf": [
        {
          "type": "array",
          "items": {}
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Cumulative success probability per period in [0,1], aligned with cash_flows."
    },
    "risk_adjustment": {
      "anyOf": [
        {
          "type": "number"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Explicit risk adjustment for non-financial risk."
    },
    "coverage_periods": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Coverage periods for the PAA (>=1)."
    },
    "attribution_years": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Years of service for attribution (>=1)."
    },
    "projected_benefits": {
      "anyOf": [
        {
          "type": "array",
          "items": {}
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Projected benefits per service year."
    },
    "acquisition_cash_flows": {
      "anyOf": [
        {
          "type": "number"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Acquisition cash flows in reporting currency."
    },
    "underlying_items_return": {
      "anyOf": [
        {
          "type": "number"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Return on underlying items (decimal)."
    }
  },
  "additionalProperties": false
}

calculate_convertible_bond

Convertible-bond engine. Value callable and puttable convertible or exchangeable bonds with credit risk using a Tsiveriotis-Fernandes lattice (equity discounted at the risk-free rate, debt at a credit spread), with conversion, issuer call, holder put, coupon schedule, and a straight-bond floor. Use this for convertible and exchangeable bonds; for a plain bond or rate curve use calculate_fixed_income, and for a standalone option or warrant use calculate_option. The lattice_tsf, lattice_intensity, finite_difference, lsmc and quantlib methods are alternative numerical schemes for the same valuation and take identical inputs (Tsiveriotis-Fernandes is the reference, lsmc is Monte Carlo, quantlib needs the optional engine); choose one. Methods: lattice_tsf/lattice_intensity/finite_difference/lsmc/quantlib: spot, face, coupon_rate, maturity, conversion_ratio, volatility, risk_free, credit_spread, call_schedule, put_schedule, rights_priority. Supply exactly one method with its declared inputs (no defaults). An unknown method, a missing input, or an extra field returns an error envelope (code INVALID_ARGUMENT) instead of raising.

read-only

Argument	Type	Description
face	any	Bond face value.
spot	any	Spot price of the underlying (or FX rate for garman_kohlhagen).
method*	string	Formula to apply; the tool description lists the exact inputs each value requires.
maturity	any	Time to expiry in years (0.5 = six months); > 0.
risk_free

calculate_credit_loss

Credit-risk engine (IFRS 9 / HKFRS 9). Compute 12-month, lifetime, and staged expected credit loss, PD/LGD/EAD, provision matrices, hazard rates, and CVA/DVA. Use this for impairment, fair-value credit adjustment, and loan-loss provisioning; for the credit component of a specific convertible bond use calculate_convertible_bond, and for liquidity, control or marketability discounts rather than credit loss use calculate_fair_value_adjustment. Methods: ecl_12m: ead, pd, lgd; ecl_lifetime: ead, pd_lifetime, lgd; ecl_staged: ead, pd_12m, pd_lifetime, lgd, stage; provision_matrix: receivables_ageing, loss_rates; pd_from_spread: credit_spread, recovery, tenor_years; cumulative_pd: annual_pd, years; hazard: hazard_rate, tenor_years; cva_dva: exposure_profile, pd, lgd, discount_rate. Supply exactly one method with its declared inputs (no defaults). An unknown method, a missing input, or an extra field returns an error envelope (code INVALID_ARGUMENT) instead of raising.

read-only

Argument	Type	Description
pd	any	Probability of default over the horizon, in [0,1].
ead	any	Exposure at default in currency units.
lgd	any	Loss given default in [0,1] (1 - recovery rate).
stage	any	IFRS 9 stage (1, 2 or 3).
years	any	Number of projection years n; equal len(cash_flows) when both are supplied.
method*

calculate_dcf

Discounted cash flow valuation engine. Choose a method and supply its exact inputs to value a business from projected free cash flows, dividends, residual income, or economic profit. Covers FCFF/FCFE DCF, NPV/IRR, terminal values, and multi-stage growth. Use this for going-concern cash-flow businesses; for asset-anchored or financial firms use calculate_residual, for peer-based pricing use calculate_market_multiple, and for pre-profit companies use calculate_loss_making_company. Methods: dcf/npv: cash_flows, discount_rate; annuity: payment, discount_rate, periods; growing_annuity: payment, discount_rate, growth_rate, periods; perpetuity: payment, discount_rate; terminal_gordon: final_cash_flow, discount_rate, perpetual_growth; terminal_multiple: final_cash_flow, exit_multiple; viu_pre_tax: cash_flows, pre_tax_discount_rate; rnpv: cash_flows, discount_rate, probabilities; lease_pv: lease_payments, incremental_borrowing_rate. Supply exactly one method with its declared inputs (no defaults). An unknown method, a missing input, or an extra field returns an error envelope (code INVALID_ARGUMENT) instead of raising.

read-only

Argument	Type	Description
method*	string	Formula to apply; the tool description lists the exact inputs each value requires.
payment	any	Level periodic payment in reporting currency.
periods	any	Number of periods n (>=1).
cash_flows	any	Projected cash flows in reporting currency, indexed t=1..n.
growth_rate

calculate_discount_rate

Cost-of-capital engine. Compute WACC, cost of equity (CAPM), cost of debt, unlevered/relevered beta, and country or size premiums from an explicit capital structure and market inputs. Use this to derive the discount rate an income-approach valuation needs; it returns a rate, not a valuation, so feed the result to calculate_dcf, or to calculate_residual for IFRS-basis measurement. Methods: wacc: equity_weight, debt_weight, cost_equity, cost_debt, tax_rate; capm: risk_free, beta, market_return; startup_capm: risk_free, beta, market_risk_premium, size_premium, illiquidity_premium; build_up: risk_free, equity_risk_premium, size_premium, industry_premium, specific_premium; currency_adjusted: base_rate, currency_risk_premium, country_risk_premium; country_risk: sovereign_yield, us_risk_free; esg: base_rate, esg_risk_premium, esg_opportunity_discount; portfolio_beta: weights, betas; ibr: risk_free, credit_spread, tenor_years. Supply exactly one method with its declared inputs (no defaults). An unknown method, a missing input, or an extra field returns an error envelope (code INVALID_ARGUMENT) instead of raising.

read-only

Argument	Type	Description
beta	any	Equity beta (market = 1.0).
betas	any	Asset/segment betas aligned with weights.
method*	string	Formula to apply; the tool description lists the exact inputs each value requires.
weights	any	Weights that must sum to 1.
tax_rate	any

calculate_expected_value

Expected-value engine. Compute expected values over discrete, continuous, simulated, or tree-structured uncertainty, plus football-field ranges. Use this for generic probability weighting of scenarios, Monte-Carlo and decision trees; it does NOT perform IFRS/HKFRS measurement of provisions, insurance or employee-benefit obligations (use calculate_actuarial_pv), and it does not price path-dependent payoffs (use calculate_structured_product). Methods: discrete: outcomes, probabilities; continuous: distribution, mean, std, lower, upper; scenario: scenarios; monte_carlo: iterations, distributions, base_params, seed; decision_tree: tree; football_field: estimates. Supply exactly one method with its declared inputs (no defaults). An unknown method, a missing input, or an extra field returns an error envelope (code INVALID_ARGUMENT) instead of raising.

read-only

Argument	Type	Description
std	any	Distribution standard deviation (>0).
mean	any	Distribution mean.
seed	any	Deterministic RNG seed (required by simulation methods for reproducibility).
tree	any	Decision tree with chance/decision nodes.
lower	any	Lower integration bound.
upper	any	Upper integration bound.
method

calculate_fair_value_adjustment

Fair-value-adjustment engine (IFRS 13). Compute exit-price adjustments including credit, liquidity, control and marketability discounts, blockage, and the fair-value hierarchy level. Use this to move from an indicated value to the fair value recognised in the accounts; for liquidity/marketability inputs of a listed instrument prefer calculate_market_multiple, and for expected credit loss use calculate_credit_loss. Methods: dlom: base_value, restricted_period, volatility, risk_free; dloc: base_value, transaction_cost_pct; control_premium: base_value, control_premium_pct; minority_discount: base_value, minority_discount_pct; highest_best_use: base_value, alternative_use_values; hierarchy_level: inputs. Supply exactly one method with its declared inputs (no defaults). An unknown method, a missing input, or an extra field returns an error envelope (code INVALID_ARGUMENT) instead of raising.

read-only

Argument	Type	Description
inputs	any	Inputs [{value, level}] used to determine the hierarchy level.
method*	string	Formula to apply; the tool description lists the exact inputs each value requires.
risk_free	any	Continuously-compounded risk-free rate (decimal).
base_value	any	Base valuation before the adjustment.
volatility	any	Annualized volatility (decimal, 0.30 = 30%); > 0.

calculate_fixed_income

Fixed-income engine. Price plain coupon bonds, solve for yield to maturity, measure interest-rate sensitivity via Macaulay and modified duration and convexity, and build a HIBOR/HKD-style term structure: bootstrap a zero curve from par rates, infer forward rates, and discount cash flows on the curve. Use this for vanilla bonds, rate risk and discount curves; for convertibles use calculate_convertible_bond and for structured payoffs use calculate_structured_product. Methods: bond_price/duration/convexity: face, coupon_rate, years, ytm, frequency; bond_yield: face, coupon_rate, years, price, frequency; matrix_pricing: target_tenor, benchmark_tenors, benchmark_yields; discount_factor: rate, years, frequency; zero_curve: par_rates, tenors, frequency; forward_rate: zero_rates, tenors, t1, t2; pv_curve: cash_flows, times, zero_rates, tenors. Supply exactly one method with its declared inputs (no defaults). An unknown method, a missing input, or an extra field returns an error envelope (code INVALID_ARGUMENT) instead of raising.

read-only

Argument	Type	Description
t1	any	Forward period start in years (>=0).
t2	any	Forward period end in years (> t1).
ytm	any	Yield to maturity (decimal, annualised).
face	any	Bond face value.
rate	any	A single interest/zero rate (decimal).
price	any

calculate_loss_making_company

Loss-making-company engine. Value currently unprofitable companies with margin-ramp DCF, revenue multiples, Merton structural equity, the VC method, distressed waterfalls, bank residual income, and SPAC deals; every method returns a central value plus a dispersion (sigma, percentiles, long-tail). Use this when earnings-based multiples break down; for standalone probability weighting of arbitrary scenarios use calculate_expected_value, and for a single going-concern DCF use calculate_dcf. Methods: margin_ramp_dcf: revenue, growth_rate, start_margin, target_margin, ramp_years, discount_rate, years, shares_outstanding, net_debt, range_method; revenue_multiple: revenue, ev_revenue_multiple, net_debt, shares_outstanding, range_method; merton_equity: firm_value, firm_volatility, debt, risk_free, maturity, range_method; vc_method: terminal_value, target_return, investment, shares_outstanding, range_method; distressed_waterfall: enterprise_value, claims, range_method; bank_residual_income: book_value, net_income, cost_equity, growth_rate, range_method; spac_deal: trust_cash, shares_outstanding, redemption_price, range_method. Supply exactly one method with its declared inputs (no defaults). An unknown method, a missing input, or an extra field returns an error envelope (code INVALID_ARGUMENT) instead of raising.

read-only

Argument	Type	Description
debt	any	Debt face value (default point) for the Merton equity model.
years	any	Number of projection years n; equal len(cash_flows) when both are supplied.
claims	any	Ordered claims [{name, amount, priority}] for a waterfall.
method*

calculate_market_multiple

Market-multiple engine. Apply peer multiples (P/E, P/B, EV/EBITDA, EV/Sales, PEG and more) or derive implied multiples to price a company on a comparable basis. Use this for market-approach pricing where peers exist; it does peer multiples only — for intrinsic cash-flow value use calculate_dcf, and for residual-income or IFRS-basis measurement use calculate_residual. Methods: ev_revenue: revenue, ev_revenue_multiple; ev_ebitda: ebitda, ev_ebitda_multiple; ev_arr: arr, ev_arr_multiple; ev_gmv: gmv, ev_gmv_multiple; pe: eps, pe_multiple; pb: book_value_per_share, pb_multiple; ps: sales_per_share, ps_multiple; cap_rate: net_operating_income, cap_rate; regression: intercept, growth_rate, growth_coefficient, market_maturity, maturity_coefficient; royalty_cap: revenue, royalty_rate, discount_rate; ddm: dividend_per_share, cost_equity, growth_rate. Supply exactly one method with its declared inputs (no defaults). An unknown method, a missing input, or an extra field returns an error envelope (code INVALID_ARGUMENT) instead of raising.

read-only

Argument	Type	Description
arr	any	Annual recurring revenue in reporting currency.
eps	any	Earnings per share.
gmv	any	Gross merchandise value in reporting currency.
ebitda	any	EBITDA in reporting currency.
method*	string	Formula to apply; the tool description lists the exact inputs each value requires.

calculate_option

Option-pricing engine. Price European and American options and warrants (Black-Scholes, Black-76, CRR binomial, Garman-Kohlhagen FX, digital, range, share-based) and their greeks. Use this for a single contingent claim or warrant on one underlying; it does NOT price listed structured payoffs such as CBBCs, inline/derivative warrants or autocallables (use calculate_structured_product). Methods: black_scholes: spot, strike, maturity, risk_free, volatility, option_type; black76: forward, strike, maturity, risk_free, volatility, option_type; binomial_american: spot, strike, maturity, risk_free, volatility, option_type, steps; garman_kohlhagen: spot, strike, maturity, domestic_rate, foreign_rate, volatility, option_type; barrier_first_passage: spot, strike, maturity, risk_free, volatility, option_type, barrier, barrier_type; asian_average: spot, strike, maturity, risk_free, volatility, option_type, average_type; digital: spot, strike, maturity, risk_free, volatility, cash_payout; range: spot, lower_strike, upper_strike, maturity, risk_free, volatility, payout; share_based: share_price, exercise_price, expected_life, volatility, risk_free, dividend_yield. Supply exactly one method with its declared inputs (no defaults). An unknown method, a missing input, or an extra field returns an error envelope (code INVALID_ARGUMENT) instead of raising.

read-only

Argument	Type	Description
spot	any	Spot price of the underlying (or FX rate for garman_kohlhagen).
steps	any	Lattice steps for binomial_american (>=50).
method*	string	Formula to apply; the tool description lists the exact inputs each value requires.
payout

calculate_residual

IFRS/HKFRS measurement engine. Compute goodwill and purchase-price allocation, impairment (IAS 36), inventory net realisable value, held-for-sale, debt waterfalls, cap tables, sum-of-the-parts and SPAC redemption; residual income and justified price-to-book; and non-financial asset fair value: investment property (IAS 40 / HKAS 40), PP&E revaluation via depreciated replacement cost (IAS 16) and biological assets at fair value less costs to sell (IAS 41). Use this for accounting-basis measurement of assets and equity; for going-concern cash flow use calculate_dcf and for peer multiples use calculate_market_multiple. Methods: goodwill: purchase_price, fair_value_net_identifiable_assets; ppa: purchase_price, tangible_assets_fv, identified_intangibles_fv; impairment_fvlcd: carrying_value, fair_value_less_costs_to_dispose; impairment_viu: carrying_value, value_in_use; inventory_nrv: carrying_value, net_realisable_value; held_for_sale: carrying_value, fair_value_less_costs_to_sell; debt_waterfall/cap_table: enterprise_value, claims; sotp: segments, net_debt, holding_discount; spac_redemption: trust_cash, shares_outstanding, redemption_price; investment_property: noi, cap_rate; ppe_revaluation: replacement_cost, accumulated_depreciation; biological_asset: expected_price, quantity, costs_to_sell; residual_income: book_value, net_income, cost_equity; justified_pb: roe, cost_equity, growth_rate; relief_from_royalty: revenue, royalty_rate, discount_rate, periods; mpeem: cash_flows, contributory_charges, discount_rate; with_without: with_cash_flows, without_cash_flows, discount_rate; recoverable_amount: fair_value_less_costs_to_dispose, value_in_use; liability_fulfilment: fulfilment_costs, mark_up, discount_rate; inventory_residual: selling_price, costs_to_complete, profit_allowance; development_residual: gross_development_value, development_costs, developer_profit. Supply exactly one method with its declared inputs (no defaults). An unknown method, a missing input, or an extra field returns an error envelope (code INVALID_ARGUMENT) instead of raising.

read-only

Argument	Type	Description
noi	any

calculate_sector_metrics

Sector-metric engine. Compute the metrics that anchor valuation in specific industries: SaaS (ARR, NRR, magic number, Rule of 40), marketplaces (take rate, GMV multiple), lending (LTV/CAC), and crypto (NVT, Metcalfe). It returns operating metrics, not a valuation; use them as inputs to calculate_market_multiple or calculate_dcf. Methods: ltv: arpu, gross_margin, churn_rate; cac: sales_marketing_expense, new_customers; arr: subscription_values; nrr: starting_revenue, ending_revenue, expansion_revenue; magic_number: net_new_arr, sales_marketing_expense_prior; rule_of_40: growth_rate, profit_margin; take_rate: revenue, gmv; gmv_multiple: gmv, ev_gmv_multiple; retention: retained_customers, starting_customers; trl: market_size, market_share, margin, exit_multiple, trl_discount; break_even: fixed_costs, asp, variable_cost; gross_margin: asp, variable_cost; token: transaction_volume, price_per_tx, velocity, supply; nvt: market_cap, transaction_volume; metcalfe: n, coefficient. Supply exactly one method with its declared inputs (no defaults). An unknown method, a missing input, or an extra field returns an error envelope (code INVALID_ARGUMENT) instead of raising.

read-only

Argument	Type	Description
n	any	Node/participant count n (>=0).
asp	any	Average selling price per unit.
gmv	any	Gross merchandise value in reporting currency.
arpu	any	Average revenue per user per period.
margin	any	Operating margin as a decimal.

calculate_structured_product

Structured-product engine. Value HKEX-listed and OTC structures: CBBCs, derivative and inline warrants, equity-linked notes and investments, autocallables, accumulators and decumulators, credit-linked notes, TRS, and CFDs. Use this for equity-linked and credit-linked payoff structures; for a plain option or warrant use calculate_option, for a convertible or exchangeable bond use calculate_convertible_bond, and for a vanilla bond or term structure use calculate_fixed_income. Methods: cbbc: notional, spot, strike, barrier, barrier_type, maturity, risk_free, volatility, option_type; cbbc_residual: notional, spot, call_price, entitlement, barrier, barrier_type, maturity, risk_free, volatility, option_type; derivative_warrant: notional, spot, strike, maturity, risk_free, volatility, average_type, option_type; inline_warrant: notional, spot, lower_strike, upper_strike, maturity, risk_free, volatility, payout; inline_warrant_avg: notional, spot, lower_strike, upper_strike, maturity, risk_free, volatility, payout, fixing_days; eli/eln: notional, spot, strike, maturity, risk_free, volatility, coupon_rate; autocallable: notional, spot, knock_out_level, observation_dates, coupon_rate_structured, maturity, risk_free, volatility; credit_linked_note: notional, credit_spread, recovery, maturity, risk_free, coupon_rate_structured; accumulator/decumulator: notional, spot, strike, knock_out_level, observation_dates, risk_free, volatility; trs: notional, spot, maturity, risk_free, dividend_yield; cfd: notional, spot, strike, maturity, risk_free. Supply exactly one method with its declared inputs (no defaults). An unknown method, a missing input, or an extra field returns an error envelope (code INVALID_ARGUMENT) instead of raising.

read-only

Argument	Type	Description
spot	any	Spot price of the underlying (or FX rate for garman_kohlhagen).
method*	string	Formula to apply; the tool description lists the exact inputs each value requires.

Fair Value MCP Server

Try it

calculate_actuarial_pv Read-only

Fair Value MCP Server

Try it

calculate_actuarial_pv Read-only

Tools (14)