calculate_cagr
Calculate the Compound Annual Growth Rate (CAGR): the smoothed annual growth rate that takes a beginning value to an ending value over a given number of years. Formula: CAGR = (End Value / Begin Value)^(1/n) - 1. WHEN TO USE: Use to state multi-year growth as a single comparable annualised rate (revenue growth, asset growth, fund performance) — the standard "growth per year" figure. WHEN NOT TO USE: Do NOT use when the beginning value is zero or negative (undefined), or when you need period-by-period volatility rather than a smoothed rate. 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 { cagr: decimal (e.g. 0.201 = 20.1%), cagr_pct: number (e.g. 20.1), inputs }. PARAMETERS: begin_value (required): Value at the START of the period, e.g. 100000. Must be > 0. end_value (required): Value at the END of the period, e.g. 250000. Must be > 0. periods (required): Number of years between the two values, e.g. 5. Must be > 0.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| periods | Yes | Number of years between the two values, e.g. 5. Must be > 0. | |
| end_value | Yes | Value at the END of the period, e.g. 250000. Must be > 0. | |
| begin_value | Yes | Value at the START of the period, e.g. 100000. Must be > 0. |