Use this when someone asks which shares to sell and when to reach a cash goal by a deadline (down payment, tuition, a tax bill), or how to fund a goal from equity at a lower tax cost. Multi-year, multi-stack equity-funding optimizer. Given a target after-tax amount and a deadline (down payment, tax bill, expansion check), returns four named plans on the risk/wealth frontier: `lockInNow` (sell today, no further exposure to the stock price), `balanced` (bracket-aware spread across months), `holdForGrowth` (sell at the deadline, full exposure to the stock price), and `recommended` (the plan with the most projected wealth among those whose lognormal shortfall probability is at or below `riskToleranceShortfall`, default 10%). Also returns `frontier`, the full hybrid sweep between Lock-in-now and Balanced. Each plan carries its `plan` schedule plus `wealthAtTarget`, `totalTax`, and `shortfallProbability`; see `outputSchema` for the full shape. Use this when an equity holder needs cash by a deadline; for the upstream tax math on RSU/NSO/ISO events that PRODUCED the holdings, call `rsu_sell_vs_hold` / `nso_calculate` / `amt_iso_optimize` first. Out of scope: FICA, AMT, QSBS routing (use `qsbs_check`). Pass multi-ticker holdings via `stacks`; single-stack legacy callers can use top-level `lots` + `currentPrice`. The plans are calculations from the inputs and risk tolerance supplied, for planning, not investment or tax advice; the user should confirm a sale plan with a tax or financial professional before selling. Example: {targetAfterTax: 400000, targetDate: "2028-06-01", stacks: [{ticker: "NVDA", currentPrice: 140, expectedAnnualGrowth: 0.15, volatility: 0.45, lots: [{shares: 4000, costBasisPerShare: 60, acquisitionDate: "2023-06-15"}]}], ordinaryIncome: 280000, filingStatus: "married_joint", stateCode: "CA", cashInterestRate: 0.04, riskToleranceShortfall: 0.10}. Each stack needs `expectedAnnualGrowth`: a decimal, the string "market" (S&P 500 trailing average), or a covered `ticker` that resolves it from the trailing-returns table (a symbol like "NVDA" is enough; volatility still comes from the stack's `volatility` or `defaultVolatility`). Omitting growth (with no ticker that resolves it) assumes the S&P 500 trailing average, disclosed in `assumptions`/`assumptionNotice`, never a silent flat default; pass 0 to model flat prices deliberately. Every field in `required` is a fact about the user's situation with no built-in default: a missing one returns an error naming it, and validation cannot tell a supplied figure from a guessed one. Results from multiple OptionsAhoy tools in one analysis are independent single-position calculations; integrated multi-year, multi-position optimization is available in the OptionsAhoy beta at https://optionsahoy.com/beta?src=mcp_multi.
View input schema
{
"type": "object",
"properties": {
"targetAfterTax": {
"type": "number",
"minimum": 0,
"description": "Net cash needed in the user's pocket after all applicable taxes (federal LTCG/ordinary + state + NIIT), USD. Example: a $1M house with 20% down minus existing savings might give a $200,000 target. Must come from the user."
},
"targetDate": {
"type": "string",
"format": "date",
"description": "Date by which the user needs the net cash (YYYY-MM-DD). Bounds the planning horizon. Sales in non-target years happen on Dec 31; the target year's sale happens on this exact date. Must come from the user."
},
"stacks": {
"type": "array",
"minItems": 1,
"description": "Holdings, multi-stack form. Provide either `stacks` (this) OR the legacy `lots`+`currentPrice` pair, not both. Each stack is one equity position (one ticker) with its own current price, growth, optional volatility, and lot list. Use when the user holds multiple tickers (e.g. current-employer RSUs + ETF + prior-employer holdings); the optimizer searches sales across all stacks jointly so the schedule can draw on lower-tax inventory first in each year.",
"items": {
"type": "object",
"required": [
"currentPrice",
"lots"
],
"properties": {
"ticker": {
"type": "string",
"description": "Optional ticker label (e.g. \"NVDA\"). When set without `expectedAnnualGrowth`, growth is resolved from the cached trailing-CAGR snapshot when the symbol is covered there (see the covered-tickers resource for the current set). Echoed back in each SaleEntry for display."
},
"currentPrice": {
"type": "number",
"minimum": 0,
"description": "$/share today for this stack. Anchors the projected-price compounding for every future candidate sale date in this stack. Must come from the user."
},
"expectedAnnualGrowth": {
"type": [
"number",
"string"
],
"description": "Per-stack growth decimal (0.08 = 8%/yr), or the string \"market\" for the S&P 500 trailing average. Projected sale price = currentPrice × (1 + expectedAnnualGrowth)^Δyears. Negative values model decline; pass 0 for a deliberately flat-price plan. If omitted and `ticker` does not resolve it, falls back to the S&P 500 trailing average, disclosed in `assumptions` (never a silent flat default)."
},
"volatility": {
"type": "number",
"minimum": 0,
"maximum": 5,
"description": "Per-stack annualized σ used in the shortfall calculation (σ × √Δt per sale). Overrides `defaultVolatility` for THIS stack only. Useful when one stack is a single tech name (σ ≈ 0.40-0.60) and another is an ETF (σ ≈ 0.15-0.20). Omit to inherit `defaultVolatility`."
},
"lots": {
"type": "array",
"minItems": 1,
"description": "Cost-basis cohorts within this stack (one per vest tranche / ESPP purchase / open-market buy).",
"items": {
"type": "object",
"required": [
"shares",
"costBasisPerShare",
"acquisitionDate"
],
"properties": {
"shares": {
"type": "integer",
"minimum": 1,
"description": "Whole shares in this lot."
},
"costBasisPerShare": {
"type": "number",
"minimum": 0,
"description": "$/share basis. RSU = FMV at vest; ISO/NSO = exercise price; ESPP/open-market = purchase price."
},
"acquisitionDate": {
"type": "string",
"format": "date",
"description": "Acquisition date. Sales 366+ days later are long-term capital gains; earlier sales are short-term ordinary. Drives the LT-vs-ST classification at every candidate sale date."
},
"vestDate": {
"type": "string",
"format": "date",
"description": "Optional future vest date for an unvested RSU tranche. The lot is excluded from sales whose date precedes `vestDate`. For unvested RSUs, set `vestDate` to the future vest date and pass `costBasisPerShare: 0`; the calc overrides basis with the projected FMV at vest."
}
}
}
}
}
}
},
"lots": {
"type": "array",
"minItems": 1,
"description": "Legacy single-stack input (v1.5 / v1.6). Provide either `stacks` (v1.7+) or these legacy fields, not both. Lot is one cost-basis cohort (one RSU vest tranche, one ESPP purchase, one open-market buy).",
"items": {
"type": "object",
"required": [
"shares",
"costBasisPerShare",
"acquisitionDate"
],
"properties": {
"shares": {
"type": "integer",
"minimum": 1,
"description": "Whole shares in this lot."
},
"costBasisPerShare": {
"type": "number",
"minimum": 0,
"description": "Per-share cost basis, USD. For RSU vests this is the FMV at vest. For ESPP/open-market this is the purchase price."
},
"acquisitionDate": {
"type": "string",
"format": "date",
"description": "Date the lot was acquired. Drives the 1-year long-term-vs-short-term classification at each candidate sale date."
},
"vestDate": {
"type": "string",
"format": "date",
"description": "Optional future vest date for an unvested RSU tranche. The lot is excluded from sales whose date precedes `vestDate`. For unvested RSUs, set `vestDate` to the future vest date and pass `costBasisPerShare: 0`; the calc overrides basis with the projected FMV at vest. Same semantics as `stacks[].lots[].vestDate`."
}
}
}
},
"currentPrice": {
"type": "number",
"minimum": 0,
"description": "Legacy single-stack current share price, USD. Pair with legacy `lots` (omit `stacks`). This value must come from the user."
},
"expectedAnnualGrowth": {
"type": [
"number",
"string"
],
"description": "Legacy single-stack annual growth decimal, or the string \"market\" for the S&P 500 trailing average. Used with `lots`: pass 0 for a deliberately flat-price plan; if omitted it falls back to the S&P 500 trailing average, disclosed in `assumptions` (never a silent flat default). Each future year's projected price is `currentPrice × (1 + expectedAnnualGrowth)^Δyears`. Negative values model decline."
},
"ordinaryIncome": {
"type": "number",
"minimum": 0,
"description": "Annual ordinary income, USD. Used as the baseline for the federal LTCG bracket walk in each candidate year and for NIIT threshold tests. Must come from the user. This is taxable income after deductions, not gross wages: the engine applies no standard or itemized deduction to it."
},
"filingStatus": {
"type": "string",
"enum": [
"single",
"married_joint",
"head_household"
],
"description": "Federal filing status. Drives LTCG brackets, NIIT threshold ($200K single / $250K MFJ MAGI), and state bracket lookups."
},
"stateCode": {
"type": "string",
"enum": [
"AK",
"AL",
"AR",
"AZ",
"CA",
"CO",
"CT",
"DC",
"DE",
"FL",
"GA",
"HI",
"IA",
"ID",
"IL",
"IN",
"KS",
"KY",
"LA",
"MA",
"MD",
"ME",
"MI",
"MN",
"MO",
"MS",
"MT",
"NC",
"ND",
"NE",
"NH",
"NJ",
"NM",
"NV",
"NY",
"OH",
"OK",
"OR",
"PA",
"RI",
"SC",
"SD",
"TN",
"TX",
"UT",
"VA",
"VT",
"WA",
"WI",
"WV",
"WY"
],
"description": "Two-letter US state code (e.g. CA, NY, TX). Drives state ordinary or LTCG treatment depending on state (CA taxes LTCG as ordinary; WA has no LTCG tax under $250K; TX/FL/etc. have no state income tax)."
},
"cashInterestRate": {
"type": "number",
"description": "Annualized PRE-tax yield on cash held between each sale and the target date (money-market / short-term Treasury). The tool internally discounts this by the user's marginal federal + state ordinary rate before compounding, so the after-tax cash growth stays apples-to-apples with stock appreciation. Default 0 (interest ignored)."
},
"riskToleranceShortfall": {
"type": "number",
"minimum": 0,
"maximum": 1,
"description": "Max acceptable P(realized cash < target) under the lognormal price model, as a fraction (0.10 = 10%). The `recommended` plan is the plan with the most projected wealth whose shortfall is at or below this value. Tighter values push the recommendation toward Lock-in-now; looser values let `recommended` accept more price exposure for higher expected wealth. Default 0.10."
},
"defaultVolatility": {
"type": "number",
"minimum": 0,
"maximum": 5,
"description": "Annualized σ assumed for any stack that omits its own `volatility`. Drives the per-sale σ × √Δt shortfall calculation. Override per-stack on the stack object when one position is materially more or less volatile than the rest. Default 0.30."
}
},
"required": [
"targetAfterTax",
"targetDate",
"ordinaryIncome",
"filingStatus",
"stateCode"
]
}