Skip to content

Tax

Federal income tax, capital gains, and after-tax projections.

calculate_federal_income_tax

Calculate federal income tax for the given taxable income and filing status.

Parameter Type Default Description
taxable_income_cents int required Taxable income in cents
filing_status string required Tax filing status. Options: single, married_joint, married_separate, head_of_household, or qualifying_widow
tax_year int 2026 Tax year. Options: 2024, 2025, or 2026

Returns tax owed, effective rate, and marginal rate.

calculate_capital_gains_tax_rate

Get the long-term capital gains tax rate based on income and filing status.

Parameter Type Default Description
taxable_income_cents int required Taxable income in cents (before capital gains)
filing_status string required Tax filing status. Options: single, married_joint, married_separate, head_of_household, or qualifying_widow
tax_year int 2026 Tax year. Options: 2024, 2025, or 2026

Returns the applicable LTCG rate for the given income level.

calculate_state_and_local_income_tax

Calculate resident state and (optionally) local income tax.

Parameter Type Default Description
state_code string required Two-letter US state code.
state_taxable_income_cents int required State taxable income in cents (after state deductions).
filing_status string required Tax filing status. Options: single, married_joint, married_separate, head_of_household, or qualifying_widow
locality string "" Optional resident locality slug for local income tax. Leave empty for state-only calculation. Recognized values depend on the state.
tax_year int 2026 Tax year

Returns state and local tax amounts, marginal/effective rates, and the state standard deduction.

calculate_amt

Calculate the Alternative Minimum Tax (Form 6251).

Parameter Type Default Description
regular_taxable_income_cents int required Regular taxable income in cents
regular_tax_cents int required Regular federal income tax (the AMT comparison baseline) in cents
filing_status string required Tax filing status. Options: single, married_joint, married_separate, head_of_household, or qualifying_widow
iso_exercise_spread_cents int 0 Bargain element (spread) on incentive stock options exercised and held past year end, in cents. A deferral preference that generates a recoverable minimum tax credit.
other_deferral_preferences_cents int 0 Other deferral (timing) AMT preference items in cents
salt_addback_cents int 0 State and local taxes added back for AMT, in cents. An exclusion preference that does not generate a recoverable credit.
other_exclusion_preferences_cents int 0 Other exclusion (permanent) AMT preference items in cents
tax_year int 2026 Tax year. Options: 2026

Returns AMTI, the phased-out exemption, the tentative minimum tax, the AMT owed, and the minimum-tax-credit (Form 8801) carryforward generated by deferral preferences such as the ISO exercise-and-hold spread.

model_iso_exercise

Model the tax effect of an incentive stock option (ISO) exercise.

Parameter Type Default Description
strike_cents int required Per-share strike (exercise) price in cents
fmv_cents int required Per-share fair market value at exercise, in cents
shares int required Number of options exercised
intent string required Disposition intent for the year of exercise. 'hold' = exercise-and-hold (qualifying path; generates an AMT preference, no regular-tax ordinary income, FICA-exempt, Form 8801 minimum-tax-credit eligible). 'disqualify_same_year' = sell in the same calendar year (ordinary income = spread, no AMT preference; FICA-exempt).
filing_status string required Tax filing status. Options: single, married_joint, married_separate, head_of_household, or qualifying_widow
ytd_supplemental_paid_cents int 0 Year-to-date supplemental wages already paid before this event, in cents. Unused for ISO directly (ISO income is not subject to federal supplemental withholding); accepted for API symmetry with the NQSO/RSU tools.
tax_year int 2026 Tax year. Options: 2026

Returns the AMT preference (for the exercise-and-hold path) or ordinary income (for a same-year disqualifying disposition), in both _cents and _dollars form, plus share-surrender placeholders and a plain-English explanation of which path was taken.

calculate_federal_tax_liability

Calculate the full federal tax liability — AGI, deductions, taxable income, ordinary-bracket tax, preferential-rate (LTCG/qualified-dividend) stacking, NIIT, Additional Medicare, and AMT — for a single tax year.

