@nestpilot/mcp-app 1.0.0

package/skills/tools/optimize_roth_conversion.md

@@ -0,0 +1,107 @@
+# Tool Skill: optimize_roth_conversion
+
+Optimizes Roth conversion strategies for retirement accounts. Analyzes tax brackets, required
+minimum distributions (RMDs), and projected income to recommend a multi-year Roth conversion
+ladder that minimizes lifetime tax burden.
+
+## When to Suggest Roth Conversions
+
+Use `optimize_roth_conversion` when the user:
+- Is in a low-income year (between jobs, early retirement, before Social Security starts)
+- Has a pre-RMD window (ages 60-72) where conversions can reduce future forced distributions
+- Has a bracket gap: current income is below their expected retirement tax bracket
+- Asks "How much should I convert to Roth each year?"
+- Wants to minimize lifetime taxes through strategic conversions
+- Asks about filling tax brackets or building a Roth conversion ladder
+
+Do NOT use for general tax questions — use `coach` instead.
+Do NOT use for basic forecasting — use `run_forecast` instead.
+
+## Questions to Ask the User
+
+Before calling the tool, gather these inputs:
+
+### Required
+- **Filing status**: SINGLE, MFJ (Married Filing Jointly), MFS (Married Filing Separately), HOH (Head of Household)
+- **Current age** and **target retirement age**
+- **Traditional IRA / 401k balance** (total pre-tax retirement account balance)
+- **Annual income** (current gross income from employment)
+
+### Optional but Valuable
+- **Other income sources** (pensions, rental income, part-time work)
+- **Expected Social Security benefit** (annual amount)
+- **Roth IRA balance** (existing Roth assets)
+- **Conversion policy preference**: conservative (fill 12% bracket), moderate (fill 22%), aggressive (fill 24%)
+
+If the user doesn't specify a conversion policy, default to "moderate" (fill up to the 22% bracket).
+
+## Presenting Results
+
+Structure the response in four parts:
+
+### 1. Lead with Savings
+"Based on your tax situation, converting $X over Y years could save approximately $Z in
+lifetime taxes compared to doing nothing."
+
+### 2. Conversion Schedule
+Present the year-by-year schedule as a table or summary:
+- Year, age, conversion amount, tax cost, bracket filled
+- Highlight the best conversion years (lowest income, most headroom)
+
+### 3. Trade-offs
+- **Upfront tax cost**: Total taxes paid on conversions
+- **Break-even age**: When the tax-free Roth growth exceeds the upfront cost
+- **RMD reduction**: How much lower Required Minimum Distributions will be at age 73+
+
+### 4. Key Considerations
+- IRMAA warnings (if any conversions push income near Medicare surcharge thresholds)
+- State tax implications note
+- Any caveats about the specific situation
+
+## Safety Gates
+
+### IRMAA Cliff Warning
+When income with conversion approaches $103,000 (single) or $206,000 (MFJ), warn:
+"Converting this amount may trigger Medicare IRMAA surcharges that add $X/month to your
+Part B and Part D premiums. Consider converting less to stay below the threshold."
+
+### ACA Subsidy Impact
+If the user is pre-65 and on ACA marketplace insurance, note that conversions increase MAGI
+and may reduce premium subsidies. Suggest coordinating with their insurance situation.
+
+### State Tax Considerations
+Always note: "This analysis uses federal tax brackets only. Your state may tax Roth conversions
+differently. Some states (like Pennsylvania) do not tax Roth conversions."
+
+## Required Disclaimers
+
+ALWAYS include in every response:
+- "This analysis is for educational purposes only and does not constitute tax advice."
+- "Consult a qualified tax professional before making Roth conversion decisions."
+- "Tax brackets and IRMAA thresholds are based on 2025 values and may change."
+
+## Evidence Packet
+
+The tool returns a full evidence packet containing:
+- All input assumptions used in the calculation
+- Step-by-step calculation methodology
+- Tax bracket headroom analysis
+- IRMAA threshold proximity for each conversion year
+- Disclaimers and caveats
+
+Present the evidence packet transparently when the user asks "show me the math" or
+"what assumptions did you use?"
+
+## Common Follow-Up Patterns
+
+After presenting Roth conversion results, offer:
+- "Want to see how this conversion strategy affects your overall retirement forecast?" → `run_forecast`
+- "Want to compare this with a different conversion policy (conservative vs. aggressive)?" → re-run with different `conversionPolicy`
+- "Want to coordinate this with your Social Security claiming strategy?" → `optimize_ss_claiming`
+- "Want to explore a what-if scenario with these conversions?" → `run_scenario`
+
+## Error Handling
+
+Same as `run_forecast`. Validation errors should prompt clarification of the specific field.
+If the backend tax API returns an error, explain what went wrong and ask the user to verify
+their inputs (especially filing status and income figures).

