Skip to main content
Glama

optionsahoy-mcp

by io.github.AlvisoOculus

equity_funding_plan

Read-onlyIdempotent

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
NameRequiredDescriptionDefault
lotsNoLegacy 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).
stacksNoHoldings, 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.
stateCodeYesTwo-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).
targetDateYesDate 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.
currentPriceNoLegacy single-stack current share price, USD. Pair with legacy `lots` (omit `stacks`). This value must come from the user.
filingStatusYesFederal filing status. Drives LTCG brackets, NIIT threshold ($200K single / $250K MFJ MAGI), and state bracket lookups.
ordinaryIncomeYesAnnual 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.
targetAfterTaxYesNet 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.
cashInterestRateNoAnnualized 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).
defaultVolatilityNoAnnualized σ 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.
expectedAnnualGrowthNoLegacy 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.
riskToleranceShortfallNoMax 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
NameRequiredDescriptionDefault
balancedYesBracket-aware spread across all candidate years: minimum tax.
frontierYesAll candidate plans from the hybrid lock-in sweep plus the named plans, sorted by shortfall probability.
lockInNowYesSell everything needed in the current calendar year: minimum price risk, usually highest tax.
recommendedYesThe 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.
holdForGrowthYesSell only in the target year: maximum expected wealth, maximum price risk.
targetDateISOYesEcho of the target date as an ISO date string.
targetAfterTaxYesEcho of the requested net cash target in dollars.
appliedRiskToleranceYesShortfall-probability tolerance actually applied (default 0.10 when not supplied).

TDQS

A4.8/5.0
Behavior5/5

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

Annotations already mark the tool read-only and idempotent; the description adds behavioral guarantees beyond that: determinism ('no randomness and no model inference'), explicit error behavior for missing required fields ('returns an error naming the field rather than an estimated result'), and no provenance checks on numeric inputs. This is valuable context that annotations do not provide.

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 well-structured and front-loaded, with the use case, output plans, alternatives, example, and parameter semantics arranged logically. However, it is somewhat verbose: 'Use this when' is repeated, and the beta-link sentence at the end is not needed for tool selection. Still, for a 12-parameter tool the density of useful detail justifies the length.

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?

For a complex tool with 12 parameters, the description covers the purpose, when to use it, alternatives, out-of-scope items, a concrete example, error behavior, and parameter semantics. It intentionally defers the output shape to the outputSchema, which is appropriate since one exists. No major gaps remain.

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 coverage of parameters is 100%, so the baseline is 3. The description adds meaning beyond the schema by explaining how `expectedAnnualGrowth` can be a decimal, the string 'market', or resolved from a ticker, and by clarifying that omitting growth is a hard error. It also explains the `stacks` vs legacy `lots` distinction and that required fields have no built-in defaults.

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 use case ('which shares to sell and when to reach a cash goal by a deadline') and names the tool's core outputs: four named plans (`lockInNow`, `balanced`, `holdForGrowth`, `recommended`) plus a `frontier` sweep. It explicitly differentiates from siblings by directing upstream tax math to `rsu_sell_vs_hold` / `nso_calculate` / `amt_iso_optimize` and QSBS to `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?

Explicit 'Use this when' statements appear twice, defining the intended scenario and giving concrete exclusions ('Out of scope: FICA, AMT, QSBS routing'). It also names sibling alternatives to call first, so the agent knows when this tool is the right choice versus others.

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

All optionsahoy-mcp toolsInspect
Try in Browser
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

TDQS

A4.6/5.0
Disambiguation4/5

Most tools are cleanly scoped to distinct instruments and decisions (ISO/AMT, NSO, RSU vest, lot selection, hedge pricing, QSBS, concentration, cash funding), and the descriptions actively cross-reference the correct tool for each scenario. The main ambiguity is among the divestment-oriented tools (rsu_lot_optimize, equity_funding_plan, concentration_analyze), though the descriptions explain their different triggers well.

Naming Consistency4/5

Names mostly follow a readable `{domain}_{action}` snake_case pattern, e.g., amt_iso_optimize, nso_calculate, qsbs_check. The verbs vary across optimize/calculate/check/analyze/plan/sell, and equity_funding_plan and protective_put_price read more as noun phrases, so the convention is recognizable but not perfectly uniform.

Tool Count5/5

With 8 tools, the set is well-scoped and each tool covers a meaningful, non-redundant computation in the equity-compensation planning domain. There are no filler tools or extreme over- nor under-provisioning.

Completeness4/5

The core single-position workflows are covered: ISO/AMT optimization, NSO exercise, RSU vest decisions, lot selection, hedging, QSBS qualification, concentration, and goal-based funding. Missing pieces are mostly edge-domain items like ESPP, disqualifying dispositions, and integrated multi-position scenarios, which are explicitly noted as out of scope or beta.

Resources