Equity comp tax/trade optimizer: ISO/AMT exercise, NSO, RSU, QSBS, concentration, hedging. 50-state.
Maintain this server? Claim it
Call this server's tools from your browser. Nothing to install.
Requests go through mcptry because browsers can't call most MCP servers directly. Header values are sent to the server for that request only and are never stored or logged.
Tool list from our last check. Connect live to refresh it.
Use this when someone asks how or when to exercise incentive stock options (ISOs), whether exercising will trigger an AMT bomb or phantom income, whether to exercise early, how to plan around the alternative minimum tax (AMT) on an exercise, or how to spread ISO exercises across several years. Computes multi-year exercise schedules and compares them by after-tax Net Final Value (NFV) at the planning horizon. NFV is the after-all-tax cash equivalent of the position at year `horizon`, summing exercised shares (held to LTCG) plus the time-valued tax stream paid along the way; the search compares per-year share allocations by NFV. The headline result is `schedules.optimized.nfv`, the dollar NFV of the highest-scoring schedule found; `schedules.lumpSum` and `schedules.evenSplit` are baseline plans whose `nfv` deltas show the value added by the optimized schedule. For NSO grants use `nso_calculate`, for RSUs at vest use `rsu_sell_vs_hold`, for §1202 QSBS qualification use `qsbs_check`. Models AMT credit recovery across future years, grant-expiration timing, and the post-termination exercise window. Deterministic computation: federal + 50-state tax tables and AMT brackets are compiled in, and the only data read at call time is OptionsAhoy's own published market data for a `ticker`. Input values are not stored. `schedules.optimized` comes from searching the full discretized candidate space and refining share by share, and a published test case checks it against an exhaustive search (see https://optionsahoy.com/verification). `departedRecommendation`, when present, comes from a scan over candidate share counts rather than the full search. Also returns `crossoverShares`, `crossoverBargain`, `alreadyInAmt`, `timing`, `stateHasAmt`, `bargainPerShare`, and `effectiveHorizon`; see `outputSchema` for the full shape. Example call: {shares: 10000, strike: 2, fmv: 200, expectedGrowth: 0.15, volatility: 0.5, filingStatus: "married_joint", ordinaryIncome: 400000, stateCode: "CA", carryforwardCredit: 0, horizon: 4, cashReturnRate: 0.05, grantDate: "2022-01-15", hasLeftCompany: false, terminationDate: null}. Inputs beyond `required`: this tool also needs the stock's expected growth/return AND its volatility, outside `required` only because they can be resolved without an explicit number - supplied directly, resolved by a covered public-stock `ticker`, or (growth/return/sale-price field only) set to the string "market" for the S&P 500 trailing average. If growth/return/sale price is neither supplied nor resolved, the tool uses the S&P 500 trailing average; if volatility is neither, the median implied volatility of the public companies OptionsAhoy covers as of the last close. Either way the result reports it (`assumptions`, plus a plain-language `assumptionNotice` stating it is a placeholder, not the user's view). Every field in `required` is a fact about the user's situation with no built-in default; a number from any other source is accepted as-is, because a syntactically valid figure passes validation with no provenance check, and it silently changes the result. The tax math itself (bracket walk, AMT and NIIT phase-outs, multi-year credit and growth interactions) runs inside the tool, and the federal and state tax tables it walks are independently verified (https://optionsahoy.com/verification). 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.
Current fair market value per share, USD. Anchors year-1 of the growth path; future years compound from here using expectedGrowth and volatilityDrag. Must come from the user.
Total Incentive Stock Option (ISO) shares available to exercise across the planning horizon. Must come from the user.
Strike price per share, USD. Must come from the user.
Planning horizon in years (1..10). The optimizer searches all feasible per-year share allocations across this many years. The user's choice, not a modelling detail, and it changes the answer: use the value they gave, and if they gave none, ask for it rather than assuming one.
ISO grant date (YYYY-MM-DD). Drives the 10-year statutory grant expiration (IRC §422) and the 2-year qualifying-disposition threshold from grant.
Two-letter US state code (e.g. CA, NY, TX). Drives state ordinary brackets, state long-term capital gains (LTCG) treatment, and state AMT (CA, CO, CT, MN).
Federal filing status. Drives the ordinary-bracket walk, the AMT exemption tier ($90,100 single / $140,200 MFJ for 2026), and the AMT exemption phaseout start ($500,000 single / $1,000,000 MFJ).
True if the user has separated from the company. Activates the 90-day post-termination ISO exercise window measured from terminationDate.
Annual ordinary income before this exercise, USD. Baseline for the bracket walk and the AMT exemption phaseout. Must come from the user. This is taxable income after deductions, not gross wages: regular tax is figured on it as given. For the AMT the calculation adds the standard deduction back (Form 6251, line 2a), unless `itemizedTaxes` is given, in which case it adds back those taxes instead.
Optional public-stock symbol (e.g. "NVDA", "AAPL"). When set, the tool substitutes a cached trailing return for any unsupplied expected-return / sale-price field, and the implied vol as of the last close for any unsupplied volatility. Growth and vol come from different sources, so some symbols resolve only one, and a vol that is not current resolves as nothing. A field the ticker cannot resolve falls through to a "required field" error naming that field: pass it explicitly, or (for the growth/return/sale-price field) pass the string "market" for the S&P 500 trailing average; never invent a number. The covered-tickers resource (resources/list) lists which symbols resolve growth.
Annualized volatility (sigma) of the stock as a decimal (0.72 = 72%). Pass the volatility itself, not a pre-computed drag: the tool derives the horizon-cumulative drag internally, and the correct formula is horizon-dependent. Resolution order: this value if passed, else the `ticker`'s implied volatility as of the last market close, else the median implied volatility of the public companies OptionsAhoy covers, which the result reports in `assumptions` and `assumptionNotice`.
Only if you itemize deductions: the state and local taxes deducted on Schedule A, line 7. The AMT adds these back instead of the standard deduction. Omit if you take the standard deduction. When omitted, the AMT add-back defaults to the full standard deduction.
Annual after-tax return on idle cash (decimal), used to time-value the cash-tax stream. 0.05 = 5% (~short-Treasury yield). Optional: defaults to 0.04 (4%, a short-Treasury-like after-tax yield) when omitted, and an explicit value overrides that default. At 0 the math collapses to a nominal sum.
Annual expected stock growth as a decimal (0.10 = 10%), or the string "market" to use the S&P 500 trailing average when the user has no view. Required unless `ticker` resolves it from trailing CAGR. This tool has no default for it: a value not stated by the user, not resolved by a covered `ticker`, and not the "market" sentinel is outside the input contract.
Alternative to `volatility`: the multiplicative price haircut already computed for the planning horizon. Supply this OR `volatility` (if both are given, volatilityDrag wins). This field is for a drag figure that already exists from a prior computation; the drag formula is horizon-dependent, so a figure derived for a different horizon does not carry over. Supplying `volatility` instead lets the tool derive it.
Separation date (YYYY-MM-DD). Required only when hasLeftCompany=true (it drives the 90-day exercise-window deadline); omit it or pass null when still employed. No longer in `required` so the common employed case needs no placeholder.
Existing federal AMT credit (Minimum Tax Credit, Form 8801) carryforward from prior tax years, USD. Recoverable in future years where regular federal tax exceeds tentative minimum tax. Optional; defaults to 0, which is correct for most first-time exercisers. Only a prior-year AMT credit makes it non-zero.
Use this when someone asks how or when to exercise incentive stock options (ISOs), whether exercising will trigger an AMT bomb or phantom income, whether to exercise early, how to plan around the alternative minimum tax (AMT) on an exercise, or how to spread ISO exercises across several years. Computes multi-year exercise schedules and compares them by after-tax Net Final Value (NFV) at the planning horizon. NFV is the after-all-tax cash equivalent of the position at year `horizon`, summing exercised shares (held to LTCG) plus the time-valued tax stream paid along the way; the search compares per-year share allocations by NFV. The headline result is `schedules.optimized.nfv`, the dollar NFV of the highest-scoring schedule found; `schedules.lumpSum` and `schedules.evenSplit` are baseline plans whose `nfv` deltas show the value added by the optimized schedule. For NSO grants use `nso_calculate`, for RSUs at vest use `rsu_sell_vs_hold`, for §1202 QSBS qualification use `qsbs_check`. Models AMT credit recovery across future years, grant-expiration timing, and the post-termination exercise window. Deterministic computation: federal + 50-state tax tables and AMT brackets are compiled in, and the only data read at call time is OptionsAhoy's own published market data for a `ticker`. Input values are not stored. `schedules.optimized` comes from searching the full discretized candidate space and refining share by share, and a published test case checks it against an exhaustive search (see https://optionsahoy.com/verification). `departedRecommendation`, when present, comes from a scan over candidate share counts rather than the full search. Also returns `crossoverShares`, `crossoverBargain`, `alreadyInAmt`, `timing`, `stateHasAmt`, `bargainPerShare`, and `effectiveHorizon`; see `outputSchema` for the full shape. Example call: {shares: 10000, strike: 2, fmv: 200, expectedGrowth: 0.15, volatility: 0.5, filingStatus: "married_joint", ordinaryIncome: 400000, stateCode: "CA", carryforwardCredit: 0, horizon: 4, cashReturnRate: 0.05, grantDate: "2022-01-15", hasLeftCompany: false, terminationDate: null}. Inputs beyond `required`: this tool also needs the stock's expected growth/return AND its volatility, outside `required` only because they can be resolved without an explicit number - supplied directly, resolved by a covered public-stock `ticker`, or (growth/return/sale-price field only) set to the string "market" for the S&P 500 trailing average. If growth/return/sale price is neither supplied nor resolved, the tool uses the S&P 500 trailing average; if volatility is neither, the median implied volatility of the public companies OptionsAhoy covers as of the last close. Either way the result reports it (`assumptions`, plus a plain-language `assumptionNotice` stating it is a placeholder, not the user's view). Every field in `required` is a fact about the user's situation with no built-in default; a number from any other source is accepted as-is, because a syntactically valid figure passes validation with no provenance check, and it silently changes the result. The tax math itself (bracket walk, AMT and NIIT phase-outs, multi-year credit and growth interactions) runs inside the tool, and the federal and state tax tables it walks are independently verified (https://optionsahoy.com/verification). 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.
| Argument | Type | Description |
|---|---|---|
| fmv* | number | Current fair market value per share, USD. Anchors year-1 of the growth path; future years compound from here using expectedGrowth and volatilityDrag. Must come from the user. |
| shares* | integer | Total Incentive Stock Option (ISO) shares available to exercise across the planning horizon. Must come from the user. |
| strike* | number | Strike price per share, USD. Must come from the user. |
| ticker | string | Optional public-stock symbol (e.g. "NVDA", "AAPL"). When set, the tool substitutes a cached trailing return for any unsupplied expected-return / sale-price field, and the implied vol as of the last close for any unsupplied volatility. Growth and vol come from different sources, so some symbols resolve only one, and a vol that is not current resolves as nothing. A field the ticker cannot resolve falls through to a "required field" error naming that field: pass it explicitly, or (for the growth/return/sale-price field) pass the string "market" for the S&P 500 trailing average; never invent a number. The covered-tickers resource (resources/list) lists which symbols resolve growth. |
| horizon* | integer | Planning horizon in years (1..10). The optimizer searches all feasible per-year share allocations across this many years. The user's choice, not a modelling detail, and it changes the answer: use the value they gave, and if they gave none, ask for it rather than assuming one. |
| grantDate* | string | ISO grant date (YYYY-MM-DD). Drives the 10-year statutory grant expiration (IRC §422) and the 2-year qualifying-disposition threshold from grant. |
| stateCode |
Use this when someone asks how risky a large single-stock position is, whether too much of their net worth is in one stock, whether they are over-concentrated in a single name, or how to reduce or diversify a concentrated position. Single-stock concentration risk analysis on an existing position. For standalone hedge pricing use `protective_put_price`; for the tax math on the option exercise or RSU vest that created the concentration, route to `amt_iso_optimize` / `nso_calculate` / `rsu_sell_vs_hold` first. Quantifies drawdown exposure at 30/50/70% downside, then compares three after-tax strategies over a three-year horizon (sell-down to target weight, hold, hedge with put or zero-cost collar), accounting for federal LTCG, state tax, the 3.8% Net Investment Income Tax (NIIT), and reinvestment opportunity cost. `totalAssets` (concentrated position + everything else) frames risk relative to the whole portfolio. Returns a top-level object with keys: `concentration` (position/totalAssets), `riskBand` (Low / Moderate / Concentrated / Highly concentrated / Extreme), `isLongTermToday`, `longTermDate`, `daysUntilLongTerm`, `lossExposure` ({drop, dollarLoss, newConcentration} for 30/50/70% drops), `waitForLtInsight`, `schedule` (yearly sales with per-year tax), `hedging` ({kind, protectionLevel, tenorYears, strike, putPrice, callStrike, callPrice, netPremium, sigma, riskFreeRate} - a 1-year 30%-OTM put by default, or the structure named by `hedgeChoice`), `sectorContextLine`, `advisorBenchmarkLine`. Example call: {positionValue: 400000, costBasis: 100000, acquisitionDate: "2022-01-01", sector: "tech_software", stateCode: "CA", filingStatus: "single", ordinaryIncome: 200000, totalAssets: 1200000, volatility: 0.45, ticker: "NVDA"}. Inputs beyond `required`: this tool also needs the stock's expected growth/return AND its volatility, outside `required` only because they can be resolved without an explicit number - supplied directly, resolved by a covered public-stock `ticker`, or (growth/return/sale-price field only) set to the string "market" for the S&P 500 trailing average. If growth/return/sale price is neither supplied nor resolved, the tool uses the S&P 500 trailing average; if volatility is neither, the median implied volatility of the public companies OptionsAhoy covers as of the last close. Either way the result reports it (`assumptions`, plus a plain-language `assumptionNotice` stating it is a placeholder, not the user's view). Every field in `required` is a fact about the user's situation with no built-in default; a number from any other source is accepted as-is, because a syntactically valid figure passes validation with no provenance check, and it silently changes the result. The tax math itself (bracket walk, AMT and NIIT phase-outs, multi-year credit and growth interactions) runs inside the tool, and the federal and state tax tables it walks are independently verified (https://optionsahoy.com/verification). 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.
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`. 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 listed in `required` is a fact about the user's situation with no built-in default: a call missing a required field returns an error naming the field rather than an estimated result, and a number from any other source is accepted as-is, because a syntactically valid figure passes validation with no provenance check. The math runs inside the tool with no randomness and no model inference. 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.
Use this when someone asks whether to exercise and hold or exercise and sell non-qualified stock options (NSOs), about a cashless exercise or same-day sale of NSOs, or what tax an NSO exercise triggers. After-tax payout on a non-qualified stock option (NSO) exercise: federal, state, and FICA (Social Security + Medicare + Additional Medicare), comparing sell-at-exercise vs hold-for-long-term-capital-gains over the chosen horizon. Use for NSOs; for ISOs use `amt_iso_optimize`, for RSUs use `rsu_sell_vs_hold`. Deterministic, offline; tax tables compiled in. Optional `ticker` resolves `expectedSalePrice` from a bundled trailing-CAGR snapshot. Returns `exercise`, `hold`, `sellNowInvest` (the counterfactual: sell at exercise and reinvest at expectedMarketReturn), `holdMinusCashless` (the dollar delta between those two), and `bracketJump`; see `outputSchema` for the full shape. NSO hold is always long-term (sub-1-year is out of scope), so there is no separate long-term flag. Example call: {shares: 5000, strike: 10, currentPrice: 50, ordinaryIncome: 180000, filingStatus: "single", stateCode: "CA", stillEmployed: true, holdYears: 2, volatility: 0.3, holdFunding: "cash", ticker: "AAPL"}. Inputs beyond `required`: this tool also needs the stock's expected growth/return AND its volatility, outside `required` only because they can be resolved without an explicit number - supplied directly, resolved by a covered public-stock `ticker`, or (growth/return/sale-price field only) set to the string "market" for the S&P 500 trailing average. If growth/return/sale price is neither supplied nor resolved, the tool uses the S&P 500 trailing average; if volatility is neither, the median implied volatility of the public companies OptionsAhoy covers as of the last close. Either way the result reports it (`assumptions`, plus a plain-language `assumptionNotice` stating it is a placeholder, not the user's view). Every field in `required` is a fact about the user's situation with no built-in default; a number from any other source is accepted as-is, because a syntactically valid figure passes validation with no provenance check, and it silently changes the result. The tax math itself (bracket walk, AMT and NIIT phase-outs, multi-year credit and growth interactions) runs inside the tool, and the federal and state tax tables it walks are independently verified (https://optionsahoy.com/verification). 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.
Use this when someone asks how much it costs to hedge or protect a stock position against a drop, to protect gains, get downside protection, or limit losses on a position, or to price a protective put, a zero-cost collar, or a put spread. Closed-form pricing of a protective put, a zero-cost collar, and a put spread on a single-stock position. For concentration-vs-hedge tax-cost comparison, use `concentration_analyze` with a `hedgeChoice`. Parameter interactions: `volatility` omitted resolves from `ticker`, else a sector-typical implied volatility; an explicit sigma overrides it. For collars, omitting `upsideCapPct` lets the tool back-solve the cap that zeros the net premium (truly zero-cost collar); supplying `upsideCapPct` overrides the solver and yields a non-zero net premium when the cap is wider than zero-cost. `tenorYears` drives the risk-free-rate lookup AND the floor-hit / cap-hit probability metrics, so changing tenor shifts every probability output even at fixed strike. `expectedReturn` affects only the probability metrics (real-world drift in the floor-hit / cap-hit calculations); premium math is risk-neutral and ignores it (when a chain resolves it defaults to that stock's trailing annualized return, else to the sector's long-run return; never 0). `protectionLevel` sets the put strike as `(1 − protectionLevel) × spot`; raising it widens the protected zone but raises premium roughly linearly. `spreadRiskLevel` (default 0.10) sets the put spread's short strike by targeting the probability the stock ends below it; it affects only the `putSpread` block. The put spread finances the same floor with a short put at a lower strike (not a short call), so it is cheaper than the bare put and needs no shares to sell calls against, which makes it the one structure of the three that works on unexercised employee options; the trade-off is that protection stops at the short strike and losses resume below it. Closed-form and deterministic. With a `ticker` and no explicit `volatility`, each leg prices at its own strike's implied volatility off that stock's listed option chain as of the last close (`pricingMode` "chain-skew"); otherwise all legs price at one sigma ("flat"), understating out-of-the-money protection. Returns a top-level object with keys: `inputs` (echoed canonical input), `riskFreeRate` (used in option pricing), `realWorldDrift` (from expectedReturn), `barePut` (strike, premium, annualCost, annualCostPct, maxLoss, badYearPrice, badYearDropPct, coveredLossAtBadYear, premiumToCoveredRatio, expectedProfit, premiumToExpectedProfitRatio), `collar` (putStrike, callStrike, netPremium, annualCost, annualCostPct, maxLoss, upsideCap, upsideCapPct, isZeroCost, capProbability), `putSpread` (available, unavailableReason, longStrike, longPremium, shortStrike, shortPremium, shortSigma, netPremium, annualCost, annualCostPct, maxLossInBand, bandWidth, shortStrikeDropPct, breachProbability, riskLevel, savingsPct, coveredLossAtBadYear), `payoffTable`, `payoffRange`, and `recommended` (the structure, of collar / bare put / put spread, that the tool's comparison rule selects for these inputs, or none). When `putSpread.available` is false, `putSpread.unavailableReason` explains why that structure could not be priced. Example call: {positionValue: 400000, sector: "tech_software", protectionLevel: 0.10, tenorYears: 1, spreadRiskLevel: 0.10}. Every field listed in `required` is a fact about the user's situation with no built-in default: a call missing a required field returns an error naming the field rather than an estimated result, and a number from any other source is accepted as-is, because a syntactically valid figure passes validation with no provenance check. The math runs inside the tool with no randomness and no model inference. 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.
Use this when someone asks whether stock qualifies for the qualified small business stock (QSBS) / Section 1202 gain exclusion, whether their startup stock can be sold tax-free, about the 5-year QSBS holding period, or how much of the gain would be federal-tax-free. Section 1202 Qualified Small Business Stock (QSBS) qualification check. Use this tool for §1202 / QSBS qualification. For AMT timing on the ISO exercise that produced the QSBS holding, use `amt_iso_optimize` first. Parameter interactions: `entityType="other"` short-circuits the verdict to `disqualified` regardless of other fields; `acquisitionMethod="secondary"` does the same; `assetCategory="over-75m"` likewise fails immediately. Under `acquisitionMethod="gift-or-inheritance"` the holding period tacks from the original holder, so supply that earlier date as `acquisitionDate` if known. `acquisitionDate` drives era classification independent of holding period: before 2009-02-17 caps exclusion at 50%, 2009-02-17 to 2010-09-27 at 75%, 2010-09-28 through 2025-07-04 reaches 100% after a 5-year hold (pre-OBBBA), and 2025-07-05 onward uses the OBBBA tiered schedule (50% at 3y, 75% at 4y, 100% at 5y). The per-issuer exclusion cap is `max($10M, 10 × adjustedBasis)` ($15M base for stock acquired after July 4, 2025); when `expectedGain` exceeds it, the overage is fully taxable and the response surfaces `taxableGain` for that delta. `industry` is the dominant industry (>80% revenue) when the corp operates in multiple. Evaluates the six statutory tests: domestic C-corporation entity, original-issuance acquisition method, gross assets at issuance (under $50M / $50-75M / over $75M tiered cap), qualified-trade-or-business industry, active-business posture (80% asset use), and holding period (3 / 4 / 5-year tiers under OBBBA). Pure stateless check: no filing, reporting, or IRS lookup happens; the six tests are evaluated against the bundled OBBBA 2026 rule set and per-state conformity table. Returns a top-level object with keys: `verdict` (qualifies / partial / too-soon / caveats / disqualified), `exclusionPercent` (0..1), `perIssuerCap` and `tenXBasisCap` (the two cap inputs), `applicableCap` (max of the two), `excludableGain`, `taxableGain`, `federalTaxSaved` (LTCG bracket on the excluded gain), `stateConforms` (full / partial / none) and `stateNote` (per-state explanation), `holdingYears`, `yearsUntilFullExclusion`, `era` (pre-2009 / pre-2010 / pre-obbba / obbba), and `tests` (array of {id, label, status, detail} for each of the six statutory tests, identifying any gate that failed). Example call: {acquisitionDate: "2020-01-15", saleDate: "2026-06-01", entityType: "us-c-corp", acquisitionMethod: "original-issuance", assetCategory: "under-50m", industry: "tech-software", activeBusiness: "yes", adjustedBasis: 100000, expectedGain: 5000000, stateCode: "CA", ordinaryIncome: 250000, filingStatus: "single"}. Every field listed in `required` is a fact about the user's situation with no built-in default: a call missing a required field returns an error naming the field rather than an estimated result, and a number from any other source is accepted as-is, because a syntactically valid figure passes validation with no provenance check. The math runs inside the tool with no randomness and no model inference. 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. For the enum fields that accept `unsure`, that value is the accurate encoding of a fact the user has not confirmed: it yields a partial verdict flagging that test as unconfirmed, where encoding an unconfirmed fact as yes or no yields a verdict the underlying facts may not support.
Use this when someone asks which vested RSU lots to sell first, in which years, to divest part of a concentrated company-stock position, compared on total computed tax: "I want to sell down half my Amazon stock; which lots, and when?". Given the vested lots (vest date, shares, cost basis), a current price, and a divest fraction, it compares WHICH lots and WHICH sale dates to use, by computed total tax, to divest that many shares, using three levers: specific-lot identification (sell higher-basis lots to realize less gain, or underwater lots to harvest losses that net against gains), long-term deferral (wait past the one-year mark to convert short-term ordinary rates to long-term capital gains), and multi-year bracket spreading (split gains across 1 to 3 tax years, with in-plan capital-loss carryforward). Every sale is priced at today's price (flat-price assumption; there is no growth model). Returns the year-by-year sell schedule grouped by tax year, the total tax (federal LTCG + NIIT + state), what a first-in-first-out (FIFO) oldest-first sell order on the same schedule would have cost (`headlineDeltaVsFifo`), a 1/2/3-year horizon trade-off, and per-lot deferral callouts. This tool owns WHICH LOTS and WHICH DATES; for WHETHER and HOW MUCH to sell down a position use `concentration_analyze`, for a single new vest use `rsu_sell_vs_hold`, and to raise a specific cash amount by a deadline use `equity_funding_plan`. Out of scope: growth/return modeling, wash-sale basis migration, AMT, unvested grants. Example: {lots: [{vestDate: "2022-08-15", shares: 120, costBasisPerShare: 95}, {vestDate: "2024-02-15", shares: 100, costBasisPerShare: 130}, {vestDate: "2026-05-15", shares: 80, costBasisPerShare: 210}], currentPrice: 180, divestFraction: 0.5, horizonYears: 2, ordinaryIncome: 200000, filingStatus: "single", stateCode: "CA"}. Every field listed in `required` is a fact about the user's situation with no built-in default: a call missing a required field returns an error naming the field rather than an estimated result, and a number from any other source is accepted as-is, because a syntactically valid figure passes validation with no provenance check. The math runs inside the tool with no randomness and no model inference. 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.
Use this when someone asks whether to sell RSUs at vest or hold them, whether to sell their vested shares or diversify out of company stock, or about the tax and withholding on a restricted stock unit (RSU) vest. After-tax RSU vest analysis: sell-at-vest vs hold-to-long-term-capital-gains (LTCG) over `holdYears`. Covers federal ordinary tax, state tax, FICA (Social Security + Medicare + Additional Medicare), and the shortfall between mandatory 22% supplemental withholding and the user's marginal bracket. Use for RSUs at vest; for ISO/AMT use `amt_iso_optimize`, for NSO use `nso_calculate`. Deterministic and offline; tax tables compiled in. Returns `vest`, `hold`, `sellNowInvest`, `holdMinusSell`, and `bracketJump`; see `outputSchema` for the full shape. Example call: {shares: 1000, currentPrice: 100, ordinaryIncome: 200000, filingStatus: "single", stateCode: "CA", stillEmployed: true, holdYears: 2, volatility: 0.3, ticker: "MSFT"}. Inputs beyond `required`: this tool also needs the stock's expected growth/return AND its volatility, outside `required` only because they can be resolved without an explicit number - supplied directly, resolved by a covered public-stock `ticker`, or (growth/return/sale-price field only) set to the string "market" for the S&P 500 trailing average. If growth/return/sale price is neither supplied nor resolved, the tool uses the S&P 500 trailing average; if volatility is neither, the median implied volatility of the public companies OptionsAhoy covers as of the last close. Either way the result reports it (`assumptions`, plus a plain-language `assumptionNotice` stating it is a placeholder, not the user's view). Every field in `required` is a fact about the user's situation with no built-in default; a number from any other source is accepted as-is, because a syntactically valid figure passes validation with no provenance check, and it silently changes the result. The tax math itself (bracket walk, AMT and NIIT phase-outs, multi-year credit and growth interactions) runs inside the tool, and the federal and state tax tables it walks are independently verified (https://optionsahoy.com/verification). 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.
| string |
| Two-letter US state code (e.g. CA, NY, TX). Drives state ordinary brackets, state long-term capital gains (LTCG) treatment, and state AMT (CA, CO, CT, MN). |
| volatility | number | Annualized volatility (sigma) of the stock as a decimal (0.72 = 72%). Pass the volatility itself, not a pre-computed drag: the tool derives the horizon-cumulative drag internally, and the correct formula is horizon-dependent. Resolution order: this value if passed, else the `ticker`'s implied volatility as of the last market close, else the median implied volatility of the public companies OptionsAhoy covers, which the result reports in `assumptions` and `assumptionNotice`. |
| filingStatus* | string | Federal filing status. Drives the ordinary-bracket walk, the AMT exemption tier ($90,100 single / $140,200 MFJ for 2026), and the AMT exemption phaseout start ($500,000 single / $1,000,000 MFJ). |
| itemizedTaxes | number | Only if you itemize deductions: the state and local taxes deducted on Schedule A, line 7. The AMT adds these back instead of the standard deduction. Omit if you take the standard deduction. When omitted, the AMT add-back defaults to the full standard deduction. |
| cashReturnRate | number | Annual after-tax return on idle cash (decimal), used to time-value the cash-tax stream. 0.05 = 5% (~short-Treasury yield). Optional: defaults to 0.04 (4%, a short-Treasury-like after-tax yield) when omitted, and an explicit value overrides that default. At 0 the math collapses to a nominal sum. |
| expectedGrowth | number | string | Annual expected stock growth as a decimal (0.10 = 10%), or the string "market" to use the S&P 500 trailing average when the user has no view. Required unless `ticker` resolves it from trailing CAGR. This tool has no default for it: a value not stated by the user, not resolved by a covered `ticker`, and not the "market" sentinel is outside the input contract. |
| hasLeftCompany* | boolean | True if the user has separated from the company. Activates the 90-day post-termination ISO exercise window measured from terminationDate. |
| ordinaryIncome* | number | Annual ordinary income before this exercise, USD. Baseline for the bracket walk and the AMT exemption phaseout. Must come from the user. This is taxable income after deductions, not gross wages: regular tax is figured on it as given. For the AMT the calculation adds the standard deduction back (Form 6251, line 2a), unless `itemizedTaxes` is given, in which case it adds back those taxes instead. |
| volatilityDrag | number | Alternative to `volatility`: the multiplicative price haircut already computed for the planning horizon. Supply this OR `volatility` (if both are given, volatilityDrag wins). This field is for a drag figure that already exists from a prior computation; the drag formula is horizon-dependent, so a figure derived for a different horizon does not carry over. Supplying `volatility` instead lets the tool derive it. |
| terminationDate | any | Separation date (YYYY-MM-DD). Required only when hasLeftCompany=true (it drives the 90-day exercise-window deadline); omit it or pass null when still employed. No longer in `required` so the common employed case needs no placeholder. |
| carryforwardCredit | number | Existing federal AMT credit (Minimum Tax Credit, Form 8801) carryforward from prior tax years, USD. Recoverable in future years where regular federal tax exceeds tentative minimum tax. Optional; defaults to 0, which is correct for most first-time exercisers. Only a prior-year AMT credit makes it non-zero. |
{
"type": "object",
"required": [
"shares",
"strike",
"fmv",
"filingStatus",
"ordinaryIncome",
"stateCode",
"horizon",
"grantDate",
"hasLeftCompany"
],
"properties": {
"fmv": {
"type": "number",
"minimum": 0,
"description": "Current fair market value per share, USD. Anchors year-1 of the growth path; future years compound from here using expectedGrowth and volatilityDrag. Must come from the user."
},
"shares": {
"type": "integer",
"minimum": 1,
"description": "Total Incentive Stock Option (ISO) shares available to exercise across the planning horizon. Must come from the user."
},
"strike": {
"type": "number",
"minimum": 0,
"description": "Strike price per share, USD. Must come from the user."
},
"ticker": {
"type": "string",
"description": "Optional public-stock symbol (e.g. \"NVDA\", \"AAPL\"). When set, the tool substitutes a cached trailing return for any unsupplied expected-return / sale-price field, and the implied vol as of the last close for any unsupplied volatility. Growth and vol come from different sources, so some symbols resolve only one, and a vol that is not current resolves as nothing. A field the ticker cannot resolve falls through to a \"required field\" error naming that field: pass it explicitly, or (for the growth/return/sale-price field) pass the string \"market\" for the S&P 500 trailing average; never invent a number. The covered-tickers resource (resources/list) lists which symbols resolve growth."
},
"horizon": {
"type": "integer",
"maximum": 10,
"minimum": 1,
"description": "Planning horizon in years (1..10). The optimizer searches all feasible per-year share allocations across this many years. The user's choice, not a modelling detail, and it changes the answer: use the value they gave, and if they gave none, ask for it rather than assuming one."
},
"grantDate": {
"type": "string",
"format": "date",
"description": "ISO grant date (YYYY-MM-DD). Drives the 10-year statutory grant expiration (IRC §422) and the 2-year qualifying-disposition threshold from grant."
},
"stateCode": {
"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"
],
"type": "string",
"description": "Two-letter US state code (e.g. CA, NY, TX). Drives state ordinary brackets, state long-term capital gains (LTCG) treatment, and state AMT (CA, CO, CT, MN)."
},
"volatility": {
"type": "number",
"maximum": 5,
"minimum": 0,
"description": "Annualized volatility (sigma) of the stock as a decimal (0.72 = 72%). Pass the volatility itself, not a pre-computed drag: the tool derives the horizon-cumulative drag internally, and the correct formula is horizon-dependent. Resolution order: this value if passed, else the `ticker`'s implied volatility as of the last market close, else the median implied volatility of the public companies OptionsAhoy covers, which the result reports in `assumptions` and `assumptionNotice`."
},
"filingStatus": {
"enum": [
"single",
"married_joint",
"head_household"
],
"type": "string",
"description": "Federal filing status. Drives the ordinary-bracket walk, the AMT exemption tier ($90,100 single / $140,200 MFJ for 2026), and the AMT exemption phaseout start ($500,000 single / $1,000,000 MFJ)."
},
"itemizedTaxes": {
"type": "number",
"minimum": 0,
"description": "Only if you itemize deductions: the state and local taxes deducted on Schedule A, line 7. The AMT adds these back instead of the standard deduction. Omit if you take the standard deduction. When omitted, the AMT add-back defaults to the full standard deduction."
},
"cashReturnRate": {
"type": "number",
"description": "Annual after-tax return on idle cash (decimal), used to time-value the cash-tax stream. 0.05 = 5% (~short-Treasury yield). Optional: defaults to 0.04 (4%, a short-Treasury-like after-tax yield) when omitted, and an explicit value overrides that default. At 0 the math collapses to a nominal sum."
},
"expectedGrowth": {
"type": [
"number",
"string"
],
"description": "Annual expected stock growth as a decimal (0.10 = 10%), or the string \"market\" to use the S&P 500 trailing average when the user has no view. Required unless `ticker` resolves it from trailing CAGR. This tool has no default for it: a value not stated by the user, not resolved by a covered `ticker`, and not the \"market\" sentinel is outside the input contract."
},
"hasLeftCompany": {
"type": "boolean",
"description": "True if the user has separated from the company. Activates the 90-day post-termination ISO exercise window measured from terminationDate."
},
"ordinaryIncome": {
"type": "number",
"minimum": 0,
"description": "Annual ordinary income before this exercise, USD. Baseline for the bracket walk and the AMT exemption phaseout. Must come from the user. This is taxable income after deductions, not gross wages: regular tax is figured on it as given. For the AMT the calculation adds the standard deduction back (Form 6251, line 2a), unless `itemizedTaxes` is given, in which case it adds back those taxes instead."
},
"volatilityDrag": {
"type": "number",
"maximum": 0.99,
"minimum": 0,
"description": "Alternative to `volatility`: the multiplicative price haircut already computed for the planning horizon. Supply this OR `volatility` (if both are given, volatilityDrag wins). This field is for a drag figure that already exists from a prior computation; the drag formula is horizon-dependent, so a figure derived for a different horizon does not carry over. Supplying `volatility` instead lets the tool derive it."
},
"terminationDate": {
"oneOf": [
{
"type": "string",
"format": "date"
},
{
"type": "null"
}
],
"description": "Separation date (YYYY-MM-DD). Required only when hasLeftCompany=true (it drives the 90-day exercise-window deadline); omit it or pass null when still employed. No longer in `required` so the common employed case needs no placeholder."
},
"carryforwardCredit": {
"type": "number",
"minimum": 0,
"description": "Existing federal AMT credit (Minimum Tax Credit, Form 8801) carryforward from prior tax years, USD. Recoverable in future years where regular federal tax exceeds tentative minimum tax. Optional; defaults to 0, which is correct for most first-time exercisers. Only a prior-year AMT credit makes it non-zero."
}
}
}| Argument | Type | Description |
|---|---|---|
| sector* | string | Sector tag. Drives the default volatility used in the hedge-cost computation when no explicit volatility is provided (a sector-typical implied volatility). |
| ticker | string | Optional public-stock symbol (e.g. "NVDA", "AAPL"). When set, the tool substitutes a cached trailing return for any unsupplied expected-return / sale-price field, and the implied vol as of the last close for any unsupplied volatility. Growth and vol come from different sources, so some symbols resolve only one, and a vol that is not current resolves as nothing. A field the ticker cannot resolve falls through to a "required field" error naming that field: pass it explicitly, or (for the growth/return/sale-price field) pass the string "market" for the S&P 500 trailing average; never invent a number. The covered-tickers resource (resources/list) lists which symbols resolve growth. |
| costBasis* | number | Total cost basis of the position, USD (sum of strikes paid + ordinary-income inclusions on RSU vest / NSO exercise / disqualified ISO). Must come from the user. |
| stateCode* | string | Two-letter US state code. Drives state LTCG and ordinary brackets. |
| volatility | number | Annualized volatility (sigma) of the stock as a decimal (0.72 = 72%). Pass the volatility itself, not a pre-computed drag: the tool uses it both for hedge pricing (as implied vol) and for the 3y horizon drag, derived internally (the drag formula is horizon-dependent). Resolution order: this value if passed, else the `ticker`'s implied volatility as of the last market close, else the median implied volatility of the public companies OptionsAhoy covers, which the result reports in `assumptions` and `assumptionNotice`. When only `volatilityDrag` is given, hedge pricing uses a sector-typical implied volatility. |
| hedgeChoice | object | Optional hedge specification. When supplied, the `hedging` output block prices this exact structure (kind, protectionLevel, tenorYears, plus a short call for a collar) instead of the default 1-year 30%-OTM put; the sell-down-vs-hold schedule is unaffected. For full standalone hedge pricing (protective put / collar / put spread) use `protective_put_price`. |
| totalAssets* | number | Total investable portfolio in dollars (concentrated position + everything else). This value must come from the user, never inferred; if the user did not state it, ask. |
| filingStatus* | string | Federal filing status. Drives LTCG brackets and the NIIT MAGI threshold. |
| positionValue* | number | Current market value of the concentrated single-stock position, USD. Must come from the user. |
| ordinaryIncome* | number | Annual ordinary income before any sales, USD. Baseline for LTCG bracket determination. Must come from the user. This is taxable income after deductions, not gross wages: the engine applies no standard or itemized deduction to it. |
| volatilityDrag | number | Alternative to `volatility`: the multiplicative price haircut already computed for the horizon. Supply this OR `volatility` (if both are given, volatilityDrag wins). This field is for a drag figure that already exists from a prior computation; the drag formula is horizon-dependent, so a figure derived for a different horizon does not carry over. Supplying `volatility` instead lets the tool derive it. |
| acquisitionDate* | string | Earliest acquisition date in the lot (YYYY-MM-DD). Drives the 1-year LTCG threshold and the long-term-vs-short-term tax routing. |
| expectedMarketReturn | number | string | Annual after-tax-proceeds reinvestment rate. Defaults to SPY trailing CAGR for the 3-year horizon if omitted; the string "market" names that same default explicitly. |
| expectedPositionReturn | number | string | Annual expected return on the concentrated stock as a decimal (0.10 = 10%), or the string "market" to use the S&P 500 trailing average when the user has no view. Required unless `ticker` resolves it from trailing CAGR. This tool has no default for it: a value not stated by the user, not resolved by a covered `ticker`, and not the "market" sentinel is outside the input contract. |
{
"type": "object",
"required": [
"positionValue",
"costBasis",
"acquisitionDate",
"sector",
"stateCode",
"filingStatus",
"ordinaryIncome",
"totalAssets"
],
"properties": {
"sector": {
"enum": [
"tech_software",
"semiconductors",
"consumer_cyclical",
"consumer_defensive",
"financials",
"healthcare_biotech",
"energy",
"industrials",
"communication",
"broad_market"
],
"type": "string",
"description": "Sector tag. Drives the default volatility used in the hedge-cost computation when no explicit volatility is provided (a sector-typical implied volatility)."
},
"ticker": {
"type": "string",
"description": "Optional public-stock symbol (e.g. \"NVDA\", \"AAPL\"). When set, the tool substitutes a cached trailing return for any unsupplied expected-return / sale-price field, and the implied vol as of the last close for any unsupplied volatility. Growth and vol come from different sources, so some symbols resolve only one, and a vol that is not current resolves as nothing. A field the ticker cannot resolve falls through to a \"required field\" error naming that field: pass it explicitly, or (for the growth/return/sale-price field) pass the string \"market\" for the S&P 500 trailing average; never invent a number. The covered-tickers resource (resources/list) lists which symbols resolve growth."
},
"costBasis": {
"type": "number",
"minimum": 0,
"description": "Total cost basis of the position, USD (sum of strikes paid + ordinary-income inclusions on RSU vest / NSO exercise / disqualified ISO). Must come from the user."
},
"stateCode": {
"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"
],
"type": "string",
"description": "Two-letter US state code. Drives state LTCG and ordinary brackets."
},
"volatility": {
"type": "number",
"maximum": 5,
"minimum": 0,
"description": "Annualized volatility (sigma) of the stock as a decimal (0.72 = 72%). Pass the volatility itself, not a pre-computed drag: the tool uses it both for hedge pricing (as implied vol) and for the 3y horizon drag, derived internally (the drag formula is horizon-dependent). Resolution order: this value if passed, else the `ticker`'s implied volatility as of the last market close, else the median implied volatility of the public companies OptionsAhoy covers, which the result reports in `assumptions` and `assumptionNotice`. When only `volatilityDrag` is given, hedge pricing uses a sector-typical implied volatility."
},
"hedgeChoice": {
"type": "object",
"required": [
"kind",
"protectionLevel",
"tenorYears"
],
"properties": {
"kind": {
"enum": [
"put",
"collar"
],
"type": "string",
"description": "Hedge instrument: 'put' (bare protective put, pay premium for downside protection) or 'collar' (put financed by a short call, caps upside in exchange for lower or zero net premium)."
},
"tenorYears": {
"type": "number",
"minimum": 0.25,
"description": "Option tenor in years. 1 = 12-month; 0.25 = ~90-day. The user's choice, not a modelling detail, and it changes the answer: use the value they gave, and if they gave none, ask for it rather than assuming one."
},
"upsideCapPct": {
"type": "number",
"description": "For collars only: optional explicit upside cap as fraction above spot (e.g. 0.20 = 20% cap). Omit to let the tool solve for the cap that makes the collar zero-net-premium."
},
"protectionLevel": {
"type": "number",
"maximum": 0.5,
"minimum": 0.05,
"description": "Put strike chosen as (1 − this fraction) × spot. 0.10 = 10% OTM put. Range 0.05..0.50. The user's choice, not a modelling detail, and it changes the answer: use the value they gave, and if they gave none, ask for it rather than assuming one."
}
},
"description": "Optional hedge specification. When supplied, the `hedging` output block prices this exact structure (kind, protectionLevel, tenorYears, plus a short call for a collar) instead of the default 1-year 30%-OTM put; the sell-down-vs-hold schedule is unaffected. For full standalone hedge pricing (protective put / collar / put spread) use `protective_put_price`."
},
"totalAssets": {
"type": "number",
"minimum": 0,
"description": "Total investable portfolio in dollars (concentrated position + everything else). This value must come from the user, never inferred; if the user did not state it, ask."
},
"filingStatus": {
"enum": [
"single",
"married_joint",
"head_household"
],
"type": "string",
"description": "Federal filing status. Drives LTCG brackets and the NIIT MAGI threshold."
},
"positionValue": {
"type": "number",
"minimum": 0,
"description": "Current market value of the concentrated single-stock position, USD. Must come from the user."
},
"ordinaryIncome": {
"type": "number",
"minimum": 0,
"description": "Annual ordinary income before any sales, USD. Baseline for LTCG bracket determination. Must come from the user. This is taxable income after deductions, not gross wages: the engine applies no standard or itemized deduction to it."
},
"volatilityDrag": {
"type": "number",
"maximum": 0.99,
"minimum": 0,
"description": "Alternative to `volatility`: the multiplicative price haircut already computed for the horizon. Supply this OR `volatility` (if both are given, volatilityDrag wins). This field is for a drag figure that already exists from a prior computation; the drag formula is horizon-dependent, so a figure derived for a different horizon does not carry over. Supplying `volatility` instead lets the tool derive it."
},
"acquisitionDate": {
"type": "string",
"format": "date",
"description": "Earliest acquisition date in the lot (YYYY-MM-DD). Drives the 1-year LTCG threshold and the long-term-vs-short-term tax routing."
},
"expectedMarketReturn": {
"type": [
"number",
"string"
],
"description": "Annual after-tax-proceeds reinvestment rate. Defaults to SPY trailing CAGR for the 3-year horizon if omitted; the string \"market\" names that same default explicitly."
},
"expectedPositionReturn": {
"type": [
"number",
"string"
],
"description": "Annual expected return on the concentrated stock as a decimal (0.10 = 10%), or the string \"market\" to use the S&P 500 trailing average when the user has no view. Required unless `ticker` resolves it from trailing CAGR. This tool has no default for it: a value not stated by the user, not resolved by a covered `ticker`, and not the \"market\" sentinel is outside the input contract."
}
}
}| Argument | Type | Description |
|---|---|---|
| lots | array | 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). |
| stacks | array | 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. |
| stateCode* | string | 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). |
| targetDate* | string | 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. |
| currentPrice | number | Legacy single-stack current share price, USD. Pair with legacy `lots` (omit `stacks`). This value must come from the user. |
| filingStatus* | string | Federal filing status. Drives LTCG brackets, NIIT threshold ($200K single / $250K MFJ MAGI), and state bracket lookups. |
| ordinaryIncome* | number | 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. |
| targetAfterTax* | number | 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. |
| cashInterestRate | number | 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). |
| defaultVolatility | number | 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. |
| expectedAnnualGrowth | number | string | 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. |
| riskToleranceShortfall | number | 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. |
{
"type": "object",
"required": [
"targetAfterTax",
"targetDate",
"ordinaryIncome",
"filingStatus",
"stateCode"
],
"properties": {
"lots": {
"type": "array",
"items": {
"type": "object",
"required": [
"shares",
"costBasisPerShare",
"acquisitionDate"
],
"properties": {
"shares": {
"type": "integer",
"minimum": 1,
"description": "Whole shares in this lot."
},
"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`."
},
"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."
},
"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."
}
}
},
"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)."
},
"stacks": {
"type": "array",
"items": {
"type": "object",
"required": [
"currentPrice",
"lots"
],
"properties": {
"lots": {
"type": "array",
"items": {
"type": "object",
"required": [
"shares",
"costBasisPerShare",
"acquisitionDate"
],
"properties": {
"shares": {
"type": "integer",
"minimum": 1,
"description": "Whole shares in this lot."
},
"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."
},
"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."
},
"costBasisPerShare": {
"type": "number",
"minimum": 0,
"description": "$/share basis. RSU = FMV at vest; ISO/NSO = exercise price; ESPP/open-market = purchase price."
}
}
},
"minItems": 1,
"description": "Cost-basis cohorts within this stack (one per vest tranche / ESPP purchase / open-market buy)."
},
"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."
},
"volatility": {
"type": "number",
"maximum": 5,
"minimum": 0,
"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`."
},
"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)."
}
}
},
"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."
},
"stateCode": {
"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"
],
"type": "string",
"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)."
},
"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."
},
"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."
},
"filingStatus": {
"enum": [
"single",
"married_joint",
"head_household"
],
"type": "string",
"description": "Federal filing status. Drives LTCG brackets, NIIT threshold ($200K single / $250K MFJ MAGI), and state bracket lookups."
},
"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."
},
"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."
},
"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)."
},
"defaultVolatility": {
"type": "number",
"maximum": 5,
"minimum": 0,
"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."
},
"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."
},
"riskToleranceShortfall": {
"type": "number",
"maximum": 1,
"minimum": 0,
"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."
}
}
}| Argument | Type | Description |
|---|---|---|
| shares* | integer | Non-qualified Stock Option (NSO) shares to exercise. Must come from the user. |
| strike* | number | Strike price per share, USD. Must come from the user. |
| ticker | string | Optional public-stock symbol (e.g. "NVDA", "AAPL"). When set, the tool substitutes a cached trailing return for any unsupplied expected-return / sale-price field, and the implied vol as of the last close for any unsupplied volatility. Growth and vol come from different sources, so some symbols resolve only one, and a vol that is not current resolves as nothing. A field the ticker cannot resolve falls through to a "required field" error naming that field: pass it explicitly, or (for the growth/return/sale-price field) pass the string "market" for the S&P 500 trailing average; never invent a number. The covered-tickers resource (resources/list) lists which symbols resolve growth. |
| haircut | number | Alternative to `volatility`: the multiplicative volatility-drag haircut on expectedSalePrice already computed for the hold. Supply this OR `volatility` (if both are given, haircut wins). This field is for a haircut figure that already exists from a prior computation; the haircut formula is horizon-dependent, so a figure derived for a different horizon does not carry over. Supplying `volatility` instead lets the tool derive it. |
| holdYears* | number | Years to hold after exercise (minimum 1). At ≥1 year, the appreciation since exercise is LTCG; sub-1-year holds are out of scope. The user's choice, not a modelling detail, and it changes the answer: use the value they gave, and if they gave none, ask for it rather than assuming one. |
| stateCode* | string | Two-letter US state code. Drives state ordinary and LTCG treatment. |
| volatility | number | Annualized volatility (sigma) of the stock as a decimal (0.72 = 72%). Pass the volatility itself, not a pre-computed drag: the tool derives the horizon-cumulative drag internally, and the correct formula is horizon-dependent. Resolution order: this value if passed, else the `ticker`'s implied volatility as of the last market close, else the median implied volatility of the public companies OptionsAhoy covers, which the result reports in `assumptions` and `assumptionNotice`. |
| holdFunding* | string | How the strike cost and exercise tax are funded. 'sell-to-cover' sells enough shares to cover strike + tax (reduces sharesRetained). 'cash' pays strike + tax from outside funds (full sharesRetained); no extra input is needed - the result reports the outside cash required as the output field cashNeededAtExercise. |
| currentPrice* | number | Current fair market value per share, USD. The bargain element at exercise is shares × (currentPrice − strike). Must come from the user. |
| filingStatus* | string | Federal filing status. Drives ordinary brackets and LTCG brackets used at the hold horizon. |
| stillEmployed* | boolean | True if still employed at exercise. FICA (Social Security + Medicare + Additional Medicare) applies only when true. |
| ordinaryIncome* | number | Annual ordinary income before this exercise, USD. Baseline for the bracket walk on the bargain element. Must come from the user. This is taxable income after deductions, not gross wages: the engine applies no standard or itemized deduction to it. |
| expectedSalePrice | number | string | Projected $/share at end of holdYears, or the string "market" to project currentPrice at the S&P 500 trailing average when the user has no view. Required unless `ticker` resolves it from currentPrice × (1 + trailing CAGR)^holdYears. This tool has no default for it: a value not stated by the user, not resolved by a covered `ticker`, and not the "market" sentinel is outside the input contract. |
| expectedMarketReturn | number | string | Annual after-tax-proceeds reinvestment rate. Defaults to SPY trailing CAGR for holdYears if omitted; the string "market" names that same default explicitly. |
{
"type": "object",
"required": [
"shares",
"strike",
"currentPrice",
"ordinaryIncome",
"filingStatus",
"stateCode",
"stillEmployed",
"holdYears",
"holdFunding"
],
"properties": {
"shares": {
"type": "integer",
"minimum": 1,
"description": "Non-qualified Stock Option (NSO) shares to exercise. Must come from the user."
},
"strike": {
"type": "number",
"minimum": 0,
"description": "Strike price per share, USD. Must come from the user."
},
"ticker": {
"type": "string",
"description": "Optional public-stock symbol (e.g. \"NVDA\", \"AAPL\"). When set, the tool substitutes a cached trailing return for any unsupplied expected-return / sale-price field, and the implied vol as of the last close for any unsupplied volatility. Growth and vol come from different sources, so some symbols resolve only one, and a vol that is not current resolves as nothing. A field the ticker cannot resolve falls through to a \"required field\" error naming that field: pass it explicitly, or (for the growth/return/sale-price field) pass the string \"market\" for the S&P 500 trailing average; never invent a number. The covered-tickers resource (resources/list) lists which symbols resolve growth."
},
"haircut": {
"type": "number",
"maximum": 1,
"minimum": 0,
"description": "Alternative to `volatility`: the multiplicative volatility-drag haircut on expectedSalePrice already computed for the hold. Supply this OR `volatility` (if both are given, haircut wins). This field is for a haircut figure that already exists from a prior computation; the haircut formula is horizon-dependent, so a figure derived for a different horizon does not carry over. Supplying `volatility` instead lets the tool derive it."
},
"holdYears": {
"type": "number",
"minimum": 1,
"description": "Years to hold after exercise (minimum 1). At ≥1 year, the appreciation since exercise is LTCG; sub-1-year holds are out of scope. The user's choice, not a modelling detail, and it changes the answer: use the value they gave, and if they gave none, ask for it rather than assuming one."
},
"stateCode": {
"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"
],
"type": "string",
"description": "Two-letter US state code. Drives state ordinary and LTCG treatment."
},
"volatility": {
"type": "number",
"maximum": 5,
"minimum": 0,
"description": "Annualized volatility (sigma) of the stock as a decimal (0.72 = 72%). Pass the volatility itself, not a pre-computed drag: the tool derives the horizon-cumulative drag internally, and the correct formula is horizon-dependent. Resolution order: this value if passed, else the `ticker`'s implied volatility as of the last market close, else the median implied volatility of the public companies OptionsAhoy covers, which the result reports in `assumptions` and `assumptionNotice`."
},
"holdFunding": {
"enum": [
"sell-to-cover",
"cash"
],
"type": "string",
"description": "How the strike cost and exercise tax are funded. 'sell-to-cover' sells enough shares to cover strike + tax (reduces sharesRetained). 'cash' pays strike + tax from outside funds (full sharesRetained); no extra input is needed - the result reports the outside cash required as the output field cashNeededAtExercise."
},
"currentPrice": {
"type": "number",
"minimum": 0,
"description": "Current fair market value per share, USD. The bargain element at exercise is shares × (currentPrice − strike). Must come from the user."
},
"filingStatus": {
"enum": [
"single",
"married_joint",
"head_household"
],
"type": "string",
"description": "Federal filing status. Drives ordinary brackets and LTCG brackets used at the hold horizon."
},
"stillEmployed": {
"type": "boolean",
"description": "True if still employed at exercise. FICA (Social Security + Medicare + Additional Medicare) applies only when true."
},
"ordinaryIncome": {
"type": "number",
"minimum": 0,
"description": "Annual ordinary income before this exercise, USD. Baseline for the bracket walk on the bargain element. Must come from the user. This is taxable income after deductions, not gross wages: the engine applies no standard or itemized deduction to it."
},
"expectedSalePrice": {
"type": [
"number",
"string"
],
"minimum": 0,
"description": "Projected $/share at end of holdYears, or the string \"market\" to project currentPrice at the S&P 500 trailing average when the user has no view. Required unless `ticker` resolves it from currentPrice × (1 + trailing CAGR)^holdYears. This tool has no default for it: a value not stated by the user, not resolved by a covered `ticker`, and not the \"market\" sentinel is outside the input contract."
},
"expectedMarketReturn": {
"type": [
"number",
"string"
],
"description": "Annual after-tax-proceeds reinvestment rate. Defaults to SPY trailing CAGR for holdYears if omitted; the string \"market\" names that same default explicitly."
}
}
}| Argument | Type | Description |
|---|---|---|
| sector* | string | Sector tag. Drives the default volatility when no explicit `volatility` is supplied (a sector-typical implied volatility). |
| ticker | string | Optional public-stock symbol (e.g. "NVDA"). When set without an explicit `volatility`, each leg prices at its own strike's chain-implied vol, else at its at-the-money vol as of the last close, else the sector default. Echoed to `tickerLabel` in the response. |
| tenorYears* | number | Option tenor in years. 1 = 12-month; 0.25 = ~90-day. The user's choice, not a modelling detail, and it changes the answer: use the value they gave, and if they gave none, ask for it rather than assuming one. |
| volatility | number | Annualized implied volatility (sigma) of the stock. Resolution order: (1) explicit `volatility` if passed; (2) the `ticker`'s implied vol as of the last close; (3) sector-typical IV as last fallback. An explicit value must come from the user; otherwise set a covered `ticker`, or omit and let the sector default apply. |
| tickerLabel | string | Optional display string echoed back in the result. Not used in pricing. |
| positionValue* | number | Market value of the underlying single-stock position, USD. Premium and max-loss scale linearly with this. Must come from the user. |
| expectedReturn | number | Annual expected stock return (decimal). Drives the real-world drift in the cap-hit / floor-hit probability metrics. Does not affect premium math. Default 0. |
| protectionLevel* | number | Put strike as (1 − this fraction) × spot. 0.10 = 10% OTM put. Range 0.05..0.50. The user's choice, not a modelling detail, and it changes the answer: use the value they gave, and if they gave none, ask for it rather than assuming one. |
| spreadRiskLevel | number | Put-spread floor breach risk: target probability the stock ENDS below the spread's short (lower) strike at expiration. Presets 0.20 / 0.10 / 0.05 / 0.01 ("1 in 5 / 10 / 20 / 100"); off-preset values snap to the nearest. A lower value pushes the short strike deeper, widening the protected band and raising the net premium toward the bare put. Only affects the `putSpread` block. Default 0.10. |
{
"type": "object",
"required": [
"positionValue",
"sector",
"protectionLevel",
"tenorYears"
],
"properties": {
"sector": {
"enum": [
"tech_software",
"semiconductors",
"consumer_cyclical",
"consumer_defensive",
"financials",
"healthcare_biotech",
"energy",
"industrials",
"communication",
"broad_market"
],
"type": "string",
"description": "Sector tag. Drives the default volatility when no explicit `volatility` is supplied (a sector-typical implied volatility)."
},
"ticker": {
"type": "string",
"description": "Optional public-stock symbol (e.g. \"NVDA\"). When set without an explicit `volatility`, each leg prices at its own strike's chain-implied vol, else at its at-the-money vol as of the last close, else the sector default. Echoed to `tickerLabel` in the response."
},
"tenorYears": {
"type": "number",
"minimum": 0.25,
"description": "Option tenor in years. 1 = 12-month; 0.25 = ~90-day. The user's choice, not a modelling detail, and it changes the answer: use the value they gave, and if they gave none, ask for it rather than assuming one."
},
"volatility": {
"type": "number",
"maximum": 5,
"minimum": 0,
"description": "Annualized implied volatility (sigma) of the stock. Resolution order: (1) explicit `volatility` if passed; (2) the `ticker`'s implied vol as of the last close; (3) sector-typical IV as last fallback. An explicit value must come from the user; otherwise set a covered `ticker`, or omit and let the sector default apply."
},
"tickerLabel": {
"type": "string",
"description": "Optional display string echoed back in the result. Not used in pricing."
},
"positionValue": {
"type": "number",
"minimum": 0,
"description": "Market value of the underlying single-stock position, USD. Premium and max-loss scale linearly with this. Must come from the user."
},
"expectedReturn": {
"type": "number",
"description": "Annual expected stock return (decimal). Drives the real-world drift in the cap-hit / floor-hit probability metrics. Does not affect premium math. Default 0."
},
"protectionLevel": {
"type": "number",
"maximum": 0.5,
"minimum": 0.05,
"description": "Put strike as (1 − this fraction) × spot. 0.10 = 10% OTM put. Range 0.05..0.50. The user's choice, not a modelling detail, and it changes the answer: use the value they gave, and if they gave none, ask for it rather than assuming one."
},
"spreadRiskLevel": {
"type": "number",
"maximum": 0.2,
"minimum": 0.01,
"description": "Put-spread floor breach risk: target probability the stock ENDS below the spread's short (lower) strike at expiration. Presets 0.20 / 0.10 / 0.05 / 0.01 (\"1 in 5 / 10 / 20 / 100\"); off-preset values snap to the nearest. A lower value pushes the short strike deeper, widening the protected band and raising the net premium toward the bare put. Only affects the `putSpread` block. Default 0.10."
}
}
}| Argument | Type | Description |
|---|---|---|
| industry* | string | §1202 Test 4: Industry classification of the corporation. Four values qualify: tech-software, manufacturing, biotech-research, retail-wholesale. Specified service trades or businesses (law, engineering, architecture, accounting-actuarial, consulting, finance, health-services, performing-arts) do NOT qualify, and farming, extraction and hospitality are separately excluded, so they do not qualify either. other-services and unsure return a caveated verdict rather than a pass or fail. |
| saleDate* | string | Planned or actual sale date (YYYY-MM-DD). Together with acquisitionDate determines holdingYears. |
| stateCode* | string | Two-letter US state code. Drives the state-conformity verdict: CA/AL/PA/MS do not conform (full state tax owed); HI/MA partial; NJ 2026-01-01 conformity switch; most others fully conform. |
| entityType* | string | §1202 Test 1: Type of issuer at the time of acquisition. Only 'us-c-corp' qualifies. S-corps, LLCs, partnerships, and foreign entities fail. |
| expectedGain* | number | Expected total gain on sale, USD. Compared against the per-issuer exclusion cap to compute excludableGain and taxableGain. Must come from the user. |
| filingStatus* | string | Federal filing status. Drives the LTCG bracket on any non-excluded gain and the NIIT MAGI threshold. |
| adjustedBasis* | number | Adjusted basis of the QSBS shares, USD. Used in the 10× basis cap: the per-issuer exclusion cap is max($10M, 10 × adjustedBasis). Must come from the user. |
| assetCategory* | string | §1202 Test 3: Aggregate gross assets of the issuing corporation at the time of issuance. 'under-50m' qualifies pre-OBBBA. '50m-to-75m' qualifies ONLY under OBBBA 2026+ (post-2025-07-05). 'over-75m' never qualifies. 'unsure' returns a partial verdict. |
| activeBusiness* | string | §1202 Test 5: Did the corporation use ≥80% of its assets in the active conduct of a qualified trade throughout the holding period? 'yes' qualifies. 'no' fails. 'unsure' returns a partial verdict (user should confirm with their CFO). |
| ordinaryIncome* | number | Annual ordinary income, USD. Baseline for the federal LTCG bracket on any taxable gain. Must come from the user. This is taxable income after deductions, not gross wages: the engine applies no standard or itemized deduction to it. |
| acquisitionDate* | string | Date the QSBS shares were acquired (YYYY-MM-DD). Drives the holding-period test and the era classification (50% pre-2009 era, 75% pre-2010 era, 100% after a 5-year hold for acquisitions from 2010-09-28 through 2025-07-04, OBBBA tiered after 2025-07-05). |
| acquisitionMethod* | string | §1202 Test 2: How the user obtained the shares. 'original-issuance' (direct from the company) qualifies. 'gift-or-inheritance' tacks the original holder's basis and clock. 'secondary' (bought on a secondary market) does NOT qualify. 'unsure' triggers a partial verdict. |
{
"type": "object",
"required": [
"acquisitionDate",
"saleDate",
"entityType",
"acquisitionMethod",
"assetCategory",
"industry",
"activeBusiness",
"adjustedBasis",
"expectedGain",
"stateCode",
"ordinaryIncome",
"filingStatus"
],
"properties": {
"industry": {
"enum": [
"tech-software",
"manufacturing",
"biotech-research",
"retail-wholesale",
"health-services",
"law",
"engineering",
"architecture",
"accounting-actuarial",
"consulting",
"finance",
"farming",
"extraction",
"hospitality",
"performing-arts",
"other-services",
"unsure"
],
"type": "string",
"description": "§1202 Test 4: Industry classification of the corporation. Four values qualify: tech-software, manufacturing, biotech-research, retail-wholesale. Specified service trades or businesses (law, engineering, architecture, accounting-actuarial, consulting, finance, health-services, performing-arts) do NOT qualify, and farming, extraction and hospitality are separately excluded, so they do not qualify either. other-services and unsure return a caveated verdict rather than a pass or fail."
},
"saleDate": {
"type": "string",
"format": "date",
"description": "Planned or actual sale date (YYYY-MM-DD). Together with acquisitionDate determines holdingYears."
},
"stateCode": {
"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"
],
"type": "string",
"description": "Two-letter US state code. Drives the state-conformity verdict: CA/AL/PA/MS do not conform (full state tax owed); HI/MA partial; NJ 2026-01-01 conformity switch; most others fully conform."
},
"entityType": {
"enum": [
"us-c-corp",
"other"
],
"type": "string",
"description": "§1202 Test 1: Type of issuer at the time of acquisition. Only 'us-c-corp' qualifies. S-corps, LLCs, partnerships, and foreign entities fail."
},
"expectedGain": {
"type": "number",
"description": "Expected total gain on sale, USD. Compared against the per-issuer exclusion cap to compute excludableGain and taxableGain. Must come from the user."
},
"filingStatus": {
"enum": [
"single",
"married_joint",
"head_household"
],
"type": "string",
"description": "Federal filing status. Drives the LTCG bracket on any non-excluded gain and the NIIT MAGI threshold."
},
"adjustedBasis": {
"type": "number",
"minimum": 0,
"description": "Adjusted basis of the QSBS shares, USD. Used in the 10× basis cap: the per-issuer exclusion cap is max($10M, 10 × adjustedBasis). Must come from the user."
},
"assetCategory": {
"enum": [
"under-50m",
"50m-to-75m",
"over-75m",
"unsure"
],
"type": "string",
"description": "§1202 Test 3: Aggregate gross assets of the issuing corporation at the time of issuance. 'under-50m' qualifies pre-OBBBA. '50m-to-75m' qualifies ONLY under OBBBA 2026+ (post-2025-07-05). 'over-75m' never qualifies. 'unsure' returns a partial verdict."
},
"activeBusiness": {
"enum": [
"yes",
"no",
"unsure"
],
"type": "string",
"description": "§1202 Test 5: Did the corporation use ≥80% of its assets in the active conduct of a qualified trade throughout the holding period? 'yes' qualifies. 'no' fails. 'unsure' returns a partial verdict (user should confirm with their CFO)."
},
"ordinaryIncome": {
"type": "number",
"minimum": 0,
"description": "Annual ordinary income, USD. Baseline for the federal LTCG bracket on any taxable gain. Must come from the user. This is taxable income after deductions, not gross wages: the engine applies no standard or itemized deduction to it."
},
"acquisitionDate": {
"type": "string",
"format": "date",
"description": "Date the QSBS shares were acquired (YYYY-MM-DD). Drives the holding-period test and the era classification (50% pre-2009 era, 75% pre-2010 era, 100% after a 5-year hold for acquisitions from 2010-09-28 through 2025-07-04, OBBBA tiered after 2025-07-05)."
},
"acquisitionMethod": {
"enum": [
"original-issuance",
"gift-or-inheritance",
"secondary",
"unsure"
],
"type": "string",
"description": "§1202 Test 2: How the user obtained the shares. 'original-issuance' (direct from the company) qualifies. 'gift-or-inheritance' tacks the original holder's basis and clock. 'secondary' (bought on a secondary market) does NOT qualify. 'unsure' triggers a partial verdict."
}
}
}| Argument | Type | Description |
|---|
| lots* | array | The vested RSU lots still held (after any sell-to-cover), one entry per vest tranche. The tool decides which of these to sell and when. Unvested grants are out of scope. At most 20 lots per call, the same cap the web calculator uses. With more tranches than that, combine the ones sharing a vest date and cost basis. |
| stateCode* | string | Two-letter US state code (e.g. CA, NY, TX). Drives state capital-gains treatment (CA taxes gains as ordinary; WA/TX/FL have no tax on most capital gains). |
| currentPrice* | number | Current share price, USD. Every sale, on every date, is priced at this value (flat-price assumption). This value must come from the user. |
| filingStatus* | string | Federal filing status. Drives LTCG brackets, the NIIT threshold, and state bracket lookups. |
| horizonYears* | integer | Tax years the plan may span: 1 = sell everything now, 2, or 3. More years let the plan spread gains across brackets and defer short-term lots to long-term, at the cost of staying exposed to the stock longer. The user's choice, not a modelling detail, and it changes the answer: use the value they gave, and if they gave none, ask for it rather than assuming one. |
| divestFraction* | number | Fraction of TOTAL shares to divest, as a decimal (0.5 = sell half). Range 0.10 to 1.0. NOTE: a decimal fraction, NOT a percent, so pass 0.5 not 50. The tool sells round(divestFraction x totalShares) shares, floored at 1. The user's choice, not a modelling detail, and it changes the answer: use the value they gave, and if they gave none, ask for it rather than assuming one. |
| ordinaryIncome* | number | Total household ordinary income for the year, USD, from all sources. Sets the federal LTCG bracket floor, the short-term ordinary rate, and the net investment income tax (NIIT) threshold test. This is taxable income after deductions, not gross wages: the engine applies no standard or itemized deduction to it. Assumed constant across plan years. Must come from the user. |
{
"type": "object",
"required": [
"lots",
"currentPrice",
"divestFraction",
"horizonYears",
"ordinaryIncome",
"filingStatus",
"stateCode"
],
"properties": {
"lots": {
"type": "array",
"items": {
"type": "object",
"required": [
"vestDate",
"shares",
"costBasisPerShare"
],
"properties": {
"shares": {
"type": "number",
"description": "Shares still held from this vest. Fractional allowed (dividend-reinvest / net-settlement lots).",
"exclusiveMinimum": 0
},
"vestDate": {
"type": "string",
"format": "date",
"description": "Date this lot vested (YYYY-MM-DD), on or before today. Drives long-term-vs-short-term status and the long-term-crossing sale date."
},
"costBasisPerShare": {
"type": "number",
"minimum": 0,
"description": "Per-share cost basis, USD: the share price on vest day, which your broker's lot-detail page lists."
}
}
},
"maxItems": 20,
"minItems": 1,
"description": "The vested RSU lots still held (after any sell-to-cover), one entry per vest tranche. The tool decides which of these to sell and when. Unvested grants are out of scope. At most 20 lots per call, the same cap the web calculator uses. With more tranches than that, combine the ones sharing a vest date and cost basis."
},
"stateCode": {
"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"
],
"type": "string",
"description": "Two-letter US state code (e.g. CA, NY, TX). Drives state capital-gains treatment (CA taxes gains as ordinary; WA/TX/FL have no tax on most capital gains)."
},
"currentPrice": {
"type": "number",
"minimum": 0,
"description": "Current share price, USD. Every sale, on every date, is priced at this value (flat-price assumption). This value must come from the user."
},
"filingStatus": {
"enum": [
"single",
"married_joint",
"head_household"
],
"type": "string",
"description": "Federal filing status. Drives LTCG brackets, the NIIT threshold, and state bracket lookups."
},
"horizonYears": {
"type": "integer",
"maximum": 3,
"minimum": 1,
"description": "Tax years the plan may span: 1 = sell everything now, 2, or 3. More years let the plan spread gains across brackets and defer short-term lots to long-term, at the cost of staying exposed to the stock longer. The user's choice, not a modelling detail, and it changes the answer: use the value they gave, and if they gave none, ask for it rather than assuming one."
},
"divestFraction": {
"type": "number",
"maximum": 1,
"minimum": 0.1,
"description": "Fraction of TOTAL shares to divest, as a decimal (0.5 = sell half). Range 0.10 to 1.0. NOTE: a decimal fraction, NOT a percent, so pass 0.5 not 50. The tool sells round(divestFraction x totalShares) shares, floored at 1. The user's choice, not a modelling detail, and it changes the answer: use the value they gave, and if they gave none, ask for it rather than assuming one."
},
"ordinaryIncome": {
"type": "number",
"minimum": 0,
"description": "Total household ordinary income for the year, USD, from all sources. Sets the federal LTCG bracket floor, the short-term ordinary rate, and the net investment income tax (NIIT) threshold test. This is taxable income after deductions, not gross wages: the engine applies no standard or itemized deduction to it. Assumed constant across plan years. Must come from the user."
}
}
}| Argument |
|---|
| Type |
|---|
| Description |
|---|
| shares* | integer | Restricted Stock Unit (RSU) shares vesting in this tranche. Must come from the user. |
| ticker | string | Optional public-stock symbol (e.g. "NVDA", "AAPL"). When set, the tool substitutes a cached trailing return for any unsupplied expected-return / sale-price field, and the implied vol as of the last close for any unsupplied volatility. Growth and vol come from different sources, so some symbols resolve only one, and a vol that is not current resolves as nothing. A field the ticker cannot resolve falls through to a "required field" error naming that field: pass it explicitly, or (for the growth/return/sale-price field) pass the string "market" for the S&P 500 trailing average; never invent a number. The covered-tickers resource (resources/list) lists which symbols resolve growth. |
| haircut | number | Alternative to `volatility`: the multiplicative volatility-drag haircut on expectedSalePrice already computed for the hold. Supply this OR `volatility` (if both are given, haircut wins). This field is for a haircut figure that already exists from a prior computation; the haircut formula is horizon-dependent, so a figure derived for a different horizon does not carry over. Supplying `volatility` instead lets the tool derive it. |
| holdYears* | number | Years to hold after vest (0.25..5). Below 1 year triggers the short-term capital gains cliff (ordinary rates on appreciation). The user's choice, not a modelling detail, and it changes the answer: use the value they gave, and if they gave none, ask for it rather than assuming one. |
| stateCode* | string | Two-letter US state code. |
| volatility | number | Annualized volatility (sigma) of the stock as a decimal (0.72 = 72%). Pass the volatility itself, not a pre-computed drag: the tool derives the horizon-cumulative drag internally, and the correct formula is horizon-dependent. Resolution order: this value if passed, else the `ticker`'s implied volatility as of the last market close, else the median implied volatility of the public companies OptionsAhoy covers, which the result reports in `assumptions` and `assumptionNotice`. |
| currentPrice* | number | Fair market value per share at vest, USD. Also the cost basis on retained shares. Must come from the user. |
| filingStatus* | string | Federal filing status. |
| stillEmployed* | boolean | True if still employed at vest. Drives FICA applicability and whether the 22% supplemental withholding rule applies. |
| ordinaryIncome* | number | Annual ordinary income before this vest, USD. Baseline for the bracket walk on the vest amount. Must come from the user. This is taxable income after deductions, not gross wages: the engine applies no standard or itemized deduction to it. |
| expectedSalePrice | number | string | Projected $/share at end of holdYears, or the string "market" to project currentPrice at the S&P 500 trailing average when the user has no view. Required unless `ticker` resolves it from currentPrice × (1 + trailing CAGR)^holdYears. This tool has no default for it: a value not stated by the user, not resolved by a covered `ticker`, and not the "market" sentinel is outside the input contract. |
| expectedMarketReturn | number | string | Annual after-tax-proceeds reinvestment rate. Defaults to SPY trailing CAGR for holdYears if omitted; the string "market" names that same default explicitly. |
{
"type": "object",
"required": [
"shares",
"currentPrice",
"ordinaryIncome",
"filingStatus",
"stateCode",
"stillEmployed",
"holdYears"
],
"properties": {
"shares": {
"type": "integer",
"minimum": 1,
"description": "Restricted Stock Unit (RSU) shares vesting in this tranche. Must come from the user."
},
"ticker": {
"type": "string",
"description": "Optional public-stock symbol (e.g. \"NVDA\", \"AAPL\"). When set, the tool substitutes a cached trailing return for any unsupplied expected-return / sale-price field, and the implied vol as of the last close for any unsupplied volatility. Growth and vol come from different sources, so some symbols resolve only one, and a vol that is not current resolves as nothing. A field the ticker cannot resolve falls through to a \"required field\" error naming that field: pass it explicitly, or (for the growth/return/sale-price field) pass the string \"market\" for the S&P 500 trailing average; never invent a number. The covered-tickers resource (resources/list) lists which symbols resolve growth."
},
"haircut": {
"type": "number",
"maximum": 1,
"minimum": 0,
"description": "Alternative to `volatility`: the multiplicative volatility-drag haircut on expectedSalePrice already computed for the hold. Supply this OR `volatility` (if both are given, haircut wins). This field is for a haircut figure that already exists from a prior computation; the haircut formula is horizon-dependent, so a figure derived for a different horizon does not carry over. Supplying `volatility` instead lets the tool derive it."
},
"holdYears": {
"type": "number",
"maximum": 5,
"minimum": 0.25,
"description": "Years to hold after vest (0.25..5). Below 1 year triggers the short-term capital gains cliff (ordinary rates on appreciation). The user's choice, not a modelling detail, and it changes the answer: use the value they gave, and if they gave none, ask for it rather than assuming one."
},
"stateCode": {
"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"
],
"type": "string",
"description": "Two-letter US state code."
},
"volatility": {
"type": "number",
"maximum": 5,
"minimum": 0,
"description": "Annualized volatility (sigma) of the stock as a decimal (0.72 = 72%). Pass the volatility itself, not a pre-computed drag: the tool derives the horizon-cumulative drag internally, and the correct formula is horizon-dependent. Resolution order: this value if passed, else the `ticker`'s implied volatility as of the last market close, else the median implied volatility of the public companies OptionsAhoy covers, which the result reports in `assumptions` and `assumptionNotice`."
},
"currentPrice": {
"type": "number",
"minimum": 0,
"description": "Fair market value per share at vest, USD. Also the cost basis on retained shares. Must come from the user."
},
"filingStatus": {
"enum": [
"single",
"married_joint",
"head_household"
],
"type": "string",
"description": "Federal filing status."
},
"stillEmployed": {
"type": "boolean",
"description": "True if still employed at vest. Drives FICA applicability and whether the 22% supplemental withholding rule applies."
},
"ordinaryIncome": {
"type": "number",
"minimum": 0,
"description": "Annual ordinary income before this vest, USD. Baseline for the bracket walk on the vest amount. Must come from the user. This is taxable income after deductions, not gross wages: the engine applies no standard or itemized deduction to it."
},
"expectedSalePrice": {
"type": [
"number",
"string"
],
"minimum": 0,
"description": "Projected $/share at end of holdYears, or the string \"market\" to project currentPrice at the S&P 500 trailing average when the user has no view. Required unless `ticker` resolves it from currentPrice × (1 + trailing CAGR)^holdYears. This tool has no default for it: a value not stated by the user, not resolved by a covered `ticker`, and not the \"market\" sentinel is outside the input contract."
},
"expectedMarketReturn": {
"type": [
"number",
"string"
],
"description": "Annual after-tax-proceeds reinvestment rate. Defaults to SPY trailing CAGR for holdYears if omitted; the string \"market\" names that same default explicitly."
}
}
}