Skip to main content
Glama
AlvisoOculus

OptionsAhoy: Stock Equity and Tax Optimizer

by AlvisoOculus
OverviewSchemaSourceRelated ServersDiscussions(1)Admin
TypeScript
Remote

rsu_lot_optimize

Read-onlyIdempotent

Find which vested RSU lots to sell and in which tax years to minimize computed tax when divesting a concentrated stock position. Compare against FIFO and see 1-, 2-, or 3-year trade-offs.

Instructions

Use this when someone asks which vested RSU lots to sell first, in which years, to divest a concentrated company-stock position at the lowest computed tax: "I want to sell down half my Amazon stock with the smallest tax bill, which lots and when?". Given the vested lots (vest date, shares, cost basis), a current price, and a divest fraction, it chooses WHICH lots and WHICH sale dates minimize computed total tax to divest that many shares, using three levers: specific-lot identification (sell higher-basis lots to realize less gain, or underwater lots to harvest losses that net against gains), long-term deferral (wait past the one-year mark to convert short-term ordinary rates to long-term capital gains), and multi-year bracket spreading (split gains across 1 to 3 tax years, with in-plan capital-loss carryforward). Every sale is priced at today's price (flat-price assumption; there is no growth model). Returns the year-by-year sell schedule grouped by tax year, the total tax (federal LTCG + NIIT + state), what a first-in-first-out (FIFO) oldest-first sell order on the same schedule would have cost (headlineDeltaVsFifo), a 1/2/3-year horizon trade-off, and per-lot deferral callouts. This tool owns WHICH LOTS and WHICH DATES; for WHETHER and HOW MUCH to sell down a position use concentration_analyze, for a single new vest use rsu_sell_vs_hold, and to raise a specific cash amount by a deadline use equity_funding_plan. Out of scope: growth/return modeling, wash-sale basis migration, AMT, unvested grants. Example: {lots: [{vestDate: "2022-08-15", shares: 120, costBasisPerShare: 95}, {vestDate: "2024-02-15", shares: 100, costBasisPerShare: 130}, {vestDate: "2026-05-15", shares: 80, costBasisPerShare: 210}], currentPrice: 180, divestFraction: 0.5, horizonYears: 2, ordinaryIncome: 200000, filingStatus: "single", stateCode: "CA"}. Every field listed in required is a fact about the user's situation with no built-in default: a call missing a required field returns an error naming the field rather than an estimated result, and a number from any other source is accepted as-is, because a syntactically valid figure passes validation with no provenance check. The math runs inside the tool with no randomness and no model inference. Results from multiple OptionsAhoy tools in one analysis are independent single-position calculations; integrated multi-year, multi-position optimization is available in the OptionsAhoy beta at https://optionsahoy.com/beta?src=mcp_multi.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
lotsYesThe vested RSU lots still held (after any sell-to-cover), one entry per vest tranche. The tool decides which of these to sell and when. Unvested grants are out of scope. At most 20 lots per call, the same cap the web calculator uses. With more tranches than that, combine the ones sharing a vest date and cost basis.
stateCodeYesTwo-letter US state code (e.g. CA, NY, TX). Drives state capital-gains treatment (CA taxes gains as ordinary; WA/TX/FL have no tax on most capital gains).
currentPriceYesCurrent share price, USD. Every sale, on every date, is priced at this value (flat-price assumption). This value must come from the user.
filingStatusYesFederal filing status. Drives LTCG brackets, the NIIT threshold, and state bracket lookups.
horizonYearsYesTax years the plan may span: 1 = sell everything now, 2, or 3. More years let the plan spread gains across brackets and defer short-term lots to long-term, at the cost of staying exposed to the stock longer. The user's choice, not a modelling detail, and it changes the answer: use the value they gave, and if they gave none, ask for it rather than assuming one.
divestFractionYesFraction of TOTAL shares to divest, as a decimal (0.5 = sell half). Range 0.10 to 1.0. NOTE: a decimal fraction, NOT a percent, so pass 0.5 not 50. The tool sells round(divestFraction x totalShares) shares, floored at 1. The user's choice, not a modelling detail, and it changes the answer: use the value they gave, and if they gave none, ask for it rather than assuming one.
ordinaryIncomeYesTotal household ordinary income for the year, USD, from all sources. Sets the federal LTCG bracket floor, the short-term ordinary rate, and the net investment income tax (NIIT) threshold test. This is taxable income after deductions, not gross wages: the engine applies no standard or itemized deduction to it. Assumed constant across plan years. Must come from the user.

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault
scheduleYesThe sell plan, grouped by tax year.
totalTaxYesTotal plan tax across all years (federal LTCG + NIIT + state, net of in-plan loss carryforward), in dollars.
totalGrossYesGross proceeds from the divested shares, in dollars.
attributionYesTelescoping attribution of the total saving vs a FIFO-all-today sale. lotSelection + spreadingDeferral = total.
totalSharesYesTotal shares across all input lots.
horizonCardsYesThe same divest target under a 1-year ("all now"), 2-year, and 3-year plan, for the trade-off strip.
sharesToSellYesShares the plan divests (round(divestFraction x totalShares), floored at 1).
totalAfterTaxYesAfter-tax proceeds from the divested shares, in dollars.
deferralCalloutsYesPer-lot short-term-to-long-term deferral opportunities.
keptUnrealizedGainYesUnrealized gain still carried by the shares NOT sold, in dollars (deferred, not eliminated).
headlineDeltaVsFifoYesDollars saved versus selling oldest-first (FIFO) on the SAME schedule. Pure lot-selection benefit; >= 0 by construction.
headlineAfterTaxKeptYesAfter-tax proceeds under the plan, in dollars: the headline "you keep $X" figure.
carryforwardRemainingYesCapital loss remaining at the end of the plan horizon, in dollars (reported, not modeled into future years).

