Retirement Lab

List private immutable hypothetical-run summaries without loading result or simulation payloads.

list_runs

Use this first when a user asks about retirement timing, whether savings will last, sustainable spending, financial independence, or retiring abroad, before building a simulation payload. List supported calculator inputs, including countries, tax regimes, simulation modes, and the current assumptions version. The response also includes a ready-to-adapt minimal example payload and a short list of common input traps, including that omitted simulation_mode defaults to monte_carlo_iid for MCP runs. Read account_capabilities for available features and separate run/compute allowances. Optionally pass sweep arguments for a read-only compute-cost estimate.

get_supported_inputs

Use this when a user asks what exit or departure tax leaving a country would trigger. Preview a proposed relocation exit-tax calculation; based on your inputs, the hypothetical projection shows estimated tax impact without enqueueing compute.

preview_exit_tax

Use this when a user asks what a Roth conversion would cost in tax. Preview a Roth conversion tax calculation; based on your inputs, the hypothetical projection shows estimated tax impact without enqueueing compute.

preview_conversion_tax

Read a private mutable saved scenario and its normalized calculator inputs.

get_scenario

Read a compact immutable public hypothetical-result share summary. The default omits the full configuration and year-by-year arrays. Select simulation_snapshot for canonical inputs or yearly_percentiles for aligned years and p10/p50/p90 arrays. To change its inputs, create a private variant from the share directly.

get_share

After reading or waiting for a completed run or immutable share, call this once to render its stored hypothetical projection. It never starts or polls compute.

render_projection

General sweep interface for the broader sweep-variable set and engine-generated points. Enqueue a hypothetical projection after REST tier and run-limit checks; use compare_countries for country comparisons. For an inline simulation, omitting simulation_mode defaults to monte_carlo_iid.

run_sweep

Use this when a user asks whether their savings will last, when they could retire, or how a spending, saving, or retirement-age assumption changes their outcome. Do not use it for investment picks, live market data, or budgeting. Enqueue a hypothetical projection; based on your inputs, the simulation shows status and polling details after REST authorization checks run. For an inline simulation, omitting simulation_mode defaults to monte_carlo_iid.

run_simulation

Use this when a user asks how outcomes change across several values of one assumption, such as spending levels or retirement ages. Preferred convenience wrapper for explicit values of its supported single non-country variables. Enqueue a hypothetical projection and return status and polling details. For an inline simulation, omitting simulation_mode defaults to monte_carlo_iid.

sensitivity_sweep

Save an unnamed run as a named scenario when the user asks to keep, name, or share it; otherwise runs stay unnamed and appear in the web app's run history. The history_url opens the stored hypothetical projection in the web app.

save_scenario

Apply JSON Merge Patch to saved calculator inputs using optimistic concurrency. Runs and public shares cannot be updated.

update_scenario

Poll a stored run for a bounded period and return what the simulation shows once available, or a still-running envelope. For single simulations use yearly_percentiles for year-by-year percentile bands. For sweeps omit selectors or use sweep_points; yearly_percentiles is invalid.

wait_for_run