TrueCalci

US Foreign Earned Income Exclusion tracker

feie_nomad_tracker

Read-onlyIdempotent

Track IRS Form 2555 Foreign Earned Income Exclusion (FEIE) Physical Presence Test eligibility (330 full foreign days in rolling 365 days), statutory exclusion cap ($130,000 for 2025), and US sticky domicile audit risks (CA, NY, VA, SC).

Behavior: Deterministic, idempotent calculation with zero external side effects. Evaluates whether daysOutsideUSInRollingPeriod meets the mandatory 330-day threshold. Applies statutory maximum exclusion limit ($126,500 for 2024, $130,000 for 2025), computes tax liability on excess income, and flags aggressive state revenue agency sticky domicile rules.

Usage Guidelines: Use for US citizen digital nomads and expats evaluating foreign earned income tax exemptions under IRS Section 911. Do not use for foreign corporate withholding tax; use b2b_withholding_risk instead.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`as_of_date`	Yes	Civil date YYYY-MM-DD. Selects the rule pack in force on that date. Required: the engine will not assume a date.
`filingStatus`	No	IRS filing status: 'single' or 'mfj' (married filing jointly).
`stateDomicile`	No	Two-letter postal code of taxpayer's last or current US state domicile (e.g. CA, NY, TX, FL). High-audit states (CA, NY, VA, SC) trigger domicile warnings.	CA
`foreignEarnedIncome`	No	Foreign earned income for the tax year, in USD.
`qualifyingDaysInTaxYear`	No	Qualifying days that fall in the tax year; the exclusion is prorated by these (26 U.S.C. 911(b)(2)(A)). Required - never assumed.
`daysOutsideUSInRollingPeriod`	No	Full 24-hour days outside the US within any 12 consecutive months (Physical Presence Test, 26 U.S.C. 911(d)(1)(B): 330 needed). Required - never assumed.

Output Schema

TableJSON Schema

Name	Required	Description	Default
`test_type`	No
`as_of_date`	No
`disclaimer`	No
`exclusions`	No
`rate_pack_id`	No
`filing_status`	No
`qualification`	No
`tax_calculation`	No
`state_tax_exposure`	No
`statutory_authority`	No
`foreign_earned_income`	No

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedSep 27, 2026

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "additionalProperties": true,
+  "properties": {
+    "as_of_date": {
+      "type": [
+        "string",
+        "number",
+        "null"
+      ]
+    },
+    "disclaimer": {
+      "type": [
+        "string",
+        "number",
+        "null"
+      ]
+    },
+    "exclusions": {
+      "type": [
+        "object",
+        "null"
+      ]
+    },
+    "filing_status": {
+      "type": [
+        "string",
+        "number",
+        "null"
+      ]
+    },
+    "foreign_earned_income": {
+      "type": [
+        "string",
+        "number",
+        "null"
+      ]
+    },
+    "qualification": {
+      "type": [
+        "object",
+        "null"
+      ]
+    },
+    "rate_pack_id": {
+      "type": [
+        "string",
+        "number",
+        "null"
+      ]
+    },
+    "state_tax_exposure": {
+      "type": [
+        "object",
+        "null"
+      ]
+    },
+    "statutory_authority": {
+      "type": [
+        "string",
+        "number",
+        "null"
+      ]
+    },
+    "tax_calculation": {
+      "type": [
+        "object",
+        "null"
+      ]
+    },
+    "test_type": {
+      "type": [
+        "string",
+        "number",
+        "null"
+      ]
+    }
+  },
+  "type": "object"
+}

Changed2 schema fields changedSep 26, 2026

addedInput schema / properties / as_of_date

Added value: +{
+  "description": "Civil date YYYY-MM-DD. Selects the rule pack in force on that date. Required: the engine will not assume a date.",
+  "example": "2026-09-26",
+  "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
+  "type": "string"
+}

addedInput schema / required
```
Added value: +[
+  "as_of_date"
+]
```

Changed14 schema fields changedSep 26, 2026

removedInput schema / properties / daysOutsideUSInRollingPeriod / default
```
Removed value: -334
```

changedInput schema / properties / daysOutsideUSInRollingPeriod / description

Previous value: -"Number of full 24-hour qualifying foreign days spent outside the US within any rolling 365-day period. Must be >= 330 to qualify."New value: +"Full 24-hour days outside the US within any 12 consecutive months (Physical Presence Test, 26 U.S.C. 911(d)(1)(B): 330 needed). Required - never assumed."

addedInput schema / properties / daysOutsideUSInRollingPeriod / example
```
Added value: +340
```
addedInput schema / properties / daysOutsideUSInRollingPeriod / maximum
```
Added value: +366
```
addedInput schema / properties / daysOutsideUSInRollingPeriod / minimum
```
Added value: +0
```
changedInput schema / properties / daysOutsideUSInRollingPeriod / type
```
Previous value: -"number"New value: +"integer"
```

