OptionsAhoy: Stock Equity and Tax Optimizer

equity_funding_plan

Read-onlyIdempotent

Build a multi-year sell schedule to meet a target after-tax cash amount by a deadline, choosing which shares to sell to minimize tax. Returns lock-in-now, balanced, hold-for-growth, and recommended plans.

Instructions

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 with the least tax. 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, zero price risk), balanced (bracket-aware spread across months), holdForGrowth (sell at the deadline, max upside), and recommended (the wealth-maximal plan whose lognormal shortfall 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 is an error, not a 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.

Input Schema

TableJSON Schema

Name	Required	Description
`lots`	No	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`	No	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 prefer the lowest-tax inventory in each year.
`stateCode`	Yes	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`	Yes	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`	No	Legacy single-stack current share price, USD. Pair with legacy `lots` (omit `stacks`). This value must come from the user.
`filingStatus`	Yes	Federal filing status. Drives LTCG brackets, NIIT threshold ($200K single / $250K MFJ MAGI), and state bracket lookups.
`ordinaryIncome`	Yes	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`	Yes	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`	No	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`	No	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`	No	Legacy single-stack annual growth decimal, or the string "market" for the S&P 500 trailing average. Required with `lots`: pass 0 for a deliberately flat-price plan (omitting it is an error, not a flat default). Each future year's projected price is `currentPrice × (1 + expectedAnnualGrowth)^Δyears`. Negative values model decline.
`riskToleranceShortfall`	No	Max acceptable P(realized cash < target) under the lognormal price model, as a fraction (0.10 = 10%). The `recommended` plan is the wealth-maximal plan whose shortfall ≤ 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.

Output Schema

TableJSON Schema

Name	Required	Description
`balanced`	Yes	Bracket-aware spread across all candidate years: minimum tax.
`frontier`	Yes	All candidate plans from the hybrid lock-in sweep plus the named plans, sorted by shortfall probability.
`lockInNow`	Yes	Sell everything needed in the current calendar year: minimum price risk, usually highest tax.
`recommended`	Yes	The wealth-maximal plan whose shortfall probability is at or below the applied risk tolerance. This is the plan the risk tolerance selects out of the frontier.
`holdForGrowth`	Yes	Sell only in the target year: maximum expected wealth, maximum price risk.
`targetDateISO`	Yes	Echo of the target date as an ISO date string.
`targetAfterTax`	Yes	Echo of the requested net cash target in dollars.
`appliedRiskTolerance`	Yes	Shortfall-probability tolerance actually applied (default 0.10 when not supplied).

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedv1.10.2Sep 8, 2026

removedInput schema / anyOf

Removed value: -[
-  {
-    "required": [
-      "stacks"
-    ]
-  },
-  {
-    "required": [
-      "lots",
-      "currentPrice"
-    ]
-  }
-]

Addedv1.10.1Aug 3, 2026
Removedv1.9.8Jul 25, 2026

Changed5 schema fields changedv1.9.7Jul 11, 2026

addedInput schema / anyOf

Added value: +[
+  {
+    "required": [
+      "stacks"
+    ]
+  },
+  {
+    "required": [
+      "lots",
+      "currentPrice"
+    ]
+  }
+]

changedInput schema / properties / stacks / description

Previous value: -"Multi-stack input. 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 prefer the lowest-tax inventory in each year."New value: +"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 prefer the lowest-tax inventory in each year."

addedInput schema / properties / stateCode / enum

Added value: +[
+  "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"
+]

removedInput schema / properties / stateCode / pattern
```
Removed value: -"^[A-Z]{2}$"
```

removedInput schema / properties / today

Removed value: -{
-  "description": "Reference \"now\" for year classification and projection compounding. Defaults to the server's current date; tests pass an explicit value for deterministic results.",
-  "format": "date",
-  "type": "string"
-}

Changed16 schema fields changedv1.9.2Jun 12, 2026

addedInput schema / properties / cashInterestRate

Added value: +{
+  "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).",
+  "type": "number"
+}

addedInput schema / properties / defaultVolatility

Added value: +{
+  "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.",
+  "minimum": 0,
+  "type": "number"
+}

addedInput schema / properties / lots / items / properties / vestDate

Added value: +{
+  "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`.",
+  "format": "date",
+  "type": "string"
+}

addedInput schema / properties / riskToleranceShortfall

Added value: +{
+  "description": "Max acceptable P(realized cash < target) under the lognormal price model, as a fraction (0.10 = 10%). The `recommended` plan is the wealth-maximal plan whose shortfall ≤ 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.",
+  "maximum": 1,
+  "minimum": 0,
+  "type": "number"
+}

changedInput schema / properties / stacks / description

Previous value: -"v1.7+ multi-stack input. Each stack is one equity position (one ticker) with its own currentPrice, growth assumption, and lot list. Use this when the user holds multiple tickers (e.g. current-employer RSUs + index fund + prior-employer holdings). For a single position, provide an array with one entry — OR omit `stacks` and use the legacy top-level `lots` + `currentPrice` fields."New value: +"Multi-stack input. 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 prefer the lowest-tax inventory in each year."

changedInput schema / properties / stacks / items / properties / currentPrice / description