Schema Changelog

Changes observed during successful MCP inspections.

  1. Addedv1.10.1

TDQS

A5/5.0
Behavior5/5

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

Annotations already signal read-only and non-destructive behavior; the description goes far beyond them by disclosing the flat-price assumption (every sale priced at today's price), the absence of randomness and model inference, the error behavior for missing required fields, and that results are independent per-position calculations. It also reveals that required fields are user facts with no defaults and that any syntactically valid number passes validation without provenance checks. No contradiction with annotations exists.

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

Conciseness5/5

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

The description is long but every sentence earns its place: the opening line states purpose, the middle explains the decision levers and return fields, and the end gives usage routing, out-of-scope exclusions, an example, and error-handling semantics. It is front-loaded with the most important scoping, and the structure flows logically from what→how→when→example→caveats. No filler or tautology.

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 7-parameter tool with an output schema, the description covers everything needed: the return values (year-by-year schedule, total tax, headlineDeltaVsFifo, horizon trade-off, per-lot callouts), the flat-price assumption, the 20-lot cap with grouping guidance, and the fact that unvested grants and wash-sale basis migration are out of scope. The example fields align with the schema, and the error behavior is clarified. 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?

Schema coverage is 100%, so the baseline is 3, but the description adds substantial meaning beyond schema names. It warns divestFraction is a decimal not a percent, explains horizonYears is a user choice that changes the answer, clarifies ordinaryIncome is taxable income after deductions with no built-in standard deduction, and notes currentPrice must come from the user and is used for all sales. This nuance materially improves correct invocation.

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 starts with a specific verb and resource: it chooses which vested RSU lots to sell, in which years, to minimize computed tax for a divestment fraction. It names the three optimization levers (lot identification, long-term deferral, bracket spreading) and explicitly distinguishes itself from siblings by stating it owns WHICH LOTS and WHICH DATES, while pointing to concentration_analyze, rsu_sell_vs_hold, and equity_funding_plan for adjacent questions. This makes the tool's unique role unmistakable.

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?

The description gives explicit when-to-use triggers (e.g., 'I want to sell down half my Amazon stock... which lots and when?') and equally explicit alternatives: concentration_analyze for whether/how much, rsu_sell_vs_hold for a single new vest, equity_funding_plan for raising cash by deadline. It also lists out-of-scope items like growth modeling, AMT, and unvested grants. No inference is required to decide when to use this tool.

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

Deploy Server

Other Tools