Skip to main content
Glama

TrueCalci

by com.truecalci
OverviewDiscussionsAdmin

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
NameRequiredDescriptionDefault
as_of_dateYesCivil date YYYY-MM-DD. Selects the rule pack in force on that date. Required: the engine will not assume a date.
filingStatusNoIRS filing status: 'single' or 'mfj' (married filing jointly).
stateDomicileNoTwo-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
foreignEarnedIncomeNoForeign earned income for the tax year, in USD.
qualifyingDaysInTaxYearNoQualifying days that fall in the tax year; the exclusion is prorated by these (26 U.S.C. 911(b)(2)(A)). Required - never assumed.
daysOutsideUSInRollingPeriodNoFull 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.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed2 schema fields changed
    • 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"
+]
  2. Changed14 schema fields changed
    • 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"
-}
  3. Changed5 schema fields changed
    • 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)."
  4. First observed

TDQS

A4.7/5.0
Behavior5/5

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

Beyond the annotations (readOnlyHint, idempotentHint), the description states the calculation is deterministic and side-effect free, evaluates the 330-day threshold, applies the statutory cap, computes tax liability on excess income, and flags aggressive state domicile rules. The annotations already cover safety, so this additional operational detail is genuinely valuable.

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 organized into three labeled sections (overview, behavior, usage guidelines), with no filler. Some redundancy exists between the overview's $130,000 for 2025 and the behavior section's repeated cap values, but otherwise every sentence earns its place given the tool's complexity.

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 six parameters and no output schema, the description conveys the core computation, eligibility threshold, caps, and state-risk flagging. It does not describe the exact output shape or the interplay of qualifyingDaysInTaxYear with proration, but the schema covers those fields and the description gives enough context for correct invocation.

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

Parameters4/5

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

Schema coverage is 100%, so the baseline is 3. The description adds meaning to key parameters: it specifies the 330-day threshold for daysOutsideUSInRollingPeriod, the statutory cap values for 2024 and 2025, and the high-audit states for stateDomicile. It does not discuss filingStatus or qualifyingDaysInTaxYear explicitly, but the schema already covers those well.

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 opens with a specific verb and resource: it tracks IRS Form 2555 FEIE eligibility, the 330-day Physical Presence Test, the statutory exclusion cap, and sticky domicile audit risks. This clearly distinguishes it from sibling tools, especially because the usage guidelines explicitly name b2b_withholding_risk as the alternative for foreign corporate withholding tax.

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?

The Usage Guidelines section explicitly states when to use the tool (US citizen digital nomads and expats evaluating Section 911 exemptions) and when not to use it, naming the sibling tool b2b_withholding_risk for foreign corporate withholding tax. This gives the agent a decisive routing rule with no ambiguity.

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

All TrueCalci toolsInspect
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