Previous value: -"Current price for this stack's shares, USD."New value: +"$/share today for this stack. Anchors the projected-price compounding for every future candidate sale date in this stack."

changedInput schema / properties / stacks / items / properties / expectedAnnualGrowth / description

Previous value: -"Optional per-stack growth decimal (e.g. 0.08 = 8%/yr). Defaults to 0."New value: +"Per-stack growth decimal (0.08 = 8%/yr). Projected sale price = currentPrice × (1 + expectedAnnualGrowth)^Δyears. Negative values model decline. Defaults to 0 (flat) unless `ticker` resolves it."

addedInput schema / properties / stacks / items / properties / lots / description

Added value: +"Cost-basis cohorts within this stack (one per vest tranche / ESPP purchase / open-market buy)."

addedInput schema / properties / stacks / items / properties / lots / items / properties / acquisitionDate / description

Added value: +"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."

addedInput schema / properties / stacks / items / properties / lots / items / properties / costBasisPerShare / description
```
Added value: +"$/share basis. RSU = FMV at vest; ISO/NSO = exercise price; ESPP/open-market = purchase price."
```
addedInput schema / properties / stacks / items / properties / lots / items / properties / shares / description
```
Added value: +"Whole shares in this lot."
```

addedInput schema / properties / stacks / items / properties / lots / items / properties / vestDate

Added value: +{
+  "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.",
+  "format": "date",
+  "type": "string"
+}

changedInput schema / properties / stacks / items / properties / ticker / description

Previous value: -"Optional display label echoed in the schedule output."New value: +"Optional ticker label (e.g. \"NVDA\"). When set without `expectedAnnualGrowth`, growth is resolved from the trailing-CAGR table (~90 public-stock symbols covered). Echoed back in each SaleEntry for display."

addedInput schema / properties / stacks / items / properties / volatility

Added value: +{
+  "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`.",
+  "minimum": 0,
+  "type": "number"
+}

addedInput schema / properties / today

