Household and UMA coordination: Claude skills backed by tested code
Analysis only. No tool in this server places orders, modifies custodian records or files returns. Two engines with different claims: optimize_household solves the whole household at once and, where the search exhausts, proves no other selection does better; coordinate_household serves accounts in a declared order, reserves budget as it goes, and is never optimal. Optimality is over the lots, prices and constraints supplied and for one objective, not a judgement about what the household should do. Budgets are allocated per tax unit: a household spanning several tax units gets several budgets and never one pooled allowance.
What taxagent-household computes
2 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 |
|---|
optimize_household | Solve the whole household at once rather than account by account. No ordering, and where the search exhausts it proves no selection does better. Budgets are still per tax unit and never pooled. Prefer this over coordinate_household unless you need the reservation behaviour. | subject_ref, document_ref, as_of, prices, idempotency_key, cash_target |
coordinate_household | Run several accounts or UMA sleeves against one shared gain budget per tax unit, reserving budget so no two runs spend the same allowance and screening cross-sleeve wash sales. Sequential, not a joint optimum; the optimality gap is reported. | subject_ref, document_ref, as_of, prices, idempotency_key, cash_target |
When to use it
Household and UMA-sleeve coordination over one shared budget per tax unit. This server carries an authenticated principal: an account named in an argument is a request to read it, never a grant.
Requests it answers:
- “How should a whole household harvest together?”
- “How do I share one gain budget across accounts?”
Skills that route here, each with the moment it applies:
household-coordination
A 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.
What it does not do
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.
- Sequential allocation. Results depend on the declared unit order and are not a joint optimum.
- Budgets are allocated per tax unit; a household spanning several tax units gets several budgets, never one.
- Cross-unit wash-sale prevention covers accounts in scope and planned purchases supplied with the request. Unseen accounts and unreported manager intentions remain outside it.
- Solved per tax unit and summed. That decomposition is exact, not an approximation: a gain budget belongs to one taxpayer, so no selection in one unit changes what is available in another and the objective is additive. A household spanning several tax units still gets several budgets and never one pooled allowance.
- Wash-sale scope follows the taxpayer and is handled before the solve, by excluding lots whose loss would be disallowed. Accounts outside the snapshot remain unseen.
- Optimality is over the supplied lots and constraints. It says nothing about which account should hold which exposure, which is an allocation decision this engine does not make.
- Beyond 40 budget-consuming lots in a tax unit the search is not exhausted and the status degrades to feasible with a reported gap.
Where the figures come from
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) |
Engine coverage, and what each engine will not claim
2 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 |
|---|
household-coordinator | implemented | household_coordinated | 2026 | no |
household-optimizer | implemented | household | 2026 | yes |
Scripted case coverage
6 of the 71 console cases call this server over JSON-RPC on every build, across 1 of the 15 client objectives the case inventory groups by: Coordinate a household.
| Case | What it asks | What it shows | Outcome |
|---|
household-coordinated | Two accounts, one shared budget | Budget is reserved per tax unit as each account is served, so no two runs spend the same allowance. | completed_with_limitations |
household-uma-wash | One sleeve would wash another sleeve's loss | Same account, same taxpayer, two managers. Neither did anything wrong and the loss would still be disallowed, so it is caught first. | completed_with_limitations |
household-gap | Falling short, and the ceiling it was measured against | Sequential allocation depends on the order units are served, so the run reports an LP bound on what any allocation could have raised. | INFEASIBLE_CONSTRAINTS |
household-joint-optimal | Solved jointly, with a proof | No ordering at all. Where the search exhausts, the run proves no other selection raises more cash within the budget — which the sequential coordinator can never say. | completed_with_limitations |
household-joint-infeasible-is-proven | An unreachable target, proven unreachable | Because each tax unit was searched exhaustively, the shortfall is a proof rather than a failure to find a plan. | INFEASIBLE_CONSTRAINTS |
household-capabilities | Which engine claims what | Two engines on one server: the joint optimizer proves optimality where its search exhausts, the coordinator never does. The server states the difference rather than letting a coordinated result read as an optimal one. | completed |
Questions it answers
How should a whole household harvest together?
Solve the whole household at once rather than account by account. No ordering, and where the search exhausts it proves no selection does better. Budgets are still per tax unit and never pooled. Prefer this over coordinate_household unless you need the reservation behaviour. 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_household on taxagent-household 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.
How do I share one gain budget across accounts?
Run several accounts or UMA sleeves against one shared gain budget per tax unit, reserving budget so no two runs spend the same allowance and screening cross-sleeve wash sales. Sequential, not a joint optimum; the optimality gap is reported. 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 coordinate_household on taxagent-household 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.