package/skills/tools/optimize_ss_claiming.md

@@ -0,0 +1,30 @@
+# Tool Skill: optimize_ss_claiming
+
+Optimizes Social Security claiming strategy. Analyzes benefit amounts across different claiming
+ages (62–70) factoring in longevity estimates, spousal benefits, survivor benefits, and the
+interaction with other retirement income sources.
+
+## When to Use
+
+Use `optimize_ss_claiming` when the user wants to:
+- Determine the optimal age to start claiming Social Security
+- Compare the cumulative benefit of early vs delayed claiming
+- Factor in spousal or survivor benefit strategies
+- Understand the breakeven age for delayed claiming
+
+## Core Purpose: Maximizing Lifetime Social Security Benefits
+
+This tool runs a breakeven analysis comparing claiming at different ages, adjusting for the
+user's health, life expectancy, other income sources, and tax situation. It considers the 8%
+per year delayed retirement credits and any applicable spousal benefit strategies.
+
+## Presenting Results
+
+Structure the response in three parts:
+1. **Recommended claiming age**: The optimal age based on the user's specific situation.
+2. **Comparison table**: Monthly and cumulative benefits at ages 62, 67, and 70.
+3. **Key factors**: Breakeven age, spousal considerations, and tax implications.
+
+## Error Handling
+
+Same as `run_forecast`. Validation errors should prompt clarification of the specific field.

package/skills/tools/rename_plan.md

@@ -0,0 +1,34 @@
+# Tool Skill: rename_plan
+
+Renames an existing saved plan. Updates the display name without changing any plan data,
+components, or associated forecasts.
+
+## When to Use
+
+Use `rename_plan` when the user:
+- Says "Rename my plan to [new name]" or "Call this plan [new name]"
+- Wants to organize plans with more descriptive labels
+- Has a generic name like "Untitled Plan" they want to improve
+
+Use `save_plan` instead if the user wants to change plan data, not just the name.
+
+## Required Inputs to Gather
+
+- `planId` (string, required) — UUID of the plan to rename
+- `name` (string, required) — the new name for the plan
+
+If the user refers to the plan by its current name, resolve the ID via `list_plans`.
+
+## Presenting the Results
+
+Structure the response:
+
+1. **Confirmation**: "Done — your plan has been renamed from '[old name]' to '[new name]'."
+
+2. **No Other Changes**: "All plan data, forecasts, and scenarios are unchanged."
+
+## Common Follow-Up Patterns
+
+- User wants to review the plan → `get_plan`
+- User wants to rename another plan → `list_plans` then `rename_plan`
+- User wants to make other changes → `save_plan`

package/skills/tools/retirement-planner.md