Parameter Type Default Description
filing_status string required Tax filing status. Options: single, married_joint, married_separate, head_of_household, or qualifying_widow
wages_cents int 0 Regular W-2 wages in cents. Must exclude RSU/NQSO supplemental compensation reported in W-2 Box 1 — those go in supplemental_ordinary_fica_subject_cents to avoid double-counting.
supplemental_ordinary_fica_subject_cents int 0 RSU vest / NQSO exercise ordinary income, in cents. FICA-subject (included in the Additional Medicare base).
supplemental_ordinary_fica_exempt_cents int 0 ISO disqualifying-disposition ordinary-income portion, in cents. FICA-exempt (excluded from the Additional Medicare base).
qualified_dividends_cents int 0 Qualified dividends in cents. Must be the subset of ordinary_dividends_cents that qualifies for preferential rates.
ordinary_dividends_cents int 0 Total ordinary dividends in cents (1099-DIV Box 1a).
short_term_capital_gains_cents int 0 Short-term capital gains in cents.
long_term_capital_gains_cents int 0 Long-term capital gains in cents.
interest_income_cents int 0 Taxable interest income in cents.
other_ordinary_cents int 0 Other ordinary income in cents (e.g., taxable distributions).
above_the_line_adjustments_cents int 0 Above-the-line adjustments in cents (traditional 401(k) deferral, HSA, SE tax/2, student-loan interest, etc.).
salt_paid_state_cents int 0 State income tax paid in cents (for itemized deduction).
salt_paid_local_cents int 0 Local income tax paid in cents.
salt_paid_property_cents int 0 Property tax paid in cents.
mortgage_interest_cents int 0 Home mortgage interest paid in cents.
mortgage_principal_balance_cents int 0 Average mortgage principal balance for the year, in cents.
mortgage_origination_year int 2024 Mortgage origination year. Pre-2018 originations get the grandfathered $1M acquisition-debt cap; 2018+ get $750K.
iso_preference_cents int 0 ISO exercise-and-hold bargain element, in cents. AMT deferral preference that generates a recoverable Form 8801 credit.
tax_year int 2026 Tax year. Options: 2026

Returns every component in both _cents and _dollars form, plus the chosen deduction, marginal ordinary rate, effective rate, and the AMT Form 8801 credit carryforward.

estimate_underpayment_safe_harbor

Estimate whether withholding meets the IRS safe-harbor threshold for avoiding underpayment penalties.

Parameter Type Default Description
prior_year_total_tax_cents int required Total tax from the prior year's return, in cents
prior_year_agi_cents int required Adjusted gross income from the prior year's return, in cents
current_year_projected_tax_cents int required Projected total federal tax for the current year, in cents
withholding_cents int required Year-to-date plus expected remaining withholding for the current year, in cents
filing_status string required Tax filing status. Options: single, married_joint, married_separate, head_of_household, or qualifying_widow
tax_year int 2026 Current tax year

Returns the safe-harbor target, the basis used (90% of current-year tax or 100/110% of prior-year tax), whether a penalty would apply, and suggested quarterly 1040-ES payments to close any gap.

get_tax_parameters

Look up year- and filing-status-specific federal tax scalars.

Parameter Type Default Description
filing_status string required Tax filing status. Options: single, married_joint, married_separate, head_of_household, or qualifying_widow
tax_year int 2026 Tax year (2026 only)

Returns SALT cap and phase-down, AMT exemption / phase-out / rate breakpoint, NIIT and Additional Medicare thresholds, supplemental wage withholding rates, mortgage acquisition-debt caps, and the 402(g) / 401(a)(17) / 414(v) / 415(c) retirement limits. Each scalar is returned in both _cents and _dollars form, plus a source citation string.

apply_after_tax_to_projection_result

Apply withdrawal taxes to a projection result, computing after-tax spendable values.

Parameter Type Default Description
projection_result_json object required The 'projection_result' object from run_projection's output. Pass the value of the 'projection_result' key directly.
account_tax_treatment string required Account tax treatment category. pre_tax: Traditional 401k/IRA (withdrawals taxed as ordinary income). post_tax_deferred: Roth 401k/IRA (tax-free withdrawals). taxable: Brokerage or savings (capital gains on liquidation). tax_advantaged: HSA, 529 (tax-free for qualified expenses).
marginal_ordinary_rate float required Marginal ordinary income tax rate as decimal (e.g., 0.22 = 22%).
ltcg_rate float required Long-term capital gains tax rate as decimal (e.g., 0.15 = 15%).
taxable_income_type string "none" How income from this account is taxed on withdrawal. none: Tax-deferred accounts (Traditional IRA, Roth). ordinary_income: Cash accounts (savings, checking). investment_income: Brokerage accounts (capital gains on sale).
initial_cost_basis_cents int null For taxable brokerage accounts: the original invested amount in cents. Cost basis stays fixed as the portfolio grows, so the taxable gain fraction increases over time. Ignored for non-brokerage accounts.

Returns the adjusted projection result with corrected after_tax_percentiles.