optionsahoy-mcp

nso_calculate

Read-onlyIdempotent

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. Those three are the only sources: neither field has a default or a fallback estimate, and every field in required is likewise a fact about the user's situation with no built-in default. A call that neither supplies nor resolves growth or volatility returns a required-field error naming the field; 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.

Input Schema

TableJSON Schema

Name	Required	Description
`shares`	Yes	Non-qualified Stock Option (NSO) shares to exercise. Must come from the user.
`strike`	Yes	Strike price per share, USD. Must come from the user.
`ticker`	No	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`	No	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`	Yes	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`	Yes	Two-letter US state code. Drives state ordinary and LTCG treatment.
`volatility`	No	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. This value must come from the user or from a `ticker` that resolves it as of the last market close; if neither supplies it, ask the user rather than estimating one.
`holdFunding`	Yes	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`	Yes	Current fair market value per share, USD. The bargain element at exercise is shares × (currentPrice − strike). Must come from the user.
`filingStatus`	Yes	Federal filing status. Drives ordinary brackets and LTCG brackets used at the hold horizon.
`stillEmployed`	Yes	True if still employed at exercise. FICA (Social Security + Medicare + Additional Medicare) applies only when true.
`ordinaryIncome`	Yes	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`	No	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`	No	Annual after-tax-proceeds reinvestment rate. Defaults to SPY trailing CAGR for holdYears if omitted; the string "market" names that same default explicitly.

Output Schema

TableJSON Schema

Name	Required	Description
`hold`	Yes	Exercise now and hold the shares holdYears for long-term capital gains treatment.
`exercise`	Yes	Tax bill at exercise on the bargain element (taxed as ordinary W-2 income).
`bracketJump`	Yes	Marginal federal bracket change caused by the new ordinary income; null when the income stays within one bracket.
`sellNowInvest`	Yes	Counterfactual: sell every share at exercise and reinvest the net cash at expectedMarketReturn for holdYears.
`holdMinusCashless`	Yes	hold.netAtYearN - sellNowInvest.netAtYearN in dollars. Positive favors holding the shares; negative favors selling at exercise and reinvesting.

TDQS

A4.9/5.0

Behavior5/5

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and the description goes well beyond them: it explains the tool is deterministic and offline, that tax tables are compiled in, that hold is always long-term, that it returns required-field errors for missing growth/volatility, that it has no defaults, and that results are independent single-position calculations. This is rich, accurate behavioral disclosure with no contradiction.

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 well-structured: purpose and outputs first, usage and alternatives next, then detailed parameter semantics and caveats. Every sentence carries important information, and the density is justified by the tool's complexity (14 params, many edge cases). While not concise in the strict sense, it is efficiently organized and front-loaded, so the essential purpose appears immediately.

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?

Given the high parameter count (14), complex tax calculations, and a provided output schema, the description is exceptionally complete. It covers all input sources (user, ticker, 'market'), error behavior, no-default policies, funding methods, and even points to verification links and multi-tool integration. Nothing an agent needs to call this correctly is missing.

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

Parameters5/5

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

Although schema coverage is 100%, the description adds substantial meaning beyond the schema. It explains the 'market' sentinel for expectedSalePrice, that volatility must be the raw sigma not a drag, that haircut is an alternative and horizon-dependent, that holdYears changes the answer and should be asked for if absent, and the cash vs sell-to-cover implications including the cashNeededAtExercise output. These clarifications materially improve parameter understanding.

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 states a specific verb and resource ('After-tax payout on a non-qualified stock option (NSO) exercise') and clearly distinguishes from siblings: 'Use for NSOs; for ISOs use `amt_iso_optimize`, for RSUs use `rsu_sell_vs_hold`.' It also lists the key outputs (exercise, hold, sellNowInvest, holdMinusCashless, bracketJump), so an agent knows exactly what this tool does and how it differs.

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?

Explicitly states when to use it ('Use this when someone asks whether to exercise and hold or exercise and sell non-qualified stock options...') and when not to, naming the alternative tools for ISOs and RSUs. Also covers edge cases like 'sub-1-year is out of scope' and warns against inventing inputs. The guidance is unambiguous and actionable.

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

All optionsahoy-mcp tools Inspect

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.

nso_calculate

Input Schema

Output Schema

TDQS

Glama MCP Gateway

TDQS

Resources