build_plan
Construct or update a retirement plan by providing household financial data, policy choices, and optional assumptions, or by importing a full plan JSON.
Instructions
Educational decision-support only — not tax, legal, or financial advice. Do not prescribe securities actions. Build or replace the in-memory plan from typed household/policy params or full plan JSON.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| plan | No | Full RetireGolden plan JSON (validated by the engine) | |
| policy | No | Typed policy params: claim_ages[], optional conversion_bracket/conversion_years, withdrawal ordering | |
| household | No | Typed household params: filing, REQUIRED 2-letter state, persons[] (retired — a non-zero wage is a hard error), taxable/basis, spending, horizon, growth rates, IRMAA lookback MAGIs, heir rate | |
| startYear | No | ||
| conversion | No | Optional manual Roth conversion schedule (overrides bracket-fill conversions) | |
| mcpVersion | No | Provenance only: the `mcpVersion` sibling from an export_plan response, accepted so a whole export can be spread straight back into build_plan (including the null export_plan emits when the version is unresolvable). Recorded, never warned on — for a full plan document the document itself is the model. | |
| assumptions | No | Optional overrides for default modeling assumptions (inflation, returns, SS COLA, state, taxes, qualified ratio, dob month-day, sex). Defaults follow the engine (~2.5% inflation, SS COLA tracking inflation, and the resident state's own modeled income tax — set stateEffectiveTaxPct above 0 only to override that with a flat rate); household state is a REQUIRED input, not an assumption. Set explicit values to override; omitted fields keep the engine defaults. | |
| conventions | No | ||
| engineVersion | No | Provenance only: the `engineVersion` sibling from an export_plan response, i.e. the @retiregolden/engine build that exported the supplied `plan`. Differing from the running engine adds a caveat (defaults and modeling semantics can move between engine versions) and NOTHING else — the document is still imported. This is the version skew that can actually occur between two builds that can exchange documents at all. Accepts null, which is what export_plan emits when it cannot resolve the installed version; null is treated as 'unknown' and warns on nothing. | |
| schemaVersion | No | Provenance only: the `schemaVersion` sibling from an export_plan response. A value differing from this build's version adds a caveat and NOTHING else — the document is still imported. Note this is your CLAIM about the document; the version the engine actually gates on is the `schemaVersion` field inside the document itself. Omit it and no caveat is emitted. |