@@ -0,0 +1,55 @@
+# Tool Skill: retirement-planner
+
+Opens the interactive Retirement Planner — a full visual planning application with plan
+creation form, forecast charts, and scenario comparison view.
+
+## When to Use
+
+Use `retirement-planner` when the user:
+- Wants a visual, interactive retirement planning experience
+- Says "show me my retirement plan", "open the planner", or "I want to see charts"
+- Wants to create or edit a retirement plan through a form UI
+- Wants to see their forecast visualized as charts
+- Wants to compare scenarios side-by-side visually
+- Has just run `create_plan` or `run_forecast` and wants to explore further
+
+## View Modes
+
+Select the mode based on the user's intent:
+
+- `editor` (default) — Input form for quick plan creation. Use when the user wants to
+  enter or modify their retirement inputs interactively.
+
+- `forecast` — Displays forecast charts for an existing plan. Use after `run_forecast`
+  has been called, especially when the user wants to see year-by-year projections visually.
+
+- `scenario` — Shows baseline vs. candidate scenario comparison. Use after `run_scenario`
+  when the user wants a visual side-by-side comparison.
+
+## Sequence Patterns
+
+**Starting fresh**: Open in `editor` mode. The user fills out inputs, then the planner
+runs its own forecast internally.
+
+**After create_plan**: Open in `editor` mode if the user wants to refine inputs, or in
+`forecast` mode to see a richer visual of what `create_plan` returned.
+
+**After run_forecast**: Open in `forecast` mode to show the year-by-year chart of the
+detailed forecast results.
+
+**After run_scenario**: Open in `scenario` mode to show the baseline vs. candidate
+comparison visually.
+
+## Integration with Tool Results
+
+The planner view is standalone — it does not automatically receive results from prior
+`create_plan` or `run_forecast` calls. If a `planId` was returned by a prior tool call,
+mention it to the user so they can load it inside the planner.
+
+## Presenting the Tool Result
+
+The tool returns a confirmation message; the actual UI renders in the host application.
+Follow the launch with:
+- "The retirement planner is now open. You can [describe the current mode action]."
+- If in `forecast` mode: "The chart shows your projected portfolio balance year by year."
+- If in `scenario` mode: "You can compare your baseline plan against the scenario on the left."

package/skills/tools/run_forecast.md

@@ -0,0 +1,65 @@
+# Tool Skill: run_forecast
+
+Runs a comprehensive deterministic retirement forecast with multi-account, multi-income-stream
+support. Returns readiness score, yearly projections, portfolio runway, legacy value, and
+success probability.
+
+## When to Use
+
+Use `run_forecast` when the user:
+- Has detailed financial data: multiple accounts (401k, IRA, Roth, taxable), income streams
+- Wants year-by-year projections through retirement
+- Asks about portfolio runway or "When will I run out of money?"
+- Wants to consider tax optimization, withdrawal ordering, or Roth conversions
+- Has a spouse and needs household-level analysis
+- Wants to understand legacy value (assets remaining at life expectancy)
+
+Use `create_plan` instead for quick projections when detailed account data is not available.
+
+## Gathering Inputs
+
+The `run_forecast` tool takes a full `PlanInputExtended` payload. Gather minimum required fields:
+
+**Required:**
+- `currentAge` — integer >= 18
+- `retirementAge` — integer >= 50
+- `targetMonthlySpending` — desired monthly spending in retirement
+- `accounts` — at least one account: `{type, balance, annualContribution?, realReturn?}`
+  - Types: `TRADITIONAL`, `ROTH`, `TAXABLE`, `CASH`
+- `incomeStreams` — at least one stream: `{type, amountMonthly, startAge?, endAge?}`
+  - Types: `SALARY`, `SOCIAL_SECURITY`, `PENSION`, `ANNUITY`, `RENTAL`, `OTHER`
+
+**Optional but valuable:**
+- `socialSecurityClaimAge` — claiming age affects monthly benefit amount
+- `safeWithdrawalRate` — default 0.04 (4% rule)
+- `effectiveTaxRate` — default 0.15; use marginal for accuracy
+- `withdrawalStrategy` — `"taxable_first"` or `"traditional_first"`
+- `horizonAge` — planning horizon (default 95)
+- `spouse` — partner data for household analysis
+
+## Presenting the Results
+
+Structure the response:
+
+1. **Headline**: "Your retirement forecast shows a [readiness score]/100 readiness score,
+   with your portfolio covering [yearsCovered] years."
+
+2. **Key Metrics**:
+   - Readiness score: X/100
+   - Portfolio runway: X years
+   - Legacy value at [horizonAge]: $X
+   - Success probability: X%
+
+3. **Year-by-Year Narrative**: "Your portfolio peaks at retirement in [year] at $X. Starting
+   from age [retirementAge], withdrawals of $X/month cover your target spending through [age]."
+
+4. **Key Assumptions**: Withdrawal rate, tax rate, return assumptions, Social Security claim age.
+
+5. **Next Step**: Offer a scenario or planner view:
+   "Want to see how delaying Social Security to 70 changes these numbers?"
+
+## Common Follow-Up Patterns
+
+- User wants to explore changes → `run_scenario`
+- User wants visual charts → `retirement-planner` in `forecast` mode with `planId` if saved
+- User wants to stress-test against a market crash → `run_scenario` with `stressTest`