Added value: +{
+  "description": "Reference \"now\" for year classification and projection compounding. Defaults to the server's current date; tests pass an explicit value for deterministic results.",
+  "format": "date",
+  "type": "string"
+}

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "description": "Equity-funding plan comparison: four named plans plus the full risk/wealth frontier. All dollar amounts are USD.",
+  "properties": {
+    "appliedRiskTolerance": {
+      "description": "Shortfall-probability tolerance actually applied (default 0.10 when not supplied).",
+      "type": "number"
+    },
+    "balanced": {
+      "description": "Bracket-aware spread across all candidate years: minimum tax.",
+      "properties": {
+        "lockInFraction": {
+          "description": "Fraction (0..1) of the target locked in by an immediate sale, for hybrid candidates. Omitted on pure named plans.",
+          "type": "number"
+        },
+        "plan": {
+          "description": "The full sale schedule for this plan. Nested year/sale entries follow the shapes described here and may carry additional fields.",
+          "properties": {
+            "comparison": {
+              "description": "This schedule vs the naive sell-everything-in-the-target-year alternative.",
+              "properties": {
+                "optimizedSavingsPct": {
+                  "description": "Tax saved as a fraction of the naive plan tax.",
+                  "type": "number"
+                },
+                "optimizedSavingsVsTargetYearSale": {
+                  "description": "Tax saved in dollars by this schedule vs the naive plan.",
+                  "type": "number"
+                },
+                "sellAllInTargetYearAfterTax": {
+                  "description": "After-tax cash in dollars under that naive plan.",
+                  "type": "number"
+                },
+                "sellAllInTargetYearTotalTax": {
+                  "description": "Tax in dollars if all needed shares were sold in the target year.",
+                  "type": "number"
+                }
+              },
+              "required": [
+                "sellAllInTargetYearTotalTax",
+                "sellAllInTargetYearAfterTax",
+                "optimizedSavingsVsTargetYearSale",
+                "optimizedSavingsPct"
+              ],
+              "type": "object"
+            },
+            "feasible": {
+              "description": "True when the schedule reaches the after-tax target by the target date.",
+              "type": "boolean"
+            },
+            "remainingNetByStack": {
+              "description": "Per-stack after-tax retained value in dollars, parallel to the input stacks array.",
+              "items": {
+                "type": "number"
+              },
+              "type": "array"
+            },
+            "remainingPositionAfterTax": {
+              "description": "After-tax value in dollars of liquidating all retained shares at the target date (the cash backstop if scheduled sales come in light).",
+              "type": "number"
+            },
+            "remainingPositionValue": {
+              "description": "Market value in dollars of retained shares at the projected target-date price.",
+              "type": "number"
+            },
+            "remainingShares": {
+              "description": "Shares retained after all scheduled sales.",
+              "type": "number"
+            },
+            "schedule": {
+              "description": "Per-year sale schedule. Each entry: year, saleDateISO, sales (array of per-lot entries: stackIndex, ticker, lotIndex, shares, grossProceeds, gainAmount, isLongTerm, federalTax, stateTax, niit, netCash), yearGrossProceeds, yearTotalTax, yearNetCash, runningCumulativeNet.",
+              "items": {
+                "additionalProperties": true,
+                "type": "object"
+              },
+              "type": "array"
+            },
+            "shortfall": {
+              "description": "Present only when the target is not reachable from the available inventory.",
+              "properties": {
+                "gap": {
+                  "description": "Dollars short of the target.",
+                  "type": "number"
+                },
+                "maxAchievableAfterTax": {
+                  "description": "Maximum after-tax cash in dollars achievable by the target date.",
+                  "type": "number"
+                }
+              },
+              "required": [
+                "maxAchievableAfterTax",
+                "gap"
+              ],
+              "type": "object"
+            },
+            "targetAfterTax": {
+              "description": "Echo of the requested net cash target in dollars.",
+              "type": "number"
+            },
+            "targetDateISO": {
+              "description": "Echo of the target date as an ISO date string.",
+              "type": "string"
+            },
+            "totalAfterTaxAchieved": {
+              "description": "Net after-tax cash in dollars the schedule produces by the target date (including after-tax cash interest when cashInterestRate is set).",
+              "type": "number"
+            },
+            "totalGrossProceeds": {
+              "description": "Total gross sale proceeds in dollars.",
+              "type": "number"
+            },
+            "totalSharesSold": {
+              "description": "Total shares sold across the schedule.",
+              "type": "number"
+            },
+            "totalTaxes": {
+              "description": "Tax totals across all scheduled sales, in dollars.",
+              "properties": {
+                "federal": {
+                  "description": "Federal capital gains / ordinary tax in dollars.",
+                  "type": "number"
+                },
+                "niit": {
+                  "description": "Net Investment Income Tax (3.8%) in dollars.",
+                  "type": "number"
+                },
+                "state": {
+                  "description": "State tax in dollars.",
+                  "type": "number"
+                },
+                "total": {
+                  "description": "Total tax in dollars.",
+                  "type": "number"
+                }
+              },
+              "required": [
+                "federal",
+                "state",
+                "niit",
+                "total"
+              ],
+              "type": "object"
+            }
+          },
+          "required": [
+            "feasible",
+            "targetAfterTax",
+            "targetDateISO",
+            "totalAfterTaxAchieved",
+            "totalSharesSold",
+            "totalGrossProceeds",
+            "totalTaxes",
+            "schedule",
+            "comparison",
+            "remainingShares",
+            "remainingPositionValue",
+            "remainingPositionAfterTax",
+            "remainingNetByStack"
+          ],
+          "type": "object"
+        },
+        "planKey": {
+          "description": "Plan identifier. \"candidate\" entries appear only inside frontier.",
+          "enum": [
+            "recommended",
+            "lock_in_now",
+            "balanced",
+            "hold_for_growth",
+            "candidate"
+          ],
+          "type": "string"
+        },
+        "planLabel": {
+          "description": "Human-readable plan name.",
+          "type": "string"
+        },
+        "shortfallProbability": {
+          "description": "Lognormal probability (0..1) that realized cash lands below the target. 0 means a deterministic hit (sell everything today).",
+          "type": "number"
+        },
+        "totalTax": {
+          "description": "Total tax paid across the plan in dollars.",
+          "type": "number"
+        },
+        "wealthAtTarget": {
+          "description": "Total wealth in dollars at the target date: net cash plus retained shares at the projected price. The metric the recommendation maximizes.",
+          "type": "number"
+        }
+      },
+      "required": [
+        "planKey",
+        "planLabel",
+        "plan",
+        "wealthAtTarget",
+        "totalTax",
+        "shortfallProbability"
+      ],
+      "type": "object"
+    },
+    "frontier": {
+      "description": "All candidate plans from the hybrid lock-in sweep plus the named plans, sorted by shortfall probability.",
+      "items": {
+        "description": "One sale plan on the risk/wealth frontier.",
+        "properties": {
+          "lockInFraction": {
+            "description": "Fraction (0..1) of the target locked in by an immediate sale, for hybrid candidates. Omitted on pure named plans.",
+            "type": "number"
+          },
+          "plan": {
+            "description": "The full sale schedule for this plan. Nested year/sale entries follow the shapes described here and may carry additional fields.",
+            "properties": {
+              "comparison": {
+                "description": "This schedule vs the naive sell-everything-in-the-target-year alternative.",
+                "properties": {
+                  "optimizedSavingsPct": {
+                    "description": "Tax saved as a fraction of the naive plan tax.",
+                    "type": "number"
+                  },
+                  "optimizedSavingsVsTargetYearSale": {
+                    "description": "Tax saved in dollars by this schedule vs the naive plan.",
+                    "type": "number"
+                  },
+                  "sellAllInTargetYearAfterTax": {
+                    "description": "After-tax cash in dollars under that naive plan.",
+                    "type": "number"
+                  },
+                  "sellAllInTargetYearTotalTax": {
+                    "description": "Tax in dollars if all needed shares were sold in the target year.",
+                    "type": "number"
+                  }
+                },
+                "required": [
+                  "sellAllInTargetYearTotalTax",
+                  "sellAllInTargetYearAfterTax",
+                  "optimizedSavingsVsTargetYearSale",
+                  "optimizedSavingsPct"
+                ],
+                "type": "object"
+              },
+              "feasible": {
+                "description": "True when the schedule reaches the after-tax target by the target date.",
+                "type": "boolean"
+              },
+              "remainingNetByStack": {
+                "description": "Per-stack after-tax retained value in dollars, parallel to the input stacks array.",
+                "items": {
+                  "type": "number"
+                },
+                "type": "array"
+              },
+              "remainingPositionAfterTax": {
+                "description": "After-tax value in dollars of liquidating all retained shares at the target date (the cash backstop if scheduled sales come in light).",
+                "type": "number"
+              },
+              "remainingPositionValue": {
+                "description": "Market value in dollars of retained shares at the projected target-date price.",
+                "type": "number"
+              },
+              "remainingShares": {
+                "description": "Shares retained after all scheduled sales.",
+                "type": "number"
+              },
+              "schedule": {
+                "description": "Per-year sale schedule. Each entry: year, saleDateISO, sales (array of per-lot entries: stackIndex, ticker, lotIndex, shares, grossProceeds, gainAmount, isLongTerm, federalTax, stateTax, niit, netCash), yearGrossProceeds, yearTotalTax, yearNetCash, runningCumulativeNet.",
+                "items": {
+                  "additionalProperties": true,
+                  "type": "object"
+                },
+                "type": "array"
+              },
+              "shortfall": {
+                "description": "Present only when the target is not reachable from the available inventory.",
+                "properties": {
+                  "gap": {
+                    "description": "Dollars short of the target.",
+                    "type": "number"
+                  },
+                  "maxAchievableAfterTax": {
+                    "description": "Maximum after-tax cash in dollars achievable by the target date.",
+                    "type": "number"
+                  }
+                },
+                "required": [
+                  "maxAchievableAfterTax",
+                  "gap"
+                ],
+                "type": "object"
+              },
+              "targetAfterTax": {
+                "description": "Echo of the requested net cash target in dollars.",
+                "type": "number"
+              },
+              "targetDateISO": {
+                "description": "Echo of the target date as an ISO date string.",
+                "type": "string"
+              },
+              "totalAfterTaxAchieved": {
+                "description": "Net after-tax cash in dollars the schedule produces by the target date (including after-tax cash interest when cashInterestRate is set).",
+                "type": "number"
+              },
+              "totalGrossProceeds": {
+                "description": "Total gross sale proceeds in dollars.",
+                "type": "number"
+              },
+              "totalSharesSold": {
+                "description": "Total shares sold across the schedule.",
+                "type": "number"
+              },
+              "totalTaxes": {
+                "description": "Tax totals across all scheduled sales, in dollars.",
+                "properties": {
+                  "federal": {
+                    "description": "Federal capital gains / ordinary tax in dollars.",
+                    "type": "number"
+                  },
+                  "niit": {
+                    "description": "Net Investment Income Tax (3.8%) in dollars.",
+                    "type": "number"
+                  },
+                  "state": {
+                    "description": "State tax in dollars.",
+                    "type": "number"
+                  },
+                  "total": {
+                    "description": "Total tax in dollars.",
+                    "type": "number"
+                  }
+                },
+                "required": [
+                  "federal",
+                  "state",
+                  "niit",
+                  "total"
+                ],
+                "type": "object"
+              }
+            },
+            "required": [
+              "feasible",
+              "targetAfterTax",
+              "targetDateISO",
+              "totalAfterTaxAchieved",
+              "totalSharesSold",
+              "totalGrossProceeds",
+              "totalTaxes",
+              "schedule",
+              "comparison",
+              "remainingShares",
+              "remainingPositionValue",
+              "remainingPositionAfterTax",
+              "remainingNetByStack"
+            ],
+            "type": "object"
+          },
+          "planKey": {
+            "description": "Plan identifier. \"candidate\" entries appear only inside frontier.",
+            "enum": [
+              "recommended",
+              "lock_in_now",
+              "balanced",
+              "hold_for_growth",
+              "candidate"
+            ],
+            "type": "string"
+          },
+          "planLabel": {
+            "description": "Human-readable plan name.",
+            "type": "string"
+          },
+          "shortfallProbability": {
+            "description": "Lognormal probability (0..1) that realized cash lands below the target. 0 means a deterministic hit (sell everything today).",
+            "type": "number"
+          },
+          "totalTax": {
+            "description": "Total tax paid across the plan in dollars.",
+            "type": "number"
+          },
+          "wealthAtTarget": {
+            "description": "Total wealth in dollars at the target date: net cash plus retained shares at the projected price. The metric the recommendation maximizes.",
+            "type": "number"
+          }
+        },
+        "required": [
+          "planKey",
+          "planLabel",
+          "plan",
+          "wealthAtTarget",
+          "totalTax",
+          "shortfallProbability"
+        ],
+        "type": "object"
+      },
+      "type": "array"
+    },
+    "holdForGrowth": {
+      "description": "Sell only in the target year: maximum expected wealth, maximum price risk.",
+      "properties": {
+        "lockInFraction": {
+          "description": "Fraction (0..1) of the target locked in by an immediate sale, for hybrid candidates. Omitted on pure named plans.",
+          "type": "number"
+        },
+        "plan": {
+          "description": "The full sale schedule for this plan. Nested year/sale entries follow the shapes described here and may carry additional fields.",
+          "properties": {
+            "comparison": {
+              "description": "This schedule vs the naive sell-everything-in-the-target-year alternative.",
+              "properties": {
+                "optimizedSavingsPct": {
+                  "description": "Tax saved as a fraction of the naive plan tax.",
+                  "type": "number"
+                },
+                "optimizedSavingsVsTargetYearSale": {
+                  "description": "Tax saved in dollars by this schedule vs the naive plan.",
+                  "type": "number"
+                },
+                "sellAllInTargetYearAfterTax": {
+                  "description": "After-tax cash in dollars under that naive plan.",
+                  "type": "number"
+                },
+                "sellAllInTargetYearTotalTax": {
+                  "description": "Tax in dollars if all needed shares were sold in the target year.",
+                  "type": "number"
+                }
+              },
+              "required": [
+                "sellAllInTargetYearTotalTax",
+                "sellAllInTargetYearAfterTax",
+                "optimizedSavingsVsTargetYearSale",
+                "optimizedSavingsPct"
+              ],
+              "type": "object"
+            },
+            "feasible": {
+              "description": "True when the schedule reaches the after-tax target by the target date.",
+              "type": "boolean"
+            },
+            "remainingNetByStack": {
+              "description": "Per-stack after-tax retained value in dollars, parallel to the input stacks array.",
+              "items": {
+                "type": "number"
+              },
+              "type": "array"
+            },
+            "remainingPositionAfterTax": {
+              "description": "After-tax value in dollars of liquidating all retained shares at the target date (the cash backstop if scheduled sales come in light).",
+              "type": "number"
+            },
+            "remainingPositionValue": {
+              "description": "Market value in dollars of retained shares at the projected target-date price.",
+              "type": "number"
+            },
+            "remainingShares": {
+              "description": "Shares retained after all scheduled sales.",
+              "type": "number"
+            },
+            "schedule": {
+              "description": "Per-year sale schedule. Each entry: year, saleDateISO, sales (array of per-lot entries: stackIndex, ticker, lotIndex, shares, grossProceeds, gainAmount, isLongTerm, federalTax, stateTax, niit, netCash), yearGrossProceeds, yearTotalTax, yearNetCash, runningCumulativeNet.",
+              "items": {
+                "additionalProperties": true,
+                "type": "object"
+              },
+              "type": "array"
+            },
+            "shortfall": {
+              "description": "Present only when the target is not reachable from the available inventory.",
+              "properties": {
+                "gap": {
+                  "description": "Dollars short of the target.",
+                  "type": "number"
+                },
+                "maxAchievableAfterTax": {
+                  "description": "Maximum after-tax cash in dollars achievable by the target date.",
+                  "type": "number"
+                }
+              },
+              "required": [
+                "maxAchievableAfterTax",
+                "gap"
+              ],
+              "type": "object"
+            },
+            "targetAfterTax": {
+              "description": "Echo of the requested net cash target in dollars.",
+              "type": "number"
+            },
+            "targetDateISO": {
+              "description": "Echo of the target date as an ISO date string.",
+              "type": "string"
+            },
+            "totalAfterTaxAchieved": {
+              "description": "Net after-tax cash in dollars the schedule produces by the target date (including after-tax cash interest when cashInterestRate is set).",
+              "type": "number"
+            },
+            "totalGrossProceeds": {
+              "description": "Total gross sale proceeds in dollars.",
+              "type": "number"
+            },
+            "totalSharesSold": {
+              "description": "Total shares sold across the schedule.",
+              "type": "number"
+            },
+            "totalTaxes": {
+              "description": "Tax totals across all scheduled sales, in dollars.",
+              "properties": {
+                "federal": {
+                  "description": "Federal capital gains / ordinary tax in dollars.",
+                  "type": "number"
+                },
+                "niit": {
+                  "description": "Net Investment Income Tax (3.8%) in dollars.",
+                  "type": "number"
+                },
+                "state": {
+                  "description": "State tax in dollars.",
+                  "type": "number"
+                },
+                "total": {
+                  "description": "Total tax in dollars.",
+                  "type": "number"
+                }
+              },
+              "required": [
+                "federal",
+                "state",
+                "niit",
+                "total"
+              ],
+              "type": "object"
+            }
+          },
+          "required": [
+            "feasible",
+            "targetAfterTax",
+            "targetDateISO",
+            "totalAfterTaxAchieved",
+            "totalSharesSold",
+            "totalGrossProceeds",
+            "totalTaxes",
+            "schedule",
+            "comparison",
+            "remainingShares",
+            "remainingPositionValue",
+            "remainingPositionAfterTax",
+            "remainingNetByStack"
+          ],
+          "type": "object"
+        },
+        "planKey": {
+          "description": "Plan identifier. \"candidate\" entries appear only inside frontier.",
+          "enum": [
+            "recommended",
+            "lock_in_now",
+            "balanced",
+            "hold_for_growth",
+            "candidate"
+          ],
+          "type": "string"
+        },
+        "planLabel": {
+          "description": "Human-readable plan name.",
+          "type": "string"
+        },
+        "shortfallProbability": {
+          "description": "Lognormal probability (0..1) that realized cash lands below the target. 0 means a deterministic hit (sell everything today).",
+          "type": "number"
+        },
+        "totalTax": {
+          "description": "Total tax paid across the plan in dollars.",
+          "type": "number"
+        },
+        "wealthAtTarget": {
+          "description": "Total wealth in dollars at the target date: net cash plus retained shares at the projected price. The metric the recommendation maximizes.",
+          "type": "number"
+        }
+      },
+      "required": [
+        "planKey",
+        "planLabel",
+        "plan",
+        "wealthAtTarget",
+        "totalTax",
+        "shortfallProbability"
+      ],
+      "type": "object"
+    },
+    "lockInNow": {
+      "description": "Sell everything needed in the current calendar year: minimum price risk, usually highest tax.",
+      "properties": {
+        "lockInFraction": {
+          "description": "Fraction (0..1) of the target locked in by an immediate sale, for hybrid candidates. Omitted on pure named plans.",
+          "type": "number"
+        },
+        "plan": {
+          "description": "The full sale schedule for this plan. Nested year/sale entries follow the shapes described here and may carry additional fields.",
+          "properties": {
+            "comparison": {
+              "description": "This schedule vs the naive sell-everything-in-the-target-year alternative.",
+              "properties": {
+                "optimizedSavingsPct": {
+                  "description": "Tax saved as a fraction of the naive plan tax.",
+                  "type": "number"
+                },
+                "optimizedSavingsVsTargetYearSale": {
+                  "description": "Tax saved in dollars by this schedule vs the naive plan.",
+                  "type": "number"
+                },
+                "sellAllInTargetYearAfterTax": {
+                  "description": "After-tax cash in dollars under that naive plan.",
+                  "type": "number"
+                },
+                "sellAllInTargetYearTotalTax": {
+                  "description": "Tax in dollars if all needed shares were sold in the target year.",
+                  "type": "number"
+                }
+              },
+              "required": [
+                "sellAllInTargetYearTotalTax",
+                "sellAllInTargetYearAfterTax",
+                "optimizedSavingsVsTargetYearSale",
+                "optimizedSavingsPct"
+              ],
+              "type": "object"
+            },
+            "feasible": {
+              "description": "True when the schedule reaches the after-tax target by the target date.",
+              "type": "boolean"
+            },
+            "remainingNetByStack": {
+              "description": "Per-stack after-tax retained value in dollars, parallel to the input stacks array.",
+              "items": {
+                "type": "number"
+              },
+              "type": "array"
+            },
+            "remainingPositionAfterTax": {
+              "description": "After-tax value in dollars of liquidating all retained shares at the target date (the cash backstop if scheduled sales come in light).",
+              "type": "number"
+            },
+            "remainingPositionValue": {
+              "description": "Market value in dollars of retained shares at the projected target-date price.",
+              "type": "number"
+            },
+            "remainingShares": {
+              "description": "Shares retained after all scheduled sales.",
+              "type": "number"
+            },
+            "schedule": {
+              "description": "Per-year sale schedule. Each entry: year, saleDateISO, sales (array of per-lot entries: stackIndex, ticker, lotIndex, shares, grossProceeds, gainAmount, isLongTerm, federalTax, stateTax, niit, netCash), yearGrossProceeds, yearTotalTax, yearNetCash, runningCumulativeNet.",
+              "items": {
+                "additionalProperties": true,
+                "type": "object"
+              },
+              "type": "array"
+            },
+            "shortfall": {
+              "description": "Present only when the target is not reachable from the available inventory.",
+              "properties": {
+                "gap": {
+                  "description": "Dollars short of the target.",
+                  "type": "number"
+                },
+                "maxAchievableAfterTax": {
+                  "description": "Maximum after-tax cash in dollars achievable by the target date.",
+                  "type": "number"
+                }
+              },
+              "required": [
+                "maxAchievableAfterTax",
+                "gap"
+              ],
+              "type": "object"
+            },
+            "targetAfterTax": {
+              "description": "Echo of the requested net cash target in dollars.",
+              "type": "number"
+            },
+            "targetDateISO": {
+              "description": "Echo of the target date as an ISO date string.",
+              "type": "string"
+            },
+            "totalAfterTaxAchieved": {
+              "description": "Net after-tax cash in dollars the schedule produces by the target date (including after-tax cash interest when cashInterestRate is set).",
+              "type": "number"
+            },
+            "totalGrossProceeds": {
+              "description": "Total gross sale proceeds in dollars.",
+              "type": "number"
+            },
+            "totalSharesSold": {
+              "description": "Total shares sold across the schedule.",
+              "type": "number"
+            },
+            "totalTaxes": {
+              "description": "Tax totals across all scheduled sales, in dollars.",
+              "properties": {
+                "federal": {
+                  "description": "Federal capital gains / ordinary tax in dollars.",
+                  "type": "number"
+                },
+                "niit": {
+                  "description": "Net Investment Income Tax (3.8%) in dollars.",
+                  "type": "number"
+                },
+                "state": {
+                  "description": "State tax in dollars.",
+                  "type": "number"
+                },
+                "total": {
+                  "description": "Total tax in dollars.",
+                  "type": "number"
+                }
+              },
+              "required": [
+                "federal",
+                "state",
+                "niit",
+                "total"
+              ],
+              "type": "object"
+            }
+          },
+          "required": [
+            "feasible",
+            "targetAfterTax",
+            "targetDateISO",
+            "totalAfterTaxAchieved",
+            "totalSharesSold",
+            "totalGrossProceeds",
+            "totalTaxes",
+            "schedule",
+            "comparison",
+            "remainingShares",
+            "remainingPositionValue",
+            "remainingPositionAfterTax",
+            "remainingNetByStack"
+          ],
+          "type": "object"
+        },
+        "planKey": {
+          "description": "Plan identifier. \"candidate\" entries appear only inside frontier.",
+          "enum": [
+            "recommended",
+            "lock_in_now",
+            "balanced",
+            "hold_for_growth",
+            "candidate"
+          ],
+          "type": "string"
+        },
+        "planLabel": {
+          "description": "Human-readable plan name.",
+          "type": "string"
+        },
+        "shortfallProbability": {
+          "description": "Lognormal probability (0..1) that realized cash lands below the target. 0 means a deterministic hit (sell everything today).",
+          "type": "number"
+        },
+        "totalTax": {
+          "description": "Total tax paid across the plan in dollars.",
+          "type": "number"
+        },
+        "wealthAtTarget": {
+          "description": "Total wealth in dollars at the target date: net cash plus retained shares at the projected price. The metric the recommendation maximizes.",
+          "type": "number"
+        }
+      },
+      "required": [
+        "planKey",
+        "planLabel",
+        "plan",
+        "wealthAtTarget",
+        "totalTax",
+        "shortfallProbability"
+      ],
+      "type": "object"
+    },
+    "recommended": {
+      "description": "The wealth-maximal plan whose shortfall probability is at or below the applied risk tolerance. Present this plan first.",
+      "properties": {
+        "lockInFraction": {
+          "description": "Fraction (0..1) of the target locked in by an immediate sale, for hybrid candidates. Omitted on pure named plans.",
+          "type": "number"
+        },
+        "plan": {
+          "description": "The full sale schedule for this plan. Nested year/sale entries follow the shapes described here and may carry additional fields.",
+          "properties": {
+            "comparison": {
+              "description": "This schedule vs the naive sell-everything-in-the-target-year alternative.",
+              "properties": {
+                "optimizedSavingsPct": {
+                  "description": "Tax saved as a fraction of the naive plan tax.",
+                  "type": "number"
+                },
+                "optimizedSavingsVsTargetYearSale": {
+                  "description": "Tax saved in dollars by this schedule vs the naive plan.",
+                  "type": "number"
+                },
+                "sellAllInTargetYearAfterTax": {
+                  "description": "After-tax cash in dollars under that naive plan.",
+                  "type": "number"
+                },
+                "sellAllInTargetYearTotalTax": {
+                  "description": "Tax in dollars if all needed shares were sold in the target year.",
+                  "type": "number"
+                }
+              },
+              "required": [
+                "sellAllInTargetYearTotalTax",
+                "sellAllInTargetYearAfterTax",
+                "optimizedSavingsVsTargetYearSale",
+                "optimizedSavingsPct"
+              ],
+              "type": "object"
+            },
+            "feasible": {
+              "description": "True when the schedule reaches the after-tax target by the target date.",
+              "type": "boolean"
+            },
+            "remainingNetByStack": {
+              "description": "Per-stack after-tax retained value in dollars, parallel to the input stacks array.",
+              "items": {
+                "type": "number"
+              },
+              "type": "array"
+            },
+            "remainingPositionAfterTax": {
+              "description": "After-tax value in dollars of liquidating all retained shares at the target date (the cash backstop if scheduled sales come in light).",
+              "type": "number"
+            },
+            "remainingPositionValue": {
+              "description": "Market value in dollars of retained shares at the projected target-date price.",
+              "type": "number"
+            },
+            "remainingShares": {
+              "description": "Shares retained after all scheduled sales.",
+              "type": "number"
+            },
+            "schedule": {
+              "description": "Per-year sale schedule. Each entry: year, saleDateISO, sales (array of per-lot entries: stackIndex, ticker, lotIndex, shares, grossProceeds, gainAmount, isLongTerm, federalTax, stateTax, niit, netCash), yearGrossProceeds, yearTotalTax, yearNetCash, runningCumulativeNet.",
+              "items": {
+                "additionalProperties": true,
+                "type": "object"
+              },
+              "type": "array"
+            },
+            "shortfall": {
+              "description": "Present only when the target is not reachable from the available inventory.",
+              "properties": {
+                "gap": {
+                  "description": "Dollars short of the target.",
+                  "type": "number"
+                },
+                "maxAchievableAfterTax": {
+                  "description": "Maximum after-tax cash in dollars achievable by the target date.",
+                  "type": "number"
+                }
+              },
+              "required": [
+                "maxAchievableAfterTax",
+                "gap"
+              ],
+              "type": "object"
+            },
+            "targetAfterTax": {
+              "description": "Echo of the requested net cash target in dollars.",
+              "type": "number"
+            },
+            "targetDateISO": {
+              "description": "Echo of the target date as an ISO date string.",
+              "type": "string"
+            },
+            "totalAfterTaxAchieved": {
+              "description": "Net after-tax cash in dollars the schedule produces by the target date (including after-tax cash interest when cashInterestRate is set).",
+              "type": "number"
+            },
+            "totalGrossProceeds": {
+              "description": "Total gross sale proceeds in dollars.",
+              "type": "number"
+            },
+            "totalSharesSold": {
+              "description": "Total shares sold across the schedule.",
+              "type": "number"
+            },
+            "totalTaxes": {
+              "description": "Tax totals across all scheduled sales, in dollars.",
+              "properties": {
+                "federal": {
+                  "description": "Federal capital gains / ordinary tax in dollars.",
+                  "type": "number"
+                },
+                "niit": {
+                  "description": "Net Investment Income Tax (3.8%) in dollars.",
+                  "type": "number"
+                },
+                "state": {
+                  "description": "State tax in dollars.",
+                  "type": "number"
+                },
+                "total": {
+                  "description": "Total tax in dollars.",
+                  "type": "number"
+                }
+              },
+              "required": [
+                "federal",
+                "state",
+                "niit",
+                "total"
+              ],
+              "type": "object"
+            }
+          },
+          "required": [
+            "feasible",
+            "targetAfterTax",
+            "targetDateISO",
+            "totalAfterTaxAchieved",
+            "totalSharesSold",
+            "totalGrossProceeds",
+            "totalTaxes",
+            "schedule",
+            "comparison",
+            "remainingShares",
+            "remainingPositionValue",
+            "remainingPositionAfterTax",
+            "remainingNetByStack"
+          ],
+          "type": "object"
+        },
+        "planKey": {
+          "description": "Plan identifier. \"candidate\" entries appear only inside frontier.",
+          "enum": [
+            "recommended",
+            "lock_in_now",
+            "balanced",
+            "hold_for_growth",
+            "candidate"
+          ],
+          "type": "string"
+        },
+        "planLabel": {
+          "description": "Human-readable plan name.",
+          "type": "string"
+        },
+        "shortfallProbability": {
+          "description": "Lognormal probability (0..1) that realized cash lands below the target. 0 means a deterministic hit (sell everything today).",
+          "type": "number"
+        },
+        "totalTax": {
+          "description": "Total tax paid across the plan in dollars.",
+          "type": "number"
+        },
+        "wealthAtTarget": {
+          "description": "Total wealth in dollars at the target date: net cash plus retained shares at the projected price. The metric the recommendation maximizes.",
+          "type": "number"
+        }
+      },
+      "required": [
+        "planKey",
+        "planLabel",
+        "plan",
+        "wealthAtTarget",
+        "totalTax",
+        "shortfallProbability"
+      ],
+      "type": "object"
+    },
+    "targetAfterTax": {
+      "description": "Echo of the requested net cash target in dollars.",
+      "type": "number"
+    },
+    "targetDateISO": {
+      "description": "Echo of the target date as an ISO date string.",
+      "type": "string"
+    }
+  },
+  "required": [
+    "recommended",
+    "lockInNow",
+    "balanced",
+    "holdForGrowth",
+    "frontier",
+    "targetAfterTax",
+    "targetDateISO",
+    "appliedRiskTolerance"
+  ],
+  "type": "object"
+}

