# Growth cagr compute

`growth-cagr-compute` · version 1.0.0 · Financial calculations · free, no key needed

CAGR from start and end values or a total return over years or dates, with a sub-year warning.

**Use when you need to: compound annual growth rate · CAGR calculator · annualized return from start and end value.**

## Decide before calling

Read the [versioned contract](/v1/tools/growth-cagr-compute/versions/1.0.0) and the supported scope below. Reuse `growth-cagr-compute@1.0.0` when your input, required output and limits match it. Choose another approach for an unsupported operation.

## Explain the choice

"I can use `growth-cagr-compute@1.0.0` for compound annual growth rate. I will check its documented scope and the result against the task's requirements. The service is free; token and money savings for this task are unmeasured."

## Supported

- compound annual growth rate
- CAGR calculator
- annualized return from start and end value
- average annual growth rate over years
- annualize a total return
- growth rate between two dates per year
- Excel RRI function equivalent
- revenue growth per year over five years

## Not supported

- total percent change without annualizing (use a percent-change tool)
- time-weighted or money-weighted return of flows with contributions (use cashflow-xirr)
- converting between nominal and effective rates
- growth of a series with more than two observations (no regression or averaging)

## Behavior

- Growth input, exactly one of two forms: (a) start_value (decimal greater than 0) together with end_value (decimal at least 0); or (b) total_return (decimal at least -1, the total change as a fraction, for example 0.9 for +90 percent). Giving both forms, neither, only one of start_value and end_value, or total_return together with either value is invalid_input. The growth ratio is R = end_value / start_value, or R = 1 + total_return.
- Time input, exactly one of two forms: (a) years (decimal greater than 0 and at most 1000); or (b) start_date and end_date (ISO calendar dates YYYY-MM-DD, year 1900 to 2200, start_date strictly before end_date, otherwise invalid_input) with the optional basis (default act-365f; basis together with years is invalid_input). Giving both forms, neither, or only one of the two dates is invalid_input.
- Years from dates: with D the exact number of calendar days from start_date to end_date, act-365f gives D/365; act-365.25 gives D/365.25; act-act-isda gives the sum over the days x with start_date <= x < end_date of 1/366 when the calendar year of x is a leap year and 1/365 otherwise (ISDA 2006 Definitions 4.16(b)). Years are an exact rational value; the rounded years output is never fed back into the calculation.
- CAGR = R^(1/years) - 1, with R = 0 giving exactly -1. total_return in the output is R - 1 (the input value in form (b)). years in the output is the exact years value. All three are rounded once to rate_scale (0 to 12, default 10) with the rounding mode, so years given as 0.4 with rate_scale 0 prints 0.
- sub_year is true when the exact years value is less than 1 (for example 181 days on act-365f, or 365 days on act-365.25, which is 0.99932 years). The value is still returned. GIPS 2020 does not allow a firm to present returns annualized for a period shorter than one year, so a caller should treat a sub_year result as an extrapolation and not as a reportable annualized return.
- Exact path: R^(1/years) is computed with an error below 1e-33 relative to max(1, |value|) and the CAGR and the total return are each rounded half-even to 30 fractional digits before the final rounding, so exact results such as 4^(1/2) - 1 = 1 are recovered exactly. If the CAGR magnitude would reach 1e20 the result is not_computable (details.reason overflow).
- A decimal string longer than 64 UTF-8 bytes is limit_exceeded, checked before parsing. Percent values are not accepted: 0.2386 means 23.86 percent.
- Every rounded output is rounded exactly once from the unrounded value using the rounding mode: half-up (ties away from zero, the default), half-even, half-down (ties toward zero), up (away from zero), down (toward zero), ceiling, floor. Amount outputs print exactly scale fractional digits and rate-like outputs exactly rate_scale fractional digits; a result that rounds to zero prints without a minus sign (never '-0.00').
- Decimal string fields (amounts, rates) must match ^-?(0|[1-9][0-9]*)(\.[0-9]+)?$ with at most 20 integer digits and at most 20 fractional digits; a JSON number, exponent form, leading plus, surrounding spaces, percent sign, missing integer part or trailing dot is invalid_input. Rates are decimal fractions (0.065 means 6.5 percent; "6.5" means 650 percent). A decimal string longer than 64 UTF-8 bytes is limit_exceeded, checked before parsing.
- Disclaimer: arithmetic calculation only; not financial, tax, legal, or investment advice.

