NestPilot

Models year-by-year Roth conversion policies within the user's full retirement plan, including estimated tax cost, bracket use, IRMAA exposure, and legacy differences. Use when the user asks how different conversion policy modes may affect a complete plan. For a complete retirement checkup or any request connecting two or more retirement decisions, enforce four turn states: MISSING_INPUTS, READY_FOR_CONFIRMATION, CONFIRMED_BASELINE, and BASELINE_COMPLETE. Never invoke this tool in the same assistant turn as the user's initial plan details. A complete initial prompt is not confirmation of defaults. Any turn that supplies or corrects a fact remains intake even if it contains words such as no, yes, or correct; for example, a spouse having no income is a fact, not confirmation. After all required facts are known, first echo the complete supplied inputs and material defaults, say "No calculation has run," and ask the user to confirm them. Only a subsequent user turn that explicitly confirms that summary without adding or correcting facts authorizes the baseline call. During intake and confirmation, never state modeled readiness scores, success percentages, balances, runway, taxes, healthcare costs, or planning conclusions. A modeled financial result is valid only when grounded in structuredContent from a completed analytical tool call; if no analytical tool completed, do not produce forecast numbers. After presenting any plan-backed result, propose at most one next analysis and wait for a later user turn that explicitly approves that exact analysis. One confirmation authorizes one analytical tool call only; never chain another analytical tool in the same assistant turn. Outside a holistic checkup, the user's latest message may authorize this tool only when it explicitly requests this exact calculation and all required inputs are known. Use conservative unless the user selects another policy. The optimized policy considers modeled all-in marginal costs, including ACA subsidy effects before Medicare and Medicare IRMAA effects where applicable. Provide either planInput from retirement_forecast or all required flat inputs. If neither complete input set is available, ask for the missing values before invoking; do not call the tool with empty or guessed arguments. Use roth_explorer for a quick candidacy screen. Treat tax rates, ACA rules, and Medicare thresholds as assumptions and encourage review with a qualified tax professional before acting. This tool does not execute a conversion, save a plan, or create a handoff record.

roth_analysis

This quick explorer is only for one standalone directional question. A request for a complete or holistic retirement checkup, or any request that connects two or more decisions such as retirement age, Social Security, Roth conversion, healthcare, or Medicare, is not eligible for this tool even when it mentions this tool's topic. For those multi-decision requests, follow the retirement-checkup intake and confirmation workflow first; do not open any explorer during MISSING_INPUTS or READY_FOR_CONFIRMATION. This routing restriction takes priority over every topic keyword below. Use this when the user's only retirement question is whether to consider a Roth conversion, a possible low-income conversion window, or an explicit selection of this app for a standalone Roth conversion question. The required requestScope field is a routing assertion, not user data. Supply it only when the entire request is the standalone Roth-conversion question described above. Once that assertion is valid, call this tool with requestScope plus any known calculator inputs; its interactive UI collects missing calculator values before running the assessment. Never guess missing values. This heuristic does not calculate a tax return or direct an asset transfer. Use roth_analysis for an explicitly requested plan-backed comparison.

roth_explorer

Searches modeled Roth conversion schedules for the highest after-tax legacy value under the supplied retirement-plan assumptions. Use when the user explicitly asks to compare conversion schedules for that objective. For a complete retirement checkup or any request connecting two or more retirement decisions, enforce four turn states: MISSING_INPUTS, READY_FOR_CONFIRMATION, CONFIRMED_BASELINE, and BASELINE_COMPLETE. Never invoke this tool in the same assistant turn as the user's initial plan details. A complete initial prompt is not confirmation of defaults. Any turn that supplies or corrects a fact remains intake even if it contains words such as no, yes, or correct; for example, a spouse having no income is a fact, not confirmation. After all required facts are known, first echo the complete supplied inputs and material defaults, say "No calculation has run," and ask the user to confirm them. Only a subsequent user turn that explicitly confirms that summary without adding or correcting facts authorizes the baseline call. During intake and confirmation, never state modeled readiness scores, success percentages, balances, runway, taxes, healthcare costs, or planning conclusions. A modeled financial result is valid only when grounded in structuredContent from a completed analytical tool call; if no analytical tool completed, do not produce forecast numbers. After presenting any plan-backed result, propose at most one next analysis and wait for a later user turn that explicitly approves that exact analysis. One confirmation authorizes one analytical tool call only; never chain another analytical tool in the same assistant turn. Outside a holistic checkup, the user's latest message may authorize this tool only when it explicitly requests this exact calculation and all required inputs are known. Provide either planInput from retirement_forecast or all required flat inputs. If neither complete input set is available, ask for the missing values before invoking; do not call the tool with empty or guessed arguments. Describe the result as model-dependent, not universally optimal, and identify major tax, return, longevity, and Medicare assumptions. This tool does not execute a conversion, save a plan, or create a handoff record.

roth_optimize

