Return a filled-in, valid contract model to copy and edit.

Call this first when you are about to build a model and are unsure how the fields fit together. Editing a working example is faster and safer than assembling one from the schema, and the returned object is guaranteed to validate.

Three shapes are available:

• 'managed_service': exercises every field, including metered streams, staged investments, a financed asset with interest, maintenance and working capital.

• 'subscription': flat fee, no metered volume, no financed asset.

• 'equipment_lease': fully metered revenue, interest-free installments, residual value.

Args:

• template ('managed_service' | 'subscription' | 'equipment_lease'): Which shape. Default 'managed_service'.

Returns: model (the object to pass to the other tools), notes (what the shape is for), and conventions (the rules that govern every model).

Examples:

• Use when: "Help me model a service contract" and no model exists yet.

• Use when: you need to check what a field is called or how it is shaped.

Expand a contract into a month-by-month cash flow schedule and compute the metrics that follow from it: IRR, NPV, simple and discounted payback, MOIC, ROI, working capital, break-even volume, and the financing cost of any asset paid in installments.

Use this as the main entry point whenever someone asks whether a deal, contract, lease, managed-service agreement or equipment purchase is worth doing.

Args:

• model (object): The contract. Call cashflow_model_template first if you are unsure how to shape it.

• schedule_detail ('none' | 'annual' | 'monthly'): How much of the schedule to return. Default 'annual'. Ask for 'monthly' only when a specific month matters; a 60-month contract returns 61 rows.

• response_format ('markdown' | 'json'): Default 'markdown'.

Returns: metrics (IRR, NPV, payback, MOIC, ROI, EBITDA), financing, workingCapital, breakeven, annual rollup, optional schedule, and warnings.

irrAnnual is null when the flows have no reportable IRR, with the reason in irrUnavailableReason. Treat null as "no IRR exists", never as zero. paybackMonth is null when the investment is never recovered within the term.

Examples:

• Use when: "Is this 5-year service contract worth signing?"

• Use when: "What is the IRR and payback on this equipment deal?"

• Don't use when: comparing two or more variants (use cashflow_compare_contracts)

• Don't use when: stress-testing assumptions (use cashflow_run_sensitivity)

Error handling: Returns a validation error naming the offending field if the model is malformed.

Re-evaluate a contract under a set of scenarios and report each one against the base case.

Five scenarios run by default: volume -20%, volume -10%, volume +20%, no price indexation, and operating cost +10%. Pass your own scenarios to override them.

Volume is listed first on purpose: a volume forecast taken from a customer's own estimate is a negotiating position, not a measurement, and it is the assumption that breaks most often.

Args:

• model (object): The contract, same shape as cashflow_evaluate_contract.

• scenarios (array, optional): Custom scenarios. Each has id, label, and any of volumeFactor, priceFactor, costFactor, revenueEscalation, costEscalation.

• response_format ('markdown' | 'json'): Default 'markdown'.

Returns: base (the unmodified case) and scenarios[], each with irrAnnual, npv, paybackMonth, irrDeltaPoints (percentage points against base, null when either side has no IRR) and npvDelta.

Examples:

• Use when: "What happens to this deal if volume comes in 20% under plan?"

• Use when: "How fragile is the return to the inflation clause?"

Evaluate two to five named contract variants and rank them side by side.

Built for the question these models exist to answer: pay cash or finance, 24 months interest-free or 36 with interest, higher fixed fee or higher per-unit price, 3-year term or 5-year.

Args:

• variants (array): 2 to 5 entries of { name, model }.

• rank_by ('npv' | 'irr' | 'payback'): Which metric orders the result. Default 'npv'.

• response_format ('markdown' | 'json'): Default 'markdown'.

Returns: variants[] ordered best first by the chosen metric, each with its headline metrics and financing cost, plus the name of the winner.

Ranking by IRR places variants without a reportable IRR last, because an absent IRR is not a low one.

Examples:

• Use when: "Should we take the 24-month interest-free plan or pay cash?"

• Use when: "Compare a 3-year and a 5-year term on the same contract."

