compare_spending_strategies
Compare four retirement spending strategies (fixed inflation-adjusted, constant dollar, Guyton-Klinger guardrails, Variable Percentage Withdrawal) over a simulated retirement period. Shows spending and portfolio trajectories.
run_projection
Run a full retirement projection for Canada or US. Projects year-by-year income, taxes, account balances, government benefits, and spending from now through life expectancy. Returns summary metrics (estate value, lifetime tax, portfolio depletion age, financial freedom age) and optional year-by-year rows. Supports singles and couples, multiple withdrawal strategies, RRSP meltdown / Roth conversion, pension splitting, SBLOC, real estate, and spending decline.
calculate_score
Calculate a Cinder Score (0-100) retirement readiness assessment. Evaluates survival risk, income coverage, tax efficiency, estate buffer, and savings rate. Returns an overall score with label (Roaring/Blazing/Kindling/Flickering/Cold) and detailed breakdown by component. Runs a full projection internally.
map_financial_data
Translate real-world financial data into Cinderfi projection inputs.
Pass account names and balances directly from YNAB, bank feeds, or spreadsheets — account types are auto-detected from names (RRSP, TFSA, 401k, Roth IRA, LIRA, HSA, etc.).
Returns a populated inputs object ready to pass directly to run_projection or run_full_analysis, plus a mapping report showing how each account was classified and what assumptions were made.
YNAB users: pass the sum of your non-transfer monthly categories as ynabMonthlyBudget. Bank users: pass annualSpending from 12 months of transactions.
run_full_analysis
Run a complete retirement analysis in one call — equivalent to opening the Cinderfi app with your financial data.
Returns:
- Retirement readiness score (0–100) with label and component breakdown
- Key metrics: financial freedom age, portfolio depletion age, lifetime tax, estate value
- Top insights and action items (account optimization, clawback risks, bracket opportunities)
- Year-by-year summary at retirement, peak, and end of life
- Upgrade prompts for Monte Carlo and optimization analysis
Ideal for agents that have already mapped user financial data via map_financial_data and want the full picture in a single tool call.
simulate_purchase
Show the retirement impact of a spending decision — a car, vacation, renovation, subscription, or any expense.
One-time purchases reduce liquid savings (drawn from non-reg → TFSA → RRSP in that order).
Recurring purchases increase annual spending permanently.
Returns: score delta, estate impact, retirement age shift, depletion risk change, and monthly retirement income delta.
Example: "What does a $60,000 car do to my retirement?" or "What if I add a $200/month subscription?"
simulate_windfall
Show the retirement impact of receiving money or increasing savings — an inheritance, bonus, tax refund, raise, or side income.
For one-time windfalls: optimally allocates across accounts in the right order (employer match → TFSA/Roth → FHSA/HSA → RRSP/IRA → non-reg). For couples (Pro), tests multiple allocation strategies across both spouses and picks the best by Cinder Score.
Returns: optimal allocation breakdown, RRSP tax refund estimate, score improvement, estate delta, and retirement age shift.
Example: "I'm getting a $50,000 inheritance — where should it go?" or "What if I save an extra $500/month?"
generate_insights
Generate personalized, actionable financial insights based on a retirement plan — RRSP/IRA ceiling analysis, contribution order, portfolio distribution, GIS clawback warnings, RRIF size, FHSA transfer deadlines, home equity concentration, and more.
Runs a full projection internally and surfaces the most important optimization opportunities for the plan. Each insight has a title, explanation, and severity (warning/info/success/ember).
Example: "Are there any red flags in my retirement plan?" or "What should I optimize first?"
run_monte_carlo
Run a Monte Carlo retirement simulation with randomized market returns. Produces probabilistic outcomes including success rate, percentile ranges for net worth/income/tax across all years, and estate value distribution. Pro tier only. CPU-intensive — runs may take 10-30 seconds.
optimize_withdrawal_order
Find the optimal retirement strategy by testing combinations of CPP/SS claiming age, RRSP meltdown / Roth conversion, and withdrawal ordering. Returns the top-5 strategies for each objective (minimize lifetime tax, maximize estate, maximize funded years). Pro tier only. CPU-intensive — runs may take 15-60 seconds.
optimize_pension_split
Find the optimal pension income split percentage between spouses to minimize combined federal + provincial tax. Sweeps 0–50% in 1% increments. Canada only. Requires Pro.
run_backtest
Test a retirement plan against every historical market window since 1871 using Robert Shiller's dataset (S&P 500 + 10-year Treasury real returns).
Returns success rate, median/worst/best outcomes, and how different spending strategies perform across all windows. Answers questions like "would my plan have survived the Great Depression?" or "does 100% equities outperform 80/20 historically?"
Modes: decumulation (retirement only), fullLifecycle (accumulation + retirement), accumulation (saving phase — did you reach FI?).
compare_scenarios
Compare 1–4 retirement scenario variants side-by-side against a base plan. Useful for answering "what if" questions — retire 5 years earlier, spend more, run bear-market assumptions, delay CPP, or enable RRSP meltdown.
Each scenario inherits all base inputs and overrides only the fields you specify. Returns a comparison table with Cinder Score, financial freedom age, estate value, lifetime tax, and depletion risk for every scenario vs the base.
Example: "Compare retiring at 60 vs 65 vs 70" or "What's the difference between 4% and 6% returns?"