package/skills/tools/run_saved_forecast.md

@@ -0,0 +1,52 @@
+# Tool Skill: run_saved_forecast
+
+Triggers a retirement forecast on a saved plan. Unlike `run_forecast` (which takes an inline
+PlanContract), this tool references a persisted plan by ID and stores the forecast results
+server-side for later retrieval.
+
+## When to Use
+
+Use `run_saved_forecast` when the user:
+- Has a saved plan and says "Run a forecast" or "How does my plan look?"
+- Wants to update projections after making changes to a saved plan
+- Needs baseline results to compare against a scenario
+- Asks for year-by-year projections on their active or named plan
+
+Use `run_forecast` instead for ad-hoc projections with inline plan data that isn't saved.
+Use `run_scenario` when the user wants to compare baseline vs. modified assumptions.
+
+## Required Inputs to Gather
+
+- `planId` (string, required) — UUID of the saved plan
+- `runType` (string, required) — one of:
+  - `"baseline"` — standard projection with current plan assumptions
+  - `"scenario"` — projection using a saved scenario's overrides
+- `scenarioId` (string, optional) — required when `runType` is `"scenario"`;
+  the UUID of the saved scenario to apply
+
+If the user doesn't specify a plan, resolve via `get_active_plan`.
+
+## Presenting the Results
+
+Structure the response:
+
+1. **Headline**: "Forecast complete for '[plan name]' ([runType] run)."
+
+2. **Key Metrics**:
+   - Readiness score: X/100
+   - Portfolio runway: X years (covers spending through age X)
+   - Legacy value at [horizon age]: $X
+   - Success probability: X%
+
+3. **Year-by-Year Narrative**: Summarize the trajectory — peak balance, drawdown start,
+   and critical inflection points.
+
+4. **Next Step**: "Want to explore a what-if scenario, or see how a different claiming
+   age affects these numbers?"
+
+## Common Follow-Up Patterns
+
+- User wants to explore changes → `save_scenario` then `run_saved_forecast` with `runType: "scenario"`
+- User wants the baseline data later → `get_baseline_forecast`
+- User wants visual charts → `retirement-planner` with the `planId`
+- User wants a stress test → `run_scenario` with `stressTest`

package/skills/tools/run_scenario.md

