@nestpilot/mcp-app 1.0.0

package/skills/tools/delete_scenario.md

@@ -0,0 +1,38 @@
+# Tool Skill: delete_scenario
+
+Deletes a saved what-if scenario permanently. Unlike plan deletion (which is a soft delete),
+scenario deletion is immediate. The scenario will no longer appear in `list_scenarios` and
+cannot be used in future forecast runs.
+
+## When to Use
+
+Use `delete_scenario` when the user:
+- Says "Delete my [scenario name] scenario" or "Remove that scenario"
+- Wants to clean up old or irrelevant what-if explorations
+- Confirms deletion after being prompted
+
+**Always confirm before deleting.** Ask: "Are you sure you want to delete the '[label]'
+scenario? This cannot be undone."
+
+## Required Inputs to Gather
+
+- `scenarioId` (string, required) — UUID of the scenario to delete
+
+If the user refers to a scenario by label, resolve via `list_scenarios`.
+
+## Presenting the Results
+
+Structure the response:
+
+1. **Confirmation**: "The scenario '[label]' has been deleted."
+
+2. **Impact Note**: "Any forecast runs that used this scenario are still saved, but you
+   won't be able to re-run the scenario."
+
+3. **Remaining Scenarios**: "You have [N] scenario(s) remaining. Want to see them?"
+
+## Common Follow-Up Patterns
+
+- User wants to see remaining scenarios → `list_scenarios`
+- User wants to create a replacement → `save_scenario`
+- User wants to clean up more → `list_scenarios` then `delete_scenario` again

package/skills/tools/generate_proposal.md

@@ -0,0 +1,63 @@
+# Tool Skill: generate_proposal
+
+Assembles a client-ready advisor proposal by orchestrating the NestPilot plan summary
+and proposal record APIs. Produces a structured deliverable an advisor can share with
+(or release to) a client. **Advisor tier only** (FEAT-0063 entitlement gate).
+
+## When to Use
+
+Use `generate_proposal` when an **advisor** wants to:
+- Package analysis results into a formal client deliverable
+- Bundle forecast + optional Roth / SS analyses into one proposal document
+- Create a proposal record that can be released to a client
+- Generate a PDF summary alongside a structured proposal
+
+Do **not** use for ad-hoc analysis — use `run_forecast`, `optimize_roth_conversion`, or
+`run_scenario` first, then call this tool to assemble the proposal.
+
+## Required Inputs
+
+| Input | Description |
+|---|---|
+| `planId` | UUID of the plan to base the proposal on |
+| `clientUserId` | UUID of the client the proposal is for |
+| `title` | Proposal title shown to the client |
+
+## Optional Inputs
+
+| Input | Default | Description |
+|---|---|---|
+| `subtitle` | — | Optional tagline |
+| `advisorNotes` | — | Custom notes appended to the proposal |
+| `includeScenarios` | `[]` | Scenario IDs to include in comparison |
+| `includeRothAnalysis` | `false` | Annotate that Roth analysis was performed |
+| `includeSsAnalysis` | `false` | Annotate that SS analysis was performed |
+| `unlockPriceCents` | `0` | Client unlock price (0 = free) |
+| `autoRelease` | `false` | Release to client immediately |
+
+## Workflow
+
+1. **Gather context**: Advisor has reviewed the plan, run scenarios, and is ready to share.
+2. **Confirm release preference**: Ask the advisor whether to release immediately or keep as draft.
+3. **Call the tool** with gathered inputs.
+4. **Present result**: Show `proposalId`, `status` (draft / released), `summaryUrl`, and `evidencePacket`.
+
+## Safety Gates
+
+- Proposal is **NOT released** unless `autoRelease: true` is explicitly provided.
+- If `autoRelease` is true, prompt the advisor to confirm before proceeding.
+- Compliance disclaimers are automatically included in the evidence packet.
+
+## Presenting Results
+
+Structure the response in three parts:
+1. **Status**: `proposalId`, `status` (draft/released), whether summary PDF was generated.
+2. **Evidence packet**: What analyses were included, assumptions, disclaimers, `generatedAt`.
+3. **Next steps**: If draft, how to release. If released, client can view it in their portal.
+
+## Error Handling
+
+- If summary generation fails: report the error; no proposal record is created.
+- If proposal creation fails: report the error; advise the advisor to retry.
+- If release fails after creation: proposal is saved as draft; advise manual release from the
+  Proposal Manager UI (`/advisor/proposals`).

