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), the statutory exclusion cap for the tax year in force on as_of_date, 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 the statutory maximum exclusion limit for the tax year in force on as_of_date, 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.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "as_of_date": "<as_of_date>"
    },
    "name": "feie_nomad_tracker"
  }
}

Input 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

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.3/5.0

Behavior4/5

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

Annotations already declare readOnly, idempotent, non-destructive, and closed-world, so 'deterministic, idempotent, zero external side effects' mostly repeats structured data. What the description does add is the actual computation: checking the 330-day threshold, applying the statutory cap, computing tax on excess income, and flagging aggressive state rules in CA/NY/VA/SC. That is genuine behavioral context beyond annotations.

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?

Front-loaded purpose followed by clearly labeled Behavior and Usage Guidelines sections, which makes it easy to scan. It is longer than strictly necessary and some behavior text duplicates the annotations, but every sentence still carries relevant tax calculation context.

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?

Covers purpose, computation logic, and routing to a sibling, and an output schema exists so return values need not be explained. The 100%-covered parameter schema fills in the remaining detail. Nothing an agent needs to call it correctly appears to be 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 baseline is 3. The description restates the 330-day threshold and the as_of_date rule-pack selection, both already documented in the schema, and adds no syntax or format detail beyond that.

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?

States a specific verb and resource: track IRS Form 2555 FEIE Physical Presence Test eligibility, the statutory exclusion cap for the tax year in force on as_of_date, and state sticky-domicile audit risk. This is far more precise than the title alone, and it separates itself from b2b_withholding_risk by naming the tax domain (Section 911 individual exclusion vs. corporate withholding).

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?

Explicitly names the audience and use case (US citizen digital nomads and expats evaluating Section 911 exemptions) and gives a clear exclusion with an alternative: do not use for foreign corporate withholding tax, use b2b_withholding_risk instead. It states both a when and a when-not with a named sibling.

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?