irs-taxpayer-mcp

Overview Schema Source Related Servers Discussions Admin

generate_full_tax_report

Read-onlyIdempotent

Estimate your full tax picture: combine federal and state taxes, FICA, credits, deductions, take-home pay, and refund inputs into one detailed report.

Instructions

Generate a detailed tax estimate combining federal tax, supported state tax, FICA, modeled credits, deductions, take-home pay, and refund inputs.

Input Schema

TableJSON Schema

Name	Required	Description
`taxYear`	Yes	Tax year (2024, 2025, or 2026)
`w2Income`	No	W-2 wages
`stateCode`	No	State code for state tax estimate
`dependents`	No	Children already verified as CTC, ACTC, and EITC qualifying children
`hasForm2555`	No	Whether Form 2555 is filed
`otherIncome`	No	Other income (rental, alimony, etc.)
`filingStatus`	Yes
`otherItemized`	No	Other itemized deductions
`stateWithheld`	No	State tax already withheld YTD
`dividendIncome`	No	1099-DIV ordinary dividends
`interestIncome`	No	1099-INT interest income
`federalWithheld`	No	Federal tax already withheld YTD
`medicalExpenses`	No	Unreimbursed medical expenses
`otherDependents`	No	Dependents already verified for the nonrefundable ODC
`mortgageInterest`	No	Mortgage interest
`taxExemptInterest`	No
`qualifiedDividends`	No	Qualified dividends (subset of dividends, taxed at CG rates)
`charitableDonations`	No	Charitable contributions
`stateLocalTaxesPaid`	No	State/local/property taxes paid
`longTermCapitalGains`	No	Long-term capital gains/losses
`selfEmploymentIncome`	No	Self-employment net profit
`aotcRefundableAllowed`	No
`estimatedPaymentsMade`	No	Estimated tax payments already made
`shortTermCapitalGains`	No	Short-term capital gains/losses
`aboveTheLineDeductions`	No	HSA, student loan interest, educator expenses, etc.
`socialSecurityBenefits`	No	Net benefits from Form SSA-1099 or RRB-1099
`qualifiedBusinessIncome`	No	QBI for Section 199A
`qualifiedBusinessIsSstb`	No
`retirementDistributions`	No	Gross Form 1099-R distributions
`socialSecurityTaxesPaid`	No	Schedule 8812 payroll-tax amount for 3-or-more-child ACTC method
`qualifiedBusinessW2Wages`	No
`aotcStudentQualifiedExpenses`	No
`longTermCapitalLossCarryover`	No	Prior-year long-term capital loss carryover
`shortTermCapitalLossCarryover`	No	Prior-year short-term capital loss carryover
`qualifiedBusinessPropertyBasis`	No
`taxableRetirementDistributions`	No
`lifetimeLearningQualifiedExpenses`	No
`marriedFilingSeparatelyLivedWithSpouse`	No
`earlyRetirementDistributionSubjectToPenalty`	No

Output Schema

TableJSON Schema

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

Schema Changelog

Changes observed during successful MCP inspections.

Changed20 schema fields changedv1.0.1Sep 7, 2026

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

addedInput schema / properties / aotcStudentQualifiedExpenses

Added value: +{
+  "items": {
+    "minimum": 0,
+    "type": "number"
+  },
+  "type": "array"
+}

changedInput schema / properties / dependents / description

Previous value: -"Qualifying children under 17"New value: +"Children already verified as CTC, ACTC, and EITC qualifying children"

addedInput schema / properties / earlyRetirementDistributionSubjectToPenalty
```
Added value: +{
+  "minimum": 0,
+  "type": "number"
+}
```

addedInput schema / properties / hasForm2555

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

addedInput schema / properties / lifetimeLearningQualifiedExpenses
```
Added value: +{
+  "minimum": 0,
+  "type": "number"
+}
```

addedInput schema / properties / longTermCapitalLossCarryover

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

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

addedInput schema / properties / otherDependents

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

addedInput schema / properties / qualifiedBusinessIsSstb
```
Added value: +{
+  "type": "boolean"
+}
```
addedInput schema / properties / qualifiedBusinessPropertyBasis
```
Added value: +{
+  "minimum": 0,
+  "type": "number"
+}
```

addedInput schema / properties / qualifiedBusinessW2Wages

Added value: +{
+  "minimum": 0,
+  "type": "number"
+}

addedInput schema / properties / retirementDistributions

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

addedInput schema / properties / shortTermCapitalLossCarryover

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

addedInput schema / properties / socialSecurityBenefits

Added value: +{
+  "description": "Net benefits from Form SSA-1099 or RRB-1099",
+  "minimum": 0,
+  "type": "number"
+}

addedInput schema / properties / socialSecurityTaxesPaid

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

addedInput schema / properties / taxExemptInterest

Added value: +{
+  "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: +{
+  "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

B3.2/5.0

Behavior3/5

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safe compute-only profile is established without description help. The description adds modest context: the term 'supported state tax' hints that state coverage is conditional, and listing 'refund inputs' clarifies the report computes refund/amount-owed impact. No contradiction with annotations — 'generate an estimate' is consistent with a read-only computation. It stops short of explaining output format or behavior on unsupported states, but the output schema partially covers that.

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?

A single 22-word sentence that front-loads the verb and resource, then efficiently enumerates the report's coverage in one clause. There is zero filler, and the description earns its place by communicating scope without redundantly listing parameter names already visible in the schema.

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

Completeness2/5

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

For a tool with 39 parameters and two required fields, the one-sentence description is thin. It does not tell an agent which of the many optional parameters matter for common scenarios, does not clarify whether unspecified fields default to zero, and provides no contrast with the heavily overlapping sibling calculators. While the output schema and annotations reduce the burden on the description, an agent still lacks the context needed to reliably select this tool over calculate_total_tax or simulate_tax_scenario and to scope the parameter set for a real user situation.

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 72%, which is in the mid-range, so the schema carries most parameter documentation (with gaps like qualifiedDividends, taxExemptInterest, and qualifiedBusinessPropertyBasis having no descriptions). The tool description adds a light semantic overlay by grouping the 39 parameters into categories (federal inputs, state inputs, FICA, credits, deductions, take-home pay, refund inputs), which helps an agent mentally organize the parameter space. It does not add per-parameter detail beyond what the schema 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 uses a specific verb ('Generate'), a clear resource ('detailed tax estimate'), and enumerates the components ('federal tax, supported state tax, FICA, modeled credits, deductions, take-home pay, and refund inputs'). This establishes it as a comprehensive aggregation tool. However, it does not explicitly differentiate from close siblings like calculate_total_tax or calculate_federal_tax; the 'combining' wording and 'full' in the name imply scope but the distinction is left to inference.

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

Usage Guidelines2/5

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

No usage guidance is provided. With 43 siblings including calculate_federal_tax, estimate_state_tax, calculate_total_tax, and simulate_tax_scenario, an agent has no explicit direction about when to invoke this comprehensive report instead of a single-component calculator. The description offers no 'use X instead when...' routing, leaving the agent to guess based on the word 'full'.

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

Deploy Server