package/skills/tools/generate_retirement_report.md

@@ -0,0 +1,50 @@
+# Tool Skill: generate_retirement_report
+
+Generates a comprehensive retirement planning PDF report. Loads a saved plan, runs a forecast,
+optionally includes saved scenarios, and produces a professional PDF with plan details, charts,
+year-by-year projections, and recommendations.
+
+## When to Use
+
+Use `generate_retirement_report` when the user wants to:
+- Create a PDF document summarizing their retirement plan and forecast
+- Generate a shareable/printable retirement analysis
+- Export their plan details, projections, and charts to a document
+- Produce a retirement readiness report in PDF format
+
+## How It Works
+
+The tool orchestrates several steps internally:
+1. Resolves the plan ID (supports "active", "default", "current" aliases)
+2. Loads the full plan via `GET /api/plans/{planId}`
+3. Runs a forecast using the plan data
+4. Optionally loads saved scenarios for comparison
+5. Invokes the Python PDF generator (`generate_report.py`) with all data
+6. Returns the PDF file path and metadata
+
+## Presenting Results
+
+After the tool returns successfully:
+1. **Confirm generation**: "Your retirement report has been generated at [path]."
+2. **Summarize contents**: Mention what sections are included (plan details, forecast KPIs,
+   charts, scenario comparison if applicable).
+3. **Offer next steps**: Suggest opening the PDF, running additional scenarios, or using
+   the interactive planner for real-time exploration.
+
+## Input Tips
+
+- **planId**: Omit or pass "active" to use the user's active plan. Pass a UUID for a specific plan.
+- **clientName**: Optional personalization for the report header (e.g., "John & Jane Doe").
+- **includeScenarios**: Defaults to true. Set to false to skip the scenario comparison section.
+- **outputPath**: Optional custom path. If omitted, generates in a temp directory.
+
+## Error Handling
+
+- If no plan is found, prompt the user to create or activate a plan first.
+- If the forecast fails, report the backend error and suggest checking plan inputs.
+- If Python/reportlab is not available, report the dependency requirement.
+
+## Prerequisites
+
+- Requires Python 3 with `reportlab` installed (`pip install reportlab`).
+- Requires a saved plan in the system.

package/skills/tools/get_active_plan.md

@@ -0,0 +1,44 @@
+# Tool Skill: get_active_plan
+
+Retrieves the user's currently active (default) retirement plan. Returns the full PlanContract
+just like `get_plan`, but without requiring a plan ID.
+
+## When to Use
+
+Use `get_active_plan` when the user:
+- Says "my plan" or "my current plan" without naming a specific one
+- Asks "What does my plan look like?" or "Show me my retirement plan"
+- Starts a conversation wanting to run a forecast but hasn't specified which plan
+- Asks about their current retirement readiness without further context
+
+Use `get_plan` instead when the user references a specific plan by name or ID.
+Use `list_plans` when the user wants to see all their plans.
+
+## Required Inputs to Gather
+
+No inputs required. The API resolves the active plan from the authenticated user's profile.
+
+## Presenting the Results
+
+Structure the response:
+
+1. **Plan Identity**: "Your active plan is '[name]', last updated [date]."
+
+2. **Quick Snapshot**:
+   - Retirement age: X
+   - Total account balances: $X across N accounts
+   - Target monthly spending: $X
+   - Readiness score (if cached from last forecast): X/100
+
+3. **Offer Next Steps**: "Would you like me to run a fresh forecast, explore a what-if
+   scenario, or update any of these assumptions?"
+
+If no active plan exists, say: "You don't have an active plan set. Would you like to
+create one, or pick from your existing plans?"
+
+## Common Follow-Up Patterns
+
+- User wants a forecast → `run_saved_forecast` using the returned `planId`
+- User wants to change assumptions → `save_plan` with updated fields
+- User wants a different plan as default → `list_plans` then `activate_plan`
+- User wants a combined analysis → `comprehensive_plan`

