Analysis only. No tool in this server places orders, modifies custodian records or files returns. Every result is scoped to the accounts this principal is entitled to read; an account named in an argument is a request, not a grant. Unknown basis blocks a lot rather than defaulting to zero.
9 commands, every one callable over MCP. Every result carries the method it used, the rule pack it was pinned to, what is still missing and whether coverage was complete, for a licensed professional to review.
| Command | What it returns | What it needs |
|---|---|---|
check_holdings | Build a snapshot from an uploaded export and report the lots that cannot support a tax calculation: unknown basis, missing acquisition date, gaps in coverage. Run this first when a document is new. | subject_ref, document_ref, as_of, prices, idempotency_key |
review_rebalance | Rebalance one account toward target weights, tax-aware. Never sells a security below its target, so with chunky lots it under-trades rather than overshooting and reports the residual drift. Withholds a purchase that would wash a loss sold inside the window. | subject_ref, document_ref, as_of, prices, idempotency_key, target_weights |
review_lots | Gain and loss by lot with a wash-sale screen across the accounts in scope. Reports what is there; proposes nothing. | subject_ref, document_ref, as_of, prices, idempotency_key |
optimize_harvest | The same harvest problem as review_harvest, solved exactly rather than greedily. Where the search exhausts it proves no other selection raises the cash at lower tax cost. Slower, and it reports a certificate and an optimality gap. | subject_ref, document_ref, as_of, prices, idempotency_key, cash_target |
review_harvest | Loss-harvesting scenario for one taxable account against a cash target, screened for wash sales. Produces a proposal for professional review, never a trade instruction. | subject_ref, document_ref, as_of, prices, idempotency_key, cash_target |
resolve_subject | Resolve an account or household you are entitled to read and report its tax units. Pass document_ref on the first call of a session: account metadata comes from the document, and nothing resolves until one has been read. | subject_ref |
get_run_status | Status of a run. Transport success is not workflow completion. | run_id |
get_scenario | Retrieve a stored evidence package by reference, including the rule pack and snapshot the run was pinned to. | evidence_ref |
get_capabilities | Which engines, asset classes and tax years this server covers for account-scope analysis, with each engine's limitations. Harvesting, exact optimization and rebalancing are separate engines making separate claims. | nothing required |
Account-scope lot analysis: gain and loss, wash-sale screening, loss-harvest scenarios. This server carries an authenticated principal: an account named in an argument is a request to read it, never a grant.
Requests it answers:
Skills that route here, each with the moment it applies:
gain-loss-reviewThe user asks what a sale would realize, how much gain they have taken this period, or how a disposal splits between short-term and long-term.
Calculate realized and unrealized gain and loss at lot level, split by holding period, from a frozen snapshot. Use when the user asks what they would realize by selling, where they stand on gains this year, or how a sale splits between short and long term.
harvest-reviewThe user wants to know what losses could be harvested, or wants to raise cash while keeping realized gains within a limit, in a taxable account.
Review tax-loss harvesting opportunities in one taxable account, with wash-sale screening and an explicit gain budget. Use when the user asks about harvesting losses, offsetting gains, or raising cash tax-efficiently. Produces scenarios for professional review, never a trade instruction.
household-coordinationA request spans several accounts of one household, or several sleeves of a UMA. Also use it whenever different managers may trade the same security for the same taxpayer.
Coordinate harvesting and cash raising across a household's accounts or a UMA's sleeves under one shared gain budget, with cross-account and cross-sleeve wash-sale prevention. Use when a request spans more than one account or manager, or when a UMA overlay must stop one sleeve from washing another's loss.
lot-reviewBefore relying on any gain, loss or harvest number, and whenever a result came back with `MISSING_BASIS`, `POSITION_MISMATCH` or `DUPLICATE_LOT`.
Check tax-lot completeness and integrity before any tax calculation — basis, acquisition dates, quantities, duplicates and position reconciliation. Use when lots have just been imported, a transfer arrived, or another skill reported blocked calculations.
rebalance-reviewThe user has approved targets and wants to move toward them, or wants to compare acting now against leaving the drift. Targets come from the advisor. This skill does not propose an allocation: an engine that inferred a target from the current holdings would be measuring drift against its own assumption.
Rebalance one account toward advisor-supplied target weights within a gain budget, showing the tax cost and the drift that remains. Use when the user asks what rebalancing would cost, or wants to compare acting now against leaving the drift.
tax-intakeNo snapshot exists, or new source documents have arrived.
Turn uploaded statements and exports into source-cited, normalized tax facts with a missing-information register. Use at the start of any engagement, or when new documents arrive and no snapshot exists yet.
tax-profileAt the start of an engagement, and whenever scope is ambiguous.
Establish the household scope, tax units, account classifications and stated assumptions that every other tax skill depends on. Use before the first analysis of an engagement, or when ownership, registration or residency is unclear.
tax-review-packAn analysis has completed and a person needs to review it, or a CPA needs a handoff.
Assemble a source-bound review package for a completed analysis — scope, assumptions, results, validation, limitations and version pins — for the responsible professional. Use when the user wants something to review, file, sign off, or hand to a CPA.
wash-sale-reviewThe user asks whether a loss will be disallowed, mentions buying back something they sold at a loss, or asks about the 30-day rule.
Screen proposed or completed loss sales for wash sales under IRC section 1091, across the accounts available, with explicit coverage gaps. Use when the user asks whether a loss is allowed, about the 30-day rule, or about repurchasing a security they sold at a loss.
Named here because leaving it out is how an agent ends up asserting something the code never computed. Each line is the registry's own wording, not a summary of it.
4 rules in the pack this server reads, each carrying its authority and legal effective date. The engines read from the pack, and a constant reappearing in the calculation path fails the build.
| Rule | Authority |
|---|---|
long_term_holding_period_years | IRC section 1222(3); Rev. Rul. 66-7 |
permanently_disallowing_registrations | Rev. Rul. 2008-5 |
replacement_matching_basis | IRC section 1091(a) |
wash_sale_window_days | IRC section 1091(a) |
3 engines behind these commands, straight from capabilities/engines.yaml. An engine with no passing reference test may not be advertised as implemented.
| Engine | Status | Scopes | Tax years | Claims optimality |
|---|---|---|---|---|
rule-based-harvest-selector | implemented | account | 2026 | no |
oracle-account-adapter | implemented | account | 2026 | yes |
rebalance-engine | implemented | account | 2026 | yes |
14 of the 71 console cases call this server over JSON-RPC on every build, across 6 of the 15 client objectives the case inventory groups by: Cap realized gains, Entitlement, scope and replay, Harvest losses, Raise cash, Rebalance and Trust the data.
| Case | What it asks | What it shows | Outcome |
|---|---|---|---|
portfolio-discover | Finding what you are allowed to analyse | The first call of a session. Account metadata comes from the document, so it is named here; entitlements still decide the answer. | completed |
portfolio-denied | An account in the document you are not entitled to | The document describes it, so it exists. It is still refused, and with the same wording as an account that does not exist at all. | ACCESS_DENIED |
portfolio-lots | Gain and loss by lot, with a wash-sale screen | What is held and what it carries. Proposes nothing: this is the tool for 'where do we stand', not 'what should we do'. | completed_with_limitations |
portfolio-harvest | Raise $10,000 by harvesting losses | A proposal, the losses it realises, and the lots it held back — one for wash-sale risk, one for unknown basis. | completed_with_limitations |
portfolio-missing-netting | A gain budget with no netting basis | 'Keep gains under $15,000' reads two ways and they give different answers, so the schema requires the caller to say which. | protocol_or_needs_input |
portfolio-infeasible | A target the budget cannot reach | The shortfall is reported. The constraint is never quietly relaxed to manufacture a result that looks like success. | INFEASIBLE_CONSTRAINTS |
portfolio-planned-purchase | A purchase you have not placed yet | Screening a planned buy before it happens turns a disallowed loss into a decision the advisor still gets to make. | completed_with_limitations |
portfolio-idempotent | The same key twice returns the same run | Repeating a request must not produce a second analysis with a new evidence package. The key is the caller's guarantee. | accepted |
portfolio-household-refused | A household asked of the account server | Running an account engine over a household is refused rather than approximated, and the refusal names what is available instead. | UNSUPPORTED_SCOPE |
portfolio-wrong-year | An analysis dated to a year with no rule pack | No reviewed pack covers 2019, so the run is blocked rather than computed from this year's rules under last decade's law. | WRONG_RULE_YEAR |
portfolio-intake | What in this document cannot be used | Run first on a new export. Lots with unknown basis are named here rather than silently treated as zero-basis later. | completed_with_limitations |
portfolio-rebalance | Rebalance to target weights, tax-aware | Closes drift within a gain budget, never selling a security below its target. With chunky lots it under-trades rather than overshooting, and reports the residual. | completed_with_limitations |
portfolio-rebalance-needs-targets | A rebalance with no target weights | Refused rather than inferred. Deriving a target from the current holdings would make the portfolio its own benchmark. | protocol_or_needs_input |
portfolio-no-execution | There is no tool that places a trade | Not disabled, not permissioned off — absent. A caller asking for one is refused at the boundary. | UNSUPPORTED_SCOPE |
Build a snapshot from an uploaded export and report the lots that cannot support a tax calculation: unknown basis, missing acquisition date, gaps in coverage. Run this first when a document is new. It needs subject_ref, document_ref, as_of, prices and idempotency_key. The account or household the analysis is scoped to. Naming one is a request to read it, never a grant. Call check_holdings on taxagent-portfolio over MCP. Every result carries the method it used, the rule pack it was pinned to, what is still missing and whether coverage was complete, for a licensed professional to review.
Rebalance one account toward target weights, tax-aware. Never sells a security below its target, so with chunky lots it under-trades rather than overshooting and reports the residual drift. Withholds a purchase that would wash a loss sold inside the window. It needs subject_ref, document_ref, as_of, prices, idempotency_key and target_weights. The account or household the analysis is scoped to. Naming one is a request to read it, never a grant. Call review_rebalance on taxagent-portfolio over MCP. Every result carries the method it used, the rule pack it was pinned to, what is still missing and whether coverage was complete, for a licensed professional to review.
Gain and loss by lot with a wash-sale screen across the accounts in scope. Reports what is there; proposes nothing. It needs subject_ref, document_ref, as_of, prices and idempotency_key. The account or household the analysis is scoped to. Naming one is a request to read it, never a grant. Call review_lots on taxagent-portfolio over MCP. Every result carries the method it used, the rule pack it was pinned to, what is still missing and whether coverage was complete, for a licensed professional to review.
The same harvest problem as review_harvest, solved exactly rather than greedily. Where the search exhausts it proves no other selection raises the cash at lower tax cost. Slower, and it reports a certificate and an optimality gap. It needs subject_ref, document_ref, as_of, prices, idempotency_key and cash_target. The account or household the analysis is scoped to. Naming one is a request to read it, never a grant. Call optimize_harvest on taxagent-portfolio over MCP. Every result carries the method it used, the rule pack it was pinned to, what is still missing and whether coverage was complete, for a licensed professional to review.
Loss-harvesting scenario for one taxable account against a cash target, screened for wash sales. Produces a proposal for professional review, never a trade instruction. It needs subject_ref, document_ref, as_of, prices, idempotency_key and cash_target. The account or household the analysis is scoped to. Naming one is a request to read it, never a grant. Call review_harvest on taxagent-portfolio over MCP. Every result carries the method it used, the rule pack it was pinned to, what is still missing and whether coverage was complete, for a licensed professional to review.
Resolve an account or household you are entitled to read and report its tax units. Pass document_ref on the first call of a session: account metadata comes from the document, and nothing resolves until one has been read. It needs subject_ref. The account or household the analysis is scoped to. Naming one is a request to read it, never a grant. Call resolve_subject on taxagent-portfolio over MCP. Every result carries the method it used, the rule pack it was pinned to, what is still missing and whether coverage was complete, for a licensed professional to review.