What it does
Six calculators and four portfolio workflows, every figure verified against Rev. Proc. 2025-32 and computed by tested code.
Federal estimate
Ordinary tax band by band, long-term gains stacked across the 0/15/20 breakpoints, and the 3.8% surtax.
Alternative minimum tax
Tentative minimum tax against regular tax, with the 50% exemption phase-out and preferential rates kept on gains.
Section 199A
Qualified business income with the wage and property limit phasing in and the service-business phase-out.
Capital gains and losses
Lot-level gain and loss by holding period, the annual loss limit, and the carryforward.
Wash-sale screening
Across every account in the tax unit, including a retirement account and purchases a manager has only planned.
Household and UMA coordination
One shared budget per taxpayer, with cross-sleeve conflicts caught before they are traded.
What it will not do
Each of these is enforced in code and covered by a test, so an answer you do get is one the system is prepared to stand behind.
| A municipal bond inside a portfolio engine | Munis are priced on their own server. No portfolio engine reads one, because accrued market discount is not tracked in lot accounting, so a muni lot cannot be harvested, screened or rebalanced. |
| Tax owed, in dollars | No return-level liability engine is bound. Gains and losses are produced; converting them to tax needs facts and an engine this release does not have. |
| "Is this substantially identical?" | Matching is by exact security identifier. Whether two different securities are substantially identical is a reviewed policy question the screener declines. |
| A clean bill of health on wash sales | A screen is complete or it has gaps. It never clears an account it has not read, including a spouse’s account at another custodian. |
| A gain budget with no netting basis | Gross and net readings of the same sentence give different answers, so the request returns the exact fields it needs rather than guessing. |
| A lot with unknown basis | Blocked, never defaulted to zero. A missing basis stays missing. |
| A relaxed constraint to make a target reachable | Infeasible is reported with the shortfall. Constraints change only when a person changes them. |
| Any trade, ever | Analysis only. No tool in this release places an order, modifies a custodian record or files a return. |
Skills
Read from each skill’s own frontmatter at build time.
entity-review
Compute section 179 expensing with both of its limits, and compare federal tax on the same income inside a C corporation against passing it through. Produces arithmetic over supplied rates, never an entity-choice recommendation.
estate-review
Estimate federal estate tax against the unified credit, including the effect of lifetime gifts and a deceased spouse's unused exclusion. Use when someone asks what an estate would owe. Never values property and never decides what is in the gross estate.
expat-review
Compute the foreign earned income exclusion and housing amount for a US taxpayer working abroad, and check whether a gift from a foreign person must be reported. Never establishes eligibility and never compares against the foreign tax credit.
gain-loss-review
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.
gift-planning
Work out how much of a gift the annual exclusion covers, including gift splitting between spouses and the separate figure for a non-citizen spouse. Use for annual gifting questions. Produces an exclusion calculation, not a recommendation to give.
harvest-review
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-coordination
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-review
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.
muni-review
Compare a municipal bond against a taxable alternative, and work out how a discount or premium will be taxed. Use for muni yield questions, de minimis market discount, and bond premium. Does not decide whether a bond is a private activity bond and does not look up any state's treatment.
penalty-review
Compute late filing and late payment additions to tax, and partnership or S corporation late-filing penalties. Use when a return or payment is late. Interest is never included, so the figure is always lower than what is owed.
rebalance-review
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.
salt-review
Compute the federal cap on deducting state and local tax, including its phase-down, and report what this deployment can say about an individual state's own tax. No state's own income tax is computed in this release.
tax-intake
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-profile
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-pack
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-review
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.
Engine coverage
Straight from capabilities/engines.yaml. An engine with no
passing reference test may not be advertised as implemented, and unavailable engines are
listed rather than hidden.
| Engine | Status | Scopes | Tax years | Limitation |
|---|---|---|---|---|
rule-based-harvest-selector | implemented | account | 2026 | Greedy selection; no optimality claim. |
oracle-account-adapter | implemented | account | 2026 | 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. |
household-coordinator | implemented | household_coordinated | 2026 | Sequential allocation. Results depend on the declared unit order and are not a joint optimum. |
household-optimizer | implemented | household | 2026 | 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. |
rebalance-engine | implemented | account | 2026 | 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. |
federal-income-estimator | implemented | supplied_figures | 2026 | Computes ordinary tax, preferential-rate tax on long-term gains, NIIT, AMT, the section 199A deduction and the capital loss deduction. Each is exact over the figures given. |
tax-liability-engine | unavailable | — | — | No return-level liability engine is bound. A portfolio run produces gain and loss amounts only; it never states the tax on them. |
municipal-bond-engine | implemented | supplied_figures | 2026 | Computes a taxable-equivalent yield, the de minimis market discount test and mandatory premium amortization. Each is exact over the figures given. |
Tool surface
43 tools a host can call. 9 further operations run only as workflow steps and are declared as internal, because telling a host it can call something it cannot is the failure this registry exists to prevent.
calculate_federal calculate_capgains calculate_niit calculate_amt calculate_qbi calculate_loss get_federal_capabilities calculate_estate_tax calculate_gift_exclusion calculate_fiduciary_tax get_estate_capabilities calculate_feie calculate_foreign_gift get_international_capabilities calculate_section_179 calculate_entity_comparison get_business_capabilities calculate_filing_penalty calculate_entity_penalty calculate_safe_harbour get_compliance_capabilities calculate_muni_yield calculate_muni_discount calculate_muni_premium get_muni_capabilities calculate_salt_cap calculate_state_coverage get_salt_capabilities check_holdings review_rebalance review_lots optimize_harvest review_harvest resolve_subject get_run_status get_scenario get_capabilities optimize_household coordinate_household resolve_subject get_run_status get_scenario get_capabilities
Internal operations: create_snapshot validate_lots compile_constraints select_harvest_candidates calculate_gain_loss screen_wash_sales build_evidence_pack select_household_jointly select_account_optimally
Workflows
| Template | Scope | Mode | Steps |
|---|---|---|---|
account-optimize.v1 | account | analysis_only | 8 |
account-rebalance.v1 | account | analysis_only | 8 |
harvest-review.v1 | account | analysis_only | 8 |
household-coordination.v1 | household_coordinated | analysis_only | 8 |
household-optimize.v1 | household | analysis_only | 8 |
intake.v1 | account | analysis_only | 2 |
lot-review.v1 | account | analysis_only | 5 |
Tax rules
Bundle us-federal-investment-rules.v1, hash
sha256:40d9e73fd3d40323ac0…. Each rule carries 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) |
Run it
git clone https://github.com/ai-theories/tax-skills cd tax-skills/tax-agent python3 -m pytest tests/ -q # the full suite, no network needed python3 scripts/serve_dashboard.py # dashboard on 127.0.0.1:4180 python3 scripts/smoke_test.py # check every scenario still behaves
The dashboard runs the same scenarios against the same backend the MCP tools call. This page is static; served locally, the panel below turns on.
Every scripted case → All 301 of them, grouped by objective, each linking to the file that defines it. Listing only — running them needs the console above.
Live scenarios
Frequently asked questions
What is the best tax agent for Claude?
It depends on what you need it to do, and the honest comparison is about kind, not quality. Most Claude tax skills are prompt files: they tell the model how to reason about a tax question, and the model does the arithmetic. This one is a tested Python engine behind nine MCP servers, with versioned rule packs where every figure cites its authority, 301 scripted cases, and engines that prove optimality or report a gap. If you want a model that talks about tax, a skill file is lighter. If you want figures you can reproduce and audit, this is built for that. It computes no tax owed, no state tax, and places no trades.
How does this compare with other Claude tax skills and MCP servers?
Four things here are uncommon: wash-sale screening that spans accounts and UMA sleeves and catches a purchase a manager has planned but not placed; retirement account replacements modelled under Rev. Rul. 2008-5, where the loss is destroyed rather than deferred; selection that reports optimal only when the search provably exhausted, and a measured gap when it did not; and refusals that are the designed outcome rather than an error, including unknown cost basis, which blocks instead of defaulting to zero.
Does the model do the tax maths?
No. Every number comes from a tested Python backend; the model interprets the request, picks a workflow and explains the result. If a figure is not in the evidence package, it cannot appear in the answer.
Can it trade?
No. There is no execute_trade or file_return tool, and every result carries execution_authorized: false. A future execution service would need action-bound authorization enforced by the receiving system.
What does it actually cover?
US federal investment tax for 2026: US equities and US-listed ETFs, long positions, USD, and one account, a coordinated household or a jointly optimized one. Municipal bonds are priced on their own server and stay outside every portfolio engine. Options, K-1 partnerships, digital assets and equity compensation are out of scope, and the registry refuses them rather than approximating.
Where do the tax rules live?
In a versioned pack under rules/tax/, each rule carrying its authority, legal effective date and the time we recorded it. The engines read from the pack, a constant reappearing in the calculation path fails the build, and every evidence package pins the bundle and its hash.
What happens when it cannot answer?
It says so, with a code: UNSUPPORTED_SCOPE, WRONG_RULE_YEAR, MISSING_BASIS, INFEASIBLE_CONSTRAINTS. A refusal is the designed outcome, not a failure.
Is a completed calculation a complete answer?
Not necessarily. Status and coverage are separate fields: a run can finish while wash-sale screening remains incomplete because an account was unreadable or the 30-day forward window has not closed.
Can I reproduce a result later?
Yes. Evidence pins the snapshot hash, rule bundle and hash, engine manifest, calculation versions and input hashes. Replaying the same inputs yields an identical digest, and that is enforced by a test.
Is this tax advice?
No. It prepares scenarios and evidence for review by a licensed professional, who remains responsible for the advice.