package/skills/tools/get_baseline_forecast.md

@@ -0,0 +1,47 @@
+# Tool Skill: get_baseline_forecast
+
+Retrieves the most recent baseline forecast results for a saved plan. Returns cached metrics
+and yearly projections without re-running the forecast engine.
+
+## When to Use
+
+Use `get_baseline_forecast` when the user:
+- Asks "What were my last forecast results?" or "Show me my numbers"
+- Needs baseline metrics for comparison without waiting for a fresh run
+- Wants to reference previous projections during a conversation
+- Asks about readiness score, legacy value, or runway from their last forecast
+
+Use `run_saved_forecast` instead when the user wants fresh projections, especially after
+making plan changes. Stale results may not reflect recent edits.
+
+## Required Inputs to Gather
+
+- `planId` (string, required) — UUID of the saved plan
+
+If the user doesn't specify, resolve via `get_active_plan`.
+
+## Presenting the Results
+
+Structure the response:
+
+1. **Freshness Note**: "These results are from your last forecast run on [date].
+   Your plan [has / has not] changed since then."
+
+2. **Key Metrics**:
+   - Readiness score: X/100
+   - Portfolio runway: X years
+   - Legacy value at [horizon age]: $X
+   - Peak portfolio value: $X at age X
+
+3. **Year-by-Year Highlights**: Summarize key inflection points — when contributions
+   stop, when withdrawals begin, when portfolio peaks, and when it depletes (if ever).
+
+4. **Staleness Warning** (if plan was modified after the forecast):
+   "Your plan has been updated since this forecast. Want me to run a fresh one?"
+
+## Common Follow-Up Patterns
+
+- Results look stale → `run_saved_forecast` with `runType: "baseline"`
+- User wants to compare with a scenario → `run_saved_forecast` with `runType: "scenario"`
+- User wants to drill into components → `get_plan_components`
+- User wants charts → `retirement-planner` with the `planId`

package/skills/tools/get_plan.md

@@ -0,0 +1,44 @@
+# Tool Skill: get_plan
+
+Retrieves a single saved retirement plan by its unique ID. Returns the full PlanContract
+including household data, accounts, income streams, goals, and metadata.
+
+## When to Use
+
+Use `get_plan` when the user:
+- Refers to a specific plan by name or ID and you need the full details
+- Wants to review or edit a plan before running a forecast
+- Needs to inspect plan components, assumptions, or configuration
+- Asks "Show me my [plan name] plan" after you have resolved the ID via `list_plans`
+
+Use `get_active_plan` instead when the user simply says "my plan" without specifying which one.
+
+## Required Inputs to Gather
+
+- `planId` (string, required) — the UUID of the saved plan
+
+If the user refers to a plan by name, first call `list_plans` to resolve the name to a `planId`.
+
+## Presenting the Results
+
+Structure the response:
+
+1. **Plan Summary**: "Here is your '[name]' plan, last updated [date]."
+
+2. **Household**: Primary age, retirement age, life expectancy. Spouse if present.
+
+3. **Accounts**: List each account with type, balance, and annual contribution.
+
+4. **Income Streams**: List each stream with type, monthly amount, and start/end ages.
+
+5. **Goals**: Target monthly spending, withdrawal strategy, safe withdrawal rate.
+
+6. **Offer Next Steps**: "Want me to run a forecast on this plan, tweak any assumptions,
+   or compare it with a scenario?"
+
+## Common Follow-Up Patterns
+
+- User wants projections → `run_saved_forecast` with the `planId`
+- User wants to change something → `save_plan` with updated fields
+- User wants to make it the default → `activate_plan`
+- User wants to see attached components → `get_plan_components`

package/skills/tools/get_plan_components.md

