irs-taxpayer-mcp

Overview Schema Source Related Servers Discussions Admin

calculate_federal_tax

Read-onlyIdempotent

Calculate federal income tax for individuals for tax years 2024-2026, including brackets, credits, and deductions. Runs locally with no data sent to servers.

Instructions

Calculate federal income tax for an individual taxpayer. Supports TY2024 through TY2026. Includes bracket breakdown, effective/marginal rates, SE tax, NIIT, Additional Medicare Tax, QBI deduction, capital gains, and child tax credit. All calculations run locally — no data is sent to any server.

Input Schema

TableJSON Schema

Name	Required	Description
`blind`	No	Taxpayer is blind
`taxYear`	Yes	Tax year (2024, 2025, or 2026)
`w2Income`	No	W-2 wage income
`dependents`	No	Legacy count of qualifying child dependents for nonrefundable CTC only
`grossIncome`	Yes	Total gross income including supplied capital gains, qualified dividends, Social Security benefits, and gross retirement distributions
`hasForm2555`	No	Whether Form 2555 is filed, which makes ACTC unavailable
`age65OrOlder`	No	Taxpayer is 65 or older
`capitalGains`	No	Long-term capital gains (can be negative for losses)
`earnedIncome`	No	Schedule 8812 earned income used for ACTC
`filingStatus`	Yes	Filing status
`stateTaxDeducted`	No	State/local taxes included in itemized deductions (for AMT)
`isoExerciseSpread`	No	ISO stock option exercise spread (for AMT calculation)
`taxExemptInterest`	No	Tax-exempt interest used by the Publication 915 worksheet
`earnedIncomeCredit`	No	EITC used by the 3-or-more-child ACTC payroll-tax method
`itemizedDeductions`	No	Total itemized deductions (if greater than standard deduction)
`qualifiedDividends`	No	Qualified dividends included in gross income, taxed at preferential rates but not netted with capital losses
`netInvestmentIncome`	No	Total net investment income for NIIT, including taxable interest, dividends, gains, rents, royalties, and passive income
`capitalGainsLongTerm`	No	Whether capital gains are long-term (default: true)
`selfEmploymentIncome`	No	Self-employment income (Schedule C)
`aotcRefundableAllowed`	No	Whether refundable AOTC is allowed after under-age-24 support rules
`otherDependentsForOdc`	No	Dependents already verified for the nonrefundable Credit for Other Dependents
`shortTermCapitalGains`	No	Short-term capital gain or loss
`aboveTheLineDeductions`	No	Above-the-line deductions (HSA, student loan interest, etc.)
`socialSecurityBenefits`	No	Net Social Security benefits included in grossIncome
`qualifiedBusinessIncome`	No	Qualified Business Income for Section 199A deduction
`qualifiedBusinessIsSstb`	No	Whether the business is a specified service trade or business
`retirementDistributions`	No	Gross Form 1099-R distributions included in grossIncome
`socialSecurityTaxesPaid`	No	Schedule 8812 payroll-tax amount for the 3-or-more-child ACTC method
`qualifiedBusinessW2Wages`	No	Section 199A W-2 wages; pass 0 when none
`qualifyingChildrenForCtc`	No	Children already verified as CTC/ACTC qualifying children under age 17 with required SSNs
`aotcStudentQualifiedExpenses`	No	Qualified AOTC expenses per already-verified eligible student
`longTermCapitalLossCarryover`	No	Prior-year long-term capital loss carryover as a positive amount
`shortTermCapitalLossCarryover`	No	Prior-year short-term capital loss carryover as a positive amount
`qualifiedBusinessPropertyBasis`	No	Unadjusted basis immediately after acquisition of qualified property; pass 0 when none
`taxableRetirementDistributions`	No	Taxable Form 1099-R amount
`lifetimeLearningQualifiedExpenses`	No	Qualified LLC expenses not used for AOTC or another benefit
`marriedFilingSeparatelyLivedWithSpouse`	No
`earlyRetirementDistributionSubjectToPenalty`	No	Taxable early-distribution amount remaining after exceptions

Output Schema

TableJSON Schema

Name	Required	Description	Default
`text`	Yes
`error`	No
`isError`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed27 schema fields changedv1.0.1Sep 7, 2026

addedInput schema / properties / aotcRefundableAllowed

Added value: +{
+  "description": "Whether refundable AOTC is allowed after under-age-24 support rules",
+  "type": "boolean"
+}

addedInput schema / properties / aotcStudentQualifiedExpenses

Added value: +{
+  "description": "Qualified AOTC expenses per already-verified eligible student",
+  "items": {
+    "minimum": 0,
+    "type": "number"
+  },
+  "type": "array"
+}

changedInput schema / properties / dependents / description

Previous value: -"Number of qualifying child dependents for Child Tax Credit"New value: +"Legacy count of qualifying child dependents for nonrefundable CTC only"

addedInput schema / properties / earlyRetirementDistributionSubjectToPenalty

Added value: +{
+  "description": "Taxable early-distribution amount remaining after exceptions",
+  "minimum": 0,
+  "type": "number"
+}

addedInput schema / properties / earnedIncome

Added value: +{
+  "description": "Schedule 8812 earned income used for ACTC",
+  "minimum": 0,
+  "type": "number"
+}

addedInput schema / properties / earnedIncomeCredit

Added value: +{
+  "description": "EITC used by the 3-or-more-child ACTC payroll-tax method",
+  "minimum": 0,
+  "type": "number"
+}

changedInput schema / properties / grossIncome / description

Previous value: -"Total gross income in USD"New value: +"Total gross income including supplied capital gains, qualified dividends, Social Security benefits, and gross retirement distributions"

addedInput schema / properties / hasForm2555