@@ -0,0 +1,66 @@
+# Tool Skill: run_scenario
+
+Runs a what-if scenario analysis comparing a baseline retirement plan against modified
+assumptions. Returns baseline vs. candidate comparison with delta metrics.
+
+## When to Use
+
+Use `run_scenario` when the user:
+- Asks "What if I retire at 62 instead of 65?"
+- Wants to compare two versions of their plan
+- Asks about enabling/disabling income streams (annuity, rental income)
+- Wants to stress-test against historical market crashes (2008, dot-com, 1929)
+- Says "How would my plan hold up in a recession?"
+- Wants to see the impact of delaying Social Security
+- Wants to understand the trade-off between saving more vs. retiring earlier
+
+## Framing Scenarios
+
+Always present scenarios as exploration, not recommendation:
+- "If X, then Y" — not "you should do X"
+- Lead with the delta: "Retiring at 62 reduces your readiness score by 8 points and
+  cuts legacy value by $180,000."
+- Explain the driver: "The 3 extra withdrawal years are the primary factor."
+
+## Input Structure
+
+`run_scenario` requires:
+- `plan` — baseline PlanContract object (the current plan)
+- `overrides` (optional) — bundle of changes:
+  - `planDeltas` — field-level changes: `[{path: "household.primary.retireAge", to: 62}]`
+  - `componentOverrides` — enable/disable plan components by UUID
+  - `stressTest` — historical market scenario: `{scenarioId: "2008_CRISIS", applyTo: "EQUITY"}`
+
+Common `planDeltas` examples:
+- Retire 3 years earlier: `{path: "household.primary.retireAge", to: retireAge - 3}`
+- Increase target spending: `{path: "goals.retirement.targetSpending.amountMonthly", to: newAmount}`
+- Delay Social Security: `{path: "household.primary.socialSecurity.claimAge", to: 70}`
+
+Common `stressTest.scenarioId` values:
+- `"2008_CRISIS"` — 2008 financial crisis
+- `"DOT_COM_BUST"` — 2000-2002 dot-com crash
+- `"1929_CRASH"` — Great Depression
+
+## Presenting the Results
+
+Structure the comparison:
+
+1. **Scenario Label**: "Scenario: [label, e.g., 'Retire at 62']"
+
+2. **Delta Summary**:
+   - Readiness score: [baseline] → [candidate] (Δ [+/-X])
+   - Legacy value: $[baseline] → $[candidate] (Δ [+/-$X])
+   - Portfolio runway: [baseline] years → [candidate] years
+
+3. **Key Driver**: Explain the 1-2 factors that most changed the outcome.
+
+4. **Trade-Off Frame**: "The trade-off is [X years of retirement] vs. [Y reduction in
+   portfolio longevity]. At your spending target of $Z/month, that math looks like..."
+
+5. **Next Step**: Offer to run another scenario or open the planner comparison view.
+
+## Error Handling
+
+If the plan object is incomplete, ask for the missing required fields before calling.
+A minimal plan requires household ages, at least one account, at least one income stream,
+and a target monthly spending goal.

package/skills/tools/save_plan.md

@@ -0,0 +1,48 @@
+# Tool Skill: save_plan
+
+Updates an existing saved plan with new or modified data. Performs a partial or full update
+of the PlanContract and persists the changes.
+
+## When to Use
+
+Use `save_plan` when the user:
+- Wants to update their retirement age, spending target, or other assumptions
+- Adds or removes accounts or income streams from an existing plan
+- Says "Change my retirement age to 62" or "Add a Roth IRA with $50k"
+- Corrects a mistake in their plan data
+- Wants to save changes after discussing adjustments
+
+Do NOT use this to create a brand-new plan — use `create_saved_plan` for that.
+
+## Required Inputs to Gather
+
+- `planId` (string, required) — UUID of the plan to update
+
+Plus any fields to update within the PlanContract:
+- `household` — age, retirement age, life expectancy, spouse changes
+- `accounts` — add, update, or remove accounts
+- `incomeStreams` — add, update, or remove income streams
+- `goals` — target spending, withdrawal strategy, safe withdrawal rate
+- `name` — to rename (though `rename_plan` is the dedicated tool for that)
+
+Fetch the current plan with `get_plan` first if you need to merge changes.
+
+## Presenting the Results
+
+Structure the response:
+
+1. **Confirmation**: "I've updated your '[name]' plan."
+
+2. **Changes Applied**: Bullet list of what changed:
+   - "Retirement age: 65 -> 62"
+   - "Added Roth IRA account ($50,000)"
+
+3. **Impact Hint**: "These changes may affect your forecast. Want me to run a fresh
+   projection to see how this looks?"
+
+## Common Follow-Up Patterns
+
+- User wants to see the impact → `run_saved_forecast`
+- User wants to compare before/after → `run_scenario` with deltas
+- User wants to undo → `save_plan` reverting to previous values (fetch via `get_plan`)
+- User wants to rename → `rename_plan`

package/skills/tools/save_scenario.md