Compute the monthly volume at which a contract stops losing money, without running the full schedule.

Contingency is folded into the contribution margin rather than added to fixed cost, because total cost is (fixed + maintenance + variable x u/u0) x (1 + contingency): contingency multiplies both sides. Fixed revenue offsets fixed cost, so a contract whose flat fee already covers its fixed base breaks even at zero units.

Escalation is excluded on purpose. Break-even is a statement about the base year.

Args:

• model (object): The contract, same shape as cashflow_evaluate_contract.

• volume_factor (number): Scales planned volume before solving. Default 1.

Returns: units, revenue, marginOfSafetyPct, averagePrice, variableCostPerUnit and contributionPerUnit. Returns null when the model has no metered streams to break even on, and unitsUnreachable true when contribution per unit is zero or negative.

Examples:

• Use when: "How many units a month do we need to cover costs?"

• Use when: "How much headroom is there between plan and break-even?"

Compute NPV, IRR and payback directly on a list of period cash flows, with no contract model involved.

Use this when the numbers already exist, for example flows lifted from a spreadsheet, a schedule produced elsewhere, or a quick sanity check.

The first element sits at period 0 and is not discounted. Outflows are negative.

Args:

• flows (array of numbers): Cash flow per period, flows[0] at t=0. Needs at least 2 entries.

• period ('monthly' | 'annual'): What one element represents. Default 'monthly'. Determines how the rate is annualized.

• discount_rate_annual (number): Effective annual rate for NPV, e.g. 0.14 for 14%. Default 0.

• interpolate_payback (boolean): Return a fractional payback period instead of whole periods. Default false.

Returns: npv, irrAnnual, irrPeriodic, irrAvailable, irrUnavailableReason, payback and cumulative totals.

irrAnnual is null when the vector has no reportable IRR: no outflow, no inflow, or flows that never sum positive. The reason says which.

A vector whose sign changes more than once may have several real IRRs. The engine returns one and flags nothing, which is a property of IRR itself. signChanges is reported so you can tell when to trust NPV instead.

Examples:

• Use when: "What is the IRR of -1000, 500, 500, 500?"

• Use when: "Discount these annual flows at 12% and tell me the NPV."

• Don't use when: you have contract terms rather than flows (use cashflow_evaluate_contract)

Compute the level monthly payment that amortizes a principal, plus the total paid and the interest it costs.

Matches the spreadsheet PMT(rate/12, nper, -pv) convention, including the zero-rate case, so the output can be checked against Excel cell by cell.

Note the rate convention: loans divide the annual rate by 12, they do not compound it. This tool divides. Discounting elsewhere in this server compounds. Mixing the two is the most common error in a hand-built model.

Args:

• principal (number): Amount financed.

• term_months (integer): Number of level payments. 0 means paid in cash.

• annual_rate (number): Nominal annual rate, e.g. 0.12 for 12% APR. Use 0 for an interest-free plan.

• include_amortization (boolean): Return the per-month interest and principal split. Default false.

Returns: monthlyPayment, totalPaid, interestPaid, and optionally an amortization schedule of { month, payment, interest, principal, balance }.

Examples:

• Use when: "What is the payment on 3.5 million over 36 months at 12%?"

• Use when: "How much interest does the 36-month plan cost versus 24 months interest-free?"

Convert an annual rate to a monthly one and back, under either convention.

'compound' is the discounting convention: (1 + annual)^(1/12) - 1. 'divide' is the loan convention: annual / 12. A 12% annual rate is 0.9489% per month compounded but 1% per month divided, and using one where the other belongs quietly distorts every downstream number.

Args:

• value (number): The rate to convert, e.g. 0.14 for 14%.

• direction ('annual_to_monthly' | 'monthly_to_annual'): Which way to convert.

• convention ('compound' | 'divide'): 'compound' for discounting, 'divide' for amortization.

Returns: input, output, and both conventions side by side so the difference is visible.

Examples:

• Use when: "What monthly rate should I discount at for a 14% cost of capital?"

• Use when: "Is 1% a month the same as 12% a year?"