Addedv1.7.0May 31, 2026

TDQS

A4.8/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, and the description adds meaningful behavioral context beyond them: 'The math runs inside the tool with no randomness and no model inference', missing required fields 'returns an error naming the field rather than an estimated result', numbers are accepted 'as-is' with 'no provenance check', and results from multiple tools are independent single-position calculations. No contradiction with annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is long but front-loaded with purpose and routing, and nearly every sentence earns its place given the tool's 12-parameter complexity, output schema, and sibling differentiation. Minor redundancy exists: 'Use this when' appears twice ('Use this when someone asks...' and 'Use this when an equity holder needs cash by a deadline') with overlapping intent, which trims the structure score slightly.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Highly complete: covers what the tool does, when to use it, when not to, input forms (stacks vs legacy), parameter semantics for growth, error behavior, deterministic execution, output plan names and their key metrics, an explicit example, and guidance on cross-tool independence and beta alternatives. The output schema exists, so not describing the full return shape is acceptable.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the baseline is 3. The description adds value beyond the schema with a complete worked example, clarification of the expectedAnnualGrowth 'market'/ticker resolution behavior, the rule that omitting growth is an error rather than a default, and the relationship between stacks, lots, and currentPrice. It doesn't add much per-parameter detail beyond the schema, hence 4 rather than 5.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific, actionable verb scope: 'Use this when someone asks which shares to sell and when to reach a cash goal by a deadline' and identifies the tool as a 'Multi-year, multi-stack equity-funding optimizer' that returns four named plans. It differentiates from siblings by naming upstream tools (rsu_sell_vs_hold, nso_calculate, amt_iso_optimize) and out-of-scope tools (qsbs_check).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides explicit when-to-use guidance: 'Use this when someone asks which shares to sell and when to reach a cash goal by a deadline...' and when-not-to-use by directing to alternatives: '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' and 'Out of scope: FICA, AMT, QSBS routing (use qsbs_check)'. Also explains the legacy lots/currentPrice vs stacks choice.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server