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
One command on the Portfolio lots and harvesting server, callable over MCP as check_holdings. 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.
What it needs, and why
Every input is checked before anything is calculated. subject_ref, document_ref, as_of, prices and idempotency_key are required; the rest refine the answer.
| Input | What it asks for | Why it matters | If you omit it |
|---|---|---|---|
subject_ref | Account or household id you are entitled to read | The account or household the analysis is scoped to. Naming one is a request to read it, never a grant. | required |
document_ref | Path to the normalized holdings export to analyse | Account metadata, lots and basis come from the export, and nothing resolves until one has been read. | required |
as_of | Analysis date, YYYY-MM-DD | Holding periods and the 30-day wash-sale window are both measured from the analysis date. | required |
prices | Price per share by security id, as decimal strings | A gain cannot be computed without a price per security, and no price is ever fetched or guessed here. | required |
idempotency_key | Caller-chosen key | Repeating the key returns the first run instead of running again, so a retry cannot spend a gain budget twice. | required |
Requests it answers
- “Which lots cannot support a tax calculation?”
- “What is missing from this holdings export?”
An agent with these skills loaded picks the command from phrasing like that, asks for whatever input is missing, and reports the figures with the method that produced them.
Run it
TAXAGENT_TENANT_ID=... TAXAGENT_PRINCIPAL_ID=... TAXAGENT_ACCOUNTS=... scripts/mcp_server.sh --server portfolioThe same command is exposed by taxagent-portfolio, so Claude, Claude Code, Codex, Cursor and any other MCP client can call it directly. 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.
Scripted cases that exercise it
1 of the 71 console cases call this command on a real server over JSON-RPC and assert the outcome. Every one runs on every build, and all of them are listed on the case inventory.
| Case | What it asks | What it shows | Outcome |
|---|---|---|---|
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 |
Limits it inherits from taxagent-portfolio
- Greedy selection; no optimality claim.
- No multi-period or risk-aware objective.
- Optimal means optimal over the lots, prices and constraints supplied, for the stated objective: reach the cash target, realize as little gain as possible, use as few trades as possible. It is not a statement about what the account should do.
- Risk, tracking error, a client's view on a position and the reason a lot was bought are outside the model entirely.
- Beyond 40 budget-consuming lots the search is not exhausted. The status degrades to feasible and a gap is reported; optimality is never claimed from a truncated search.
- Account scope only. Running it once per account is not a household optimum.
- Drift is the sum of absolute differences between current and target weight. The engine never sells more of a security than its overweight, so with chunky lots it under-trades rather than overshooting, and residual drift is expected and reported.
- Buys are allocated across underweight securities in proportion to their shortfall. A purchase has no tax consequence, so there is nothing to optimise about which lot it becomes.
- A buy is withheld when the security was sold at a loss inside the wash-sale window, which leaves that drift open until the window closes.
- Requires advisor-supplied target weights. Inferring a target from the current holdings would make the portfolio its own benchmark.
- Account scope only, and no view on transaction costs, market impact, tracking error or which account should hold which exposure.
The server, its other 8 commands and what it deliberately leaves alone are on the Portfolio lots and harvesting page.