Retirement income

Retirement Income

A thin orchestration layer over the planfi MCP (https://ai.planfi.app/mcp/free). All decumulation math — withdrawal sequencing, RMD timing, Social Security actuarial breakeven, ACA subsidy cliffs, and estate-tax exemption logic — lives server-side. This skill only gathers inputs and calls the tools — it does not compute anything locally and bakes in no defaults of its own. Each tool applies its own server-side defaults and reports them back in a structured assumed_defaults[] array (read those back to the user — see Step 3). Read-only.

Step 0 — Make sure the planfi tools are connected

This skill uses these tools (may be namespaced, e.g. mcp__planfi__analyze_withdrawal_strategy): analyze_withdrawal_strategy, optimize_social_security, analyze_healthcare_bridge, analyze_estate_exposure, analyze_guaranteed_income, analyze_defined_benefit, analyze_annuity_products, analyze_bond_ladder, analyze_cash_ladder, analyze_ibond_ladder, analyze_long_term_care, analyze_spending_strategy, analyze_rmd, analyze_irmaa, analyze_medicare_enrollment, analyze_inherited_ira, analyze_disability_income, plus optional generate_financial_plan (for plan_id chaining + a share_url). Use whichever name your environment exposes (bare or mcp__planfi__-prefixed); below they are written bare.

If they're NOT available, tell the user to connect the MCP, then continue:

claude mcp add --transport http planfi https://ai.planfi.app/mcp/free

Try free, then add your key. The command above adds the free connector — https://ai.planfi.app/mcp/free (no key needed). Once you create an API key, add a new connector with the MCP url — https://ai.planfi.app/mcp — and authorize it with your key.

(On claude.ai: add a custom connector pointing at https://ai.planfi.app/mcp/free.)

Access — free for personal use. The planfi MCP is free to try (a small monthly allowance, no key needed). Heavy automated abuse forced us to add limits — but it stays free for personal use: email [email protected] and we'll send you a free API key, no charge. (Companies and commercial use have paid plans.) To use a key, pass it as an Authorization: Bearer pft_… header in your MCP client config.

Step 1 — (Optional but preferred) build a plan first to chain context + get a share link

Feed it into the forecast (not just plan_id chaining): generate_financial_plan now accepts guaranteed_income and bond_ladder directly as plan inputs, so they flow into net worth, FIRE %, and Monte-Carlo backtesting — the income floor reduces the portfolio-funded spend. Use the standalone analyze tools below for a focused what-if; pass the feature into the plan to see its effect on the whole household forecast.

If the user has (or wants) a full household model, call generate_financial_plan once and capture the returned plan_id. All six retirement-income tools accept { plan_id } (plus inline overrides), so they can resolve age, balances, spend, and income from the saved plan instead of you re-sending every figure. generate_financial_plan returns a share_url (planfi.app), and several of the decumulation tools also return their own share_url (see Step 3) — so a plan is one of several ways to give the user a sharable link.

This step is optional: every tool below runs from raw inputs too. Prefer the plan path when the session already has a model, when the user is asking more than one of these questions, or when they want a sharable artifact.

Engine facts to bake in: all decimals are fractions (24% → 0.24); all dollars are today's (real) dollars; brackets, exemptions, and IRMAA/ACA thresholds are approximate ~2026 values.

Step 2 — Route by intent

Pick the tool that matches what the user is asking. Pass { plan_id } when you have one; otherwise pass the raw fields below.

"What order should I draw down my accounts? / which account do I spend first in retirement — taxable, IRA, or Roth? / tax-efficient withdrawal sequence / should I tap my 401k or brokerage first? / how do I minimize taxes drawing down my portfolio?" → analyze_withdrawal_strategy

Always CALL analyze_withdrawal_strategy for these — do not answer from general knowledge or quote a "taxable-then-traditional-then-Roth" rule of thumb from memory. When the user gives the balances, spend, and age, run it and lead with its real output, THEN explain.

Tax-smart withdrawal sequencing across taxable → tax-deferred → Roth, RMD-aware, with the projected tax drag and portfolio longevity of the suggested order. REQUIRED: taxable_balance, traditional_balance, roth_balance, annual_spend, current_age. Optional: birth_year (RMD timing), years (drawdown horizon, default 30), filing_status (single | married_joint), growth_rate, inflation_rate, capital_gains_rate, enable_niit, state_flat_rate, tax_year, plan_id, overrides.

analyze_withdrawal_strategy({
  taxable_balance: 800000, traditional_balance: 1200000, roth_balance: 300000,
  annual_spend: 90000, current_age: 60
})

"When should I claim Social Security? / claim at 62 vs 67 vs 70 / what's my SS benefit if I retire early / how much will Social Security pay me / should I delay to 70 / spousal + survivor benefit / what if the trust fund gets cut?" → optimize_social_security

Always CALL optimize_social_security for these — do not answer from general knowledge or quote claiming rules of thumb from memory (the "8% per year of delay", "break-even in your late 70s", "claim at FRA" heuristics). When the user gives earnings history / a benefit estimate / a birth year, run it and lead with its real output, THEN explain.

Self-orchestrating: compares claiming ages (typically 62 / FRA / 70), returns the lifetime-value breakeven age and the recommended claim age. When given a full earnings history, it runs the complete SSA benefit pipeline instead of a rule of thumb: caps each year at that year's max taxable earnings, indexes to the National Average Wage Index at age 60, computes AIME (top-35 / 420), projects the 90/32/15 bend points to the eligibility year, floors the PIA to the nearest dime, compounds COLA from age 62, applies the early/delayed claiming adjustment, and can apply a trust-fund-depletion benefit cut.

Provide any one of: earnings_history (array of { year, earnings } — nominal annual covered earnings, runs the full pipeline), or aime (average indexed monthly earnings), or monthly_amount (your estimated benefit at FRA). Optional: fra (Full Retirement Age, default 67), claim_age (62–70, whole months allowed e.g. 66.5), birth_year (drives FRA + indexing/eligibility years), life_expectancy (default 90), cola_rate (forward COLA past last published, default 0.025), nawi_growth_rate (wage growth to project caps/bend points past published NAWI, default 0.045), trust_fund_cut ({ year, cut_pct } — discount benefits received at/after year, default cut 23%), spouse_aime / spouse_monthly_amount (for spousal/survivor coordination), tax_year, plan_id, overrides. Runs from sparse input — missing fields fall back to server defaults reported in assumed_defaults[] (see Step 3).

// Rule-of-thumb from an estimate:
optimize_social_security({ monthly_amount: 2800, fra: 67 })

// Full SSA pipeline from earnings history, with a trust-fund cut:
optimize_social_security({
  birth_year: 1964,
  earnings_history: [{ year: 1990, earnings: 45000 }, /* … */ { year: 2025, earnings: 168000 }],
  claim_age: 67,
  trust_fund_cut: { year: 2033, cut_pct: 0.23 }
})

"How do I cover health insurance before Medicare? / what will ACA / Obamacare cost if I retire at 58? / health insurance gap before 65 / can I keep my MAGI low enough for a subsidy? / COBRA vs marketplace when I retire early?" → analyze_healthcare_bridge

Always CALL analyze_healthcare_bridge for these — do not answer from general knowledge or quote subsidy rules of thumb from memory. When the user gives a retirement age and projected income, run it and lead with its real output, THEN explain.

ACA marketplace cost from the retirement age until Medicare at 65, including how premium subsidies move with MAGI (and the subsidy-cliff interaction with the withdrawal / Roth-conversion plan). REQUIRED: retirement_age, projected_annual_income (projected MAGI). Optional: household_size, state (2-letter code), spouse_age, current_hsa_balance, hsa_coverage_type (individual | family), annual_hsa_contribution, cobra_available, cobra_monthly_premium, cobra_months_remaining, annual_out_of_pocket, tobacco_user, marginal_tax_rate, medicare_eligibility_age (default 65), tax_year, plan_id, overrides.

analyze_healthcare_bridge({ retirement_age: 58, projected_annual_income: 45000 })

"Will my estate owe estate tax? / am I over the estate-tax exemption? / what happens when the exemption sunsets in 2026? / will my kids owe federal or state estate tax on my estate? / how much of my estate is taxable?" → analyze_estate_exposure

Always CALL analyze_estate_exposure for these — do not answer from general knowledge or quote the exemption amount from memory. When the user gives their asset values, run it and lead with its real output, THEN explain.

Self-orchestrating: projects the estate forward and compares it to the federal (and optionally state) exemption, returning the projected taxable estate and estimated estate tax. All inputs are optional (or resolved via plan_id): liquid_assets, real_estate_value, mortgage_principal, current_age (default 50), life_expectancy (default 90), federal_exemption_scenario (high | sunset, default sunset), federal_exemption_override, portability, estimated_growth_rate (default 0.05), married, state_code (2-letter; MA/NY/OR/WA have tables), tax_year, plan_id, overrides. Runs from sparse input.

analyze_estate_exposure({ liquid_assets: 12000000, real_estate_value: 2000000, current_age: 60, married: true })

"Should I take the pension lump sum or the monthly annuity? / is a SPIA worth it? / should I buy an immediate annuity for guaranteed income? / lump sum vs lifetime payments / does a QLAC make sense to defer RMDs? / annuity vs investing it myself?" → analyze_guaranteed_income

Always CALL analyze_guaranteed_income for these — do not answer from general knowledge or quote "annuities are a bad deal" / "take the lump sum" rules of thumb from memory. When the user gives the lump sum and monthly benefit, run it and lead with its real output, THEN explain.

Compares a guaranteed lifetime income stream against its alternative (a pension lump sum, or a DIY portfolio drawn at a safe withdrawal rate), returning the present-value comparison, the breakeven/longevity age, the real income floor it buys, the after-tax monthly income, and a recommendation. Handles both a pension election (lump sum vs lifetime monthly) and an annuity purchase (SPIA, or a QLAC with RMD-deferral on the premium). KEY PARAMS: decision_type ('pension_election' | 'spia' | 'qlac', default pension_election); lump_sum (the pension lump sum, or the annuity premium); monthly_benefit (the lifetime monthly payout). Optional: current_age (default 65), life_expectancy (default 90), filing_status (single | married_joint), payout_start_age (default 65), cola, discount_rate, expected_return (DIY return), desired_annual_spend (for income-floor % of spend), survivor_pct (joint-and-survivor fraction, e.g. 0.5), spouse_age, marginal_tax_rate, inflation_rate, other_taxable_income, tax_year, overrides, or plan_id to derive age/filing/income from a saved plan.

analyze_guaranteed_income({
  decision_type: 'pension_election', lump_sum: 600000, monthly_benefit: 3200,
  current_age: 63, life_expectancy: 90, filing_status: 'married_joint'
})

For the employer/government defined-benefit pension election specifically — the single-life vs joint-and-survivor (50%/75%/100%) reduction, the actuarial early-vs-normal claiming reduction, and the COLA vs non-COLA real-erosion view — use analyze_defined_benefit (next section); it owns the survivor and early-claiming actuarial detail. Use analyze_guaranteed_income here for the broader lump-vs-lifetime / SPIA / QLAC-vs-DIY-portfolio framing.

"Should I take my pension as a lump sum or monthly? / 50% vs 75% vs 100% survivor benefit? / claim my pension early or wait until normal retirement age? / does my pension have a COLA — what is it really worth over 25 years?" → analyze_defined_benefit

Always CALL analyze_defined_benefit for these — do not answer from general knowledge / quote rules of thumb from memory. When the user gives the numbers, run it and lead with its real output.

The full defined-benefit pension election for a worker with a traditional employer or government pension. It computes, all in real / today's dollars:

• Lump sum vs lifetime annuity — the present value of the monthly single-life stream (discounted by a real rate over life expectancy) vs the offered lump-sum cashout, the implied real IRR of taking the annuity, the break-even age at which cumulative annuity benefit overtakes the lump.
• Survivor / joint-and-survivor election — single-life vs 50% / 75% / 100% J&S: the reduced monthly benefit vs the spousal protection, and the break-even on the survivor's expected remaining years.
• COLA vs non-COLA — the real erosion of a fixed (non-COLA) pension over a 25–30 year retirement, and the present value adjusted for whether the pension has a cost-of-living adjustment.
• Early vs normal claiming — the actuarial reduction for claiming before normal retirement age. It also returns the real income floor the pension buys (survivor-adjusted monthly × 12) — which folds into the forecast like Social Security / guaranteed income, reducing the portfolio-funded spend — plus the after-tax monthly income and a recommended election with its deciding comparison. KEY PARAMS: singleLifeMonthly (the base single-life monthly benefit at the claim age). Optional: lumpSum (the offered cashout — enables the lump-vs-annuity branch), currentAge (default 65), claimAge (default 65), normalRetirementAge (default 65), lifeExpectancy (default 90), hasCola / colaRate / inflationRate (COLA + real-erosion view), discountRate (default 0.03), survivorOption (single | joint_50 | joint_75 | joint_100), survivorReducedMonthly, survivorLifeExpectancy, earlyReductionPerYear (plan-specific actuarial reduction; else SS-style), filingStatus (single | married_joint), otherTaxableIncome, tax_year, plan_id, overrides.

analyze_defined_benefit({
  singleLifeMonthly: 2000, lumpSum: 350000, currentAge: 65, claimAge: 65,
  lifeExpectancy: 90, discountRate: 0.03, hasCola: false
})

Cross-link: this is the pension-election actuarial companion to analyze_guaranteed_income — use analyze_defined_benefit for the survivor / early-claiming / COLA detail of an employer DB pension, and analyze_guaranteed_income for the broader SPIA / QLAC / DIY-portfolio framing of a guaranteed income stream. Pairs with analyze_withdrawal_strategy (the income floor reduces the market-funded draw) and optimize_social_security (coordinate the two guaranteed-income claiming decisions).

"Should I buy a fixed-indexed / RILA / MYGA / variable annuity (GLWB)? / is an indexed annuity a good deal? / how is a non-qualified annuity taxed / what's the exclusion ratio? / MYGA vs CD / should I 1035-exchange my old annuity? / annuity with a lifetime-income rider vs investing it?" → analyze_annuity_products

Always CALL analyze_annuity_products for these — do not answer from general knowledge or quote "annuities have high fees" / "indexed annuities are bad" rules of thumb from memory. When the user gives the premium and product type, run it and lead with its real output, THEN explain.

Evaluates accumulation-phase annuity products beyond a level/COLA immediate stream — a MYGA (multi-year guaranteed fixed rate), a FIA (fixed-indexed, cap / participation / spread crediting, principal-protected), a RILA (registered index-linked, buffer/floor downside), or a VA with a GLWB rider (variable subaccount + a guaranteed-lifetime-withdrawal rollup) — projects the accumulation value and effective credited rate, computes the non-qualified exclusion-ratio tax (IRC §72) and 1035 exchanges, and compares the product against keeping the money invested DIY, returning a recommendation. The server owns every crediting/fee/rate default and reports them in assumed_defaults[] — pass only what the user states.

analyze_annuity_products({ product_type: 'fia', premium: 250000, current_age: 60, payout_start_age: 67, cap_rate: 0.09, is_qualified: false })

This is the deferred/accumulation companion to analyze_guaranteed_income (which handles the immediate SPIA/QLAC/pension-election decision) and pairs with analyze_withdrawal_strategy (how the annuity income fits the broader tax-smart drawdown order).

"Can I build a guaranteed income floor / bond ladder for the first N years? / build me a Treasury or TIPS ladder / how much do I need in bonds to cover my first 10 years of spending? / TIPS ladder for sequence-of-returns protection / duration-match my early retirement spend?" → analyze_bond_ladder

Always CALL analyze_bond_ladder for these — do not answer from general knowledge or sketch a ladder from memory. When the user gives the annual spend and number of years, run it and lead with its real output, THEN explain.

Builds a Treasury/TIPS ladder to floor the first N years of retirement spending — cost today, per-rung maturities and face values, real-vs-nominal coverage, and what % of desired spend it guarantees. A direct complement to analyze_withdrawal_strategy: the ladder floors the first N years (sequence-of-returns protection), while the withdrawal strategy handles the market-funded remainder. Server owns all yield / inflation defaults and surfaces them via assumed_defaults[]. REQUIRED: annual_spend, years. Optional: ladder_type (tips | nominal | mixed), real_yield, inflation_rate, existing_income_annual, nominal_yield, swr, filing_status, state_flat_rate, current_age, start_year, tax_year, or plan_id.

analyze_bond_ladder({ annual_spend: 60000, years: 10, ladder_type: 'tips' })

"How do I ladder CDs / I-Bonds / EE bonds for safe near-term cash? / build me a CD ladder / brokered vs bank CDs / are EE bonds worth the 20-year double / how do I park near-term cash safely and beat inflation? / what's my CD early-withdrawal penalty?" → analyze_cash_ladder

Always CALL analyze_cash_ladder for these — do not answer from general knowledge or quote CD/APY rules of thumb from memory. When the user gives the annual need and number of years, run it and lead with its real output, THEN explain.

The mass-market complement to analyze_bond_ladder: instead of brokerage Treasuries/TIPS, this ladders the FDIC-insured and savings-bond vehicles real conservative savers actually use — CD ladders (brokered vs bank, early-withdrawal penalty, callable-call/reinvestment risk), I-Bonds (fixed + variable composite rate, $10k annual purchase cap, federal tax-deferral + state exemption), and Series EE bonds (the 20-year guaranteed double). Returns per-rung CD maturities, the blended APY, annual maturing principal (the liquidity story), the savings-bond values at your hold horizon (with over-cap flags), the FDIC-insured flag, and a tax block that surfaces the asymmetry — CD interest is annually taxable and state-taxable, while Treasury/savings-bond interest is state-exempt and federally tax-deferred until redemption. Use it for the near-term safe-cash sleeve; use analyze_bond_ladder for the brokerage Treasury/TIPS floor. REQUIRED: annual_need, years. Optional: vehicle (cd | ibond | ee | mixed), cd_type (brokered | bank, default brokered), cd_yield, callable, early_withdrawal_penalty_months, ibond_fixed_rate, ibond_variable_rate, ee_doubling, annual_purchase_cap, inflation_rate, existing_income_annual, filing_status, state_flat_rate, swr, start_year, current_age, tax_year, or plan_id.

analyze_cash_ladder({ annual_need: 40000, years: 5, vehicle: 'cd', cd_type: 'brokered' })

"Build me an I-bond ladder / how much can I buy in I-bonds this year / I-bonds vs TIPS after tax / what's my early-redemption penalty / TreasuryDirect $10k limit across me and my spouse / can I beat inflation with Series I bonds?" → analyze_ibond_ladder

Always CALL analyze_ibond_ladder for these — do not answer from general knowledge / quote rules of thumb from memory (the $10k cap, the composite-rate formula, the 12-month lockup, the 3-months-interest penalty, the I-bond-vs-TIPS tax-deferral tradeoff). When the user gives the numbers, run it and lead with its real output: the per-year purchase schedule under the cap, the projected composite-rate accrual and redemption value net of any early penalty, the I-bond-vs-TIPS after-tax-real comparison, and the recommended purchase plan.

This is the I-bond / TIPS-specific ladder planner — distinct from analyze_cash_ladder and analyze_bond_ladder because it models the deterministic cap / lockup / penalty / phantom-tax math those nominal engines do not:

• Purchase cap — the hard $10,000 per person per calendar year TreasuryDirect electronic limit, plus an extra $5,000 in paper I-bonds via a federal tax refund; models a multi-year ladder accumulating under the annual cap across 1 or 2 spouses (flags any over-cap amount).
• Composite rate — fixed rate + (2 × semiannual inflation) + (fixed × semiannual inflation), reset every 6 months; projects accrual from a supplied fixed rate + assumed inflation.
• Lockup + penalty — the 12-month fully-locked minimum hold, and the 3-months-of-interest early-redemption penalty if redeemed before 5 years (no penalty after 5).
• I-bonds vs TIPS — TIPS principal adjusts with CPI and pay a real coupon with no purchase cap, but are taxed annually on phantom inflation accruals (vs I-bonds tax-DEFERRED until redemption); the tool compares after-tax real yield and liquidity and names a winner.
• Tax — I-bond interest is federal-taxable (deferred), state-tax-exempt, and optionally federally tax-free if used for qualified education (income-limited, with a MAGI phaseout). REQUIRED: annualPurchaseTarget, holdYears. Optional: ladderYears, spouses (1–2), ibondFixedRate, assumedInflation, redeemAtYear (triggers penalty/lockup math), tipsRealYield, tipsCoupon, usedForQualifiedEducation, filingStatus (single | married_joint), otherTaxableIncome, stateFlatRate, tax_year, plan_id, overrides.

analyze_ibond_ladder({ annualPurchaseTarget: 10000, holdYears: 5, spouses: 1, ibondFixedRate: 0.013, assumedInflation: 0.0344 })

Cross-link: use analyze_ibond_ladder for the I-bond/TIPS inflation-protected sleeve (cap, lockup, penalty, phantom-tax); analyze_cash_ladder for the broader CD / EE / I-bond near-term safe-cash mix; and analyze_bond_ladder for the brokerage Treasury/TIPS floor that funds the first N years of spend.

"Will long-term care wipe out my plan? / should I self-insure or buy an LTC policy? / is long-term-care insurance worth it? / what will a nursing home / assisted living cost my plan? / hybrid life-LTC policy vs self-funding / will LTC costs bankrupt my surviving spouse?" → analyze_long_term_care

Always CALL analyze_long_term_care for these — do not answer from general knowledge or quote "LTC insurance is a waste" / "you need $X" rules of thumb from memory. When the user gives their age and care assumptions, run it and lead with its real output, THEN explain.

Models expected long-term-care cost exposure (custodial home care, assisted living, or nursing home) and compares self-insure vs a traditional LTC policy vs a hybrid (life/LTC) policy on an after-tax present-value basis — including the tail-risk note (self-insure can win the expected case but lose at P90) and the impact on a surviving spouse's plan. The largest uninsured late-life spending shock. Self-orchestrates from sparse input — server fills a care-cost table by care_type, care probability, duration, and start age, all surfaced in assumed_defaults[]. KEY PARAMS: current_age; strategy (self_insure | traditional | hybrid); care_type (custodial_home | assisted_living | nursing_home). Optional: care_start_age (default 84), care_duration_years (default 3), annual_care_cost_today (else from the care_type table), probability_need_care (default 0.70), life_expectancy, discount_rate, filing_status, married, survivor_spending_factor, a policy block (annual_premium, premium_pay_years, annual_benefit, benefit_period_years, elimination_period_days, inflation_protection_pct, return_of_premium_or_death_benefit), tax_year, plan_id, overrides.

analyze_long_term_care({ current_age: 60, care_type: 'assisted_living', strategy: 'self_insure', married: true })

"How much should I spend each year? / is the 4% rule safe for me? / should I use Guyton-Klinger guardrails or VPW? / dynamic vs fixed withdrawal rate / how much can I safely withdraw / does spending decline as I age (the spending smile)? / bucket strategy so I don't sell stocks low?" → analyze_spending_strategy

Always CALL analyze_spending_strategy for these — do not answer from general knowledge or quote the "4% rule" from memory. When the user gives the portfolio balance, spend, age, and horizon, run it and lead with its real output, THEN explain.

A spending-rate engine that layers on top of the account-order question (analyze_withdrawal_strategy): it decides how much to pull each year, not which account to pull it from. Compares dynamic spending rules against a static 4% SWR baseline — Guyton-Klinger guardrails (raise spending in prosperity years, cut it when the withdrawal rate drifts above a capital-preservation band), VPW (variable percentage withdrawal — spend a horizon-based fraction that rises as the horizon shrinks), the spending smile (Blanchett — real spending declines through the go-go years, then ticks back up late for health costs), and a bucket+buffer strategy (hold N years of cash, spend it in down markets so you never sell equities low, refill in up years). Reports the year-by-year schedule, spend volatility vs flat 4%, the number of raises/cuts, RMD-floor years, depletion risk, and the extra lifetime spending vs the constant-4% comparator. Tax-agnostic in v1 — pair with analyze_withdrawal_strategy for the tax-smart account order and run_backtesting for sequence risk. KEY PARAMS: portfolio_balance, annual_spend, current_age, years. Optional: strategy (guardrails | vpw | smile | bucket | constant_pct), guardrail bands, raise/cut percentages, birth_year (RMD floor), filing_status, tax_year, plan_id, overrides.

analyze_spending_strategy({ portfolio_balance: 1500000, annual_spend: 60000, current_age: 62, years: 30 })

"Will my RMDs cause a tax torpedo / how much Roth-conversion runway do I have before 73 or 75? / how big will my required minimum distributions be? / when do RMDs start for me? / will my RMDs push me into a higher bracket? / how many years do I have to convert before RMDs hit?" → analyze_rmd

Always CALL analyze_rmd for these — do not answer from general knowledge or quote the RMD start age / divisor from memory. When the user gives the traditional balance and age, run it and lead with its real output, THEN explain.

Projects required minimum distributions on the traditional balance: the SECURE-2.0 RMD start age (73 or 75, derived from birth year), the conversion-runway years before RMDs begin, the first RMD amount/divisor, the lifetime RMD total and tax, the peak-RMD year, and a tax-torpedo flag (whether the first RMD pushes your marginal rate above where it would be without it) plus a year-by-year schedule. All values are real / today's dollars. This is the why behind a Roth-conversion ladder — the runway years are the low-income window to convert before RMDs stack. REQUIRED: traditional_balance, current_age. Optional: birth_year (drives 73 vs 75), filing_status (single | married_joint), other_taxable_income (for the torpedo / marginal-rate math), growth_rate (REAL, default 0.05), life_expectancy (default 92), tax_year.

analyze_rmd({ traditional_balance: 1000000, current_age: 65, birth_year: 1961, other_taxable_income: 50000 })

"I inherited an IRA — how do I empty it over 10 years? / Do I have to take annual RMDs on an inherited IRA? / smartest way to draw down a beneficiary IRA / inherited Roth IRA under the SECURE Act?" → analyze_inherited_ira

Always CALL analyze_inherited_ira for these — do not answer from general knowledge or quote the 10-year rule from memory. When the user gives the balance (and ideally whether the original owner had started RMDs), run it and lead with its real output: the required-vs-optional annual-RMD determination, the recommended schedule, the per-year tax table, and total tax saved vs the naive year-10 lump.

This is the post-SECURE-Act drawdown decision for a non-spouse beneficiary of an inherited IRA:

1. Annual-RMD determination — annual single-life RMDs are required in years 1–9 only when the original owner had already reached their required beginning date (owner_died_pre_rbd: false, traditional); pre-RBD or Roth means no annual requirement, but the full balance must still be emptied by Dec 31 of year 10.
2. Lump-vs-even-vs-bracket-fill — quantifies total federal tax across the 10-year window for year-10 lump vs even 10-year spread vs a bracket-fill schedule (withdraw up to the top of the beneficiary's marginal bracket each year), and recommends the lowest-tax schedule.
3. Year-10 cliff — deferring everything to year 10 can spike one year into the top bracket + NIIT
   • IRMAA; the tool surfaces those tripped surcharges as warnings.

REQUIRED: inherited_balance. Optional: account_type (traditional | roth), owner_died_pre_rbd (drives the annual-RMD determination), beneficiary_age, year_of_death, other_taxable_income, filing_status (single | married_joint), growth_rate (default 0.05), tax_year.

analyze_inherited_ira({ inherited_balance: 500000, account_type: 'traditional', owner_died_pre_rbd: true, beneficiary_age: 55, other_taxable_income: 90000, filing_status: 'single' })

Cross-link: a year-10 lump lifts MAGI two years later, so pair with analyze_irmaa to check the Medicare surcharge that the cliff triggers; and with analyze_advanced_taxes / analyze_estimated_taxes to size the quarterly payments on each year's distribution.

"What Medicare IRMAA surcharge will my income trigger / how do I stay under the next cliff? / will my income raise my Medicare premiums? / what's the IRMAA threshold for my MAGI? / how much headroom before the next IRMAA bracket? / does a Roth conversion push me over an IRMAA cliff?" → analyze_irmaa

Always CALL analyze_irmaa for these — do not answer from general knowledge or quote the IRMAA thresholds from memory. When the user gives their MAGI, run it and lead with its real output, THEN explain.

Maps MAGI to the Medicare IRMAA tier: the annual and monthly Part B/D surcharge, the landed tier index, the first surcharge threshold, the next cliff threshold with headroom to it, and the step-up in surcharge if you cross it. Reflects the 2-year MAGI lookback (the income tax year is two years before the Medicare year) and that for married_joint the household MAGI covers both spouses. Pairs with analyze_rmd / analyze_roth_conversion — RMDs and conversions both raise MAGI into the next IRMAA cliff. REQUIRED: magi. Optional: filing_status (single | married_joint), current_age (default 65), tax_year.

analyze_irmaa({ magi: 150000, filing_status: 'single' })

"When do I have to sign up for Medicare? / will I owe a late-enrollment penalty? / I'm turning 65 — what's my enrollment window? / I'm still working at 65 on my employer plan, do I need Part B? / I'm on COBRA, does that count? / I missed my Medicare sign-up, how much will it cost me forever? / when does my Special Enrollment Period / Medigap window close? / do I have to stop HSA contributions before Medicare?" → analyze_medicare_enrollment

Always CALL analyze_medicare_enrollment for these — do not answer from general knowledge / quote the "7-month window", "10% per year", or "COBRA counts" rules of thumb from memory. When the user gives the numbers (age / months since 65, months uncovered, coverage type), run it and lead with its real output: the enrollment-window status, whether a penalty applies and its permanent monthly + lifetime dollar cost (Part B and Part D), the creditable-coverage determination, the SEP deadline, and the Medigap guaranteed-issue deadline.

This is the enrollment-TIMING and late-PENALTY side of Medicare — distinct from analyze_irmaa, which owns the income-based surcharge. It computes:

• Initial Enrollment Period (IEP) — the 7-month window (3 months before through 3 months after the 65th-birthday month); flags whether you're inside it (before_iep / inside_iep / iep_closed / in_sep).
• Part B late penalty — a PERMANENT 10% surcharge on the Part B base premium for each full 12-month period eligible-but-unenrolled without creditable coverage (only full years count), as a monthly and lifetime-dollar figure.
• Part D late penalty — 1% of the national base beneficiary premium per uncovered month, also permanent.
• Creditable-coverage test for working past 65 on an employer plan or COBRA — COBRA is NOT creditable for Part B (the penalty still accrues), and the HSA interaction (stop HSA contributions 6 months before Medicare enrollment).
• Special Enrollment Period (SEP) — the 8-month window after losing employer coverage that avoids the penalty, with the deadline.
• Medigap — the one-time 6-month guaranteed-issue window opening at Part B enrollment.

REQUIRED: none (defaults to age 65). Optional: current_age, birth_month, months_eligible_unenrolled_part_b, months_eligible_unenrolled_part_d, has_creditable_coverage, coverage_type (employer | cobra | marketplace | none), employer_coverage_end_months_ago, contributing_to_hsa, enrolled_in_part_b, part_b_enrollment_months_ago, tax_year, plan_id.

analyze_medicare_enrollment({ current_age: 66, months_eligible_unenrolled_part_b: 30, has_creditable_coverage: false })

Cross-link: after settling enrollment timing, run analyze_irmaa to size the income-based surcharge, and analyze_healthcare_bridge for the pre-65 coverage that bridges to Medicare.

"What happens to my income if I become disabled? / how much will SSDI pay me? / what's my disability protection gap? / does my group LTD plus SSDI replace enough of my paycheck? / is my disability benefit taxable? / stress-test losing my income to disability" → analyze_disability_income

Always CALL analyze_disability_income for these — do not answer from general knowledge / quote rules of thumb ("SSDI replaces ~40%", "60% LTD") from memory. When the user gives the numbers (their AIME or earnings, spending, and group-LTD %), run it and lead with its real output: the estimated monthly SSDI, the combined SSDI + LTD after the dollar-for-dollar offset, the after-tax replacement ratio for each premium-payer case, the elimination-period and Medicare-bridge gap costs, the SGA cap, and the protection shortfall.

Quantifies the working-age disability income shock and protection gap. It computes, all in today's dollars:

• SSDI benefit estimate — the primary insurance amount from AIME via the bend-point formula; SSDI pays the full un-reduced PIA and auto-converts to the retirement benefit at full retirement age with no reduction.
• Elimination period + Medicare bridge — the 5-month wait before benefits start and the further 24-month wait before Medicare, each priced as an out-of-pocket coverage-gap cost.
• SGA earnings cap — benefits stop if earned income exceeds the substantial-gainful-activity threshold ($1,620/mo, $2,700/mo if blind in 2026).
• Group LTD coordination — own-occ vs any-occ definitions; the LTD benefit is offset dollar-for-dollar by SSDI, so the combined benefit ≈ the LTD target %, not LTD + SSDI.
• Taxability flip — employer-paid LTD premiums make the benefit taxable; employee-paid (after-tax) premiums make it tax-free; returns the after-tax replacement ratio for both.

REQUIRED: aime. Optional (fall back to plan/defaults): annual_salary, household_annual_spend, filing_status, group_ltd_percent, ltd_premiums_employer_paid, ltd_definition, target_replacement_ratio, ssdi_taxable, blind, earned_income_while_disabled, monthly_healthcare_cost, tax_year, plan_id.

analyze_disability_income({ aime: 6000, annual_salary: 108000, household_annual_spend: 72000, group_ltd_percent: 0.60, ltd_premiums_employer_paid: true, filing_status: 'single' })

Cross-link: pair with analyze_insurance_needs for the broader life + long-term-disability coverage sizing (this tool quantifies the SSDI + group-LTD income gap; that one sizes the policy to close it), and with optimize_social_security — the SSDI benefit auto-converts to the retirement benefit at the same un-reduced PIA at full retirement age, so the disability and Social Security claiming decisions share the same earnings record.

Step 3 — Surface results honestly

For whichever tool you called:

• Lead with the headline — the recommended drawdown order + tax drag / longevity; the recommended Social Security claim age + breakeven age; the annual ACA bridge cost (net of subsidy) to age 65; the projected taxable estate + estimated estate tax; or — for analyze_guaranteed_income — the present-value comparison (lifetime income vs lump-sum/premium) with the net advantage, the breakeven age vs your longevity age, the real income floor it buys (and what % of your desired spend that covers), and the lump-sum-vs-lifetime / buy-annuity-vs-keep-invested recommendation.
• Read back assumed_defaults[]. Every one of these tools returns a structured assumed_defaults[] array of { field, assumed_value, note } objects naming each input the caller omitted and the default the server applied (e.g. FRA 67, life expectancy ~90, growth ~5%, filing status, RMD age, exemption scenario). Surface each one so the user can correct any assumption. (disclosures.key_assumptions is separate static prose describing the model's methodology — you can mention it, but the per-field defaults to confirm live in assumed_defaults[].)
• Honor disclosures.not_advice (a boolean) — present as planning estimates, not financial / tax advice.
• Follow next_actions[] — each is { tool, why, prefilled_args } (carrying { plan_id } when available). Use the server-suggested chains rather than guessing. The actual edges among these tools: analyze_withdrawal_strategy → analyze_guaranteed_income / analyze_bond_ladder / analyze_long_term_care / analyze_relocation; analyze_guaranteed_income → analyze_withdrawal_strategy / optimize_social_security / analyze_bond_ladder / generate_financial_plan; analyze_bond_ladder → analyze_withdrawal_strategy / optimize_social_security / analyze_cash_ladder / generate_financial_plan; analyze_cash_ladder → analyze_bond_ladder / analyze_withdrawal_strategy (the safe-cash sleeve pairs with the brokerage Treasury/TIPS floor and the market-funded drawdown); analyze_long_term_care → analyze_insurance_needs / analyze_survivor_stress_test / analyze_guaranteed_income / analyze_bond_ladder; analyze_rmd → analyze_roth_conversion (spend the runway years) / analyze_irmaa (RMDs lift MAGI into the next surcharge cliff) / analyze_withdrawal_strategy; analyze_irmaa → analyze_rmd / analyze_roth_conversion (both move MAGI relative to the cliff); analyze_medicare_enrollment → analyze_irmaa (size the income-based surcharge once enrollment timing is settled) / analyze_healthcare_bridge (pre-65 coverage that bridges to Medicare); analyze_inherited_ira → analyze_irmaa (the year-10 lump lifts MAGI two years later) / analyze_advanced_taxes / analyze_estimated_taxes (size the quarterly tax on each distribution). (optimize_social_security, analyze_healthcare_bridge, and analyze_estate_exposure currently emit no outgoing next_actions edges.) analyze_spending_strategy (the spend-amount question) is the natural companion to analyze_withdrawal_strategy (the account-order question) and to run_backtesting (sequence-of-returns risk on the chosen rule).
• For a share link: optimize_social_security always returns a share_url; analyze_estate_exposure, analyze_withdrawal_strategy, analyze_healthcare_bridge, analyze_guaranteed_income, analyze_bond_ladder, analyze_long_term_care, and analyze_medicare_enrollment return a share_url only when you pass a plan_id that resolves a plan. Surface whichever share_url the tool returns; otherwise run generate_financial_plan (Step 1) for one.

Recommended call sequence (typical session)

1. (preferred) generate_financial_plan → capture plan_id (+ share_url).
2. Route by intent → one of the six tools (with { plan_id } or raw fields).
3. Read back the headline + each entry in assumed_defaults[].
4. Follow next_actions[] — e.g. withdrawal order chains to a guaranteed-income / bond-ladder floor or a retirement relocation; guaranteed income chains to the withdrawal order, Social Security timing, or generate_financial_plan. The tax-optimizer skill (Roth conversions in low-income gap years) is a natural manual follow-on even where no server edge exists.

Fictional examples

1. "I'm 60 retiring with $800k taxable, $1.2M traditional, $300k Roth and need $90k/yr — what's the tax-smart drawdown order?" → analyze_withdrawal_strategy({ taxable_balance: 800000, traditional_balance: 1200000, roth_balance: 300000, annual_spend: 90000, current_age: 60 }). Lead with the recommended sequence and its tax drag / portfolio longevity; follow the tool's next_actions[] (e.g. building a guaranteed-income / bond-ladder floor) and offer the tax-optimizer skill for Roth conversions in the pre-RMD gap years. Read back each assumed_defaults[] entry (e.g. years 30, growth rate 5%, filing status, RMD start age 73).

2. "Retiring at 58 with $45k projected income — what will ACA coverage cost me until Medicare at 65?" → analyze_healthcare_bridge({ retirement_age: 58, projected_annual_income: 45000 }). Lead with the net annual premium after subsidy and how it changes if MAGI rises; flag the subsidy-cliff interaction with any Roth conversions / withdrawals, and offer analyze_withdrawal_strategy to keep MAGI in the subsidy band. Read back each assumed_defaults[] entry (e.g. household size 1, state CA, marginal tax rate 24%, Medicare eligibility age 65).

3. "My employer is offering a $600k lump sum or $3,200/mo for life — which should I take? And would a SPIA make more sense?" → analyze_guaranteed_income({ decision_type: 'pension_election', lump_sum: 600000, monthly_benefit: 3200, current_age: 63 }). Lead with the PV comparison (lifetime monthly vs the lump sum) and the net advantage, then the breakeven age vs the assumed longevity age, and the real income floor the monthly buys. Read back each assumed_defaults[] entry (discount rate, expected DIY return, life expectancy, payout start age). To compare a SPIA instead, re-run with decision_type: 'spia', lump_sum as the premium, and monthly_benefit as the annuity payout; for a QLAC use decision_type: 'qlac' to see the RMD deferred on the premium. Follow the tool's next_actions[] (withdrawal order, Social Security timing, or generate_financial_plan for a sharable link), and consider the tax-optimizer skill — turning on pension income shifts your marginal bracket and changes your Roth-conversion room in the pre-RMD gap years.

4. "We're 60, married, and terrified long-term care will wipe out whoever's left — should we self-insure or buy a policy?" → analyze_long_term_care({ current_age: 60, care_type: 'assisted_living', strategy: 'self_insure', married: true }). Lead with the expected after-tax PV cost exposure and the three-way comparison (self-insure vs traditional vs hybrid), then the tail-risk note (self-insure may win the expected case but lose at P90) and the surviving-spouse impact. To price a policy, re-run with strategy: 'traditional' (or 'hybrid') and a policy block. Follow the tool's next_actions[] — sizing life/disability coverage (analyze_insurance_needs), stress-testing the survivor (analyze_survivor_stress_test), or pre-funding the care with a analyze_guaranteed_income floor or a analyze_bond_ladder. Read back each assumed_defaults[] entry (e.g. care start age 84, duration 3 yrs, probability of needing care 0.70, the care-cost table value). Neighboring features outside this skill: analyze_estate_exposure (in this skill) and analyze_healthcare_bridge for the pre-Medicare gap.

5. "I'm 65 with $1M in a traditional IRA and about $50k of other income — will my RMDs cause a tax torpedo, and how many years do I have to convert before they hit?" → analyze_rmd({ traditional_balance: 1000000, current_age: 65, birth_year: 1961, other_taxable_income: 50000 }). Lead with the RMD start age (73 or 75 from birth year) and the conversion-runway years before it, then the first RMD amount/divisor, lifetime RMD tax, and whether tax_torpedo.triggered is true (the first RMD pushing your marginal rate up). The runway years are the low-income window for a Roth-conversion ladder — hand off to the tax-optimizer skill (analyze_roth_conversion) to fill that bracket, and run analyze_irmaa to check the RMDs don't push MAGI over a Medicare surcharge cliff. Read back each assumed_defaults[] entry (growth rate, life expectancy 92, filing status).

6. "My retirement MAGI lands around $150k single — what Medicare IRMAA surcharge does that trigger, and how much headroom before the next cliff?" → analyze_irmaa({ magi: 150000, filing_status: 'single' }). Lead with the annual/monthly Part B/D surcharge and the landed tier, then the next-cliff threshold and the headroom to it (and the step-up if you cross it). Remind them of the 2-year lookback (this Medicare year reflects income two years back) and that for married_joint the surcharge applies to both spouses. Then check analyze_rmd / the tax-optimizer skill — RMDs and Roth conversions both raise MAGI toward the cliff, so plan conversions to stay just under it.

7. "My pension offers a $350k lump sum or $2,000/mo for life with no COLA, I'm 65 — which wins, and should I take the 100% survivor option for my spouse?" → analyze_defined_benefit({ singleLifeMonthly: 2000, lumpSum: 350000, currentAge: 65, claimAge: 65, lifeExpectancy: 90, discountRate: 0.03, hasCola: false }). Lead with the PV comparison (lifetime annuity vs the lump sum) and its net advantage, the implied real IRR of taking the annuity, and the break-even age; then the non-COLA real-erosion view (what the fixed $2,000/mo is worth in year 25), and — re-running with survivorOption: 'joint_100' (+ survivorReducedMonthly if the plan states it) — the survivor break-even vs the spouse's expected remaining years. Note the real income floor it buys folds into the forecast like Social Security. Read back each assumed_defaults[] entry (discount rate, life expectancy, derived survivor reduction, inflation rate). For the broader SPIA/QLAC-vs-DIY framing of any guaranteed stream, pair with analyze_guaranteed_income; coordinate the claiming with optimize_social_security.

(All seven examples use fictional figures — never reuse a real user's numbers in documentation.)

Notes

• All decimals are fractions; all dollars are today's (real) dollars; brackets / exemptions / IRMAA / ACA thresholds are ~2026.
• analyze_withdrawal_strategy (balances + spend + age) and analyze_healthcare_bridge (retirement_age + projected_annual_income) have REQUIRED inputs — ask for them before calling. optimize_social_security and analyze_estate_exposure self-orchestrate from sparse input.
• Pass { plan_id } to reuse a saved household model; pass overrides (or any inline field) to shallow-override on top of it. All six tools accept plan_id and overrides.
• All six tools emit a structured assumed_defaults[] array of { field, assumed_value, note } — read those back to the user to confirm or correct each silent default. disclosures.key_assumptions is separate static methodology prose and disclosures.not_advice is a boolean.
• Share links: optimize_social_security always returns a share_url; analyze_estate_exposure, analyze_withdrawal_strategy, analyze_healthcare_bridge, analyze_guaranteed_income, and analyze_bond_ladder return one only when a passed plan_id resolves a plan. Otherwise chain generate_financial_plan.
• Decumulation is tax-driven — the natural neighbor is the tax-optimizer skill (Roth conversion ladders, multi-year tax timing) during low-income gap years.
• Two distinct decumulation questions pair up: analyze_withdrawal_strategy answers the account order (which account to draw, tax-smart), while analyze_spending_strategy answers the spend amount (Guyton-Klinger guardrails, VPW, spending smile, bucket+buffer vs a static 4% SWR). Run both, then run_backtesting to stress the chosen spending rule against historical sequence risk.
• Not financial or tax advice. Planning estimates only.