@@ -0,0 +1,50 @@
+# Tool Skill: get_plan_components
+
+Returns the financial components attached to a saved plan — accounts, income streams,
+expenses, and insurance policies. Each component includes its type, configuration, and
+link back to the parent plan.
+
+## When to Use
+
+Use `get_plan_components` when the user:
+- Asks "What accounts are in my plan?" or "Show me my income streams"
+- Wants a detailed breakdown of plan building blocks without the full PlanContract
+- Needs to verify which components exist before adding or removing one
+- Asks about a specific component type (e.g., "Do I have a Roth in this plan?")
+
+Use `get_plan` instead if you need the full plan including household, goals, and metadata.
+
+## Required Inputs to Gather
+
+- `planId` (string, required) — UUID of the plan
+
+If the user doesn't specify, resolve from the active plan via `get_active_plan`.
+
+## Presenting the Results
+
+Structure the response by component type:
+
+1. **Accounts**:
+   - Type | Balance | Annual Contribution | Return Rate
+   - e.g., "Traditional 401(k): $320,000, contributing $22,500/yr at 6% real return"
+
+2. **Income Streams**:
+   - Type | Monthly Amount | Start Age | End Age
+   - e.g., "Social Security: $2,800/mo starting at age 67"
+
+3. **Expenses** (if present):
+   - Label | Monthly Amount | Start Age | End Age
+   - e.g., "Healthcare: $800/mo from age 65 to 95"
+
+4. **Insurance** (if present):
+   - Type | Coverage | Premium
+
+5. **Offer Next Steps**: "Want to add a new account, adjust an income stream, or
+   run a forecast with these components?"
+
+## Common Follow-Up Patterns
+
+- User wants to add a component → `save_plan` with the new component appended
+- User wants to remove one → `save_plan` with the component removed
+- User wants to run numbers → `run_saved_forecast`
+- User wants to see the full plan → `get_plan`

package/skills/tools/get_scenario.md

@@ -0,0 +1,46 @@
+# Tool Skill: get_scenario
+
+Retrieves a single saved what-if scenario by ID. Returns the full scenario definition
+including label, deltas, overrides, bundle, linked plan, and metadata.
+
+## When to Use
+
+Use `get_scenario` when the user:
+- Wants to review what a saved scenario contains before running it
+- Asks "What's in my [scenario name] scenario?"
+- Needs to verify scenario details before applying it to a different plan
+- Refers to a scenario by name and you need the full definition
+
+Use `list_scenarios` first if you need to resolve a name to an ID.
+
+## Required Inputs to Gather
+
+- `scenarioId` (string, required) — UUID of the scenario
+
+If the user refers to a scenario by label, call `list_scenarios` to resolve the ID.
+
+## Presenting the Results
+
+Structure the response:
+
+1. **Scenario Identity**: "Scenario '[label]', created [date]."
+
+2. **Changes Defined**:
+   - **Deltas**: List each change in plain language:
+     "Retirement age changed to 60" / "Target spending increased to $7,000/mo"
+   - **Overrides**: List toggled components:
+     "Pension income: disabled" / "Rental income: enabled"
+   - **Stress Test**: Historical scenario if present:
+     "Applies 2008 financial crisis to equity returns"
+   - **Bundle**: Named preset if used
+
+3. **Linked Plan**: "Associated with plan '[name]'" or "Standalone (can apply to any plan)."
+
+4. **Next Step**: "Want me to run a forecast with this scenario, or modify it?"
+
+## Common Follow-Up Patterns
+
+- User wants to run it → `run_saved_forecast` with `runType: "scenario"` and the `scenarioId`
+- User wants to change it → `save_scenario` with updated fields or delete and recreate
+- User wants to delete it → `delete_scenario`
+- User wants to apply it to a different plan → `run_saved_forecast` with a different `planId`

package/skills/tools/list_plans.md

