Run the first safe call
Make one computed call, then see the engine decline a case, resolve that decline with the affirmations it asks for, and get a reconcile that needs human review. About ten minutes.
Before you start
You need an API key in TAX_MCP_API_KEY (see Set up). Every response on this page is produced by the engine when the page is built, so it matches what the API returns today.
1. Compute a federal return
A single filer with $85,000 of W-2 wages. wages is W-2 box 1, medicareWages is box 5, and federalWithholding is box 2. canBeClaimedAsDependent and noForeignOrTerritoryExclusionAffirmed are answers about this return, required on every call: true for the second attests that no one on the return (the filer, and on a joint return either spouse) files Form 2555 for the year or excludes income under §931 (Form 4563) or §933 (Puerto Rico). Answer both for each return; never hard-code them.
curl https://tax-mcp.com/api/mcp/tax-compute/federal \
-H "Authorization: Bearer $TAX_MCP_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"year": 2025,
"filingStatus": "single",
"canBeClaimedAsDependent": false,
"noForeignOrTerritoryExclusionAffirmed": true,
"wages": 85000,
"medicareWages": 85000,
"federalWithholding": 9500
}'{
"computed": true,
"year": 2025,
"filingStatus": "single",
"taxableIncome": 69250,
"incomeTax": 10155,
"totalTax": 10155,
"lines": [
{ "lineId": "1040:15", "label": "Taxable income", "amount": 69250 },
{
"lineId": "1040:16",
"label": "Income tax",
"amount": 10155,
"derivation": "<5 derivation steps — see full response>"
},
{ "lineId": "1040:24", "label": "Total tax", "amount": 10155 }
],
"flags": [
"OBBBA-2025-new-deductions-senior-bonus/tips/overtime/car-loan-NOT-evaluated-engine-cannot-verify-eligibility-from-W2/1099-preparer-must-confirm"
],
"owedOrRefund": 655,
"billed": true,
"retry_safe": true,
"next_action": "none",
"provenance": { "engine": "deterministic", "jurisdiction": "federal", "tax_year": 2025 },
"legal_notice": {
"ref": "https://tax-mcp.com/terms#compute-notice",
"version": "v1",
"text": "<computation-support notice — see full response>"
}
}Full response, including line derivations
{
"computed": true,
"year": 2025,
"filingStatus": "single",
"taxableIncome": 69250,
"incomeTax": 10155,
"totalTax": 10155,
"lines": [
{
"lineId": "1040:15",
"label": "Taxable income",
"amount": 69250,
"derivation": []
},
{
"lineId": "1040:16",
"label": "Income tax",
"amount": 10155,
"derivation": [
{
"lineId": "1040:16",
"label": "Tax Table method (IRS-mandated below $100,000 taxable income)",
"inputs": [
{ "name": "taxableIncome", "value": 69250 }
],
"rule": {
"description": "Form 1040 instructions require the published Tax Table — a lookup on the midpoint of a narrow taxable-income band — for taxable income under $100,000; the exact bracket formula (Tax Computation Worksheet) applies only at $100,000 or more.",
"authority": "Form 1040 instructions — Tax Table"
},
"computation": "taxable income $69,250 → Tax Table band midpoint $69,275",
"result": 0
},
{
"lineId": "1040:16",
"label": "Ordinary income tax — 10% bracket",
"inputs": [
{ "name": "taxableIncomeInBracket", "value": 11925 }
],
"rule": {
"description": "marginal rate × taxable income falling within this bracket",
"authority": "IRC §1(j)",
"constantRef": {
"table": "BRACKETS_BY_YEAR",
"key": "2025/single",
"value": "10% (up to $11,925)",
"revProc": "Rev. Proc. 2024-40"
}
},
"computation": "0.1 × $11,925 = $1,192.5",
"result": 1192.5
},
{
"lineId": "1040:16",
"label": "Ordinary income tax — 12% bracket",
"inputs": [
{ "name": "taxableIncomeInBracket", "value": 36550 }
],
"rule": {
"description": "marginal rate × taxable income falling within this bracket",
"authority": "IRC §1(j)",
"constantRef": {
"table": "BRACKETS_BY_YEAR",
"key": "2025/single",
"value": "12% (up to $48,475)",
"revProc": "Rev. Proc. 2024-40"
}
},
"computation": "0.12 × $36,550 = $4,386",
"result": 4386
},
{
"lineId": "1040:16",
"label": "Ordinary income tax — 22% bracket",
"inputs": [
{ "name": "taxableIncomeInBracket", "value": 20800 }
],
"rule": {
"description": "marginal rate × taxable income falling within this bracket",
"authority": "IRC §1(j)",
"constantRef": {
"table": "BRACKETS_BY_YEAR",
"key": "2025/single",
"value": "22% (up to $103,350)",
"revProc": "Rev. Proc. 2024-40"
}
},
"computation": "0.22 × $20,800 = $4,576",
"result": 4576
},
{
"lineId": "1040:16",
"label": "Whole-dollar rounding — ordinary income tax",
"inputs": [
{ "name": "unroundedOrdinaryTax", "value": 10155 }
],
"rule": {
"description": "round the ordinary income tax to whole dollars",
"authority": "Form 1040 instructions — whole-dollar rounding"
},
"computation": "$10,155 − $10,154.5 = $0.5",
"result": 0.5
}
]
},
{
"lineId": "1040:24",
"label": "Total tax",
"amount": 10155,
"derivation": []
}
],
"flags": [
"OBBBA-2025-new-deductions-senior-bonus/tips/overtime/car-loan-NOT-evaluated-engine-cannot-verify-eligibility-from-W2/1099-preparer-must-confirm"
],
"owedOrRefund": 655,
"billed": true,
"retry_safe": true,
"next_action": "none",
"provenance": { "engine": "deterministic", "jurisdiction": "federal", "tax_year": 2025 },
"legal_notice": {
"ref": "https://tax-mcp.com/terms#compute-notice",
"version": "v1",
"text": "Computation support only. Not tax, legal, accounting, or financial advice. Customer is responsible for review, filing positions, and use only within the documented supported envelope."
}
}Read the envelope first: computed: true, next_action: "none". Then the figures: total tax $10,155, and owedOrRefund of $655 still owed (positive means a balance due). Lines computed from a rule (here, income tax) carry a derivation: the rule, its authority, and the arithmetic. Open the full response to see it.
The same call from code:
const response = await fetch("https://tax-mcp.com/api/mcp/tax-compute/federal", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.TAX_MCP_API_KEY}`,
"Content-Type": "application/json",
"Idempotency-Key": crypto.randomUUID(), // reuse it if you retry this same request
},
body: JSON.stringify({
"year": 2025,
"filingStatus": "single",
"canBeClaimedAsDependent": false,
"noForeignOrTerritoryExclusionAffirmed": true,
"wages": 85000,
"medicareWages": 85000,
"federalWithholding": 9500
}),
});
if (!response.ok) {
// 4xx/5xx: nothing was computed or billed. The body's next_action says what to do.
const err = await response.json().catch(() => ({}));
throw new Error(`${response.status} ${err.error ?? ""}: ${err.next_action ?? ""}`);
}
const result = await response.json();
if (result.computed) {
console.log("total tax", result.totalTax, "owed (+) / refund (-)", result.owedOrRefund);
} else {
// A decline is a final answer. Route it to a preparer; do not retry the same body.
console.log("declined", result.code, result.reason);
}import os, uuid, requests
response = requests.post(
"https://tax-mcp.com/api/mcp/tax-compute/federal",
headers={
"Authorization": f"Bearer {os.environ['TAX_MCP_API_KEY']}",
"Idempotency-Key": str(uuid.uuid4()), # reuse it if you retry this same request
},
json={
"year": 2025,
"filingStatus": "single",
"canBeClaimedAsDependent": false,
"noForeignOrTerritoryExclusionAffirmed": true,
"wages": 85000,
"medicareWages": 85000,
"federalWithholding": 9500
},
)
if not response.ok:
# 4xx/5xx: nothing was computed or billed. The body's next_action says what to do.
raise RuntimeError(f"{response.status_code}: {response.text[:300]}")
result = response.json()
if result["computed"]:
print("total tax", result["totalTax"], "owed (+) / refund (-)", result.get("owedOrRefund"))
else:
# A decline is a final answer. Route it to a preparer; do not retry the same body.
print("declined", result["code"], result["reason"])2. See a deterministic decline
Add $30,000 of self-employment income. The request looks computable, but the engine cannot tell from a single number whether it is the final net profit of one sole proprietor, so it declines instead of guessing:
curl https://tax-mcp.com/api/mcp/tax-compute/federal \
-H "Authorization: Bearer $TAX_MCP_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"year": 2025,
"filingStatus": "single",
"canBeClaimedAsDependent": false,
"noForeignOrTerritoryExclusionAffirmed": true,
"wages": 40000,
"medicareWages": 40000,
"scheduleCIncome": 30000
}'{
"computed": false,
"code": "schedule_c_needs_review",
"reason": "Schedule C self-employment compute requires scheduleCIsSingleSolePropFinalNetAffirmed:true — attesting the amount is the FINAL Schedule C line-31 net of ONE sole proprietor with no depreciation/§179/bonus, no SE health-insurance (§162(l)) or home-office (§280A), not farm/clergy/statutory-employee, not a §1402 optional method, and not two spouses' combined self-employment (the Social-Security OASDI cap is per-individual — combining two spouses' SE into one scalar under-collects). Any of those → a preparer must complete Schedule C + Schedule SE. (The §199A QBI 20% deduction is a separate opt-in, scheduleCQbiEligible.)",
"billed": true,
"retry_safe": false,
"next_action": "review_inputs"
}Full response, including line derivations
{
"computed": false,
"code": "schedule_c_needs_review",
"reason": "Schedule C self-employment compute requires scheduleCIsSingleSolePropFinalNetAffirmed:true — attesting the amount is the FINAL Schedule C line-31 net of ONE sole proprietor with no depreciation/§179/bonus, no SE health-insurance (§162(l)) or home-office (§280A), not farm/clergy/statutory-employee, not a §1402 optional method, and not two spouses' combined self-employment (the Social-Security OASDI cap is per-individual — combining two spouses' SE into one scalar under-collects). Any of those → a preparer must complete Schedule C + Schedule SE. (The §199A QBI 20% deduction is a separate opt-in, scheduleCQbiEligible.)",
"billed": true,
"retry_safe": false,
"next_action": "review_inputs"
}A decline is a safety success, not a failure or an outage
It is a 200, it is billed like a computed answer, and it is not something you did wrong. Whether the case can ever compute depends on your INPUT: a bare retry of the same request re-declines every time, which is why retry_safe is false. The reason names exactly what is missing.
3. Resolve it with affirmations
The reason names the attestation the engine needs, scheduleCIsSingleSolePropFinalNetAffirmed. This path also needs scheduleCNoAmtAdjustmentAffirmed, and self-employment tax needs W-2 box 3 in socialSecurityWages. The capability manifestlists every affirmation up front, so you can collect them before you call. An affirmation is a preparer's statement of fact: only send true when someone has checked it. With them, the same income computes, including self-employment tax:
curl https://tax-mcp.com/api/mcp/tax-compute/federal \
-H "Authorization: Bearer $TAX_MCP_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"year": 2025,
"filingStatus": "single",
"canBeClaimedAsDependent": false,
"noForeignOrTerritoryExclusionAffirmed": true,
"wages": 40000,
"medicareWages": 40000,
"socialSecurityWages": 40000,
"scheduleCIncome": 30000,
"scheduleCIsSingleSolePropFinalNetAffirmed": true,
"scheduleCNoAmtAdjustmentAffirmed": true
}'{
"computed": true,
"year": 2025,
"filingStatus": "single",
"taxableIncome": 52131,
"incomeTax": 6382,
"totalTax": 10620,
"lines": [
{ "lineId": "1040:15", "label": "Taxable income", "amount": 52131 },
{
"lineId": "1040:16",
"label": "Income tax",
"amount": 6382,
"derivation": "<5 derivation steps — see full response>"
},
{ "lineId": "1040:24", "label": "Total tax", "amount": 10620 }
],
"flags": [
"OBBBA-2025-new-deductions-senior-bonus/tips/overtime/car-loan-NOT-evaluated-engine-cannot-verify-eligibility-from-W2/1099-preparer-must-confirm",
"SCHEDULE-C-SE-COMPUTED ($30,000 net) → self-employment tax $4,238 (Schedule SE: net×0.9235=$27,705; OASDI $3,435 at 12.4% to the $176,100 wage base less the SE earner's $40,000 box-3 wages; Medicare $803 at 2.9%) → Schedule 2. The §164(f) one-half-SE-tax deduction $2,119 reduces AGI (Schedule 1 line 15). The net is ORDINARY income → AGI (Schedule 1 line 3 → 1040 line 8), NOT in the §1411 NIIT base. Assumes (affirmed): FINAL Schedule C line-31 net of ONE sole proprietor, no depreciation / §179 / SE-health-insurance / home-office, not farm/clergy/statutory, not two spouses' combined SE."
],
"billed": true,
"retry_safe": true,
"next_action": "none",
"provenance": { "engine": "deterministic", "jurisdiction": "federal", "tax_year": 2025 },
"legal_notice": {
"ref": "https://tax-mcp.com/terms#compute-notice",
"version": "v1",
"text": "<computation-support notice — see full response>"
}
}Full response, including line derivations
{
"computed": true,
"year": 2025,
"filingStatus": "single",
"taxableIncome": 52131,
"incomeTax": 6382,
"totalTax": 10620,
"lines": [
{
"lineId": "1040:15",
"label": "Taxable income",
"amount": 52131,
"derivation": []
},
{
"lineId": "1040:16",
"label": "Income tax",
"amount": 6382,
"derivation": [
{
"lineId": "1040:16",
"label": "Tax Table method (IRS-mandated below $100,000 taxable income)",
"inputs": [
{ "name": "taxableIncome", "value": 52131 }
],
"rule": {
"description": "Form 1040 instructions require the published Tax Table — a lookup on the midpoint of a narrow taxable-income band — for taxable income under $100,000; the exact bracket formula (Tax Computation Worksheet) applies only at $100,000 or more.",
"authority": "Form 1040 instructions — Tax Table"
},
"computation": "taxable income $52,131 → Tax Table band midpoint $52,125",
"result": 0
},
{
"lineId": "1040:16",
"label": "Ordinary income tax — 10% bracket",
"inputs": [
{ "name": "taxableIncomeInBracket", "value": 11925 }
],
"rule": {
"description": "marginal rate × taxable income falling within this bracket",
"authority": "IRC §1(j)",
"constantRef": {
"table": "BRACKETS_BY_YEAR",
"key": "2025/single",
"value": "10% (up to $11,925)",
"revProc": "Rev. Proc. 2024-40"
}
},
"computation": "0.1 × $11,925 = $1,192.5",
"result": 1192.5
},
{
"lineId": "1040:16",
"label": "Ordinary income tax — 12% bracket",
"inputs": [
{ "name": "taxableIncomeInBracket", "value": 36550 }
],
"rule": {
"description": "marginal rate × taxable income falling within this bracket",
"authority": "IRC §1(j)",
"constantRef": {
"table": "BRACKETS_BY_YEAR",
"key": "2025/single",
"value": "12% (up to $48,475)",
"revProc": "Rev. Proc. 2024-40"
}
},
"computation": "0.12 × $36,550 = $4,386",
"result": 4386
},
{
"lineId": "1040:16",
"label": "Ordinary income tax — 22% bracket",
"inputs": [
{ "name": "taxableIncomeInBracket", "value": 3650 }
],
"rule": {
"description": "marginal rate × taxable income falling within this bracket",
"authority": "IRC §1(j)",
"constantRef": {
"table": "BRACKETS_BY_YEAR",
"key": "2025/single",
"value": "22% (up to $103,350)",
"revProc": "Rev. Proc. 2024-40"
}
},
"computation": "0.22 × $3,650 = $803",
"result": 803
},
{
"lineId": "1040:16",
"label": "Whole-dollar rounding — ordinary income tax",
"inputs": [
{ "name": "unroundedOrdinaryTax", "value": 6382 }
],
"rule": {
"description": "round the ordinary income tax to whole dollars",
"authority": "Form 1040 instructions — whole-dollar rounding"
},
"computation": "$6,382 − $6,381.5 = $0.5",
"result": 0.5
}
]
},
{
"lineId": "1040:24",
"label": "Total tax",
"amount": 10620,
"derivation": []
}
],
"flags": [
"OBBBA-2025-new-deductions-senior-bonus/tips/overtime/car-loan-NOT-evaluated-engine-cannot-verify-eligibility-from-W2/1099-preparer-must-confirm",
"SCHEDULE-C-SE-COMPUTED ($30,000 net) → self-employment tax $4,238 (Schedule SE: net×0.9235=$27,705; OASDI $3,435 at 12.4% to the $176,100 wage base less the SE earner's $40,000 box-3 wages; Medicare $803 at 2.9%) → Schedule 2. The §164(f) one-half-SE-tax deduction $2,119 reduces AGI (Schedule 1 line 15). The net is ORDINARY income → AGI (Schedule 1 line 3 → 1040 line 8), NOT in the §1411 NIIT base. Assumes (affirmed): FINAL Schedule C line-31 net of ONE sole proprietor, no depreciation / §179 / SE-health-insurance / home-office, not farm/clergy/statutory, not two spouses' combined SE."
],
"billed": true,
"retry_safe": true,
"next_action": "none",
"provenance": { "engine": "deterministic", "jurisdiction": "federal", "tax_year": 2025 },
"legal_notice": {
"ref": "https://tax-mcp.com/terms#compute-notice",
"version": "v1",
"text": "Computation support only. Not tax, legal, accounting, or financial advice. Customer is responsible for review, filing positions, and use only within the documented supported envelope."
}
}4. See a reconcile that needs review
Reconcile recomputes a California return from the facts you assert and compares it with the filed figures. Here the filed AGI is higher than the wages provided, so the engine reports the difference and asks a person to look. It never decides which side is wrong.
curl https://tax-mcp.com/api/mcp/tax-compute/reconcile \
-H "Authorization: Bearer $TAX_MCP_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"sourceProfile": {
"state": "ca",
"year": 2025,
"filingStatus": "single",
"canBeClaimedAsDependent": false,
"noForeignOrTerritoryExclusionAffirmed": true,
"wages": 80000,
"medicareWages": 80000,
"caWithholding": 5000
},
"filed": { "stateAGI": 95000 }
}'{
"computed": {
"computed": true,
"state": "ca",
"year": 2025,
"filingStatus": "single",
"stateAGI": 80000,
"stateDeductions": 5706,
"stateTaxableIncome": 74294,
"incomeTaxBeforeCredits": 3349,
"exemptionCredits": 153,
"incomeTax": 3196,
"additionalTaxes": [],
"totalTax": 3196,
"lines": [
{ "lineId": "540:13", "label": "Federal AGI", "amount": 80000, "agiRole": "agi_base" },
{
"lineId": "540:17",
"label": "CA adjusted gross income",
"amount": 80000,
"agiRole": "agi_total"
},
{
"lineId": "540:18",
"label": "CA standard deduction",
"amount": 5706,
"agiRole": "below_agi",
"cite": "<primary-source cite — see full response>"
},
{
"lineId": "540:19",
"label": "CA taxable income",
"amount": 74294,
"agiRole": "below_agi"
},
{
"lineId": "540:31",
"label": "CA tax (2025 California Tax Table)",
"amount": 3349,
"agiRole": "below_agi",
"cite": "<primary-source cite — see full response>"
},
{
"lineId": "540:32",
"label": "CA exemption credits",
"amount": 153,
"agiRole": "below_agi",
"cite": "<primary-source cite — see full response>"
},
{
"lineId": "540:33",
"label": "CA tax after exemption credits",
"amount": 3196,
"agiRole": "below_agi"
},
{
"lineId": "540:64",
"label": "Total CA tax",
"amount": 3196,
"agiRole": "below_agi"
}
],
"flags": [
"CA-AGI-assumed-equal-to-federal-AGI (wages-only; no Schedule CA 540 adjustments). A filer with CA-specific adjustments (HSA add-back, US-Treasury/out-of-state-muni interest, SS exclusion) needs Schedule CA 540.",
"CA-AMT-not-computed (Schedule P, R&TC §17062). A full-year resident with no AMT preference items owes regular CA tax; a filer with preference items (ISO, accelerated depreciation, etc.) must complete Schedule P.",
"CA-exemption-credits-computed-with personal/blind/senior=1 ($153 each), dependents=0 ($475 each); blind/senior/dependents default to 0 when not supplied — supply them if applicable.",
"CA payments = withholding $5,000 + estimated $0 + extension $0 + prior-year-overpayment-applied $0 = $5,000. These coexist, but must NOT double-count — caEstimatedPayments must NOT also include the prior-year overpayment (that double-counts and over-states the refund)."
],
"totalPayments": 5000,
"balanceDue": 0,
"overpayment": 1804
},
"filed": { "stateAGI": 95000 },
"diff": [
{
"line": "CA AGI (540:17)",
"engine": 80000,
"filed": 95000,
"delta": 15000,
"cls": "DIFFERS",
"note": "source set appears INCOMPLETE vs the filed oracle — this line's difference is expected when the provided documents are a subset (not a confirmed engine-vs-preparer disagreement; see the top-level needs_review status)"
},
{
"line": "CA taxable income (540:19)",
"engine": 74294,
"filed": null,
"delta": null,
"cls": "NO-FILED",
"note": "filed line not parsed — diff declined"
},
{
"line": "Total CA tax (540:64)",
"engine": 3196,
"filed": null,
"delta": null,
"cls": "NO-FILED",
"note": "filed line not parsed — diff declined"
},
{
"line": "Total payments (540:78)",
"engine": 5000,
"filed": null,
"delta": null,
"cls": "NO-FILED",
"note": "filed line not parsed — diff declined"
},
{
"line": "Balance due (540:111)",
"engine": 0,
"filed": null,
"delta": null,
"cls": "NO-FILED",
"note": "filed line not parsed — diff declined"
},
{
"line": "Overpayment (540:115)",
"engine": 1804,
"filed": null,
"delta": null,
"cls": "NO-FILED",
"note": "filed line not parsed — diff declined"
}
],
"summary": { "MATCH": 0, "ENGINE-DECLINED": 0, "DIFFERS": 1, "NO-FILED": 5 },
"status": "needs_review",
"docTriage": [],
"flags": [
"Computed from the PROVIDED SOURCE DOCUMENTS only — this is a completeness check, NOT the filer's final CA tax. Divergence vs the filed return most likely means the source set is INCOMPLETE (income on the filed return not represented in the provided documents). A human must review before relying on any number."
],
"billed": true,
"retry_safe": true,
"next_action": "review_inputs",
"provenance": { "engine": "deterministic", "jurisdiction": "ca_reconcile" },
"legal_notice": {
"ref": "https://tax-mcp.com/terms#compute-notice",
"version": "v1",
"text": "<computation-support notice — see full response>"
}
}Full response, including line derivations
{
"computed": {
"computed": true,
"state": "ca",
"year": 2025,
"filingStatus": "single",
"stateAGI": 80000,
"stateDeductions": 5706,
"stateTaxableIncome": 74294,
"incomeTaxBeforeCredits": 3349,
"exemptionCredits": 153,
"incomeTax": 3196,
"additionalTaxes": [],
"totalTax": 3196,
"lines": [
{ "lineId": "540:13", "label": "Federal AGI", "amount": 80000, "agiRole": "agi_base" },
{
"lineId": "540:17",
"label": "CA adjusted gross income",
"amount": 80000,
"agiRole": "agi_total"
},
{
"lineId": "540:18",
"label": "CA standard deduction",
"amount": 5706,
"agiRole": "below_agi",
"cite": {
"jurisdiction": "ca",
"cellKey": "std_deduction.2025.single",
"authority": "CA FTB 2025 Standard Deduction — R&TC §17073.5 (CPI-indexed)"
}
},
{
"lineId": "540:19",
"label": "CA taxable income",
"amount": 74294,
"agiRole": "below_agi"
},
{
"lineId": "540:31",
"label": "CA tax (2025 California Tax Table)",
"amount": 3349,
"agiRole": "below_agi",
"cite": {
"jurisdiction": "ca",
"cellKey": "brackets.2025.single",
"authority": "CA FTB 2025 Form 540 booklet 2025 California Tax Table (rate schedule at band midpoint; required when taxable income ≤ $100,000)"
}
},
{
"lineId": "540:32",
"label": "CA exemption credits",
"amount": 153,
"agiRole": "below_agi",
"cite": {
"jurisdiction": "ca",
"cellKey": "exemption_credit.2025.personal",
"authority": "CA FTB 2025 Form 540 lines 7–10 Exemption Credits — R&TC §17054 ($153 personal/blind/senior, $475 dependent)"
}
},
{
"lineId": "540:33",
"label": "CA tax after exemption credits",
"amount": 3196,
"agiRole": "below_agi"
},
{
"lineId": "540:64",
"label": "Total CA tax",
"amount": 3196,
"agiRole": "below_agi"
}
],
"flags": [
"CA-AGI-assumed-equal-to-federal-AGI (wages-only; no Schedule CA 540 adjustments). A filer with CA-specific adjustments (HSA add-back, US-Treasury/out-of-state-muni interest, SS exclusion) needs Schedule CA 540.",
"CA-AMT-not-computed (Schedule P, R&TC §17062). A full-year resident with no AMT preference items owes regular CA tax; a filer with preference items (ISO, accelerated depreciation, etc.) must complete Schedule P.",
"CA-exemption-credits-computed-with personal/blind/senior=1 ($153 each), dependents=0 ($475 each); blind/senior/dependents default to 0 when not supplied — supply them if applicable.",
"CA payments = withholding $5,000 + estimated $0 + extension $0 + prior-year-overpayment-applied $0 = $5,000. These coexist, but must NOT double-count — caEstimatedPayments must NOT also include the prior-year overpayment (that double-counts and over-states the refund)."
],
"totalPayments": 5000,
"balanceDue": 0,
"overpayment": 1804
},
"filed": { "stateAGI": 95000 },
"diff": [
{
"line": "CA AGI (540:17)",
"engine": 80000,
"filed": 95000,
"delta": 15000,
"cls": "DIFFERS",
"note": "source set appears INCOMPLETE vs the filed oracle — this line's difference is expected when the provided documents are a subset (not a confirmed engine-vs-preparer disagreement; see the top-level needs_review status)"
},
{
"line": "CA taxable income (540:19)",
"engine": 74294,
"filed": null,
"delta": null,
"cls": "NO-FILED",
"note": "filed line not parsed — diff declined"
},
{
"line": "Total CA tax (540:64)",
"engine": 3196,
"filed": null,
"delta": null,
"cls": "NO-FILED",
"note": "filed line not parsed — diff declined"
},
{
"line": "Total payments (540:78)",
"engine": 5000,
"filed": null,
"delta": null,
"cls": "NO-FILED",
"note": "filed line not parsed — diff declined"
},
{
"line": "Balance due (540:111)",
"engine": 0,
"filed": null,
"delta": null,
"cls": "NO-FILED",
"note": "filed line not parsed — diff declined"
},
{
"line": "Overpayment (540:115)",
"engine": 1804,
"filed": null,
"delta": null,
"cls": "NO-FILED",
"note": "filed line not parsed — diff declined"
}
],
"summary": { "MATCH": 0, "ENGINE-DECLINED": 0, "DIFFERS": 1, "NO-FILED": 5 },
"status": "needs_review",
"docTriage": [],
"flags": [
"Computed from the PROVIDED SOURCE DOCUMENTS only — this is a completeness check, NOT the filer's final CA tax. Divergence vs the filed return most likely means the source set is INCOMPLETE (income on the filed return not represented in the provided documents). A human must review before relying on any number."
],
"billed": true,
"retry_safe": true,
"next_action": "review_inputs",
"provenance": { "engine": "deterministic", "jurisdiction": "ca_reconcile" },
"legal_notice": {
"ref": "https://tax-mcp.com/terms#compute-notice",
"version": "v1",
"text": "Computation support only. Not tax, legal, accounting, or financial advice. Customer is responsible for review, filing positions, and use only within the documented supported envelope."
}
}What you just learned
- Branch on
computed(orstatusfor reconcile) andnext_actionbefore reading any figure. - A decline is a final answer; change the input, never just retry.
- Send an
Idempotency-Keyon every POST and reuse it when you retry the same request, so a retry is never billed twice.
See also: All guides, Responses & states, Declines & affirmations, and Reference overview.
Roadmap status for this page
Generated from the roadmap (updated 2026-10-30). Shipped & certified means live and independently checked against primary tax sources; certifying means live, with those checks still in progress.
| Capability | Status |
|---|---|
| Docs quickstart + runnable deterministic-decline exampleDocs quickstart with a runnable example of a deterministic decline. | ✅ shipped & certified |