removedInput schema / properties / effectiveTaxBracketPercent

Removed value: -{
-  "default": 24,
-  "description": "Estimated federal marginal tax rate percentage applied to income exceeding the statutory cap (e.g. 24 for 24%).",
-  "type": "number"
-}

addedInput schema / properties / filingStatus

Added value: +{
+  "description": "IRS filing status: 'single' or 'mfj' (married filing jointly).",
+  "enum": [
+    "single",
+    "mfj"
+  ],
+  "type": "string"
+}

removedInput schema / properties / foreignEarnedIncome / default
```
Removed value: -160000
```

changedInput schema / properties / foreignEarnedIncome / description

Previous value: -"Total annual compensation earned while working outside the US in USD ($). Must be positive."New value: +"Foreign earned income for the tax year, in USD."

addedInput schema / properties / foreignEarnedIncome / example
```
Added value: +120000
```
addedInput schema / properties / foreignEarnedIncome / exclusiveMinimum
```
Added value: +0
```

addedInput schema / properties / qualifyingDaysInTaxYear

Added value: +{
+  "description": "Qualifying days that fall in the tax year; the exclusion is prorated by these (26 U.S.C. 911(b)(2)(A)). Required - never assumed.",
+  "example": 365,
+  "maximum": 366,
+  "minimum": 0,
+  "type": "integer"
+}

removedInput schema / properties / taxYear

Removed value: -{
-  "default": 2025,
-  "description": "Applicable US federal tax filing year (2024, 2025, or 2026).",
-  "type": "number"
-}

Changed5 schema fields changedSep 5, 2026

changedInput schema / properties / daysOutsideUSInRollingPeriod / description

Previous value: -"Full 24-hour days outside the US in rolling 365-day window"New value: +"Number of full 24-hour qualifying foreign days spent outside the US within any rolling 365-day period. Must be >= 330 to qualify."

changedInput schema / properties / effectiveTaxBracketPercent / description

Previous value: -"Estimated federal marginal tax rate %"New value: +"Estimated federal marginal tax rate percentage applied to income exceeding the statutory cap (e.g. 24 for 24%)."

changedInput schema / properties / foreignEarnedIncome / description

Previous value: -"Annual foreign earned compensation in USD ($)"New value: +"Total annual compensation earned while working outside the US in USD ($). Must be positive."

changedInput schema / properties / stateDomicile / description

Previous value: -"State of former/current US domicile (e.g. CA, NY, TX, FL)"New value: +"Two-letter postal code of taxpayer's last or current US state domicile (e.g. CA, NY, TX, FL). High-audit states (CA, NY, VA, SC) trigger domicile warnings."

changedInput schema / properties / taxYear / description

Previous value: -"Applicable tax year (2024, 2025, or 2026)"New value: +"Applicable US federal tax filing year (2024, 2025, or 2026)."

First observedSep 5, 2026

TDQS

A4.4/5.0

Behavior4/5

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false, so the safety profile is covered. The description adds calculation-specific behavior: it evaluates the 330-day threshold, applies the statutory cap, computes liability on excess, and flags sticky domicile states. It repeats the idempotent/read-only nature already in annotations, preventing a 5.

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

Conciseness4/5

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

The description is front-loaded with purpose and structured with explicit 'Behavior' and 'Usage Guidelines' labels, making it scannable. It is slightly redundant: the $130,000 2025 exclusion cap is stated in both the opening sentence and the Behavior section, which costs a perfect score.

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

Completeness5/5

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

With an output schema present, the description need not explain return values. It covers purpose, usage, alternatives, and behavioral rules, while the schema fully documents all six parameters. Nothing an agent needs in order to call this tool correctly is missing.

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 100%, so the schema already documents all six parameters in detail, including enums, required fields, and legal citations. The description references the 330-day threshold and exclusion caps but adds no parameter semantics beyond what the schema provides. Baseline 3 is appropriate.

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

Purpose5/5

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

The description gives a specific verb+resource: tracking IRS Form 2555 FEIE Physical Presence Test eligibility, statutory exclusion cap, and US sticky domicile risks. It explicitly distinguishes the tool from the sibling b2b_withholding_risk, so an agent can tell them apart without opening schemas.

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

Usage Guidelines5/5

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

It states the exact audience (US citizen digital nomads and expats evaluating FEIE under Section 911), provides a clear exclusion (do not use for foreign corporate withholding tax), and names the alternative tool (b2b_withholding_risk). This is explicit when/when-not guidance.

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

All TrueCalci tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources

Need Help?