@@ -0,0 +1,50 @@
+# Tool Skill: save_scenario
+
+Persists a what-if scenario so it can be re-run, compared, or shared. A scenario captures
+a set of modifications (deltas, overrides, stress tests) that can be applied against a
+baseline plan to produce an alternative forecast.
+
+## When to Use
+
+Use `save_scenario` when the user:
+- Wants to save a what-if for later: "Save this as my early-retirement scenario"
+- Has explored a scenario via `run_scenario` and wants to keep it
+- Wants to build a library of scenarios to compare (e.g., "conservative" vs. "aggressive")
+- Says "Remember these changes" or "I want to come back to this"
+
+Use `run_scenario` for one-off exploration that doesn't need to persist.
+
+## Required Inputs to Gather
+
+- `label` (string, required) — descriptive name (e.g., "Retire at 60", "No Pension")
+
+**Optional inputs (at least one recommended):**
+- `deltas` — array of field-level changes:
+  `[{path: "household.primary.retireAge", to: 60}]`
+- `overrides` — component-level toggles:
+  `{componentId: "uuid", enabled: false}` to disable an income stream
+- `bundle` — a named preset group of changes (e.g., `"aggressive_growth"`)
+- `planId` — UUID of the plan this scenario is associated with; if omitted, the scenario
+  is standalone and can be applied to any plan
+
+## Presenting the Results
+
+Structure the response:
+
+1. **Confirmation**: "Saved scenario '[label]' (ID: [scenarioId])."
+
+2. **What It Contains**:
+   - Deltas: list each change in human-readable form
+   - Overrides: list toggled components
+   - Stress test: name of historical scenario if included
+
+3. **Association**: "This scenario is [linked to plan '[name]' / standalone]."
+
+4. **Next Step**: "Want me to run a forecast using this scenario, or create another one?"
+
+## Common Follow-Up Patterns
+
+- User wants to see the impact → `run_saved_forecast` with `runType: "scenario"` and `scenarioId`
+- User wants to list all scenarios → `list_scenarios`
+- User wants to modify the scenario → `save_scenario` with updated fields (or delete and recreate)
+- User wants to compare multiple scenarios → run forecasts for each and compare

package/skills/tools/verify_forecast.md

@@ -0,0 +1,43 @@
+# Tool Skill: verify_forecast
+
+Runs a retirement forecast and returns a verification packet — a structured, auditable record
+of the inputs, calculation trace, and verdict. Used to verify advisor projections or double-check
+personal planning scenarios.
+
+## When to Use
+
+Use `verify_forecast` when the user wants to:
+- Verify numbers from their financial advisor
+- Create an auditable record of their retirement projection
+- Get a "second opinion" on a specific set of assumptions
+
+## Core Purpose: Independent Verification
+
+This is NestPilot's signature capability. The verification packet is the user's proof that
+the math was run independently, with explicit assumptions, and the results are reproducible.
+
+ALWAYS frame verification as: "Let's verify these numbers independently."
+NEVER suggest the advisor was wrong — present the verification as a confirmation or a
+starting point for a conversation with the advisor.
+
+## Presenting the Verification Packet
+
+Structure the response in three parts:
+1. **Assumptions verified**: List the key inputs (return rate, withdrawal rate, balance,
+   timeline) that were used in the calculation.
+2. **Result**: The verified balance, income, and longevity assessment.
+3. **Verdict**: "The projection is mathematically consistent with the stated assumptions" OR
+   "The projection assumes [X] which appears [optimistic/conservative] — here's why..."
+
+## Framing the Verdict
+
+- If results match: "The projection checks out. The math supports a balance of $[X] at age [Y]
+  under these assumptions."
+- If there's a discrepancy: "Our calculation shows $[X] vs the stated $[Y]. The difference is
+  likely due to [possible cause]. We recommend confirming the assumed return rate and
+  whether Social Security income is included."
+- NEVER say "your advisor is wrong" — say "the numbers differ, which is worth discussing."
+
+## Error Handling
+
+Same as `run_forecast`. Validation errors should prompt clarification of the specific field.