@@ -0,0 +1,44 @@
+# Tool Skill: list_plans
+
+Returns all saved retirement plans belonging to the authenticated user. Each entry includes the
+plan ID, name, creation date, last-modified date, and whether it is the active plan.
+
+## When to Use
+
+Use `list_plans` when the user:
+- Asks "What plans do I have?" or "Show me my saved plans"
+- Wants to pick a plan before running a forecast or scenario
+- Needs to compare or manage multiple plans (e.g., "conservative" vs. "aggressive")
+- Refers to a plan by name and you need to resolve the plan ID
+
+Do NOT call this if the user already provided a specific `planId` — go straight to `get_plan`.
+
+## Required Inputs to Gather
+
+No inputs required. The API identifies the user from the auth token.
+
+Optional query hints the user might provide:
+- A name fragment to filter on (client-side filtering after retrieval)
+- Whether they only want the active plan — prefer `get_active_plan` in that case
+
+## Presenting the Results
+
+Structure the response:
+
+1. **Count**: "You have [N] saved plan(s)."
+
+2. **Plan List** (table or bullet list):
+   - Name | Created | Last Modified | Active?
+   - Highlight the currently active plan with a label like "(active)".
+
+3. **Prompt for Action**: "Which plan would you like to work with? I can open it,
+   run a forecast, or compare scenarios."
+
+If the list is empty, say: "You don't have any saved plans yet. Would you like to create one?"
+
+## Common Follow-Up Patterns
+
+- User picks a plan by name → resolve to `planId`, then `get_plan`
+- User wants to create a new plan → `create_saved_plan`
+- User asks which plan is active → `get_active_plan`
+- User wants to delete or rename → `delete_plan` / `rename_plan`

package/skills/tools/list_scenarios.md

@@ -0,0 +1,42 @@
+# Tool Skill: list_scenarios
+
+Returns all saved what-if scenarios for the authenticated user, optionally filtered to a
+specific plan. Each entry includes the scenario ID, label, associated plan (if any),
+and creation date.
+
+## When to Use
+
+Use `list_scenarios` when the user:
+- Asks "What scenarios do I have?" or "Show me my saved what-ifs"
+- Wants to pick a scenario before running a forecast
+- Needs to compare or manage their scenario library
+- Asks "What scenarios are attached to this plan?"
+
+## Required Inputs to Gather
+
+- `planId` (string, optional) — if provided, returns only scenarios linked to that plan;
+  if omitted, returns all scenarios across all plans plus standalone ones
+
+If the user says "scenarios for my plan" without specifying which, resolve via `get_active_plan`.
+
+## Presenting the Results
+
+Structure the response:
+
+1. **Count**: "You have [N] saved scenario(s) [for plan '[name]' / total]."
+
+2. **Scenario List** (table or bullets):
+   - Label | Linked Plan | Created | Key Changes
+   - Summarize the deltas briefly, e.g., "Retire at 60, no pension"
+
+3. **Prompt for Action**: "Which scenario would you like to run, view, or delete?"
+
+If no scenarios exist: "You don't have any saved scenarios yet. Would you like to
+create one? Tell me what change you'd like to explore."
+
+## Common Follow-Up Patterns
+
+- User picks a scenario → `get_scenario` for details, or `run_saved_forecast` to execute
+- User wants to create a new one → `save_scenario`
+- User wants to delete one → `delete_scenario`
+- User wants to compare two → run `run_saved_forecast` for each and compare results

package/skills/tools/medicare-guardian.md

