Project a savings plan
project_savings_planRead-onlyIdempotent
What "X up front and Y a month for Z years" grows to, and how much of it is growth.
Handles the plan arithmetic that a lump-sum calculation gets wrong: only the
opening amount is invested for the whole span. The house conventions for timing
and compounding are fixed here.
Returns the central figure at the supplied rate and ``total_contributed``. No
range is returned: the outlook's band is stated at the model's horizon and does
not transfer to a plan's shorter dispersion horizon. ``dispersion_horizon_years``
under about ten means the figure is arithmetic at an assumed rate rather than an
expectation. No client profile is read.
``per_annum_by_year`` replaces ``per_annum`` with one rate per year, such as the
glide path rates ``describe_portfolio_outlook`` returns for a strategy with a
target date; ``per_annum`` in the result is then the constant rate that ends this
plan at the same value.
Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"years": "<years>"
},
"name": "project_savings_plan"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| years | Yes | ||
| cadence | No | monthly | |
| per_annum | No | What the money is assumed to earn each year, as a fraction — 0.06 for 6%. An assumption the caller supplies, not a forecast this tool makes. describe_portfolio_outlook gives it for a particular strategy; pass the unrounded `expected_return` from its figures (before fees, as its text says) rather than the one-decimal text, which moves a twenty-year end value by around 1%. Give this or per_annum_by_year. | |
| contribution | No | Paid in each period, at the cadence below. | |
| initial_amount | No | ||
| per_annum_by_year | No |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| years | Yes | ||
| growth | Yes | terminal_value minus total_contributed. | |
| cadence | Yes | ||
| currency | Yes | ||
| deposits | Yes | How many recurring deposits actually land. Full periods only, so thirteen months of a quarterly plan is four deposits and not four and a third. | |
| per_annum | Yes | The rate this was measured at. Not a forecast. | |
| contribution | Yes | Per period, at the cadence given. | |
| initial_amount | Yes | ||
| terminal_value | Yes | Projected value at the end, at the central rate. | |
| per_annum_by_year | No | The yearly rates given, when there were any; per_annum is then the constant rate that ends this plan at the same value, which depends on the plan's own timing of money. | |
| total_contributed | Yes | What the client actually pays in. Their own money, and the figure to put beside the projection — the difference between the two is the only part that is modelled. | |
| rate_duration_years | Yes | How much the end value moves when the rate does: a persistent 1pp on the rate is worth about this many percent on the terminal value. | |
| dispersion_horizon_years | Yes | The horizon a RANGE around this figure would have to be built at — not the span, and not the average holding period. Reported because no range is given: see the module docstring. Below about ten years the return model has essentially no predictive power, so a plan whose figure here is under that is not a basis for a decision. |