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

Compares which vested RSU lots to sell and in which tax years, by total computed tax, to divest part of a concentrated stock position.

Instructions

Use this when someone asks which vested RSU lots to sell first, in which years, to divest part of a concentrated company-stock position, compared on total computed tax: "I want to sell down half my Amazon stock; which lots, and when?". Given the vested lots (vest date, shares, cost basis), a current price, and a divest fraction, it compares WHICH lots and WHICH sale dates to use, by 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

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

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

A4.8/5.0
Behavior5/5

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

Annotations already declare read-only/idempotent/closed-world, so the bar is exceeded by real additions: flat-price assumption for every sale (no growth model), deterministic math with no randomness or model inference, error-on-missing-required-field behavior, no provenance check on supplied numbers, and the caveat that cross-tool results are independent single-position calculations. These are behavioral facts an agent cannot get from the annotations or schema.

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?

Long, but well front-loaded: the triggering question and the sibling routing come first, and the levers, outputs, and caveats are grouped logically. The closing provenance sentence and the beta promo link are marginally promotional rather than operational, which costs it a point without undermining the structure.

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?

With an output schema present, return values need not be described, yet the description still names the key outputs (year-by-year schedule, total federal LTCG + NIIT + state tax, `headlineDeltaVsFifo`, horizon trade-off) to set expectations for a FIFO benchmark. Combined with annotations covering safety and a fully documented 7-parameter schema, an agent has everything needed to call it correctly.

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 is 100%, so baseline is 3, but the description adds semantic meaning beyond the schema: the three optimization levers (specific-lot selection, long-term deferral past the one-year mark, 1-to-3-year bracket spreading with loss carryforward), the flat-price pricing rule that governs `currentPrice`, and a fully worked example call. It stops short of explaining every parameter's interaction with the output.

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 precise verb+resource+scope: it decides WHICH vested RSU lots to sell in WHICH years, compared on computed total tax, and explicitly claims ownership of "WHICH LOTS and WHICH DATES" versus sibling tools. The concrete user-question framing ("sell down half my Amazon stock; which lots, and when?") makes the tool's job unmistakable. It is distinguishable from all listed siblings without opening any schema.

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?

It routes explicitly: `concentration_analyze` for whether/how much to sell, `rsu_sell_vs_hold` for a single new vest, `equity_funding_plan` to raise a specific cash amount by a deadline. It also enumerates out-of-scope areas (growth modeling, wash-sale basis migration, AMT, unvested grants), so both positive and negative selection conditions are stated.

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