@@ -0,0 +1,59 @@
+# Tool Skill: medicare-guardian
+
+Opens the interactive Medicare Guardian view — an enrollment readiness tool that helps users
+understand their Medicare enrollment deadlines, penalty risks, and IRMAA surcharges.
+
+## When to Use
+
+Use `medicare-guardian` when the user:
+- Is approaching age 65 and asking about Medicare enrollment
+- Wants to know their enrollment window (IEP, SEP, or GEP)
+- Is asking about Medicare penalties or late enrollment consequences
+- Wants to understand IRMAA surcharges based on their income
+- Is still working and asking whether they can delay enrollment
+- Mentions retiring and needs to switch from employer coverage to Medicare
+- Asks about COBRA and Medicare coordination or timing
+- Wants deadline reminders for Medicare enrollment
+- Needs to understand creditable vs. non-creditable drug coverage
+
+## CRITICAL Boundaries
+
+**DO NOT recommend specific Medicare plans** (Part C/Advantage plans, Part D drug plans).
+The Medicare Guardian is an enrollment timing and penalty avoidance tool — NOT a plan comparison
+tool. Recommending specific plans creates regulatory exposure.
+
+What you CAN do:
+- Explain enrollment windows (IEP: 7-month window centered on the month you turn 65)
+- Explain penalty rules (Part B: 10% per year delayed beyond IEP; Part D: 1%/month)
+- Explain IRMAA income thresholds and how to appeal them
+- Explain when employer coverage allows delayed enrollment (employer size 100+ = SEP eligible)
+- Explain HSA rules (must stop contributions 6 months before Medicare Part A starts)
+
+## View Modes
+
+The guardian opens in one of three modes:
+- `timeline` (default) — shows enrollment windows and key dates based on date of birth
+- `sep_check` — evaluates Special Enrollment Period eligibility (for those still working)
+- `penalty_estimate` — calculates potential penalty exposure
+
+Select the mode based on the user's primary concern:
+- "When do I need to sign up?" → `timeline`
+- "Can I delay? I'm still working" → `sep_check`
+- "I missed my window, what are my penalties?" → `penalty_estimate`
+
+## Presenting the Results
+
+The view handles its own analysis display. After opening the guardian, if the user wants
+to discuss the results, guide them through:
+
+1. **Enrollment Status**: Whether they are in, approaching, or past their IEP
+2. **Coverage Assessment**: Whether current coverage allows delayed enrollment
+3. **Penalty Risk**: Quantify the permanent surcharge risk if applicable
+4. **IRMAA Warning**: If income exceeds ~$103,000 (single) / ~$206,000 (joint) for 2024
+5. **Action Items**: Clear next steps with dates
+
+## Error Handling
+
+If the view fails to load, ask the user for their date of birth and employment status, then
+explain enrollment timing conceptually from general knowledge. Recommend they visit
+Medicare.gov for authoritative deadline confirmation.

package/skills/tools/nestpilot_run_plan.md

@@ -0,0 +1,61 @@
+# Tool Skill: nestpilot_run_plan
+
+Runs a full retirement readiness assessment through the NestPilot Agent Runtime using the
+`retirement-readiness` skill. Accepts natural language input and returns a structured
+assessment with session continuity support.
+
+## When to Use
+
+Use `nestpilot_run_plan` when the user:
+- Provides retirement situation in natural language: "I'm 42, have $300k saved, contribute
+  $1,500/month, plan to retire at 65. Am I on track?"
+- Wants a complete retirement readiness assessment without manually entering structured inputs
+- Says "check my retirement plan" or "am I on track?"
+- Wants the agent to gather and analyze their situation conversationally
+- Has a complex situation that benefits from the agent's contextual reasoning
+
+Use `create_plan` instead when the user has already provided structured inputs (age, balance,
+contribution amounts, rates) and you can pass them directly.
+
+## How It Works
+
+`nestpilot_run_plan` communicates with the NestPilot Agent Runtime service:
+1. Creates a new session (or continues an existing one via `sessionId`)
+2. Sends the user's message prefixed with `[skill:retirement-readiness]`
+3. The agent runtime processes the skill workflow and returns analysis results
+
+## Input
+
+- `message` — The user's retirement planning question or data in natural language.
+  Include as much context as available: age, current savings, monthly contributions,
+  retirement target age, expected expenses.
+
+  Example: "I'm 45, have $400k in my 401k, contribute $2k/month, and want to retire
+  at 67 with $6k/month income. How do I look?"
+
+- `sessionId` — (optional) Existing session ID to continue a conversation thread.
+  Omit to start a fresh session. The tool returns the `sessionId` for follow-up calls.
+
+## Presenting the Results
+
+The result includes:
+- `sessionId` — preserve this for follow-up questions in the same conversation
+- Agent analysis: readiness assessment, key findings, recommendations
+
+Follow up the result with:
+- A summary of the agent's assessment in plain language
+- Key numbers if provided (readiness score, projected balance, sustainability)
+- Offer to run a specific scenario: "Want me to run a scenario showing what happens
+  if you increase contributions by $500/month?"
+
+## Session Continuity
+
+For multi-turn retirement conversations, pass the `sessionId` from the first call to
+subsequent calls. This allows the agent to maintain context across the conversation.
+
+## Error Handling
+
+If the Agent Runtime service is unavailable (connection refused), fall back to `create_plan`
+with structured inputs extracted from the user's message:
+"The agent service is temporarily unavailable. Let me calculate your retirement projection
+directly — [gather required inputs and call create_plan]."