Added value: +{
+  "description": "Whether Form 2555 is filed, which makes ACTC unavailable",
+  "type": "boolean"
+}

addedInput schema / properties / lifetimeLearningQualifiedExpenses

Added value: +{
+  "description": "Qualified LLC expenses not used for AOTC or another benefit",
+  "minimum": 0,
+  "type": "number"
+}

addedInput schema / properties / longTermCapitalLossCarryover

Added value: +{
+  "description": "Prior-year long-term capital loss carryover as a positive amount",
+  "minimum": 0,
+  "type": "number"
+}

addedInput schema / properties / marriedFilingSeparatelyLivedWithSpouse
```
Added value: +{
+  "type": "boolean"
+}
```

addedInput schema / properties / netInvestmentIncome

Added value: +{
+  "description": "Total net investment income for NIIT, including taxable interest, dividends, gains, rents, royalties, and passive income",
+  "minimum": 0,
+  "type": "number"
+}

addedInput schema / properties / otherDependentsForOdc

Added value: +{
+  "description": "Dependents already verified for the nonrefundable Credit for Other Dependents",
+  "minimum": 0,
+  "type": "integer"
+}

addedInput schema / properties / qualifiedBusinessIsSstb

Added value: +{
+  "description": "Whether the business is a specified service trade or business",
+  "type": "boolean"
+}

addedInput schema / properties / qualifiedBusinessPropertyBasis

Added value: +{
+  "description": "Unadjusted basis immediately after acquisition of qualified property; pass 0 when none",
+  "minimum": 0,
+  "type": "number"
+}

addedInput schema / properties / qualifiedBusinessW2Wages

Added value: +{
+  "description": "Section 199A W-2 wages; pass 0 when none",
+  "minimum": 0,
+  "type": "number"
+}

addedInput schema / properties / qualifiedDividends

Added value: +{
+  "description": "Qualified dividends included in gross income, taxed at preferential rates but not netted with capital losses",
+  "minimum": 0,
+  "type": "number"
+}

addedInput schema / properties / qualifyingChildrenForCtc

Added value: +{
+  "description": "Children already verified as CTC/ACTC qualifying children under age 17 with required SSNs",
+  "minimum": 0,
+  "type": "integer"
+}

addedInput schema / properties / retirementDistributions

Added value: +{
+  "description": "Gross Form 1099-R distributions included in grossIncome",
+  "minimum": 0,
+  "type": "number"
+}

changedInput schema / properties / shortTermCapitalGains / description

Previous value: -"Short-term capital gains (taxed as ordinary income)"New value: +"Short-term capital gain or loss"

addedInput schema / properties / shortTermCapitalLossCarryover

Added value: +{
+  "description": "Prior-year short-term capital loss carryover as a positive amount",
+  "minimum": 0,
+  "type": "number"
+}

addedInput schema / properties / socialSecurityBenefits

Added value: +{
+  "description": "Net Social Security benefits included in grossIncome",
+  "minimum": 0,
+  "type": "number"
+}

addedInput schema / properties / socialSecurityTaxesPaid

Added value: +{
+  "description": "Schedule 8812 payroll-tax amount for the 3-or-more-child ACTC method",
+  "minimum": 0,
+  "type": "number"
+}

addedInput schema / properties / taxExemptInterest

Added value: +{
+  "description": "Tax-exempt interest used by the Publication 915 worksheet",
+  "minimum": 0,
+  "type": "number"
+}

changedInput schema / properties / taxYear / description

Previous value: -"Tax year (2024 or 2025)"New value: +"Tax year (2024, 2025, or 2026)"

addedInput schema / properties / taxableRetirementDistributions

Added value: +{
+  "description": "Taxable Form 1099-R amount",
+  "minimum": 0,
+  "type": "number"
+}

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "additionalProperties": false,
+  "properties": {
+    "error": {
+      "additionalProperties": false,
+      "properties": {
+        "code": {
+          "type": "string"
+        },
+        "message": {
+          "type": "string"
+        },
+        "suggestion": {
+          "type": "string"
+        }
+      },
+      "required": [
+        "code",
+        "message",
+        "suggestion"
+      ],
+      "type": "object"
+    },
+    "isError": {
+      "type": "boolean"
+    },
+    "text": {
+      "type": "string"
+    }
+  },
+  "required": [
+    "text",
+    "isError"
+  ],
+  "type": "object"
+}

First observedv0.5.3Feb 25, 2026

TDQS

A3.8/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already establish that the tool is read-only, idempotent, and non-destructive. The description adds a meaningful behavioral guarantee beyond those annotations: calculations run locally with no data sent to a server. It also communicates the scope of calculations included, which helps set expectations for what the tool can handle.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is four short, purposeful sentences: primary purpose first, then year support, covered calculations, and a privacy guarantee. There is no filler or redundancy, and the feature list earns its place by clarifying the tool's scope for a complex calculator.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with 38 parameters, the description provides sufficient scope, supported years, covered tax areas, and privacy context, while the rich schema and output schema carry the remaining burden. Missing explicit alternative routing is a minor gap, but nothing essential is absent.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 97%, so the schema already documents the 38 parameters in detail. The description's feature list maps high-level tax topics like NIIT, QBI, capital gains, and child tax credit to related inputs, but it does not add parameter-specific information beyond what the schema already provides.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb ('Calculate') and resource ('federal income tax for an individual taxpayer'), and it lists the major tax components covered. However, it does not explicitly differentiate itself from overlapping siblings such as calculate_total_tax or simulate_tax_scenario, so sibling distinction is only implicit.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives useful selection context: federal individual income tax, supported tax years 2024–2026, and the breadth of calculations included. It does not explicitly state when to prefer this tool over alternatives like calculate_total_tax, get_tax_brackets, or calculate_eitc, nor does it provide any exclusions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server