| amt_iso_optimizeA | Multi-year Incentive Stock Option (ISO) exercise schedule that maximizes 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 optimizer chooses the per-year share allocation that lands the highest NFV across all feasible schedules. When the user asks for "maximum value", "best schedule", or "optimal exercise plan", report NFV (in dollars) as the primary headline — schedules.optimized.nfv is the recommended plan; compare it against schedules.lumpSum.nfv and schedules.evenSplit.nfv to show the value delta from the optimization. Use this tool for ISO planning; 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. Pure deterministic computation: no network access, no PII retention; federal + 50-state tax tables and AMT brackets are compiled in. The optimizer searches the full feasible share-per-year space (exhaustive, not heuristic). Returns a top-level object with keys: schedules (object containing lumpSum, evenSplit, and optimized — each {nfv, federalLTCG, stateLTCG, amtPremiumFV, grossGain}), crossoverShares (max shares that can be exercised in year 1 before tentative AMT exceeds regular tax), crossoverBargain, alreadyInAmt (boolean), timing (grant expiration / qualifying disposition / 90-day window flags), stateHasAmt, bargainPerShare, effectiveHorizon, and departedRecommendation when applicable. 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}. IMPORTANT: every field listed in required must come from the user's message OR be derivable from an optional ticker. The model invoking this tool MUST NOT invent a value for any required field. If the user did not supply it and no ticker resolves it, ask the user. |
| nso_calculateA | 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 a top-level object with these keys: exercise: bargainElement, federal, state, socialSecurity, medicare, additionalMedicare, total, netCashSellAll, sharesSoldToCover, sharesRetained.
hold: expectedGain, capGainFederal, capGainState, capGainTotal, isLongTerm at end of holdYears (LTCG triggers at holdYears ≥ 1).
sellNowInvest: counterfactual where shares are sold at exercise and proceeds reinvested at expectedMarketReturn.
holdMinusCashless: dollar delta between hold and sellNowInvest.
bracketJump: fromRate, toRate, thresholdAtJump describing the marginal bracket change at exercise.
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"}. IMPORTANT: every field listed in required must come from the user's message OR be derivable from an optional ticker. The model invoking this tool MUST NOT invent a value for any required field. If the user did not supply it and no ticker resolves it, ask the user. |
| rsu_sell_vs_holdA | After-tax payout on a Restricted Stock Unit (RSU) vest: federal ordinary income tax, state income tax, FICA (Social Security + Medicare + Additional Medicare), and the gap between mandatory 22% federal supplemental withholding and the user's marginal bracket. Use this tool for RSUs at vest; for ISO/AMT planning use amt_iso_optimize, for NSO use nso_calculate. Compares sell-at-vest vs hold-for-long-term-capital-gains (LTCG) across the chosen horizon, accounting for the 12-month short-term-vs-long-term holding threshold and the optional expected-growth assumption. Pure deterministic computation: no network access; tax tables and the 22% supplemental-withholding rate are compiled in. Returns a top-level object with keys: vest (vestValue, federal, state, socialSecurity, medicare, additionalMedicare, total, netCashAtVest, federalWithheldAtVest), hold (expectedGain at horizon, capGainFederal/State/Total including NIIT, isLongTerm), sellNowInvest (counterfactual: sell at vest and reinvest at expectedMarketReturn), holdMinusSell (dollar delta), and bracketJump (fromRate, toRate, thresholdAtJump on the vest amount). Example call: {shares: 1000, currentPrice: 100, ordinaryIncome: 200000, filingStatus: "single", stateCode: "CA", stillEmployed: true, holdYears: 2, volatility: 0.3, ticker: "MSFT"}. IMPORTANT: every field listed in required must come from the user's message OR be derivable from an optional ticker. The model invoking this tool MUST NOT invent a value for any required field. If the user did not supply it and no ticker resolves it, ask the user. |
| concentration_analyzeA | 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 portfolio and MUST come from the user, never inferred. 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 (NFV + cost when hedgeChoice provided), 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"}. IMPORTANT: every field listed in required must come from the user's message OR be derivable from an optional ticker. The model invoking this tool MUST NOT invent a value for any required field. If the user did not supply it and no ticker resolves it, ask the user. |
| protective_put_priceA | Black-Scholes pricing of a protective put or zero-cost collar on a single-stock position. Use for standalone hedge pricing on a single-stock position; for concentration-vs-hedge tax-cost comparison, use concentration_analyze with a hedgeChoice. Parameter interactions an agent should know: volatility omitted falls back to sector_stats[sector].annualVol × 1.20 (the implied-over-realized vol multiplier); supply an explicit sigma when the user provides one. 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 (default 0). protectionLevel sets the put strike as (1 − protectionLevel) × spot; raising it widens the protected zone but raises premium roughly linearly. Closed-form, deterministic, offline: sector volatility table and risk-free-rate curve compiled in. Reports annualized hedge cost as a percentage of position value, maximum loss with the hedge in place, upside-participation cap (collar only, since the short call offsets the long put premium), and probability of hitting the protection floor over the tenor. Returns a top-level object with keys: inputs (echoed canonical input), riskFreeRate (used in Black-Scholes), 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), payoffTable, payoffRange, and recommended (the better of bare put vs collar given the inputs). Both barePut and collar blocks are always returned regardless of caller preference; the caller picks. Example call: {positionValue: 400000, sector: "tech_software", protectionLevel: 0.10, tenorYears: 1}. IMPORTANT: every field listed in required must come from the user's message. The model invoking this tool MUST NOT invent a value for any required field. If the user did not supply it, ask the user. For enum fields that accept unsure, pass unsure when the user does not know; do not guess yes/no. |
| qsbs_checkA | 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 an agent should know: entityType="other" short-circuits the verdict to does-not-qualify 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); 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 eight 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), holding period (3 / 4 / 5-year tiers under OBBBA), adjusted basis, and expected gain at sale. Pure stateless check: no filing, reporting, or IRS lookup happens; the eight 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 / does-not-qualify), 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 / 2009-2010 / pre-obbba / obbba), and tests (array of {id, label, status, detail} for each of the eight statutory tests so an agent can show which gate 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"}. IMPORTANT: every field listed in required must come from the user's message. The model invoking this tool MUST NOT invent a value for any required field. If the user did not supply it, ask the user. For enum fields that accept unsure, pass unsure when the user does not know; do not guess yes/no. |