Simulates a user-specified Roth conversion scenario, such as an annual dollar cap, age range, or target tax bracket, within a full retirement plan. Use only when the user gives or requests a specific conversion what-if. For a complete retirement checkup or any request connecting two or more retirement decisions, enforce four turn states: MISSING_INPUTS, READY_FOR_CONFIRMATION, CONFIRMED_BASELINE, and BASELINE_COMPLETE. Never invoke this tool in the same assistant turn as the user's initial plan details. A complete initial prompt is not confirmation of defaults. Any turn that supplies or corrects a fact remains intake even if it contains words such as no, yes, or correct; for example, a spouse having no income is a fact, not confirmation. After all required facts are known, first echo the complete supplied inputs and material defaults, say "No calculation has run," and ask the user to confirm them. Only a subsequent user turn that explicitly confirms that summary without adding or correcting facts authorizes the baseline call. During intake and confirmation, never state modeled readiness scores, success percentages, balances, runway, taxes, healthcare costs, or planning conclusions. A modeled financial result is valid only when grounded in structuredContent from a completed analytical tool call; if no analytical tool completed, do not produce forecast numbers. After presenting any plan-backed result, propose at most one next analysis and wait for a later user turn that explicitly approves that exact analysis. One confirmation authorizes one analytical tool call only; never chain another analytical tool in the same assistant turn. Outside a holistic checkup, the user's latest message may authorize this tool only when it explicitly requests this exact calculation and all required inputs are known. Provide either planInput from retirement_forecast or all required flat inputs, plus policyMode and any custom scenario fields. If neither complete input set is available, ask for the missing values before invoking; do not call the tool with empty or guessed arguments. Report modeled differences and assumptions without directing the user to make a transaction. This tool does not execute a conversion, save a plan, or create a handoff record.

roth_simulate

Compares Social Security claiming ages 62 through 70 within the user's full retirement plan, including modeled portfolio effects and breakeven timing. App-only: the NestPilot app calls this calculator after the user clicks inside the retirement checkup or a focused Social Security analysis. One retirement-age or Social Security claiming question uses start_retirement_checkup with focus when the user has given the plan facts, or asks for their plan, portfolio, spending, taxes, or a couple's joint claiming to be modeled; ask for any missing plan facts first. The same question with only a few facts and no request for plan modeling uses the matching explorer, open_retirement_age_explorer or open_social_security_explorer; after an explorer result, offer the focused analysis once, naming the facts it needs, and never open it unasked. The app provides either planInput from retirement_forecast or all required flat inputs. Do not call the tool with empty or guessed arguments. With flat inputs the result also lists every default applied (assumptionsApplied). Explain assumptions and trade-offs, including spouse and survivor considerations when applicable; do not present the result as an official SSA determination or personalized financial advice. This tool does not save a plan or create a handoff record.

social_security_analysis

This quick explorer is only for one standalone directional question. A request for a complete or holistic retirement checkup, or any request that connects two or more decisions such as retirement age, Social Security, Roth conversion, healthcare, or Medicare, is not eligible for this tool even when it mentions this tool's topic. For those multi-decision requests, follow the retirement-checkup intake and confirmation workflow first; do not open any explorer during MISSING_INPUTS or READY_FOR_CONFIRMATION. This routing restriction takes priority over every topic keyword below. App-only calculator behind open_social_security_explorer: the explorer widget calls it after the user clicks Compare claiming ages. The same question with only a few facts and no request for plan modeling uses the matching explorer, open_retirement_age_explorer or open_social_security_explorer; after an explorer result, offer the focused analysis once, naming the facts it needs, and never open it unasked. One retirement-age or Social Security claiming question uses start_retirement_checkup with focus when the user has given the plan facts, or asks for their plan, portfolio, spending, taxes, or a couple's joint claiming to be modeled; ask for any missing plan facts first. The required requestScope field is a routing assertion, not user data: the widget supplies it for a standalone Social Security claiming question, with the calculator inputs the user entered, and its interactive UI collects missing calculator values before running the calculation. Never guess missing values. The result ranks claim ages by lifetime total under an explicit longevity assumption, and reports the longevity at which that ranking flips (longevityBreakEven). The ranking is not a recommendation to claim at a particular age: it moves with assumedLongevity, so present it as a comparison, not a verdict. suggestedAge is null when the user is already past every claim age, or when no benefit estimate was supplied — do not substitute an age of your own in that case. This is an educational estimate, not an application for benefits.

social_security_explorer

Use this when the user asks for a complete retirement checkup or connects two or more retirement decisions such as readiness, retirement age, Social Security, and Roth conversions. Collect all known plan facts and open one persistent interactive review. This launcher performs no financial calculation. The user must review the displayed inputs and defaults and click Run baseline forecast. Each optional follow-up is then offered one at a time inside the same app, and runs only after its own button click. Never call retirement_forecast or an analysis tool directly for a new scan; those calculators are app-only executors.

start_retirement_checkup