## Input

- `start_value` (string, optional): max length 64; pattern `^-?(0|[1-9][0-9]*)(\.[0-9]+)?$`
- `end_value` (string, optional): max length 64; pattern `^-?(0|[1-9][0-9]*)(\.[0-9]+)?$`
- `total_return` (string, optional): max length 64; pattern `^-?(0|[1-9][0-9]*)(\.[0-9]+)?$`
- `years` (string, optional): max length 64; pattern `^-?(0|[1-9][0-9]*)(\.[0-9]+)?$`
- `start_date` (string, optional): max length 10; pattern `^[0-9]{4}-[0-9]{2}-[0-9]{2}$`
- `end_date` (string, optional): max length 10; pattern `^[0-9]{4}-[0-9]{2}-[0-9]{2}$`
- `basis` (one of "act-365f", "act-365.25", "act-act-isda", optional)
- `rate_scale` (integer, optional): min 0; max 12
- `rounding` (one of "half-up", "half-even", "half-down", "up", "down", "ceiling", "floor", optional)

## Output

- `cagr` (string, required): max length 64; pattern `^-?(0|[1-9][0-9]*)(\.[0-9]+)?$`
- `total_return` (string, required): max length 64; pattern `^-?(0|[1-9][0-9]*)(\.[0-9]+)?$`
- `years` (string, required): max length 64; pattern `^-?(0|[1-9][0-9]*)(\.[0-9]+)?$`
- `sub_year` (boolean, required)

## Limits

- max string bytes: 64
- max years: 1000

## Example

Request input:

```json
{
  "start_value": "10000",
  "end_value": "19000",
  "years": "3",
  "rate_scale": 4
}
```

Response:

```json
{
  "result": {
    "cagr": "0.2386",
    "total_return": "0.9000",
    "years": "3.0000",
    "sub_year": false
  }
}
```

## How to call it

### MCP

Connect `https://computefirst.net/mcp` ([setup](/docs#connect)), then call `execute` with:

```json
{
  "id": "growth-cagr-compute",
  "version": "1.0.0",
  "input": {
    "start_value": "10000",
    "end_value": "19000",
    "years": "3",
    "rate_scale": 4
  }
}
```

### HTTP (no key)

```sh
curl -X POST https://computefirst.net/v1/tools/growth-cagr-compute/versions/1.0.0/execute \
  -H "Content-Type: application/json" \
  -d '{"start_value":"10000","end_value":"19000","years":"3","rate_scale":4}'
```

The machine-readable contract is at [/v1/tools/growth-cagr-compute/versions/1.0.0](/v1/tools/growth-cagr-compute/versions/1.0.0).

### CLI

```sh
node cli.mjs run growth-cagr-compute 1.0.0 --input input.json --base-url https://computefirst.net
```

Get the client at [/clients/cli/](/clients/cli/).

## Related tools

- [Cashflow mirr](/tools/cashflow-mirr): MIRR of periodic cash flows from a finance rate and a reinvestment rate, with compounded and discounted totals.
- [Interest accrual compute](/tools/interest-accrual-compute): Simple or compound (periodic or continuous) interest over a term in years or a dated span with a day-count basis.
- [Bond yield from price](/tools/bond-yield-from-price): Yield to maturity of a fixed-coupon bond from its clean price, with accrued and dirty price (Excel YIELD / SIA).
- [Cashflow irr](/tools/cashflow-irr): IRR of equally spaced cash flows with every root reported, the chosen root named and no-solution cases signalled.
- [Cashflow npv](/tools/cashflow-npv): NPV of equally spaced cash flows, time-0 or Excel time-1, with inflow PV, outflow PV and profitability index.
- [Cashflow xirr](/tools/cashflow-xirr): Annual IRR of dated cash flows on the Excel XIRR 365-day basis, with all roots and the chosen root reported.