{"openapi":"3.1.0","info":{"title":"Obolus Finanz Payroll API","version":"2.1.0","description":"Multi-country payroll and tax calculation API for DE, AT, US, CH, CA, AU, UK, and IE. This OpenAPI document is derived from the MCP descriptor."},"servers":[{"url":"https://localhost:10000"}],"tags":[{"name":"mcp","description":"MCP transport and discovery operations"},{"name":"tools","description":"Direct tool endpoints mirrored from MCP"},{"name":"resources","description":"Utility resource endpoints"},{"name":"openapi","description":"OpenAPI discovery endpoint"}],"security":[],"paths":{"/api/mcp-discovery":{"get":{"tags":["mcp"],"operationId":"getMcpDiscoveryDescriptor","summary":"Get MCP discovery descriptor","responses":{"200":{"description":"MCP descriptor","content":{"application/json":{"schema":{"$ref":"#/components/schemas/McpDescriptor"}}}},"401":{"description":"Valid API key required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthRequiredError"}}}},"403":{"description":"Requested operation or field requires API key access","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RestrictedFieldError"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitError"}}}}},"security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"x-access-control":{"api_key_env_flag":"PUBLIC_API_REQUIRE_KEY_MCP_DISCOVERY"}}},"/api/openapi":{"get":{"tags":["openapi"],"operationId":"getOpenApiSpec","summary":"Get OpenAPI specification","responses":{"200":{"description":"OpenAPI specification","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericObject"}}}},"401":{"description":"Valid API key required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthRequiredError"}}}},"403":{"description":"Requested operation or field requires API key access","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RestrictedFieldError"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitError"}}}}},"security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"x-access-control":{"api_key_env_flag":"PUBLIC_API_REQUIRE_KEY_OPENAPI_DISCOVERY"}}},"/api/mcp":{"get":{"tags":["mcp"],"operationId":"openMcpTransportStream","summary":"Open the Streamable HTTP MCP transport","description":"Stateless Streamable HTTP compatibility stream. Use POST /api/mcp for initialize, tools/list, and tools/call.","responses":{"200":{"description":"SSE stream for the MCP transport endpoint","content":{"text/event-stream":{"schema":{"type":"string"}}}},"401":{"description":"Valid API key required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthRequiredError"}}}},"403":{"description":"Requested operation or field requires API key access","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RestrictedFieldError"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitError"}}}}},"security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"x-access-control":{"api_key_env_flag":"PUBLIC_API_REQUIRE_KEY_MCP_TRANSPORT"}},"post":{"tags":["mcp"],"operationId":"postMcpTransportMessage","summary":"Send JSON-RPC messages to the MCP transport","description":"Primary stateless MCP transport endpoint for initialize, tools/list, and tools/call requests.","requestBody":{"required":true,"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/GenericObject"},{"type":"array","items":{"$ref":"#/components/schemas/GenericObject"}}]}}}},"responses":{"200":{"description":"JSON-RPC response payload","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/GenericObject"},{"type":"array","items":{"$ref":"#/components/schemas/GenericObject"}}]}}}},"202":{"description":"Notification accepted with no JSON-RPC response body"},"401":{"description":"Valid API key required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthRequiredError"}}}},"403":{"description":"Requested operation or field requires API key access","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RestrictedFieldError"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitError"}}}}},"security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"x-access-control":{"api_key_env_flag":"PUBLIC_API_REQUIRE_KEY_MCP_TRANSPORT"}}},"/api/berechne":{"post":{"tags":["tools"],"operationId":"postBerechne","summary":"Use this only for a detailed country-specific payroll or net salary calculation for one country/person workflow. For multi-country salary, net income, tax burden, or social-contribution comparisons, use taxcompare first. berechne is country-polymorphic: the same field names can mean different things depending on Land and the selected tax system. Use the declared Obolus field names exactly: top-level Land, Stjahr, Currency, LZZ, Modus, Personen. LZZ maps to 1=year, 2=month, 3=week, 4=day, and salary amounts such as Personen[].Gehalt_ct must be the gross amount for that selected period in minor currency units. Country-specific usage: DE: German payroll. Steuerklasse 1-6; Bundesland is the full Obolus state name such as Berlin or Nordrhein-Westfalen. For normal employees use the MCP preset de_payroll_preset=DE_STANDARD_EMPLOYEE_STATUTORY plus de_health_extra_contribution_percent as a literal percent such as 2.5. ChatGPT should not fill raw Obolus German payroll flags; the adapter translates semantic presets and aliases into backend compatibility fields. AT: Austrian payroll. Steuerklasse 1=standard employee, 2=sole earner with child, 3=single parent with child; Bundesland is the Austrian federal state; annual/monthly periods are the normal UI paths; pendler fields are Austria-only commuter inputs; BK/STS/STX/NETX can represent 13th/14th salary handling. CH: Swiss payroll. Steuerklasse 1=Tarif A, 2=Tarif B, 3=Tarif C, 4=Tarif H; Bundesland is the canton, currently Zurich in the UI; payroll deductions can include AHV/IV/EO, ALV, occupational pension, accident/sickness items; private KVG/LAMal health bills are not modeled as payroll health insurance. US: United States payroll. Steuerklasse 1=Single, 3=Joint, 4=Head of Household; Bundesland is the state; PreTax_Deduction_ct is for 401k/IRA/HSA-style deductions; Sonstige_Bezuege is supplemental income; outputs can split federal/state tax and OASDI/Medicare-style payroll contributions. UK: United Kingdom payroll. Steuerklasse 1=1257L standard tax code; Bundesland is region; PreTax_Deduction_ct is salary sacrifice or pension; Hat_Studienkredit toggles student loan repayment; outputs include PAYE income tax, National Insurance, and student loan where applicable. IE: Ireland payroll. Steuerklasse 1=Single, 2=Joint one income, 3=Joint two incomes; PreTax_Deduction_ct is pension contribution; Hat_Studienkredit is only relevant when a student-loan deduction is modeled; outputs include PAYE, USC, PRSI, and tax-credit information. CA: Canada payroll. Steuerklasse represents the federal/provincial claim setup; Bundesland is province such as Ontario, Quebec, or British Columbia; PreTax_Deduction_ct is RRSP/pension-style deduction; outputs can include federal/provincial tax, CPP/QPP, EI, and RRSP/credit information. AU: Australia payroll. Steuerklasse 1=Resident, 2=Non-Resident, 3=Working Holiday; PreTax_Deduction_ct is super salary sacrifice; Hat_Studienkredit toggles HELP/HECS repayment; Sonstige_Bezuege is bonus pay; outputs include PAYG tax, Medicare Levy, voluntary super, and employer super info. For standard German employees, ChatGPT/MCP should use semantic preset fields, not legacy numeric insurance fields: de_payroll_preset=DE_STANDARD_EMPLOYEE_STATUTORY, de_statutory_pension_and_unemployment=true, de_statutory_health_and_care=true, de_health_extra_contribution_percent=2.5 for a 2.5% Zusatzbeitrag, Kirche=0, KinderPVA=0, Kinderfreibetrag=0. Do not encode de_health_extra_contribution_percent as 25, 250, basis points, tenths, or cents. Raw Obolus fields such as gesetzliche_RV, gesetzlicheKvPvStatus, KV_Art, and KVZ are compatibility fields that can be valid in existing product/API payloads, especially for pensioners, civil servants, pension-exempt workers, and private health insurance. ChatGPT-facing calls should prefer semantic preset fields when possible. For \"Germany, normal employee, tax class I\", send de_payroll_preset=DE_STANDARD_EMPLOYEE_STATUTORY, de_statutory_pension_and_unemployment=true, de_statutory_health_and_care=true, and de_health_extra_contribution_percent=2.5 for a 2.5% Zusatzbeitrag. Bundesland must be the full Obolus state name such as Berlin. Do not send raw German Obolus flags such as gesetzliche_RV, gesetzlicheKvPvStatus, KV_Art, or KVZ in ChatGPT-facing calls; the adapter maps the semantic fields internally.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BerechneRequest"}}}},"responses":{"200":{"description":"berechne response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BerechneResponse"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Valid API key required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthRequiredError"}}}},"403":{"description":"Requested operation or field requires API key access","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RestrictedFieldError"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitError"}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-mcp-tool":"berechne","x-access-control":{"api_key_env_flag":"PUBLIC_API_REQUIRE_KEY_BERECHNE","restricted_fields_env":"PUBLIC_API_RESTRICTED_FIELDS_BERECHNE"},"security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}]}},"/api/taxcompare":{"post":{"tags":["tools"],"operationId":"postTaxcompare","summary":"Use this as the default tool whenever the user asks to compare salary, annual net income, tax burden, social contributions, or effective burden across multiple countries. Do not use berechne for multi-country comparisons unless the user asks for detailed country-specific payroll. If the user asks for one salary across multiple countries, always use taxcompare first. Use this endpoint for multi-country salary/tax comparisons. Select taxcompare when the user provides one salary or income amount, two or more countries, and wants tax, net salary, deductions, take-home pay, ranking, or 'where do I keep more money' results. Typical trigger phrases include: calculate tax for 50k in Germany, Ireland, USA, Canada; compare net salary across these countries; where do I pay less tax on EUR 80k; what is take-home pay in X, Y, Z; rank these countries by net income; how much do I keep after tax in Germany vs Ireland. Routing rule: if countries.length >= 2 and the same salary/income is used, use taxcompare. If countries.length === 1, use berechne. If the user provides detailed payroll assumptions such as tax class, province/state, health insurance, children, church tax, pension exemption, deductions, or benefits, use berechne unless taxcompare supports those fields explicitly. Do not use berechne repeatedly for simple multi-country comparisons unless taxcompare cannot accept the required inputs. Use shared_gross when the user wants to compare the same salary offer across countries. Prefer salary_ct in minor units, such as 5000000 for EUR 50,000. annual_gross is a backward-compatible annual major-unit alias, such as 50000 for EUR 50,000. Use local_median_gross when the user wants a local-market benchmark. In this mode Obolus fans out to country-specific editorial median gross benchmarks; annual_gross is optional and ignored when omitted. taxcompare is annual and country-level. It is not the right tool for detailed payroll inputs such as German KVZ, tax class IV factor, private health insurance, commuter allowance, or monthly gross; use berechne for that. countries accepts DE, AT, CH, US, UK, IE, CA, and AU. currency accepts EUR, USD, CHF, CAD, AUD, GBP and lower-case equivalents; results normalize currency codes to lower-case. joint_assessment and children are broad comparison assumptions. Country-specific filing details are simplified for comparability; for a precise single-country case, call berechne. Results are annual major-currency estimates. net is annual take-home pay; tax is annual tax burden; social_contributions are annual employee payroll/social deductions or the country-specific equivalent; effective_rate is a percentage-point burden value such as 37.7 for 37.7%. Country meanings differ: DE/AT emphasize income tax plus statutory social contributions, CH can include withholding and payroll social deductions but not private KVG/LAMal health bills, US includes federal/state and OASDI/Medicare-style items, UK includes PAYE/National Insurance, IE includes PAYE/USC/PRSI, CA includes federal/provincial tax plus CPP/QPP/EI, and AU includes PAYG/Medicare/super-related outputs.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaxcompareRequest"}}}},"responses":{"200":{"description":"taxcompare response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaxcompareResponse"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Valid API key required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthRequiredError"}}}},"403":{"description":"Requested operation or field requires API key access","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RestrictedFieldError"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitError"}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-mcp-tool":"taxcompare","x-access-control":{"api_key_env_flag":"PUBLIC_API_REQUIRE_KEY_TAXCOMPARE","restricted_fields_env":"PUBLIC_API_RESTRICTED_FIELDS_TAXCOMPARE"},"security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}]}},"/api/health":{"get":{"tags":["resources"],"operationId":"getHealth","summary":"Checks whether the backend is reachable.","responses":{"200":{"description":"health resource response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericObject"}}}},"401":{"description":"Valid API key required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthRequiredError"}}}},"403":{"description":"Requested operation or field requires API key access","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RestrictedFieldError"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitError"}}}}}}}},"components":{"schemas":{"Error":{"type":"object","additionalProperties":true,"properties":{"error":{"type":"string"}},"required":["error"]},"AuthRequiredError":{"type":"object","additionalProperties":true,"properties":{"error":{"type":"string"}},"required":["error"]},"RestrictedFieldError":{"type":"object","additionalProperties":true,"properties":{"error":{"type":"string"},"restricted_fields":{"type":"array","items":{"type":"string"}}},"required":["error"]},"RateLimitError":{"type":"object","additionalProperties":true,"properties":{"error":{"type":"string"},"scope":{"type":"string"},"retry_after_seconds":{"type":"integer"}},"required":["error"]},"McpDescriptor":{"mcp":"1.0.1","name":"Obolus Finanz Payroll API","description":"Multi-country payroll and tax calculation API for DE, AT, US, CH, CA, AU, UK, and IE.","version":"2.1.0","metadata":{"supported_countries":["DE","AT","US","CH","CA","AU","UK","IE"],"berechne_amount_unit":"minor currency units","taxcompare_amount_unit":"major currency units","openapi_url":"/api/openapi","mcp_transport_url":"/api/mcp","mcp_discovery_url":"/api/mcp-discovery","publication_scope":"public-entry-tools-only","public_tools":["berechne","taxcompare"],"rate_limits":{"mcp_discovery":"30 requests / 5 minutes","mcp_transport":"GET stream 100 requests / 5 minutes; POST invoke 200 requests / 5 minutes","openapi_discovery":"30 requests / 5 minutes","berechne":"15 requests / 5 minutes","taxcompare":"20 requests / 5 minutes"},"authentication":{"accepted_headers":["x-public-api-key","x-api-key","authorization: Bearer <token>"],"env_controls":["PUBLIC_API_KEYS","PUBLIC_API_REQUIRE_KEY","PUBLIC_API_REQUIRE_KEY_<TOOL>","PUBLIC_API_RESTRICTED_FIELDS_<TOOL>"]},"notes":["berechne expects monetary input amounts in minor units such as cents, and the amount must match the selected payroll period.","For berechne, LZZ values are 1=year, 2=month, 3=week, 4=day. Gehalt_ct is the gross amount for that period.","Country-specific berechne usage: DE: German payroll. Steuerklasse 1-6; Bundesland is the full Obolus state name such as Berlin or Nordrhein-Westfalen. For normal employees use the MCP preset de_payroll_preset=DE_STANDARD_EMPLOYEE_STATUTORY plus de_health_extra_contribution_percent as a literal percent such as 2.5. ChatGPT should not fill raw Obolus German payroll flags; the adapter translates semantic presets and aliases into backend compatibility fields. AT: Austrian payroll. Steuerklasse 1=standard employee, 2=sole earner with child, 3=single parent with child; Bundesland is the Austrian federal state; annual/monthly periods are the normal UI paths; pendler fields are Austria-only commuter inputs; BK/STS/STX/NETX can represent 13th/14th salary handling. CH: Swiss payroll. Steuerklasse 1=Tarif A, 2=Tarif B, 3=Tarif C, 4=Tarif H; Bundesland is the canton, currently Zurich in the UI; payroll deductions can include AHV/IV/EO, ALV, occupational pension, accident/sickness items; private KVG/LAMal health bills are not modeled as payroll health insurance. US: United States payroll. Steuerklasse 1=Single, 3=Joint, 4=Head of Household; Bundesland is the state; PreTax_Deduction_ct is for 401k/IRA/HSA-style deductions; Sonstige_Bezuege is supplemental income; outputs can split federal/state tax and OASDI/Medicare-style payroll contributions. UK: United Kingdom payroll. Steuerklasse 1=1257L standard tax code; Bundesland is region; PreTax_Deduction_ct is salary sacrifice or pension; Hat_Studienkredit toggles student loan repayment; outputs include PAYE income tax, National Insurance, and student loan where applicable. IE: Ireland payroll. Steuerklasse 1=Single, 2=Joint one income, 3=Joint two incomes; PreTax_Deduction_ct is pension contribution; Hat_Studienkredit is only relevant when a student-loan deduction is modeled; outputs include PAYE, USC, PRSI, and tax-credit information. CA: Canada payroll. Steuerklasse represents the federal/provincial claim setup; Bundesland is province such as Ontario, Quebec, or British Columbia; PreTax_Deduction_ct is RRSP/pension-style deduction; outputs can include federal/provincial tax, CPP/QPP, EI, and RRSP/credit information. AU: Australia payroll. Steuerklasse 1=Resident, 2=Non-Resident, 3=Working Holiday; PreTax_Deduction_ct is super salary sacrifice; Hat_Studienkredit toggles HELP/HECS repayment; Sonstige_Bezuege is bonus pay; outputs include PAYG tax, Medicare Levy, voluntary super, and employer super info.","For standard German employees, ChatGPT/MCP should use semantic preset fields, not legacy numeric insurance fields: de_payroll_preset=DE_STANDARD_EMPLOYEE_STATUTORY, de_statutory_pension_and_unemployment=true, de_statutory_health_and_care=true, de_health_extra_contribution_percent=2.5 for a 2.5% Zusatzbeitrag, Kirche=0, KinderPVA=0, Kinderfreibetrag=0. Do not encode de_health_extra_contribution_percent as 25, 250, basis points, tenths, or cents. Raw Obolus fields such as gesetzliche_RV, gesetzlicheKvPvStatus, KV_Art, and KVZ are compatibility fields that can be valid in existing product/API payloads, especially for pensioners, civil servants, pension-exempt workers, and private health insurance. ChatGPT-facing calls should prefer semantic preset fields when possible.","For German berechne requests, raw backend payroll flags are internal compatibility fields. ChatGPT-facing calls should use de_payroll_preset and semantic booleans; contradictory raw combinations produce advisory warnings rather than hard failures because existing product/API payloads may use valid non-standard cases.","For German berechne requests, de_health_extra_contribution_percent is a percent value such as 2.5 for 2.5%, not 25, 170, or basis points.","taxcompare usage: If the user asks for one salary across multiple countries, always use taxcompare first. Use this endpoint for multi-country salary/tax comparisons. Select taxcompare when the user provides one salary or income amount, two or more countries, and wants tax, net salary, deductions, take-home pay, ranking, or 'where do I keep more money' results. Typical trigger phrases include: calculate tax for 50k in Germany, Ireland, USA, Canada; compare net salary across these countries; where do I pay less tax on EUR 80k; what is take-home pay in X, Y, Z; rank these countries by net income; how much do I keep after tax in Germany vs Ireland. Routing rule: if countries.length >= 2 and the same salary/income is used, use taxcompare. If countries.length === 1, use berechne. If the user provides detailed payroll assumptions such as tax class, province/state, health insurance, children, church tax, pension exemption, deductions, or benefits, use berechne unless taxcompare supports those fields explicitly. Do not use berechne repeatedly for simple multi-country comparisons unless taxcompare cannot accept the required inputs. Use shared_gross when the user wants to compare the same salary offer across countries. Prefer salary_ct in minor units, such as 5000000 for EUR 50,000. annual_gross is a backward-compatible annual major-unit alias, such as 50000 for EUR 50,000. Use local_median_gross when the user wants a local-market benchmark. In this mode Obolus fans out to country-specific editorial median gross benchmarks; annual_gross is optional and ignored when omitted. taxcompare is annual and country-level. It is not the right tool for detailed payroll inputs such as German KVZ, tax class IV factor, private health insurance, commuter allowance, or monthly gross; use berechne for that. countries accepts DE, AT, CH, US, UK, IE, CA, and AU. currency accepts EUR, USD, CHF, CAD, AUD, GBP and lower-case equivalents; results normalize currency codes to lower-case. joint_assessment and children are broad comparison assumptions. Country-specific filing details are simplified for comparability; for a precise single-country case, call berechne. Results are annual major-currency estimates. net is annual take-home pay; tax is annual tax burden; social_contributions are annual employee payroll/social deductions or the country-specific equivalent; effective_rate is a percentage-point burden value such as 37.7 for 37.7%. Country meanings differ: DE/AT emphasize income tax plus statutory social contributions, CH can include withholding and payroll social deductions but not private KVG/LAMal health bills, US includes federal/state and OASDI/Medicare-style items, UK includes PAYE/National Insurance, IE includes PAYE/USC/PRSI, CA includes federal/provincial tax plus CPP/QPP/EI, and AU includes PAYG/Medicare/super-related outputs.","Complex cockpit and investment simulations are intentionally not published via MCP/OpenAPI."]},"capabilities":{"tools":{"berechne":{"description":"Use this only for a detailed country-specific payroll or net salary calculation for one country/person workflow. For multi-country salary, net income, tax burden, or social-contribution comparisons, use taxcompare first. berechne is country-polymorphic: the same field names can mean different things depending on Land and the selected tax system. Use the declared Obolus field names exactly: top-level Land, Stjahr, Currency, LZZ, Modus, Personen. LZZ maps to 1=year, 2=month, 3=week, 4=day, and salary amounts such as Personen[].Gehalt_ct must be the gross amount for that selected period in minor currency units. Country-specific usage: DE: German payroll. Steuerklasse 1-6; Bundesland is the full Obolus state name such as Berlin or Nordrhein-Westfalen. For normal employees use the MCP preset de_payroll_preset=DE_STANDARD_EMPLOYEE_STATUTORY plus de_health_extra_contribution_percent as a literal percent such as 2.5. ChatGPT should not fill raw Obolus German payroll flags; the adapter translates semantic presets and aliases into backend compatibility fields. AT: Austrian payroll. Steuerklasse 1=standard employee, 2=sole earner with child, 3=single parent with child; Bundesland is the Austrian federal state; annual/monthly periods are the normal UI paths; pendler fields are Austria-only commuter inputs; BK/STS/STX/NETX can represent 13th/14th salary handling. CH: Swiss payroll. Steuerklasse 1=Tarif A, 2=Tarif B, 3=Tarif C, 4=Tarif H; Bundesland is the canton, currently Zurich in the UI; payroll deductions can include AHV/IV/EO, ALV, occupational pension, accident/sickness items; private KVG/LAMal health bills are not modeled as payroll health insurance. US: United States payroll. Steuerklasse 1=Single, 3=Joint, 4=Head of Household; Bundesland is the state; PreTax_Deduction_ct is for 401k/IRA/HSA-style deductions; Sonstige_Bezuege is supplemental income; outputs can split federal/state tax and OASDI/Medicare-style payroll contributions. UK: United Kingdom payroll. Steuerklasse 1=1257L standard tax code; Bundesland is region; PreTax_Deduction_ct is salary sacrifice or pension; Hat_Studienkredit toggles student loan repayment; outputs include PAYE income tax, National Insurance, and student loan where applicable. IE: Ireland payroll. Steuerklasse 1=Single, 2=Joint one income, 3=Joint two incomes; PreTax_Deduction_ct is pension contribution; Hat_Studienkredit is only relevant when a student-loan deduction is modeled; outputs include PAYE, USC, PRSI, and tax-credit information. CA: Canada payroll. Steuerklasse represents the federal/provincial claim setup; Bundesland is province such as Ontario, Quebec, or British Columbia; PreTax_Deduction_ct is RRSP/pension-style deduction; outputs can include federal/provincial tax, CPP/QPP, EI, and RRSP/credit information. AU: Australia payroll. Steuerklasse 1=Resident, 2=Non-Resident, 3=Working Holiday; PreTax_Deduction_ct is super salary sacrifice; Hat_Studienkredit toggles HELP/HECS repayment; Sonstige_Bezuege is bonus pay; outputs include PAYG tax, Medicare Levy, voluntary super, and employer super info. For standard German employees, ChatGPT/MCP should use semantic preset fields, not legacy numeric insurance fields: de_payroll_preset=DE_STANDARD_EMPLOYEE_STATUTORY, de_statutory_pension_and_unemployment=true, de_statutory_health_and_care=true, de_health_extra_contribution_percent=2.5 for a 2.5% Zusatzbeitrag, Kirche=0, KinderPVA=0, Kinderfreibetrag=0. Do not encode de_health_extra_contribution_percent as 25, 250, basis points, tenths, or cents. Raw Obolus fields such as gesetzliche_RV, gesetzlicheKvPvStatus, KV_Art, and KVZ are compatibility fields that can be valid in existing product/API payloads, especially for pensioners, civil servants, pension-exempt workers, and private health insurance. ChatGPT-facing calls should prefer semantic preset fields when possible. For \"Germany, normal employee, tax class I\", send de_payroll_preset=DE_STANDARD_EMPLOYEE_STATUTORY, de_statutory_pension_and_unemployment=true, de_statutory_health_and_care=true, and de_health_extra_contribution_percent=2.5 for a 2.5% Zusatzbeitrag. Bundesland must be the full Obolus state name such as Berlin. Do not send raw German Obolus flags such as gesetzliche_RV, gesetzlicheKvPvStatus, KV_Art, or KVZ in ChatGPT-facing calls; the adapter maps the semantic fields internally.","annotations":{"readOnlyHint":true,"destructiveHint":false,"openWorldHint":false},"endpoint":{"url":"/api/berechne","method":"POST"},"access_control":{"api_key_supported":true,"require_key_env":"PUBLIC_API_REQUIRE_KEY_BERECHNE","restricted_fields_env":"PUBLIC_API_RESTRICTED_FIELDS_BERECHNE"},"input_schema":{"type":"object","additionalProperties":true,"description":"Input schema for one-country detailed Obolus payroll calculations. Prefer the high-level user-facing fields country, tax_year, gross_salary, location, employee_type, tax, and social_security for German ChatGPT calls. Do not send raw German engine flags such as KVZ, gesetzliche_RV, gesetzlicheKvPvStatus, or KV_Art from ChatGPT-facing calls; they remain accepted only as backward-compatible product/API payload fields. Prefer taxcompare for multi-country comparisons. Legacy Obolus fields use minor currency units and are period-specific. Country-specific usage: DE: German payroll. Steuerklasse 1-6; Bundesland is the full Obolus state name such as Berlin or Nordrhein-Westfalen. For normal employees use the MCP preset de_payroll_preset=DE_STANDARD_EMPLOYEE_STATUTORY plus de_health_extra_contribution_percent as a literal percent such as 2.5. ChatGPT should not fill raw Obolus German payroll flags; the adapter translates semantic presets and aliases into backend compatibility fields. AT: Austrian payroll. Steuerklasse 1=standard employee, 2=sole earner with child, 3=single parent with child; Bundesland is the Austrian federal state; annual/monthly periods are the normal UI paths; pendler fields are Austria-only commuter inputs; BK/STS/STX/NETX can represent 13th/14th salary handling. CH: Swiss payroll. Steuerklasse 1=Tarif A, 2=Tarif B, 3=Tarif C, 4=Tarif H; Bundesland is the canton, currently Zurich in the UI; payroll deductions can include AHV/IV/EO, ALV, occupational pension, accident/sickness items; private KVG/LAMal health bills are not modeled as payroll health insurance. US: United States payroll. Steuerklasse 1=Single, 3=Joint, 4=Head of Household; Bundesland is the state; PreTax_Deduction_ct is for 401k/IRA/HSA-style deductions; Sonstige_Bezuege is supplemental income; outputs can split federal/state tax and OASDI/Medicare-style payroll contributions. UK: United Kingdom payroll. Steuerklasse 1=1257L standard tax code; Bundesland is region; PreTax_Deduction_ct is salary sacrifice or pension; Hat_Studienkredit toggles student loan repayment; outputs include PAYE income tax, National Insurance, and student loan where applicable. IE: Ireland payroll. Steuerklasse 1=Single, 2=Joint one income, 3=Joint two incomes; PreTax_Deduction_ct is pension contribution; Hat_Studienkredit is only relevant when a student-loan deduction is modeled; outputs include PAYE, USC, PRSI, and tax-credit information. CA: Canada payroll. Steuerklasse represents the federal/provincial claim setup; Bundesland is province such as Ontario, Quebec, or British Columbia; PreTax_Deduction_ct is RRSP/pension-style deduction; outputs can include federal/provincial tax, CPP/QPP, EI, and RRSP/credit information. AU: Australia payroll. Steuerklasse 1=Resident, 2=Non-Resident, 3=Working Holiday; PreTax_Deduction_ct is super salary sacrifice; Hat_Studienkredit toggles HELP/HECS repayment; Sonstige_Bezuege is bonus pay; outputs include PAYG tax, Medicare Levy, voluntary super, and employer super info. For standard German employees, ChatGPT/MCP should use semantic preset fields, not legacy numeric insurance fields: de_payroll_preset=DE_STANDARD_EMPLOYEE_STATUTORY, de_statutory_pension_and_unemployment=true, de_statutory_health_and_care=true, de_health_extra_contribution_percent=2.5 for a 2.5% Zusatzbeitrag, Kirche=0, KinderPVA=0, Kinderfreibetrag=0. Do not encode de_health_extra_contribution_percent as 25, 250, basis points, tenths, or cents. Raw Obolus fields such as gesetzliche_RV, gesetzlicheKvPvStatus, KV_Art, and KVZ are compatibility fields that can be valid in existing product/API payloads, especially for pensioners, civil servants, pension-exempt workers, and private health insurance. ChatGPT-facing calls should prefer semantic preset fields when possible.","properties":{"country":{"type":"string","enum":["DE","AT","US","CH","CA","AU","UK","IE"],"description":"Preferred high-level country code for ChatGPT-facing calls. For German payroll use DE. The adapter maps this to legacy Land."},"tax_year":{"type":"integer","description":"Preferred high-level tax year for ChatGPT-facing calls. The adapter maps this to legacy Stjahr.","examples":[2026]},"gross_salary":{"type":"object","additionalProperties":false,"description":"Preferred high-level gross salary input. Amount is in major currency units, not cents. The adapter maps it to legacy Gehalt_ct minor units and LZZ.","properties":{"amount":{"type":"number","minimum":0,"description":"Gross salary in major currency units, for example 60000 for EUR 60,000 annual gross or 5000 for EUR 5,000 monthly gross."},"currency":{"type":"string","enum":["EUR","USD","CHF","CAD","AUD","GBP"],"description":"Salary currency, for example EUR."},"period":{"type":"string","enum":["annual","monthly","weekly","daily"],"description":"Salary period. annual maps to LZZ=1, monthly to LZZ=2, weekly to LZZ=3, daily to LZZ=4."}},"required":["amount","currency","period"]},"location":{"type":"object","additionalProperties":false,"description":"Preferred high-level location input. For Germany, federal_state may be a state code such as BE or a full Obolus state name such as Berlin.","properties":{"federal_state":{"type":"string","description":"German federal state code or full state name, for example BE or Berlin. The adapter maps BE to Berlin."}}},"employee_type":{"type":"string","enum":["standard_statutory_employee","private_health_insurance","pension_exempt","pension_exempt_private_health"],"default":"standard_statutory_employee","description":"Preferred high-level German employee type. Use standard_statutory_employee for the common statutory pension, unemployment, health, and care insurance case."},"payroll_preset":{"type":"string","enum":["DE_STANDARD_EMPLOYEE_STATUTORY","DE_PRIVATE_HEALTH_INSURANCE","DE_PENSION_EXEMPT","DE_PENSION_EXEMPT_PRIVATE_HEALTH"],"default":"DE_STANDARD_EMPLOYEE_STATUTORY","description":"Preferred high-level payroll preset. Use DE_STANDARD_EMPLOYEE_STATUTORY for a normal German employee with statutory pension, unemployment, health, and care insurance."},"tax":{"type":"object","additionalProperties":false,"description":"Preferred high-level tax assumptions for ChatGPT-facing calls. The adapter maps these to Steuerklasse, Kirche, and Kinderfreibetrag.","properties":{"tax_class":{"type":"integer","enum":[1,2,3,4,5,6],"description":"German tax class, 1 through 6."},"church_tax":{"type":"boolean","default":false,"description":"Whether German church tax applies. false maps to Kirche=0 and true maps to Kirche=1."},"child_allowance_factor":{"type":"number","minimum":0,"default":0,"description":"German child allowance factor, for example 0, 0.5, 1, or 2."}}},"social_security":{"type":"object","additionalProperties":false,"description":"Preferred high-level German social-security assumptions. Use enums instead of raw Obolus flags. The adapter maps statutory/exempt/private choices to the legacy payroll-engine fields.","properties":{"pension_insurance":{"type":"string","enum":["statutory","exempt"],"default":"statutory","description":"Use statutory for normal employees. Use exempt only for civil servants, self-employed, pensioners, or explicitly pension-exempt cases."},"unemployment_insurance":{"type":"string","enum":["statutory","exempt"],"default":"statutory","description":"Use statutory for normal employees. This is mapped together with pension_insurance for the legacy German payroll engine."},"health_insurance":{"type":"string","enum":["statutory","private"],"default":"statutory","description":"Use statutory for German GKV/PV. Use private only when the user explicitly has private health insurance."},"health_additional_contribution_percent":{"type":"number","minimum":0,"maximum":5,"examples":[2.5,2.9],"description":"German statutory health Zusatzbeitrag as literal percentage points, for example 2.9 for 2.90%. Do not use basis points such as 290."},"long_term_care_insurance":{"type":"string","enum":["statutory","private"],"default":"statutory","description":"Use statutory for normal German care insurance. Private should only be used together with private health insurance."},"children_for_care_insurance":{"type":"integer","minimum":0,"default":0,"description":"Number of children relevant for German long-term care insurance contribution logic."},"private_health_employee_contribution_ct":{"type":"integer","minimum":0,"description":"Private health insurance employee contribution in minor units for the selected period. Required only when health_insurance is private."}}},"Land":{"type":"string","enum":["DE","AT","US","CH","CA","AU","UK","IE"],"description":"Country code for the calculation."},"Stjahr":{"type":"integer","description":"Tax year.","examples":[2026]},"Currency":{"type":"string","enum":["EUR","USD","CHF","CAD","AUD","GBP"],"description":"Display currency / calculation currency code."},"LZZ":{"type":"integer","enum":[1,2,3,4],"default":1,"description":"Payroll period identifier for the calculation. Values: 1=year, 2=month, 3=week, 4=day. All salary and payroll monetary inputs must be for this period, not automatically annualized."},"Modus":{"type":"integer","enum":[1,2,3],"default":1,"description":"Calculation mode. Use 1 for one person, 2 for two persons, and 3 for the German TaxSim capped real-splitting simulation."},"Faktor":{"type":"number","default":1,"description":"Global factor for factor-based tax class handling."},"KinderFRB":{"type":"number","default":0,"description":"Top-level child allowance, child count, dependent count, or child-credit factor for the calculation. DE uses allowance-style factors; AT/CH/US and other systems use country-specific child/dependent meanings where supported."},"KinderPVA":{"type":"integer","minimum":0,"default":0,"description":"Total child count relevant for German long-term care insurance contribution logic. Leave 0 outside German care-insurance scenarios unless a country-specific child workflow explicitly requires it."},"Kindergeld":{"type":"integer","default":0,"description":"Child benefit amount in minor units for the selected calculation context. Leave 0 for standard payroll estimates unless explicitly modeling child benefit or a country-specific dependent benefit."},"Personen":{"type":"array","minItems":1,"maxItems":2,"description":"One or two payroll person records. Each person contains salary, tax class, region, insurance, child, and optional special-income inputs.","items":{"type":"object","additionalProperties":true,"properties":{"Land":{"type":"string","enum":["DE","AT","US","CH","CA","AU","UK","IE"],"description":"Country code that selects the payroll/tax system for this person. Interpret all country-polymorphic fields in this person record, such as Steuerklasse, Bundesland, PreTax_Deduction_ct, Kinderfreibetrag, and output tax buckets, through this Land value. Supported systems: DE, AT, CH, US, UK, IE, CA, AU."},"Gehalt_ct":{"type":"integer","minimum":0,"description":"Gross pay for this person's selected payroll period in minor units. The value must match LZZ/Lohnzahlungszeitraum: for EUR 70,000 per year with LZZ=1 send 7000000; for monthly payroll with LZZ=2 send the monthly gross, for example 583333 for EUR 5,833.33."},"Gehalt_ct_ohne_Sonst":{"type":"integer","minimum":0,"description":"Gross pay excluding one-off or bonus payments for the selected payroll period, in minor units."},"Steuerklasse":{"type":"integer","description":"Country-polymorphic tax class, tariff, filing status, or tax-code selector. Do not reuse German tax-class meanings outside Land=DE. DE: 1=single, 2=single parent, 3/4/5=married tax classes, 6=additional job. AT: 1=standard employee, 2=sole earner with child, 3=single parent with child. CH: 1=Tarif A, 2=Tarif B, 3=Tarif C, 4=Tarif H. US: 1=Single, 3=Joint, 4=Head of Household. UK: 1=1257L standard tax code. IE: 1=Single, 2=Joint one income, 3=Joint two incomes. AU: 1=Resident, 2=Non-Resident, 3=Working Holiday. CA uses the payroll claim setup for federal/provincial tax calculation."},"Geldwerter_Vorteil":{"type":"integer","description":"Taxable benefits in minor units. Used as in-kind benefit, taxable benefit, benefit in kind, natural salary, or imputed income depending on country; supported for DE, AT, CH, UK, US, CA, and IE."},"PreTax_Deduction_ct":{"type":"integer","description":"Country-polymorphic pre-tax deductions in minor units for the selected payroll period. Interpret by Land: AT occupational provision/commuter-related deduction, CH pillar 3a or occupational pension purchase, US 401k/IRA/HSA, UK salary sacrifice or pension, CA RRSP/pension, AU super salary sacrifice, and IE pension contribution."},"pendlerEuro":{"type":"integer","description":"Austria-only commuter allowance amount in minor units."},"Pendler_KM":{"type":"integer","description":"Austria-only commuting distance in kilometers."},"Pendler_Zumutbar":{"type":"integer","description":"Austrian commuter reasonableness flag."},"Pendler_Tage":{"type":"integer","description":"Austria-only monthly commuter days."},"Altersrente_Bezug":{"type":"integer","description":"1 if pension/retirement benefits apply, otherwise 0. Mainly used for DE/AT pensioner workflows."},"Bundesland":{"type":"string","description":"Country-polymorphic region selector for regional taxes and payroll rules. DE uses full Obolus state names such as Berlin, Bayern, Nordrhein-Westfalen, Sachsen, not ISO abbreviations such as BE or BY. AT uses Austrian federal states such as Wien. CH uses the canton such as Zurich. US uses state names such as California. CA uses provinces such as Ontario, Quebec, or British Columbia. UK uses England, Scotland, Wales, or Northern Ireland. Leave omitted for country examples that omit it unless the user gives a specific supported region.","examples":["Baden-Wuerttemberg","Bayern","Berlin","Brandenburg","Bremen","Hamburg","Hessen","Mecklenburg-Vorpommern","Niedersachsen","Nordrhein-Westfalen","Rheinland-Pfalz","Saarland","Sachsen","Sachsen-Anhalt","Schleswig-Holstein","Thueringen"]},"Lohnzahlungszeitraum":{"type":"integer","description":"Payroll period for this person. Values: 1=year, 2=month, 3=week, 4=day. The person's Gehalt_ct must be the gross amount for the same period. Some country UIs expose only a subset: AT/CH commonly annual or monthly; DE/US and defaults commonly annual, monthly, or weekly."},"Stjahr":{"type":"integer","description":"Tax year."},"Faktor":{"type":"number","description":"Germany-only tax factor used for tax class IV/factor workflows."},"Geburtsjahr":{"type":"integer","description":"Birth year."},"Versorgungsbezuege":{"type":"integer","description":"Germany-only pension or civil-service pension payments in minor units."},"Erster_mntl_Versorgungsbezug":{"type":"integer","description":"Germany-only first monthly pension payment in minor units."},"Versorgungsbezuege_Sonderzahlung":{"type":"integer","description":"Germany-only special pension payment in minor units."},"Erstes_Jahr_Versorgungsbezug":{"type":"integer","description":"Germany-only first tax year of pension receipt."},"Monate_Versorgungsbezuege":{"type":"integer","description":"Germany-only number of months with pension payments."},"Freibetrag_Sonst":{"type":"integer","description":"Allowance on one-off payments in minor units."},"Hinzubetrag":{"type":"integer","description":"Additional amount on one-off payments in minor units."},"Sonstige_Bezuege":{"type":"integer","description":"One-off payments or bonus income in minor units. Country meanings include DE other remuneration, UK/US/CA/IE supplemental income, AU bonus pay, and AT/CH special salary or bonus handling where supported."},"Sonstige_Entschaedigung":{"type":"integer","description":"Compensation payments in minor units."},"Sonstige_Sterbe":{"type":"integer","description":"Death benefit / survivor payment in minor units."},"de_payroll_preset":{"type":"string","enum":["DE_STANDARD_EMPLOYEE_STATUTORY","DE_PRIVATE_HEALTH_INSURANCE","DE_PENSION_EXEMPT","DE_PENSION_EXEMPT_PRIVATE_HEALTH"],"default":"DE_STANDARD_EMPLOYEE_STATUTORY","oneOf":[{"const":"DE_STANDARD_EMPLOYEE_STATUTORY","title":"Germany standard employee with statutory pension and statutory health","description":"Use this for the normal German employee case. The adapter maps it to Obolus backend flags gesetzliche_RV=0, gesetzlicheKvPvStatus=0, KV_Art=0, AN_Beitraege_PKV=0."},{"const":"DE_PRIVATE_HEALTH_INSURANCE","title":"Germany employee with private health insurance","description":"Use this only when the user explicitly has PKV. The adapter keeps statutory pension/unemployment enabled and maps health/care to private. Provide de_private_health_employee_contribution_ct."},{"const":"DE_PENSION_EXEMPT","title":"Germany pension/unemployment exempt with statutory health","description":"Use this for civil servants, self-employed, or other no-statutory-pension cases that still use statutory health/care handling."},{"const":"DE_PENSION_EXEMPT_PRIVATE_HEALTH","title":"Germany pension/unemployment exempt with private health","description":"Use this only for exempt PKV cases. Provide de_private_health_employee_contribution_ct."}],"description":"Preferred ChatGPT-facing German payroll preset. Use this instead of raw Obolus flags. For 'Germany, normal employee, tax class I' choose DE_STANDARD_EMPLOYEE_STATUTORY."},"de_statutory_pension_and_unemployment":{"type":"boolean","default":true,"description":"Semantic Germany-only adapter field. true means statutory pension and unemployment insurance apply. The adapter maps true to Obolus gesetzliche_RV=0 and false to gesetzliche_RV=1. Use false only for civil servants, self-employed, or explicitly pension-exempt cases."},"de_statutory_health_and_care":{"type":"boolean","default":true,"description":"Semantic Germany-only adapter field. true means statutory health and long-term care insurance apply. The adapter maps true to Obolus gesetzlicheKvPvStatus=0 and KV_Art=0; false means private health insurance and requires de_private_health_employee_contribution_ct."},"de_health_extra_contribution_percent":{"type":"number","minimum":0,"maximum":10,"examples":[1.7,2.5],"description":"Preferred MCP/ChatGPT alias for the German statutory health insurance Zusatzbeitrag. Use the literal percent value, for example 2.5 for 2.5%. The server normalizes this to legacy KVZ. Do not use basis points, tenths, cents, 25, 250, or any minor-unit encoding."},"de_private_health_employee_contribution_ct":{"type":"integer","minimum":0,"description":"Semantic Germany-only adapter field for private health insurance employee contribution in minor units for the selected payroll period. Required when de_statutory_health_and_care=false or a private-health preset is selected. Leave omitted or 0 for statutory GKV/PV."},"Freibetrag_AG":{"type":"integer","description":"Employer/payroll allowance or additional withholding amount in minor units. Country meanings include DE employer wage-tax feature, AT allowance notice, US/CA additional withholding, and UK payroll allowance handling."},"Hinzubetrag_AG":{"type":"integer","description":"Employer surcharge in minor units."},"Hat_Studienkredit":{"type":"integer","description":"Student loan repayment flag. Relevant for UK student loan, AU HELP/HECS, and IE student-loan-style deductions where modeled."},"Stfr_vermgsbteil":{"type":"integer","description":"Tax-free capital-forming benefit share in minor units."},"Entschädigungen_vermgsbteil":{"type":"integer","description":"Capital-forming compensation share in minor units."},"Sonstige_Bezuege_Versorgungsbezug":{"type":"integer","description":"One-off payments tied to pension benefits in minor units."},"KinderPVA":{"type":"integer","minimum":0,"default":0,"description":"Number of children relevant for German long-term care insurance. Children can reduce the care insurance rate; use 0 when no child discount applies."},"Kirche":{"type":"integer","description":"Church tax membership flag. Use 1 when church tax applies and 0 when it does not."},"Kinderfreibetrag":{"type":"number","default":0,"description":"Child allowance, dependent count, or child-credit factor for this person. DE uses child allowance shares such as 0, 0.5, 1, or 2. AT uses child count for Familienbonus workflows. CH uses child deduction count. US uses dependent credits count. CA/UK/AU/IE use dependent or child context where supported, often outside direct payroll tax."}},"required":["Land","Gehalt_ct","Steuerklasse","Geburtsjahr"]}}},"examples":[{"country":"DE","tax_year":2026,"gross_salary":{"amount":60000,"currency":"EUR","period":"annual"},"location":{"federal_state":"BE"},"employee_type":"standard_statutory_employee","payroll_preset":"DE_STANDARD_EMPLOYEE_STATUTORY","tax":{"tax_class":1,"church_tax":false,"child_allowance_factor":0},"social_security":{"pension_insurance":"statutory","unemployment_insurance":"statutory","health_insurance":"statutory","health_additional_contribution_percent":2.9,"long_term_care_insurance":"statutory","children_for_care_insurance":0}},{"Land":"DE","Stjahr":2026,"Currency":"EUR","LZZ":2,"Modus":1,"Faktor":1,"KinderFRB":0,"KinderPVA":0,"Kindergeld":0,"Personen":[{"Land":"DE","Gehalt_ct":583333,"Gehalt_ct_ohne_Sonst":583333,"Steuerklasse":1,"Bundesland":"Berlin","Lohnzahlungszeitraum":2,"Stjahr":2026,"Faktor":1,"Geburtsjahr":1988,"de_payroll_preset":"DE_STANDARD_EMPLOYEE_STATUTORY","de_statutory_pension_and_unemployment":true,"de_statutory_health_and_care":true,"de_health_extra_contribution_percent":2.5,"Kirche":0,"KinderPVA":0,"Kinderfreibetrag":0}]},{"Land":"DE","Stjahr":2026,"Currency":"EUR","LZZ":1,"Modus":1,"Faktor":1,"KinderFRB":0,"KinderPVA":0,"Kindergeld":0,"Personen":[{"Land":"DE","Gehalt_ct":7000000,"Gehalt_ct_ohne_Sonst":7000000,"Steuerklasse":1,"Bundesland":"Berlin","Lohnzahlungszeitraum":1,"Stjahr":2026,"Faktor":1,"Geburtsjahr":1988,"de_payroll_preset":"DE_STANDARD_EMPLOYEE_STATUTORY","de_statutory_pension_and_unemployment":true,"de_statutory_health_and_care":true,"de_health_extra_contribution_percent":2.5,"Kirche":0,"KinderPVA":0,"Kinderfreibetrag":0}]},{"Land":"DE","Stjahr":2026,"Currency":"EUR","LZZ":2,"Modus":1,"Faktor":1,"KinderFRB":0,"KinderPVA":0,"Kindergeld":0,"Personen":[{"Land":"DE","Gehalt_ct":583333,"Gehalt_ct_ohne_Sonst":583333,"Steuerklasse":1,"Bundesland":"Berlin","Lohnzahlungszeitraum":2,"Stjahr":2026,"Faktor":1,"Geburtsjahr":1988,"de_payroll_preset":"DE_PRIVATE_HEALTH_INSURANCE","de_statutory_pension_and_unemployment":true,"de_statutory_health_and_care":false,"de_health_extra_contribution_percent":0,"de_private_health_employee_contribution_ct":45000,"Kirche":0,"KinderPVA":0,"Kinderfreibetrag":0}]},{"Land":"AT","Stjahr":2026,"Currency":"EUR","LZZ":2,"Modus":1,"Faktor":1,"KinderFRB":0,"KinderPVA":0,"Kindergeld":0,"Personen":[{"Land":"AT","Gehalt_ct":500000,"Gehalt_ct_ohne_Sonst":500000,"Steuerklasse":1,"Bundesland":"Wien","Lohnzahlungszeitraum":2,"Stjahr":2026,"Faktor":1,"Geburtsjahr":1988,"PreTax_Deduction_ct":0,"pendlerEuro":0,"Pendler_KM":0,"Pendler_Zumutbar":0,"Pendler_Tage":0,"Kinderfreibetrag":0}]},{"Land":"CH","Stjahr":2026,"Currency":"CHF","LZZ":1,"Modus":1,"Faktor":1,"KinderFRB":0,"KinderPVA":0,"Kindergeld":0,"Personen":[{"Land":"CH","Gehalt_ct":10000000,"Gehalt_ct_ohne_Sonst":10000000,"Steuerklasse":1,"Bundesland":"Zürich","Lohnzahlungszeitraum":1,"Stjahr":2026,"Faktor":1,"Geburtsjahr":1988,"PreTax_Deduction_ct":0,"Kinderfreibetrag":0}]},{"Land":"US","Stjahr":2026,"Currency":"USD","LZZ":1,"Modus":1,"Faktor":1,"KinderFRB":0,"KinderPVA":0,"Kindergeld":0,"Personen":[{"Land":"US","Gehalt_ct":9000000,"Gehalt_ct_ohne_Sonst":9000000,"Steuerklasse":1,"Bundesland":"California","Lohnzahlungszeitraum":1,"Stjahr":2026,"Faktor":1,"Geburtsjahr":1988,"PreTax_Deduction_ct":0,"Sonstige_Bezuege":0,"Freibetrag_AG":0,"Kinderfreibetrag":0}]},{"Land":"UK","Stjahr":2026,"Currency":"GBP","LZZ":1,"Modus":1,"Faktor":1,"KinderFRB":0,"KinderPVA":0,"Kindergeld":0,"Personen":[{"Land":"UK","Gehalt_ct":6000000,"Gehalt_ct_ohne_Sonst":6000000,"Steuerklasse":1,"Bundesland":"England","Lohnzahlungszeitraum":1,"Stjahr":2026,"Faktor":1,"Geburtsjahr":1988,"PreTax_Deduction_ct":0,"Hat_Studienkredit":0,"Sonstige_Bezuege":0,"Freibetrag_AG":0,"Kinderfreibetrag":0}]},{"Land":"IE","Stjahr":2026,"Currency":"EUR","LZZ":1,"Modus":1,"Faktor":1,"KinderFRB":0,"KinderPVA":0,"Kindergeld":0,"Personen":[{"Land":"IE","Gehalt_ct":7000000,"Gehalt_ct_ohne_Sonst":7000000,"Steuerklasse":1,"Lohnzahlungszeitraum":1,"Stjahr":2026,"Faktor":1,"Geburtsjahr":1988,"PreTax_Deduction_ct":0,"Hat_Studienkredit":0,"Sonstige_Bezuege":0,"Kinderfreibetrag":0}]},{"Land":"CA","Stjahr":2026,"Currency":"CAD","LZZ":1,"Modus":1,"Faktor":1,"KinderFRB":0,"KinderPVA":0,"Kindergeld":0,"Personen":[{"Land":"CA","Gehalt_ct":8500000,"Gehalt_ct_ohne_Sonst":8500000,"Steuerklasse":1,"Bundesland":"Ontario","Lohnzahlungszeitraum":1,"Stjahr":2026,"Faktor":1,"Geburtsjahr":1988,"PreTax_Deduction_ct":0,"Sonstige_Bezuege":0,"Freibetrag_AG":0,"Kinderfreibetrag":0}]},{"Land":"AU","Stjahr":2026,"Currency":"AUD","LZZ":1,"Modus":1,"Faktor":1,"KinderFRB":0,"KinderPVA":0,"Kindergeld":0,"Personen":[{"Land":"AU","Gehalt_ct":9000000,"Gehalt_ct_ohne_Sonst":9000000,"Steuerklasse":1,"Lohnzahlungszeitraum":1,"Stjahr":2026,"Faktor":1,"Geburtsjahr":1988,"PreTax_Deduction_ct":0,"Hat_Studienkredit":0,"Sonstige_Bezuege":0,"Kinderfreibetrag":0}]}]},"output_schema":{"type":"object","additionalProperties":true,"description":"Output schema for one-country detailed Obolus payroll calculations. Interpret person1, person2, and gesamt with the original request Land; stable field names such as ST, LSTLZZ, RSV, KSV, PSV, ASV, and VTL have country-specific meanings rather than one global meaning. Monetary amounts are minor units. Output country-specific usage: DE outputs keep German payroll meanings: ST/LSTLZZ are wage tax, SOLZLZZ is solidarity surcharge, KST is church tax, and RSV/KSV/PSV/ASV are statutory pension, health, care, and unemployment insurance. AT outputs emphasize Austrian wage tax plus social insurance; BK, STS, STX, and NETX can represent annual or special-payment handling such as 13th/14th salary paths. CH outputs can represent federal, cantonal, municipal, withholding, AHV/IV/EO, ALV, accident, sickness, and pension-fund payroll deductions; private KVG/LAMal health bills are not modeled as payroll health insurance. US outputs map stable Obolus fields to federal/state income tax, Social Security/OASDI, Medicare, additional withholding, supplemental income, and pre-tax retirement/HSA-style deduction context. UK outputs map stable Obolus fields to PAYE income tax, National Insurance, student loan where enabled, salary sacrifice or pension, and regional/tax-code context. IE outputs map stable Obolus fields to PAYE, USC, PRSI, pension contribution, tax credits, and student-loan-style deductions where modeled. CA outputs map stable Obolus fields to federal/provincial tax, CPP/QPP, EI, RRSP or pension deductions, province-specific credits, and additional withholding. AU outputs map stable Obolus fields to PAYG tax, Medicare Levy, HELP/HECS where enabled, voluntary super salary sacrifice, bonus pay, and employer super information.","properties":{"person1":{"type":"object","additionalProperties":true,"description":"Payroll result for the first person. Interpret stable output codes with the original request Land and the output country-specific usage notes.","properties":{"info":{"type":"string","description":"Backend note, warning, or informational message for the calculation."},"BK":{"type":"integer","description":"Country-polymorphic special payment, bonus-related gross component, or total package component in minor units. AT commonly represents 13th/14th salary handling; AU can represent total package including super."},"BKS":{"type":"integer","description":"Country-polymorphic tax or contribution value related to special payment handling, in minor units."},"SOLZLZZ":{"type":"integer","description":"Country-specific payroll-period surcharge or informational deduction in minor units. DE=solidarity surcharge, CH=municipal tax, CA=tax withholding, IE=student loan where modeled."},"SOLZS":{"type":"integer","description":"Solidarity surcharge or country-specific equivalent on special payments, in minor units. Interpret by original request Land."},"STS":{"type":"integer","description":"Country-polymorphic social contribution or country-specific charge on special payments, in minor units. Interpret by original request Land."},"LSTLZZ":{"type":"integer","description":"Country-specific period tax or deduction in minor units. Interpret by original request Land: DE/AT=period wage tax, CH=cantonal tax, US/CA=federal tax, UK=student loan, AU=HELP/HECS repayment, IE=USC."},"KST":{"type":"integer","description":"Church tax or country-specific religious levy deducted from payroll, in minor units. Mainly relevant for DE and CH; most other systems have no payroll church tax."},"ST":{"type":"integer","description":"Primary payroll tax in minor units. Interpret by original request Land: DE/AT/UK=income tax, CH=federal or withholding tax component, US=federal plus state or state component depending response mapping, CA=provincial component, AU=PAYG tax, IE=PAYE."},"STJ":{"type":"integer","description":"Annualized income tax value after child allowance or country-specific adjustment logic, in minor units. Interpret by original request Land."},"ZVE":{"type":"number","description":"Taxable income used as the basis for the wage, payroll, or income tax calculation, in minor units. Interpret by original request Land."},"ZVEJ":{"type":"number","description":"Taxable income after child allowances or country-specific adjustment logic, in minor units. Interpret by original request Land."},"KFBP":{"type":"string","description":"Child allowance, child benefit, tax-credit, or favorable-test information returned by the calculator. Interpret by original request Land."},"RSV":{"type":"integer","description":"Employee pension or retirement contribution for the selected payroll period in minor units. DE/AT=statutory pension, CH=AHV/IV/EO and possibly pension fund, US=Social Security/OASDI, CA=CPP/QPP, UK=workplace or state-pension-related contribution context, IE=pension/PRSA or PRSI pension context, AU=voluntary super contribution."},"KSV":{"type":"integer","description":"Country-specific health, Medicare, USC, or equivalent contribution for the selected payroll period in minor units. DE/AT=statutory health contribution, CH=occupational accident/sickness or pillar-related payroll deduction rather than private KVG/LAMal bill, US=Medicare, AU=Medicare Levy, IE=USC, CA=province-related health or employment-insurance context depending backend mapping."},"PSV":{"type":"integer","description":"Employee long-term care insurance or country-specific equivalent contribution for the selected payroll period in minor units. DE=nursing care insurance; CH can represent NBU/KTG-style accident/sickness context. Usually unused in other tax systems."},"ASV":{"type":"integer","description":"Employee unemployment insurance or country-specific social contribution for the selected payroll period in minor units. DE/AT=unemployment/rest social insurance, CH=ALV/NBU, UK=National Insurance, IE=PRSI, CA=Employment Insurance or RRSP employee context depending response mapping, US=state disability/unemployment-style employee item where applicable, AU is normally unused because unemployment benefits are tax-funded."},"NET":{"type":"integer","description":"Net pay remaining after country-specific taxes and payroll deductions for the selected payroll period, in minor units."},"STX":{"type":"integer","description":"Income tax due after annual tax equalization, joint assessment, or country-specific compensation logic, in minor units. Interpret by original request Land."},"STXJ":{"type":"integer","description":"Income tax after annual equalization including child allowance, child benefit, tax credit, or country-specific dependent effects, in minor units."},"NETX":{"type":"integer","description":"Net pay after annual tax equalization or country-specific compensation logic, excluding child benefit effects, in minor units. Interpret by original request Land."},"NETXJ":{"type":"integer","description":"Actual annual available net income after country-specific annual adjustments, in minor units. Interpret by original request Land."},"GWV":{"type":"integer","description":"Taxable benefit or monetary advantage included in the calculation, in minor units. Country meanings include in-kind benefit, benefit in kind, taxable benefit, or imputed income."},"VTL":{"type":"integer","description":"Forecast, informational, or country-specific adjustment value in minor units. DE=tax refund/forecast info, AT=tax on 13th/14th salary, CH=withholding-tax info, US=401k/IRA info, UK=student loan, CA=RRSP/federal credit info, AU=employer superannuation, IE=USC or tax-credit info."},"Brutto":{"type":"integer","description":"Gross earnings used in the calculation, before country-specific taxes and payroll deductions, in minor units."}}},"person2":{"type":"object","additionalProperties":true,"description":"Payroll result for the second person. Values are zero or empty when the calculation mode uses only one person. Interpret stable output codes with the original request Land.","properties":{"info":{"type":"string","description":"Backend note, warning, or informational message for the calculation."},"BK":{"type":"integer","description":"Country-polymorphic special payment, bonus-related gross component, or total package component in minor units. AT commonly represents 13th/14th salary handling; AU can represent total package including super."},"BKS":{"type":"integer","description":"Country-polymorphic tax or contribution value related to special payment handling, in minor units."},"SOLZLZZ":{"type":"integer","description":"Country-specific payroll-period surcharge or informational deduction in minor units. DE=solidarity surcharge, CH=municipal tax, CA=tax withholding, IE=student loan where modeled."},"SOLZS":{"type":"integer","description":"Solidarity surcharge or country-specific equivalent on special payments, in minor units. Interpret by original request Land."},"STS":{"type":"integer","description":"Country-polymorphic social contribution or country-specific charge on special payments, in minor units. Interpret by original request Land."},"LSTLZZ":{"type":"integer","description":"Country-specific period tax or deduction in minor units. Interpret by original request Land: DE/AT=period wage tax, CH=cantonal tax, US/CA=federal tax, UK=student loan, AU=HELP/HECS repayment, IE=USC."},"KST":{"type":"integer","description":"Church tax or country-specific religious levy deducted from payroll, in minor units. Mainly relevant for DE and CH; most other systems have no payroll church tax."},"ST":{"type":"integer","description":"Primary payroll tax in minor units. Interpret by original request Land: DE/AT/UK=income tax, CH=federal or withholding tax component, US=federal plus state or state component depending response mapping, CA=provincial component, AU=PAYG tax, IE=PAYE."},"STJ":{"type":"integer","description":"Annualized income tax value after child allowance or country-specific adjustment logic, in minor units. Interpret by original request Land."},"ZVE":{"type":"number","description":"Taxable income used as the basis for the wage, payroll, or income tax calculation, in minor units. Interpret by original request Land."},"ZVEJ":{"type":"number","description":"Taxable income after child allowances or country-specific adjustment logic, in minor units. Interpret by original request Land."},"KFBP":{"type":"string","description":"Child allowance, child benefit, tax-credit, or favorable-test information returned by the calculator. Interpret by original request Land."},"RSV":{"type":"integer","description":"Employee pension or retirement contribution for the selected payroll period in minor units. DE/AT=statutory pension, CH=AHV/IV/EO and possibly pension fund, US=Social Security/OASDI, CA=CPP/QPP, UK=workplace or state-pension-related contribution context, IE=pension/PRSA or PRSI pension context, AU=voluntary super contribution."},"KSV":{"type":"integer","description":"Country-specific health, Medicare, USC, or equivalent contribution for the selected payroll period in minor units. DE/AT=statutory health contribution, CH=occupational accident/sickness or pillar-related payroll deduction rather than private KVG/LAMal bill, US=Medicare, AU=Medicare Levy, IE=USC, CA=province-related health or employment-insurance context depending backend mapping."},"PSV":{"type":"integer","description":"Employee long-term care insurance or country-specific equivalent contribution for the selected payroll period in minor units. DE=nursing care insurance; CH can represent NBU/KTG-style accident/sickness context. Usually unused in other tax systems."},"ASV":{"type":"integer","description":"Employee unemployment insurance or country-specific social contribution for the selected payroll period in minor units. DE/AT=unemployment/rest social insurance, CH=ALV/NBU, UK=National Insurance, IE=PRSI, CA=Employment Insurance or RRSP employee context depending response mapping, US=state disability/unemployment-style employee item where applicable, AU is normally unused because unemployment benefits are tax-funded."},"NET":{"type":"integer","description":"Net pay remaining after country-specific taxes and payroll deductions for the selected payroll period, in minor units."},"STX":{"type":"integer","description":"Income tax due after annual tax equalization, joint assessment, or country-specific compensation logic, in minor units. Interpret by original request Land."},"STXJ":{"type":"integer","description":"Income tax after annual equalization including child allowance, child benefit, tax credit, or country-specific dependent effects, in minor units."},"NETX":{"type":"integer","description":"Net pay after annual tax equalization or country-specific compensation logic, excluding child benefit effects, in minor units. Interpret by original request Land."},"NETXJ":{"type":"integer","description":"Actual annual available net income after country-specific annual adjustments, in minor units. Interpret by original request Land."},"GWV":{"type":"integer","description":"Taxable benefit or monetary advantage included in the calculation, in minor units. Country meanings include in-kind benefit, benefit in kind, taxable benefit, or imputed income."},"VTL":{"type":"integer","description":"Forecast, informational, or country-specific adjustment value in minor units. DE=tax refund/forecast info, AT=tax on 13th/14th salary, CH=withholding-tax info, US=401k/IRA info, UK=student loan, CA=RRSP/federal credit info, AU=employer superannuation, IE=USC or tax-credit info."},"Brutto":{"type":"integer","description":"Gross earnings used in the calculation, before country-specific taxes and payroll deductions, in minor units."}}},"gesamt":{"type":"object","additionalProperties":true,"description":"Combined payroll result across all persons in the calculation. Uses the same country-specific output-code meanings as person1 and person2.","properties":{"info":{"type":"string","description":"Backend note, warning, or informational message for the calculation."},"BK":{"type":"integer","description":"Country-polymorphic special payment, bonus-related gross component, or total package component in minor units. AT commonly represents 13th/14th salary handling; AU can represent total package including super."},"BKS":{"type":"integer","description":"Country-polymorphic tax or contribution value related to special payment handling, in minor units."},"SOLZLZZ":{"type":"integer","description":"Country-specific payroll-period surcharge or informational deduction in minor units. DE=solidarity surcharge, CH=municipal tax, CA=tax withholding, IE=student loan where modeled."},"SOLZS":{"type":"integer","description":"Solidarity surcharge or country-specific equivalent on special payments, in minor units. Interpret by original request Land."},"STS":{"type":"integer","description":"Country-polymorphic social contribution or country-specific charge on special payments, in minor units. Interpret by original request Land."},"LSTLZZ":{"type":"integer","description":"Country-specific period tax or deduction in minor units. Interpret by original request Land: DE/AT=period wage tax, CH=cantonal tax, US/CA=federal tax, UK=student loan, AU=HELP/HECS repayment, IE=USC."},"KST":{"type":"integer","description":"Church tax or country-specific religious levy deducted from payroll, in minor units. Mainly relevant for DE and CH; most other systems have no payroll church tax."},"ST":{"type":"integer","description":"Primary payroll tax in minor units. Interpret by original request Land: DE/AT/UK=income tax, CH=federal or withholding tax component, US=federal plus state or state component depending response mapping, CA=provincial component, AU=PAYG tax, IE=PAYE."},"STJ":{"type":"integer","description":"Annualized income tax value after child allowance or country-specific adjustment logic, in minor units. Interpret by original request Land."},"ZVE":{"type":"number","description":"Taxable income used as the basis for the wage, payroll, or income tax calculation, in minor units. Interpret by original request Land."},"ZVEJ":{"type":"number","description":"Taxable income after child allowances or country-specific adjustment logic, in minor units. Interpret by original request Land."},"KFBP":{"type":"string","description":"Child allowance, child benefit, tax-credit, or favorable-test information returned by the calculator. Interpret by original request Land."},"RSV":{"type":"integer","description":"Employee pension or retirement contribution for the selected payroll period in minor units. DE/AT=statutory pension, CH=AHV/IV/EO and possibly pension fund, US=Social Security/OASDI, CA=CPP/QPP, UK=workplace or state-pension-related contribution context, IE=pension/PRSA or PRSI pension context, AU=voluntary super contribution."},"KSV":{"type":"integer","description":"Country-specific health, Medicare, USC, or equivalent contribution for the selected payroll period in minor units. DE/AT=statutory health contribution, CH=occupational accident/sickness or pillar-related payroll deduction rather than private KVG/LAMal bill, US=Medicare, AU=Medicare Levy, IE=USC, CA=province-related health or employment-insurance context depending backend mapping."},"PSV":{"type":"integer","description":"Employee long-term care insurance or country-specific equivalent contribution for the selected payroll period in minor units. DE=nursing care insurance; CH can represent NBU/KTG-style accident/sickness context. Usually unused in other tax systems."},"ASV":{"type":"integer","description":"Employee unemployment insurance or country-specific social contribution for the selected payroll period in minor units. DE/AT=unemployment/rest social insurance, CH=ALV/NBU, UK=National Insurance, IE=PRSI, CA=Employment Insurance or RRSP employee context depending response mapping, US=state disability/unemployment-style employee item where applicable, AU is normally unused because unemployment benefits are tax-funded."},"NET":{"type":"integer","description":"Net pay remaining after country-specific taxes and payroll deductions for the selected payroll period, in minor units."},"STX":{"type":"integer","description":"Income tax due after annual tax equalization, joint assessment, or country-specific compensation logic, in minor units. Interpret by original request Land."},"STXJ":{"type":"integer","description":"Income tax after annual equalization including child allowance, child benefit, tax credit, or country-specific dependent effects, in minor units."},"NETX":{"type":"integer","description":"Net pay after annual tax equalization or country-specific compensation logic, excluding child benefit effects, in minor units. Interpret by original request Land."},"NETXJ":{"type":"integer","description":"Actual annual available net income after country-specific annual adjustments, in minor units. Interpret by original request Land."},"GWV":{"type":"integer","description":"Taxable benefit or monetary advantage included in the calculation, in minor units. Country meanings include in-kind benefit, benefit in kind, taxable benefit, or imputed income."},"VTL":{"type":"integer","description":"Forecast, informational, or country-specific adjustment value in minor units. DE=tax refund/forecast info, AT=tax on 13th/14th salary, CH=withholding-tax info, US=401k/IRA info, UK=student loan, CA=RRSP/federal credit info, AU=employer superannuation, IE=USC or tax-credit info."},"Brutto":{"type":"integer","description":"Gross earnings used in the calculation, before country-specific taxes and payroll deductions, in minor units."}}},"faktor":{"type":"number","description":"Tax factor used for German tax class IV factor workflows when applicable."},"source_url":{"type":"string","description":"Canonical Obolus URL for the matching interactive calculator."},"visual_report":{"type":"string","description":"Deep link to the interactive report or calculator view."},"localized_cta":{"type":"object","additionalProperties":false,"properties":{"de":{"type":"string","description":"German CTA for the visual report link."},"en":{"type":"string","description":"English CTA for the visual report link."}},"required":["de","en"],"description":"Localized call-to-action labels for opening the visual Obolus report link."},"assumptions":{"type":"object","additionalProperties":true,"description":"Normalized user-facing assumptions used for the payroll calculation, including country, salary period, location, tax class, church tax, and German social-security choices. Use this to explain what the calculation assumed without exposing raw payroll-engine flags."},"warnings":{"type":"array","description":"Non-blocking warnings about suspicious inputs, such as annual gross sent with monthly LZZ, scaled German Zusatzbeitrag values, or raw German insurance combinations that may be intentional for non-standard cases.","items":{"type":"string","description":"Human-readable warning message."}}},"required":["source_url","visual_report","localized_cta"]}},"taxcompare":{"description":"Use this as the default tool whenever the user asks to compare salary, annual net income, tax burden, social contributions, or effective burden across multiple countries. Do not use berechne for multi-country comparisons unless the user asks for detailed country-specific payroll. If the user asks for one salary across multiple countries, always use taxcompare first. Use this endpoint for multi-country salary/tax comparisons. Select taxcompare when the user provides one salary or income amount, two or more countries, and wants tax, net salary, deductions, take-home pay, ranking, or 'where do I keep more money' results. Typical trigger phrases include: calculate tax for 50k in Germany, Ireland, USA, Canada; compare net salary across these countries; where do I pay less tax on EUR 80k; what is take-home pay in X, Y, Z; rank these countries by net income; how much do I keep after tax in Germany vs Ireland. Routing rule: if countries.length >= 2 and the same salary/income is used, use taxcompare. If countries.length === 1, use berechne. If the user provides detailed payroll assumptions such as tax class, province/state, health insurance, children, church tax, pension exemption, deductions, or benefits, use berechne unless taxcompare supports those fields explicitly. Do not use berechne repeatedly for simple multi-country comparisons unless taxcompare cannot accept the required inputs. Use shared_gross when the user wants to compare the same salary offer across countries. Prefer salary_ct in minor units, such as 5000000 for EUR 50,000. annual_gross is a backward-compatible annual major-unit alias, such as 50000 for EUR 50,000. Use local_median_gross when the user wants a local-market benchmark. In this mode Obolus fans out to country-specific editorial median gross benchmarks; annual_gross is optional and ignored when omitted. taxcompare is annual and country-level. It is not the right tool for detailed payroll inputs such as German KVZ, tax class IV factor, private health insurance, commuter allowance, or monthly gross; use berechne for that. countries accepts DE, AT, CH, US, UK, IE, CA, and AU. currency accepts EUR, USD, CHF, CAD, AUD, GBP and lower-case equivalents; results normalize currency codes to lower-case. joint_assessment and children are broad comparison assumptions. Country-specific filing details are simplified for comparability; for a precise single-country case, call berechne. Results are annual major-currency estimates. net is annual take-home pay; tax is annual tax burden; social_contributions are annual employee payroll/social deductions or the country-specific equivalent; effective_rate is a percentage-point burden value such as 37.7 for 37.7%. Country meanings differ: DE/AT emphasize income tax plus statutory social contributions, CH can include withholding and payroll social deductions but not private KVG/LAMal health bills, US includes federal/state and OASDI/Medicare-style items, UK includes PAYE/National Insurance, IE includes PAYE/USC/PRSI, CA includes federal/provincial tax plus CPP/QPP/EI, and AU includes PAYG/Medicare/super-related outputs.","annotations":{"readOnlyHint":true,"destructiveHint":false,"openWorldHint":false},"endpoint":{"url":"/api/taxcompare","method":"POST"},"access_control":{"api_key_supported":true,"require_key_env":"PUBLIC_API_REQUIRE_KEY_TAXCOMPARE","restricted_fields_env":"PUBLIC_API_RESTRICTED_FIELDS_TAXCOMPARE"},"input_schema":{"type":"object","additionalProperties":false,"description":"Plain object input schema for Obolus country-to-country salary comparisons. If the user asks for one salary across multiple countries, always use taxcompare first. Use this tool for requests such as \"compare EUR 50,000 salary in USA, Ireland, Germany, Canada\". Prefer salary_ct=5000000, currency=\"EUR\", tax_year=2026, countries=[\"US\",\"IE\",\"DE\",\"CA\"], period=\"annual\", gross_mode=\"shared_gross\". If the user asks for one salary across multiple countries, always use taxcompare first. Use this endpoint for multi-country salary/tax comparisons. Select taxcompare when the user provides one salary or income amount, two or more countries, and wants tax, net salary, deductions, take-home pay, ranking, or 'where do I keep more money' results. Typical trigger phrases include: calculate tax for 50k in Germany, Ireland, USA, Canada; compare net salary across these countries; where do I pay less tax on EUR 80k; what is take-home pay in X, Y, Z; rank these countries by net income; how much do I keep after tax in Germany vs Ireland. Routing rule: if countries.length >= 2 and the same salary/income is used, use taxcompare. If countries.length === 1, use berechne. If the user provides detailed payroll assumptions such as tax class, province/state, health insurance, children, church tax, pension exemption, deductions, or benefits, use berechne unless taxcompare supports those fields explicitly. Do not use berechne repeatedly for simple multi-country comparisons unless taxcompare cannot accept the required inputs. Use shared_gross when the user wants to compare the same salary offer across countries. Prefer salary_ct in minor units, such as 5000000 for EUR 50,000. annual_gross is a backward-compatible annual major-unit alias, such as 50000 for EUR 50,000. Use local_median_gross when the user wants a local-market benchmark. In this mode Obolus fans out to country-specific editorial median gross benchmarks; annual_gross is optional and ignored when omitted. taxcompare is annual and country-level. It is not the right tool for detailed payroll inputs such as German KVZ, tax class IV factor, private health insurance, commuter allowance, or monthly gross; use berechne for that. countries accepts DE, AT, CH, US, UK, IE, CA, and AU. currency accepts EUR, USD, CHF, CAD, AUD, GBP and lower-case equivalents; results normalize currency codes to lower-case. joint_assessment and children are broad comparison assumptions. Country-specific filing details are simplified for comparability; for a precise single-country case, call berechne. Results are annual major-currency estimates. net is annual take-home pay; tax is annual tax burden; social_contributions are annual employee payroll/social deductions or the country-specific equivalent; effective_rate is a percentage-point burden value such as 37.7 for 37.7%. Country meanings differ: DE/AT emphasize income tax plus statutory social contributions, CH can include withholding and payroll social deductions but not private KVG/LAMal health bills, US includes federal/state and OASDI/Medicare-style items, UK includes PAYE/National Insurance, IE includes PAYE/USC/PRSI, CA includes federal/provincial tax plus CPP/QPP/EI, and AU includes PAYG/Medicare/super-related outputs.","properties":{"salary_ct":{"type":"integer","minimum":0,"description":"Preferred salary input for ChatGPT/MCP calls. Salary in minor units for the selected period, for example 5000000 for EUR 50,000. With period=annual this is annual salary; with period=monthly this is monthly salary and Obolus annualizes it for the comparison. Required for shared_gross mode unless annual_gross is provided as a legacy alias."},"annual_gross":{"type":"number","description":"Backward-compatible annual gross salary alias in major currency units, not cents. Prefer salary_ct. Example: 50000 means 50,000 in the selected currency. Required for shared_gross mode only when salary_ct is not provided; optional and ignored when omitted for local_median_gross."},"gross_mode":{"type":"string","enum":["shared_gross","local_median_gross"],"default":"shared_gross","description":"Comparison basis. Use shared_gross for the same user-provided annual gross across all countries. Use local_median_gross for country-specific editorial median gross benchmarks. Defaults to shared_gross when omitted."},"period":{"type":"string","enum":["annual","monthly"],"default":"annual","description":"Period for salary_ct. Use annual when salary_ct is the annual gross salary. Use monthly when salary_ct is one monthly gross salary; taxcompare annualizes it before comparing countries. annual_gross is always annual and ignores this field."},"person_type":{"type":"string","enum":["single","married"],"default":"single","description":"Broad household assumption for comparison. single maps to joint_assessment=false; married maps to joint_assessment=true unless joint_assessment is provided explicitly. For precise country-specific filing details, use berechne."},"joint_assessment":{"type":"boolean","default":false,"description":"Broad joint filing / joint assessment assumption for comparable country-level estimates. For precise country-specific filing details, use berechne."},"children":{"type":"integer","minimum":0,"default":0,"description":"Number of children or dependents used as a broad comparison assumption. Country-specific child allowance and credit rules are simplified for comparability."},"tax_year":{"anyOf":[{"type":"string"},{"type":"integer"}],"description":"Tax year, for example 2026. The same tax year is applied to every selected country."},"countries":{"type":"array","minItems":1,"items":{"type":"string","enum":["DE","AT","US","CH","CA","AU","UK","IE"]},"description":"List of country tax systems to compare. Use at least two countries for a comparison. Supported values: DE, AT, CH, US, UK, IE, CA, AU."},"currency":{"type":"string","enum":["eur","usd","chf","cad","aud","gbp","EUR","USD","CHF","CAD","AUD","GBP"],"description":"Input and output currency: EUR, USD, CHF, CAD, AUD, GBP, or lower-case equivalents. Results normalize currency codes to lower-case. Unlike berechne, taxcompare prefers salary_ct for salary input and returns major currency units."}},"required":["countries","currency"],"examples":[{"salary_ct":5000000,"gross_mode":"shared_gross","period":"annual","person_type":"single","joint_assessment":false,"children":0,"tax_year":2026,"countries":["US","IE","DE","CA"],"currency":"EUR"},{"salary_ct":7000000,"gross_mode":"shared_gross","period":"annual","person_type":"single","joint_assessment":false,"children":0,"tax_year":2026,"countries":["DE","AT","CH","US","UK","IE","CA","AU"],"currency":"EUR"},{"gross_mode":"local_median_gross","period":"annual","joint_assessment":false,"children":0,"tax_year":2026,"countries":["DE","AT","CH","US","UK","IE","CA","AU"],"currency":"eur"}]},"output_schema":{"type":"object","additionalProperties":true,"description":"Annual country comparison response. Amounts are returned in major currency units in the requested lower-case currency, not cents. Results are meant for cross-country comparison; use berechne for detailed single-country payroll output.","properties":{"comparison_basis":{"type":"string","enum":["shared_gross","local_median_gross"],"description":"Basis used for the comparison: shared_gross for the same gross salary in each country, or local_median_gross for country-specific median benchmarks."},"gross_inputs":{"type":"object","description":"Annual gross salary input used for each country, keyed by country code and expressed in the selected major currency. In shared_gross mode these values are usually identical; in local_median_gross mode they differ by country benchmark.","additionalProperties":{"type":"number","description":"Annual gross salary used for this country in the selected major currency."}},"benchmark_method_version":{"type":"string","description":"Editorial benchmark method version used when comparison_basis is local_median_gross."},"benchmark_sources":{"type":"object","description":"Country-level benchmark source metadata used in local_median_gross mode, keyed by country code.","additionalProperties":{"type":"string","description":"Human-readable source note or source identifier for this country's median gross benchmark."}},"ranking_by_net":{"type":"array","description":"Countries ranked by estimated annual net salary, highest net first. Use this for 'where do I keep more money' and 'rank by net income' answers.","items":{"type":"object","additionalProperties":false,"properties":{"rank":{"type":"integer","description":"1-based rank by net salary, highest net first."},"country":{"type":"string","enum":["DE","AT","US","CH","CA","AU","UK","IE"],"description":"Country code for this ranked comparison result."},"net":{"type":"number","description":"Estimated annual net salary for this country in the requested major currency."},"total_deductions":{"type":"number","description":"Estimated annual tax plus social contributions for this country in the requested major currency."},"effective_rate":{"type":"number","description":"Total deduction rate as percentage points of gross income. Example: 37.7 means 37.7%."}},"required":["rank","country","net"]}},"results":{"type":"array","description":"Country-level comparison results with gross salary, net salary, income/payroll tax, social contributions, total deductions, and effective burden.","items":{"type":"object","additionalProperties":true,"properties":{"country":{"type":"string","enum":["DE","AT","US","CH","CA","AU","UK","IE"],"description":"Country code for this comparison result: DE, AT, CH, US, UK, IE, CA, or AU."},"net":{"type":"number","description":"Estimated annual net income after taxes and payroll/social deductions in the selected major currency. This is annual take-home pay, not monthly net."},"tax":{"type":"number","description":"Estimated annual tax burden in the selected major currency. Country meanings differ: for example PAYE/PAYG/income tax, federal plus state/provincial components, or withholding tax depending on system."},"social_contributions":{"type":"number","description":"Estimated annual employee social contributions or country-specific payroll deductions in the selected major currency. Examples include statutory social insurance, OASDI/Medicare, National Insurance, PRSI, CPP/QPP/EI, Medicare Levy, or Swiss payroll social deductions; private health bills may be outside payroll."},"total_deductions":{"type":"number","description":"Estimated annual tax plus employee social contributions/payroll deductions in the selected major currency."},"effective_rate":{"type":"number","description":"Combined tax and social contribution burden as percentage points of gross income. Example: 37.7 means 37.7%."},"input_annual_gross":{"type":"number","description":"Annual gross salary used for this country in the selected major currency. In local_median_gross mode this is the country-specific benchmark after currency conversion."},"input_currency":{"type":"string","enum":["eur","usd","chf","cad","aud","gbp"],"description":"Currency code for the gross input and result values, in lower-case ISO style."},"comparison_basis":{"type":"string","enum":["shared_gross","local_median_gross"],"description":"Comparison basis used for this country result."},"gross_source":{"type":"string","description":"Source or mode that produced the gross input, such as shared_user_input for same-salary comparisons or country_median_gross_benchmark for local-market benchmarks."}},"required":["country","net","tax","social_contributions","total_deductions","effective_rate","input_annual_gross","input_currency","comparison_basis"]}}},"required":["results","comparison_basis","gross_inputs","ranking_by_net"]}}},"resources":{"health":{"description":"Checks whether the backend is reachable.","url":"/api/health","method":"GET"},"openapi":{"description":"Returns the OpenAPI specification derived from the MCP descriptor.","url":"/api/openapi","method":"GET"}}}},"GenericObject":{"type":"object","additionalProperties":true},"LocalizedReferral":{"type":"object","additionalProperties":false,"properties":{"de":{"type":"string","description":"German CTA for the visual report link."},"en":{"type":"string","description":"English CTA for the visual report link."}},"required":["de","en"]},"BerechneRequest":{"type":"object","additionalProperties":true,"description":"Input schema for one-country detailed Obolus payroll calculations. Prefer the high-level user-facing fields country, tax_year, gross_salary, location, employee_type, tax, and social_security for German ChatGPT calls. Do not send raw German engine flags such as KVZ, gesetzliche_RV, gesetzlicheKvPvStatus, or KV_Art from ChatGPT-facing calls; they remain accepted only as backward-compatible product/API payload fields. Prefer taxcompare for multi-country comparisons. Legacy Obolus fields use minor currency units and are period-specific. Country-specific usage: DE: German payroll. Steuerklasse 1-6; Bundesland is the full Obolus state name such as Berlin or Nordrhein-Westfalen. For normal employees use the MCP preset de_payroll_preset=DE_STANDARD_EMPLOYEE_STATUTORY plus de_health_extra_contribution_percent as a literal percent such as 2.5. ChatGPT should not fill raw Obolus German payroll flags; the adapter translates semantic presets and aliases into backend compatibility fields. AT: Austrian payroll. Steuerklasse 1=standard employee, 2=sole earner with child, 3=single parent with child; Bundesland is the Austrian federal state; annual/monthly periods are the normal UI paths; pendler fields are Austria-only commuter inputs; BK/STS/STX/NETX can represent 13th/14th salary handling. CH: Swiss payroll. Steuerklasse 1=Tarif A, 2=Tarif B, 3=Tarif C, 4=Tarif H; Bundesland is the canton, currently Zurich in the UI; payroll deductions can include AHV/IV/EO, ALV, occupational pension, accident/sickness items; private KVG/LAMal health bills are not modeled as payroll health insurance. US: United States payroll. Steuerklasse 1=Single, 3=Joint, 4=Head of Household; Bundesland is the state; PreTax_Deduction_ct is for 401k/IRA/HSA-style deductions; Sonstige_Bezuege is supplemental income; outputs can split federal/state tax and OASDI/Medicare-style payroll contributions. UK: United Kingdom payroll. Steuerklasse 1=1257L standard tax code; Bundesland is region; PreTax_Deduction_ct is salary sacrifice or pension; Hat_Studienkredit toggles student loan repayment; outputs include PAYE income tax, National Insurance, and student loan where applicable. IE: Ireland payroll. Steuerklasse 1=Single, 2=Joint one income, 3=Joint two incomes; PreTax_Deduction_ct is pension contribution; Hat_Studienkredit is only relevant when a student-loan deduction is modeled; outputs include PAYE, USC, PRSI, and tax-credit information. CA: Canada payroll. Steuerklasse represents the federal/provincial claim setup; Bundesland is province such as Ontario, Quebec, or British Columbia; PreTax_Deduction_ct is RRSP/pension-style deduction; outputs can include federal/provincial tax, CPP/QPP, EI, and RRSP/credit information. AU: Australia payroll. Steuerklasse 1=Resident, 2=Non-Resident, 3=Working Holiday; PreTax_Deduction_ct is super salary sacrifice; Hat_Studienkredit toggles HELP/HECS repayment; Sonstige_Bezuege is bonus pay; outputs include PAYG tax, Medicare Levy, voluntary super, and employer super info. For standard German employees, ChatGPT/MCP should use semantic preset fields, not legacy numeric insurance fields: de_payroll_preset=DE_STANDARD_EMPLOYEE_STATUTORY, de_statutory_pension_and_unemployment=true, de_statutory_health_and_care=true, de_health_extra_contribution_percent=2.5 for a 2.5% Zusatzbeitrag, Kirche=0, KinderPVA=0, Kinderfreibetrag=0. Do not encode de_health_extra_contribution_percent as 25, 250, basis points, tenths, or cents. Raw Obolus fields such as gesetzliche_RV, gesetzlicheKvPvStatus, KV_Art, and KVZ are compatibility fields that can be valid in existing product/API payloads, especially for pensioners, civil servants, pension-exempt workers, and private health insurance. ChatGPT-facing calls should prefer semantic preset fields when possible.","properties":{"country":{"type":"string","enum":["DE","AT","US","CH","CA","AU","UK","IE"],"description":"Preferred high-level country code for ChatGPT-facing calls. For German payroll use DE. The adapter maps this to legacy Land."},"tax_year":{"type":"integer","description":"Preferred high-level tax year for ChatGPT-facing calls. The adapter maps this to legacy Stjahr.","examples":[2026]},"gross_salary":{"type":"object","additionalProperties":false,"description":"Preferred high-level gross salary input. Amount is in major currency units, not cents. The adapter maps it to legacy Gehalt_ct minor units and LZZ.","properties":{"amount":{"type":"number","minimum":0,"description":"Gross salary in major currency units, for example 60000 for EUR 60,000 annual gross or 5000 for EUR 5,000 monthly gross."},"currency":{"type":"string","enum":["EUR","USD","CHF","CAD","AUD","GBP"],"description":"Salary currency, for example EUR."},"period":{"type":"string","enum":["annual","monthly","weekly","daily"],"description":"Salary period. annual maps to LZZ=1, monthly to LZZ=2, weekly to LZZ=3, daily to LZZ=4."}},"required":["amount","currency","period"]},"location":{"type":"object","additionalProperties":false,"description":"Preferred high-level location input. For Germany, federal_state may be a state code such as BE or a full Obolus state name such as Berlin.","properties":{"federal_state":{"type":"string","description":"German federal state code or full state name, for example BE or Berlin. The adapter maps BE to Berlin."}}},"employee_type":{"type":"string","enum":["standard_statutory_employee","private_health_insurance","pension_exempt","pension_exempt_private_health"],"default":"standard_statutory_employee","description":"Preferred high-level German employee type. Use standard_statutory_employee for the common statutory pension, unemployment, health, and care insurance case."},"payroll_preset":{"type":"string","enum":["DE_STANDARD_EMPLOYEE_STATUTORY","DE_PRIVATE_HEALTH_INSURANCE","DE_PENSION_EXEMPT","DE_PENSION_EXEMPT_PRIVATE_HEALTH"],"default":"DE_STANDARD_EMPLOYEE_STATUTORY","description":"Preferred high-level payroll preset. Use DE_STANDARD_EMPLOYEE_STATUTORY for a normal German employee with statutory pension, unemployment, health, and care insurance."},"tax":{"type":"object","additionalProperties":false,"description":"Preferred high-level tax assumptions for ChatGPT-facing calls. The adapter maps these to Steuerklasse, Kirche, and Kinderfreibetrag.","properties":{"tax_class":{"type":"integer","enum":[1,2,3,4,5,6],"description":"German tax class, 1 through 6."},"church_tax":{"type":"boolean","default":false,"description":"Whether German church tax applies. false maps to Kirche=0 and true maps to Kirche=1."},"child_allowance_factor":{"type":"number","minimum":0,"default":0,"description":"German child allowance factor, for example 0, 0.5, 1, or 2."}}},"social_security":{"type":"object","additionalProperties":false,"description":"Preferred high-level German social-security assumptions. Use enums instead of raw Obolus flags. The adapter maps statutory/exempt/private choices to the legacy payroll-engine fields.","properties":{"pension_insurance":{"type":"string","enum":["statutory","exempt"],"default":"statutory","description":"Use statutory for normal employees. Use exempt only for civil servants, self-employed, pensioners, or explicitly pension-exempt cases."},"unemployment_insurance":{"type":"string","enum":["statutory","exempt"],"default":"statutory","description":"Use statutory for normal employees. This is mapped together with pension_insurance for the legacy German payroll engine."},"health_insurance":{"type":"string","enum":["statutory","private"],"default":"statutory","description":"Use statutory for German GKV/PV. Use private only when the user explicitly has private health insurance."},"health_additional_contribution_percent":{"type":"number","minimum":0,"maximum":5,"examples":[2.5,2.9],"description":"German statutory health Zusatzbeitrag as literal percentage points, for example 2.9 for 2.90%. Do not use basis points such as 290."},"long_term_care_insurance":{"type":"string","enum":["statutory","private"],"default":"statutory","description":"Use statutory for normal German care insurance. Private should only be used together with private health insurance."},"children_for_care_insurance":{"type":"integer","minimum":0,"default":0,"description":"Number of children relevant for German long-term care insurance contribution logic."},"private_health_employee_contribution_ct":{"type":"integer","minimum":0,"description":"Private health insurance employee contribution in minor units for the selected period. Required only when health_insurance is private."}}},"Land":{"type":"string","enum":["DE","AT","US","CH","CA","AU","UK","IE"],"description":"Country code for the calculation."},"Stjahr":{"type":"integer","description":"Tax year.","examples":[2026]},"Currency":{"type":"string","enum":["EUR","USD","CHF","CAD","AUD","GBP"],"description":"Display currency / calculation currency code."},"LZZ":{"type":"integer","enum":[1,2,3,4],"default":1,"description":"Payroll period identifier for the calculation. Values: 1=year, 2=month, 3=week, 4=day. All salary and payroll monetary inputs must be for this period, not automatically annualized."},"Modus":{"type":"integer","enum":[1,2,3],"default":1,"description":"Calculation mode. Use 1 for one person, 2 for two persons, and 3 for the German TaxSim capped real-splitting simulation."},"Faktor":{"type":"number","default":1,"description":"Global factor for factor-based tax class handling."},"KinderFRB":{"type":"number","default":0,"description":"Top-level child allowance, child count, dependent count, or child-credit factor for the calculation. DE uses allowance-style factors; AT/CH/US and other systems use country-specific child/dependent meanings where supported."},"KinderPVA":{"type":"integer","minimum":0,"default":0,"description":"Total child count relevant for German long-term care insurance contribution logic. Leave 0 outside German care-insurance scenarios unless a country-specific child workflow explicitly requires it."},"Kindergeld":{"type":"integer","default":0,"description":"Child benefit amount in minor units for the selected calculation context. Leave 0 for standard payroll estimates unless explicitly modeling child benefit or a country-specific dependent benefit."},"Personen":{"type":"array","minItems":1,"maxItems":2,"description":"One or two payroll person records. Each person contains salary, tax class, region, insurance, child, and optional special-income inputs.","items":{"type":"object","additionalProperties":true,"properties":{"Land":{"type":"string","enum":["DE","AT","US","CH","CA","AU","UK","IE"],"description":"Country code that selects the payroll/tax system for this person. Interpret all country-polymorphic fields in this person record, such as Steuerklasse, Bundesland, PreTax_Deduction_ct, Kinderfreibetrag, and output tax buckets, through this Land value. Supported systems: DE, AT, CH, US, UK, IE, CA, AU."},"Gehalt_ct":{"type":"integer","minimum":0,"description":"Gross pay for this person's selected payroll period in minor units. The value must match LZZ/Lohnzahlungszeitraum: for EUR 70,000 per year with LZZ=1 send 7000000; for monthly payroll with LZZ=2 send the monthly gross, for example 583333 for EUR 5,833.33."},"Gehalt_ct_ohne_Sonst":{"type":"integer","minimum":0,"description":"Gross pay excluding one-off or bonus payments for the selected payroll period, in minor units."},"Steuerklasse":{"type":"integer","description":"Country-polymorphic tax class, tariff, filing status, or tax-code selector. Do not reuse German tax-class meanings outside Land=DE. DE: 1=single, 2=single parent, 3/4/5=married tax classes, 6=additional job. AT: 1=standard employee, 2=sole earner with child, 3=single parent with child. CH: 1=Tarif A, 2=Tarif B, 3=Tarif C, 4=Tarif H. US: 1=Single, 3=Joint, 4=Head of Household. UK: 1=1257L standard tax code. IE: 1=Single, 2=Joint one income, 3=Joint two incomes. AU: 1=Resident, 2=Non-Resident, 3=Working Holiday. CA uses the payroll claim setup for federal/provincial tax calculation."},"Geldwerter_Vorteil":{"type":"integer","description":"Taxable benefits in minor units. Used as in-kind benefit, taxable benefit, benefit in kind, natural salary, or imputed income depending on country; supported for DE, AT, CH, UK, US, CA, and IE."},"PreTax_Deduction_ct":{"type":"integer","description":"Country-polymorphic pre-tax deductions in minor units for the selected payroll period. Interpret by Land: AT occupational provision/commuter-related deduction, CH pillar 3a or occupational pension purchase, US 401k/IRA/HSA, UK salary sacrifice or pension, CA RRSP/pension, AU super salary sacrifice, and IE pension contribution."},"pendlerEuro":{"type":"integer","description":"Austria-only commuter allowance amount in minor units."},"Pendler_KM":{"type":"integer","description":"Austria-only commuting distance in kilometers."},"Pendler_Zumutbar":{"type":"integer","description":"Austrian commuter reasonableness flag."},"Pendler_Tage":{"type":"integer","description":"Austria-only monthly commuter days."},"Altersrente_Bezug":{"type":"integer","description":"1 if pension/retirement benefits apply, otherwise 0. Mainly used for DE/AT pensioner workflows."},"Bundesland":{"type":"string","description":"Country-polymorphic region selector for regional taxes and payroll rules. DE uses full Obolus state names such as Berlin, Bayern, Nordrhein-Westfalen, Sachsen, not ISO abbreviations such as BE or BY. AT uses Austrian federal states such as Wien. CH uses the canton such as Zurich. US uses state names such as California. CA uses provinces such as Ontario, Quebec, or British Columbia. UK uses England, Scotland, Wales, or Northern Ireland. Leave omitted for country examples that omit it unless the user gives a specific supported region.","examples":["Baden-Wuerttemberg","Bayern","Berlin","Brandenburg","Bremen","Hamburg","Hessen","Mecklenburg-Vorpommern","Niedersachsen","Nordrhein-Westfalen","Rheinland-Pfalz","Saarland","Sachsen","Sachsen-Anhalt","Schleswig-Holstein","Thueringen"]},"Lohnzahlungszeitraum":{"type":"integer","description":"Payroll period for this person. Values: 1=year, 2=month, 3=week, 4=day. The person's Gehalt_ct must be the gross amount for the same period. Some country UIs expose only a subset: AT/CH commonly annual or monthly; DE/US and defaults commonly annual, monthly, or weekly."},"Stjahr":{"type":"integer","description":"Tax year."},"Faktor":{"type":"number","description":"Germany-only tax factor used for tax class IV/factor workflows."},"Geburtsjahr":{"type":"integer","description":"Birth year."},"Versorgungsbezuege":{"type":"integer","description":"Germany-only pension or civil-service pension payments in minor units."},"Erster_mntl_Versorgungsbezug":{"type":"integer","description":"Germany-only first monthly pension payment in minor units."},"Versorgungsbezuege_Sonderzahlung":{"type":"integer","description":"Germany-only special pension payment in minor units."},"Erstes_Jahr_Versorgungsbezug":{"type":"integer","description":"Germany-only first tax year of pension receipt."},"Monate_Versorgungsbezuege":{"type":"integer","description":"Germany-only number of months with pension payments."},"Freibetrag_Sonst":{"type":"integer","description":"Allowance on one-off payments in minor units."},"Hinzubetrag":{"type":"integer","description":"Additional amount on one-off payments in minor units."},"Sonstige_Bezuege":{"type":"integer","description":"One-off payments or bonus income in minor units. Country meanings include DE other remuneration, UK/US/CA/IE supplemental income, AU bonus pay, and AT/CH special salary or bonus handling where supported."},"Sonstige_Entschaedigung":{"type":"integer","description":"Compensation payments in minor units."},"Sonstige_Sterbe":{"type":"integer","description":"Death benefit / survivor payment in minor units."},"de_payroll_preset":{"type":"string","enum":["DE_STANDARD_EMPLOYEE_STATUTORY","DE_PRIVATE_HEALTH_INSURANCE","DE_PENSION_EXEMPT","DE_PENSION_EXEMPT_PRIVATE_HEALTH"],"default":"DE_STANDARD_EMPLOYEE_STATUTORY","oneOf":[{"const":"DE_STANDARD_EMPLOYEE_STATUTORY","title":"Germany standard employee with statutory pension and statutory health","description":"Use this for the normal German employee case. The adapter maps it to Obolus backend flags gesetzliche_RV=0, gesetzlicheKvPvStatus=0, KV_Art=0, AN_Beitraege_PKV=0."},{"const":"DE_PRIVATE_HEALTH_INSURANCE","title":"Germany employee with private health insurance","description":"Use this only when the user explicitly has PKV. The adapter keeps statutory pension/unemployment enabled and maps health/care to private. Provide de_private_health_employee_contribution_ct."},{"const":"DE_PENSION_EXEMPT","title":"Germany pension/unemployment exempt with statutory health","description":"Use this for civil servants, self-employed, or other no-statutory-pension cases that still use statutory health/care handling."},{"const":"DE_PENSION_EXEMPT_PRIVATE_HEALTH","title":"Germany pension/unemployment exempt with private health","description":"Use this only for exempt PKV cases. Provide de_private_health_employee_contribution_ct."}],"description":"Preferred ChatGPT-facing German payroll preset. Use this instead of raw Obolus flags. For 'Germany, normal employee, tax class I' choose DE_STANDARD_EMPLOYEE_STATUTORY."},"de_statutory_pension_and_unemployment":{"type":"boolean","default":true,"description":"Semantic Germany-only adapter field. true means statutory pension and unemployment insurance apply. The adapter maps true to Obolus gesetzliche_RV=0 and false to gesetzliche_RV=1. Use false only for civil servants, self-employed, or explicitly pension-exempt cases."},"de_statutory_health_and_care":{"type":"boolean","default":true,"description":"Semantic Germany-only adapter field. true means statutory health and long-term care insurance apply. The adapter maps true to Obolus gesetzlicheKvPvStatus=0 and KV_Art=0; false means private health insurance and requires de_private_health_employee_contribution_ct."},"de_health_extra_contribution_percent":{"type":"number","minimum":0,"maximum":10,"examples":[1.7,2.5],"description":"Preferred MCP/ChatGPT alias for the German statutory health insurance Zusatzbeitrag. Use the literal percent value, for example 2.5 for 2.5%. The server normalizes this to legacy KVZ. Do not use basis points, tenths, cents, 25, 250, or any minor-unit encoding."},"de_private_health_employee_contribution_ct":{"type":"integer","minimum":0,"description":"Semantic Germany-only adapter field for private health insurance employee contribution in minor units for the selected payroll period. Required when de_statutory_health_and_care=false or a private-health preset is selected. Leave omitted or 0 for statutory GKV/PV."},"Freibetrag_AG":{"type":"integer","description":"Employer/payroll allowance or additional withholding amount in minor units. Country meanings include DE employer wage-tax feature, AT allowance notice, US/CA additional withholding, and UK payroll allowance handling."},"Hinzubetrag_AG":{"type":"integer","description":"Employer surcharge in minor units."},"Hat_Studienkredit":{"type":"integer","description":"Student loan repayment flag. Relevant for UK student loan, AU HELP/HECS, and IE student-loan-style deductions where modeled."},"Stfr_vermgsbteil":{"type":"integer","description":"Tax-free capital-forming benefit share in minor units."},"Entschädigungen_vermgsbteil":{"type":"integer","description":"Capital-forming compensation share in minor units."},"Sonstige_Bezuege_Versorgungsbezug":{"type":"integer","description":"One-off payments tied to pension benefits in minor units."},"KinderPVA":{"type":"integer","minimum":0,"default":0,"description":"Number of children relevant for German long-term care insurance. Children can reduce the care insurance rate; use 0 when no child discount applies."},"Kirche":{"type":"integer","description":"Church tax membership flag. Use 1 when church tax applies and 0 when it does not."},"Kinderfreibetrag":{"type":"number","default":0,"description":"Child allowance, dependent count, or child-credit factor for this person. DE uses child allowance shares such as 0, 0.5, 1, or 2. AT uses child count for Familienbonus workflows. CH uses child deduction count. US uses dependent credits count. CA/UK/AU/IE use dependent or child context where supported, often outside direct payroll tax."}},"required":["Land","Gehalt_ct","Steuerklasse","Geburtsjahr"]}}},"examples":[{"country":"DE","tax_year":2026,"gross_salary":{"amount":60000,"currency":"EUR","period":"annual"},"location":{"federal_state":"BE"},"employee_type":"standard_statutory_employee","payroll_preset":"DE_STANDARD_EMPLOYEE_STATUTORY","tax":{"tax_class":1,"church_tax":false,"child_allowance_factor":0},"social_security":{"pension_insurance":"statutory","unemployment_insurance":"statutory","health_insurance":"statutory","health_additional_contribution_percent":2.9,"long_term_care_insurance":"statutory","children_for_care_insurance":0}},{"Land":"DE","Stjahr":2026,"Currency":"EUR","LZZ":2,"Modus":1,"Faktor":1,"KinderFRB":0,"KinderPVA":0,"Kindergeld":0,"Personen":[{"Land":"DE","Gehalt_ct":583333,"Gehalt_ct_ohne_Sonst":583333,"Steuerklasse":1,"Bundesland":"Berlin","Lohnzahlungszeitraum":2,"Stjahr":2026,"Faktor":1,"Geburtsjahr":1988,"de_payroll_preset":"DE_STANDARD_EMPLOYEE_STATUTORY","de_statutory_pension_and_unemployment":true,"de_statutory_health_and_care":true,"de_health_extra_contribution_percent":2.5,"Kirche":0,"KinderPVA":0,"Kinderfreibetrag":0}]},{"Land":"DE","Stjahr":2026,"Currency":"EUR","LZZ":1,"Modus":1,"Faktor":1,"KinderFRB":0,"KinderPVA":0,"Kindergeld":0,"Personen":[{"Land":"DE","Gehalt_ct":7000000,"Gehalt_ct_ohne_Sonst":7000000,"Steuerklasse":1,"Bundesland":"Berlin","Lohnzahlungszeitraum":1,"Stjahr":2026,"Faktor":1,"Geburtsjahr":1988,"de_payroll_preset":"DE_STANDARD_EMPLOYEE_STATUTORY","de_statutory_pension_and_unemployment":true,"de_statutory_health_and_care":true,"de_health_extra_contribution_percent":2.5,"Kirche":0,"KinderPVA":0,"Kinderfreibetrag":0}]},{"Land":"DE","Stjahr":2026,"Currency":"EUR","LZZ":2,"Modus":1,"Faktor":1,"KinderFRB":0,"KinderPVA":0,"Kindergeld":0,"Personen":[{"Land":"DE","Gehalt_ct":583333,"Gehalt_ct_ohne_Sonst":583333,"Steuerklasse":1,"Bundesland":"Berlin","Lohnzahlungszeitraum":2,"Stjahr":2026,"Faktor":1,"Geburtsjahr":1988,"de_payroll_preset":"DE_PRIVATE_HEALTH_INSURANCE","de_statutory_pension_and_unemployment":true,"de_statutory_health_and_care":false,"de_health_extra_contribution_percent":0,"de_private_health_employee_contribution_ct":45000,"Kirche":0,"KinderPVA":0,"Kinderfreibetrag":0}]},{"Land":"AT","Stjahr":2026,"Currency":"EUR","LZZ":2,"Modus":1,"Faktor":1,"KinderFRB":0,"KinderPVA":0,"Kindergeld":0,"Personen":[{"Land":"AT","Gehalt_ct":500000,"Gehalt_ct_ohne_Sonst":500000,"Steuerklasse":1,"Bundesland":"Wien","Lohnzahlungszeitraum":2,"Stjahr":2026,"Faktor":1,"Geburtsjahr":1988,"PreTax_Deduction_ct":0,"pendlerEuro":0,"Pendler_KM":0,"Pendler_Zumutbar":0,"Pendler_Tage":0,"Kinderfreibetrag":0}]},{"Land":"CH","Stjahr":2026,"Currency":"CHF","LZZ":1,"Modus":1,"Faktor":1,"KinderFRB":0,"KinderPVA":0,"Kindergeld":0,"Personen":[{"Land":"CH","Gehalt_ct":10000000,"Gehalt_ct_ohne_Sonst":10000000,"Steuerklasse":1,"Bundesland":"Zürich","Lohnzahlungszeitraum":1,"Stjahr":2026,"Faktor":1,"Geburtsjahr":1988,"PreTax_Deduction_ct":0,"Kinderfreibetrag":0}]},{"Land":"US","Stjahr":2026,"Currency":"USD","LZZ":1,"Modus":1,"Faktor":1,"KinderFRB":0,"KinderPVA":0,"Kindergeld":0,"Personen":[{"Land":"US","Gehalt_ct":9000000,"Gehalt_ct_ohne_Sonst":9000000,"Steuerklasse":1,"Bundesland":"California","Lohnzahlungszeitraum":1,"Stjahr":2026,"Faktor":1,"Geburtsjahr":1988,"PreTax_Deduction_ct":0,"Sonstige_Bezuege":0,"Freibetrag_AG":0,"Kinderfreibetrag":0}]},{"Land":"UK","Stjahr":2026,"Currency":"GBP","LZZ":1,"Modus":1,"Faktor":1,"KinderFRB":0,"KinderPVA":0,"Kindergeld":0,"Personen":[{"Land":"UK","Gehalt_ct":6000000,"Gehalt_ct_ohne_Sonst":6000000,"Steuerklasse":1,"Bundesland":"England","Lohnzahlungszeitraum":1,"Stjahr":2026,"Faktor":1,"Geburtsjahr":1988,"PreTax_Deduction_ct":0,"Hat_Studienkredit":0,"Sonstige_Bezuege":0,"Freibetrag_AG":0,"Kinderfreibetrag":0}]},{"Land":"IE","Stjahr":2026,"Currency":"EUR","LZZ":1,"Modus":1,"Faktor":1,"KinderFRB":0,"KinderPVA":0,"Kindergeld":0,"Personen":[{"Land":"IE","Gehalt_ct":7000000,"Gehalt_ct_ohne_Sonst":7000000,"Steuerklasse":1,"Lohnzahlungszeitraum":1,"Stjahr":2026,"Faktor":1,"Geburtsjahr":1988,"PreTax_Deduction_ct":0,"Hat_Studienkredit":0,"Sonstige_Bezuege":0,"Kinderfreibetrag":0}]},{"Land":"CA","Stjahr":2026,"Currency":"CAD","LZZ":1,"Modus":1,"Faktor":1,"KinderFRB":0,"KinderPVA":0,"Kindergeld":0,"Personen":[{"Land":"CA","Gehalt_ct":8500000,"Gehalt_ct_ohne_Sonst":8500000,"Steuerklasse":1,"Bundesland":"Ontario","Lohnzahlungszeitraum":1,"Stjahr":2026,"Faktor":1,"Geburtsjahr":1988,"PreTax_Deduction_ct":0,"Sonstige_Bezuege":0,"Freibetrag_AG":0,"Kinderfreibetrag":0}]},{"Land":"AU","Stjahr":2026,"Currency":"AUD","LZZ":1,"Modus":1,"Faktor":1,"KinderFRB":0,"KinderPVA":0,"Kindergeld":0,"Personen":[{"Land":"AU","Gehalt_ct":9000000,"Gehalt_ct_ohne_Sonst":9000000,"Steuerklasse":1,"Lohnzahlungszeitraum":1,"Stjahr":2026,"Faktor":1,"Geburtsjahr":1988,"PreTax_Deduction_ct":0,"Hat_Studienkredit":0,"Sonstige_Bezuege":0,"Kinderfreibetrag":0}]}]},"BerechneResponse":{"type":"object","additionalProperties":true,"description":"Output schema for one-country detailed Obolus payroll calculations. Interpret person1, person2, and gesamt with the original request Land; stable field names such as ST, LSTLZZ, RSV, KSV, PSV, ASV, and VTL have country-specific meanings rather than one global meaning. Monetary amounts are minor units. Output country-specific usage: DE outputs keep German payroll meanings: ST/LSTLZZ are wage tax, SOLZLZZ is solidarity surcharge, KST is church tax, and RSV/KSV/PSV/ASV are statutory pension, health, care, and unemployment insurance. AT outputs emphasize Austrian wage tax plus social insurance; BK, STS, STX, and NETX can represent annual or special-payment handling such as 13th/14th salary paths. CH outputs can represent federal, cantonal, municipal, withholding, AHV/IV/EO, ALV, accident, sickness, and pension-fund payroll deductions; private KVG/LAMal health bills are not modeled as payroll health insurance. US outputs map stable Obolus fields to federal/state income tax, Social Security/OASDI, Medicare, additional withholding, supplemental income, and pre-tax retirement/HSA-style deduction context. UK outputs map stable Obolus fields to PAYE income tax, National Insurance, student loan where enabled, salary sacrifice or pension, and regional/tax-code context. IE outputs map stable Obolus fields to PAYE, USC, PRSI, pension contribution, tax credits, and student-loan-style deductions where modeled. CA outputs map stable Obolus fields to federal/provincial tax, CPP/QPP, EI, RRSP or pension deductions, province-specific credits, and additional withholding. AU outputs map stable Obolus fields to PAYG tax, Medicare Levy, HELP/HECS where enabled, voluntary super salary sacrifice, bonus pay, and employer super information.","properties":{"person1":{"type":"object","additionalProperties":true,"description":"Payroll result for the first person. Interpret stable output codes with the original request Land and the output country-specific usage notes.","properties":{"info":{"type":"string","description":"Backend note, warning, or informational message for the calculation."},"BK":{"type":"integer","description":"Country-polymorphic special payment, bonus-related gross component, or total package component in minor units. AT commonly represents 13th/14th salary handling; AU can represent total package including super."},"BKS":{"type":"integer","description":"Country-polymorphic tax or contribution value related to special payment handling, in minor units."},"SOLZLZZ":{"type":"integer","description":"Country-specific payroll-period surcharge or informational deduction in minor units. DE=solidarity surcharge, CH=municipal tax, CA=tax withholding, IE=student loan where modeled."},"SOLZS":{"type":"integer","description":"Solidarity surcharge or country-specific equivalent on special payments, in minor units. Interpret by original request Land."},"STS":{"type":"integer","description":"Country-polymorphic social contribution or country-specific charge on special payments, in minor units. Interpret by original request Land."},"LSTLZZ":{"type":"integer","description":"Country-specific period tax or deduction in minor units. Interpret by original request Land: DE/AT=period wage tax, CH=cantonal tax, US/CA=federal tax, UK=student loan, AU=HELP/HECS repayment, IE=USC."},"KST":{"type":"integer","description":"Church tax or country-specific religious levy deducted from payroll, in minor units. Mainly relevant for DE and CH; most other systems have no payroll church tax."},"ST":{"type":"integer","description":"Primary payroll tax in minor units. Interpret by original request Land: DE/AT/UK=income tax, CH=federal or withholding tax component, US=federal plus state or state component depending response mapping, CA=provincial component, AU=PAYG tax, IE=PAYE."},"STJ":{"type":"integer","description":"Annualized income tax value after child allowance or country-specific adjustment logic, in minor units. Interpret by original request Land."},"ZVE":{"type":"number","description":"Taxable income used as the basis for the wage, payroll, or income tax calculation, in minor units. Interpret by original request Land."},"ZVEJ":{"type":"number","description":"Taxable income after child allowances or country-specific adjustment logic, in minor units. Interpret by original request Land."},"KFBP":{"type":"string","description":"Child allowance, child benefit, tax-credit, or favorable-test information returned by the calculator. Interpret by original request Land."},"RSV":{"type":"integer","description":"Employee pension or retirement contribution for the selected payroll period in minor units. DE/AT=statutory pension, CH=AHV/IV/EO and possibly pension fund, US=Social Security/OASDI, CA=CPP/QPP, UK=workplace or state-pension-related contribution context, IE=pension/PRSA or PRSI pension context, AU=voluntary super contribution."},"KSV":{"type":"integer","description":"Country-specific health, Medicare, USC, or equivalent contribution for the selected payroll period in minor units. DE/AT=statutory health contribution, CH=occupational accident/sickness or pillar-related payroll deduction rather than private KVG/LAMal bill, US=Medicare, AU=Medicare Levy, IE=USC, CA=province-related health or employment-insurance context depending backend mapping."},"PSV":{"type":"integer","description":"Employee long-term care insurance or country-specific equivalent contribution for the selected payroll period in minor units. DE=nursing care insurance; CH can represent NBU/KTG-style accident/sickness context. Usually unused in other tax systems."},"ASV":{"type":"integer","description":"Employee unemployment insurance or country-specific social contribution for the selected payroll period in minor units. DE/AT=unemployment/rest social insurance, CH=ALV/NBU, UK=National Insurance, IE=PRSI, CA=Employment Insurance or RRSP employee context depending response mapping, US=state disability/unemployment-style employee item where applicable, AU is normally unused because unemployment benefits are tax-funded."},"NET":{"type":"integer","description":"Net pay remaining after country-specific taxes and payroll deductions for the selected payroll period, in minor units."},"STX":{"type":"integer","description":"Income tax due after annual tax equalization, joint assessment, or country-specific compensation logic, in minor units. Interpret by original request Land."},"STXJ":{"type":"integer","description":"Income tax after annual equalization including child allowance, child benefit, tax credit, or country-specific dependent effects, in minor units."},"NETX":{"type":"integer","description":"Net pay after annual tax equalization or country-specific compensation logic, excluding child benefit effects, in minor units. Interpret by original request Land."},"NETXJ":{"type":"integer","description":"Actual annual available net income after country-specific annual adjustments, in minor units. Interpret by original request Land."},"GWV":{"type":"integer","description":"Taxable benefit or monetary advantage included in the calculation, in minor units. Country meanings include in-kind benefit, benefit in kind, taxable benefit, or imputed income."},"VTL":{"type":"integer","description":"Forecast, informational, or country-specific adjustment value in minor units. DE=tax refund/forecast info, AT=tax on 13th/14th salary, CH=withholding-tax info, US=401k/IRA info, UK=student loan, CA=RRSP/federal credit info, AU=employer superannuation, IE=USC or tax-credit info."},"Brutto":{"type":"integer","description":"Gross earnings used in the calculation, before country-specific taxes and payroll deductions, in minor units."}}},"person2":{"type":"object","additionalProperties":true,"description":"Payroll result for the second person. Values are zero or empty when the calculation mode uses only one person. Interpret stable output codes with the original request Land.","properties":{"info":{"type":"string","description":"Backend note, warning, or informational message for the calculation."},"BK":{"type":"integer","description":"Country-polymorphic special payment, bonus-related gross component, or total package component in minor units. AT commonly represents 13th/14th salary handling; AU can represent total package including super."},"BKS":{"type":"integer","description":"Country-polymorphic tax or contribution value related to special payment handling, in minor units."},"SOLZLZZ":{"type":"integer","description":"Country-specific payroll-period surcharge or informational deduction in minor units. DE=solidarity surcharge, CH=municipal tax, CA=tax withholding, IE=student loan where modeled."},"SOLZS":{"type":"integer","description":"Solidarity surcharge or country-specific equivalent on special payments, in minor units. Interpret by original request Land."},"STS":{"type":"integer","description":"Country-polymorphic social contribution or country-specific charge on special payments, in minor units. Interpret by original request Land."},"LSTLZZ":{"type":"integer","description":"Country-specific period tax or deduction in minor units. Interpret by original request Land: DE/AT=period wage tax, CH=cantonal tax, US/CA=federal tax, UK=student loan, AU=HELP/HECS repayment, IE=USC."},"KST":{"type":"integer","description":"Church tax or country-specific religious levy deducted from payroll, in minor units. Mainly relevant for DE and CH; most other systems have no payroll church tax."},"ST":{"type":"integer","description":"Primary payroll tax in minor units. Interpret by original request Land: DE/AT/UK=income tax, CH=federal or withholding tax component, US=federal plus state or state component depending response mapping, CA=provincial component, AU=PAYG tax, IE=PAYE."},"STJ":{"type":"integer","description":"Annualized income tax value after child allowance or country-specific adjustment logic, in minor units. Interpret by original request Land."},"ZVE":{"type":"number","description":"Taxable income used as the basis for the wage, payroll, or income tax calculation, in minor units. Interpret by original request Land."},"ZVEJ":{"type":"number","description":"Taxable income after child allowances or country-specific adjustment logic, in minor units. Interpret by original request Land."},"KFBP":{"type":"string","description":"Child allowance, child benefit, tax-credit, or favorable-test information returned by the calculator. Interpret by original request Land."},"RSV":{"type":"integer","description":"Employee pension or retirement contribution for the selected payroll period in minor units. DE/AT=statutory pension, CH=AHV/IV/EO and possibly pension fund, US=Social Security/OASDI, CA=CPP/QPP, UK=workplace or state-pension-related contribution context, IE=pension/PRSA or PRSI pension context, AU=voluntary super contribution."},"KSV":{"type":"integer","description":"Country-specific health, Medicare, USC, or equivalent contribution for the selected payroll period in minor units. DE/AT=statutory health contribution, CH=occupational accident/sickness or pillar-related payroll deduction rather than private KVG/LAMal bill, US=Medicare, AU=Medicare Levy, IE=USC, CA=province-related health or employment-insurance context depending backend mapping."},"PSV":{"type":"integer","description":"Employee long-term care insurance or country-specific equivalent contribution for the selected payroll period in minor units. DE=nursing care insurance; CH can represent NBU/KTG-style accident/sickness context. Usually unused in other tax systems."},"ASV":{"type":"integer","description":"Employee unemployment insurance or country-specific social contribution for the selected payroll period in minor units. DE/AT=unemployment/rest social insurance, CH=ALV/NBU, UK=National Insurance, IE=PRSI, CA=Employment Insurance or RRSP employee context depending response mapping, US=state disability/unemployment-style employee item where applicable, AU is normally unused because unemployment benefits are tax-funded."},"NET":{"type":"integer","description":"Net pay remaining after country-specific taxes and payroll deductions for the selected payroll period, in minor units."},"STX":{"type":"integer","description":"Income tax due after annual tax equalization, joint assessment, or country-specific compensation logic, in minor units. Interpret by original request Land."},"STXJ":{"type":"integer","description":"Income tax after annual equalization including child allowance, child benefit, tax credit, or country-specific dependent effects, in minor units."},"NETX":{"type":"integer","description":"Net pay after annual tax equalization or country-specific compensation logic, excluding child benefit effects, in minor units. Interpret by original request Land."},"NETXJ":{"type":"integer","description":"Actual annual available net income after country-specific annual adjustments, in minor units. Interpret by original request Land."},"GWV":{"type":"integer","description":"Taxable benefit or monetary advantage included in the calculation, in minor units. Country meanings include in-kind benefit, benefit in kind, taxable benefit, or imputed income."},"VTL":{"type":"integer","description":"Forecast, informational, or country-specific adjustment value in minor units. DE=tax refund/forecast info, AT=tax on 13th/14th salary, CH=withholding-tax info, US=401k/IRA info, UK=student loan, CA=RRSP/federal credit info, AU=employer superannuation, IE=USC or tax-credit info."},"Brutto":{"type":"integer","description":"Gross earnings used in the calculation, before country-specific taxes and payroll deductions, in minor units."}}},"gesamt":{"type":"object","additionalProperties":true,"description":"Combined payroll result across all persons in the calculation. Uses the same country-specific output-code meanings as person1 and person2.","properties":{"info":{"type":"string","description":"Backend note, warning, or informational message for the calculation."},"BK":{"type":"integer","description":"Country-polymorphic special payment, bonus-related gross component, or total package component in minor units. AT commonly represents 13th/14th salary handling; AU can represent total package including super."},"BKS":{"type":"integer","description":"Country-polymorphic tax or contribution value related to special payment handling, in minor units."},"SOLZLZZ":{"type":"integer","description":"Country-specific payroll-period surcharge or informational deduction in minor units. DE=solidarity surcharge, CH=municipal tax, CA=tax withholding, IE=student loan where modeled."},"SOLZS":{"type":"integer","description":"Solidarity surcharge or country-specific equivalent on special payments, in minor units. Interpret by original request Land."},"STS":{"type":"integer","description":"Country-polymorphic social contribution or country-specific charge on special payments, in minor units. Interpret by original request Land."},"LSTLZZ":{"type":"integer","description":"Country-specific period tax or deduction in minor units. Interpret by original request Land: DE/AT=period wage tax, CH=cantonal tax, US/CA=federal tax, UK=student loan, AU=HELP/HECS repayment, IE=USC."},"KST":{"type":"integer","description":"Church tax or country-specific religious levy deducted from payroll, in minor units. Mainly relevant for DE and CH; most other systems have no payroll church tax."},"ST":{"type":"integer","description":"Primary payroll tax in minor units. Interpret by original request Land: DE/AT/UK=income tax, CH=federal or withholding tax component, US=federal plus state or state component depending response mapping, CA=provincial component, AU=PAYG tax, IE=PAYE."},"STJ":{"type":"integer","description":"Annualized income tax value after child allowance or country-specific adjustment logic, in minor units. Interpret by original request Land."},"ZVE":{"type":"number","description":"Taxable income used as the basis for the wage, payroll, or income tax calculation, in minor units. Interpret by original request Land."},"ZVEJ":{"type":"number","description":"Taxable income after child allowances or country-specific adjustment logic, in minor units. Interpret by original request Land."},"KFBP":{"type":"string","description":"Child allowance, child benefit, tax-credit, or favorable-test information returned by the calculator. Interpret by original request Land."},"RSV":{"type":"integer","description":"Employee pension or retirement contribution for the selected payroll period in minor units. DE/AT=statutory pension, CH=AHV/IV/EO and possibly pension fund, US=Social Security/OASDI, CA=CPP/QPP, UK=workplace or state-pension-related contribution context, IE=pension/PRSA or PRSI pension context, AU=voluntary super contribution."},"KSV":{"type":"integer","description":"Country-specific health, Medicare, USC, or equivalent contribution for the selected payroll period in minor units. DE/AT=statutory health contribution, CH=occupational accident/sickness or pillar-related payroll deduction rather than private KVG/LAMal bill, US=Medicare, AU=Medicare Levy, IE=USC, CA=province-related health or employment-insurance context depending backend mapping."},"PSV":{"type":"integer","description":"Employee long-term care insurance or country-specific equivalent contribution for the selected payroll period in minor units. DE=nursing care insurance; CH can represent NBU/KTG-style accident/sickness context. Usually unused in other tax systems."},"ASV":{"type":"integer","description":"Employee unemployment insurance or country-specific social contribution for the selected payroll period in minor units. DE/AT=unemployment/rest social insurance, CH=ALV/NBU, UK=National Insurance, IE=PRSI, CA=Employment Insurance or RRSP employee context depending response mapping, US=state disability/unemployment-style employee item where applicable, AU is normally unused because unemployment benefits are tax-funded."},"NET":{"type":"integer","description":"Net pay remaining after country-specific taxes and payroll deductions for the selected payroll period, in minor units."},"STX":{"type":"integer","description":"Income tax due after annual tax equalization, joint assessment, or country-specific compensation logic, in minor units. Interpret by original request Land."},"STXJ":{"type":"integer","description":"Income tax after annual equalization including child allowance, child benefit, tax credit, or country-specific dependent effects, in minor units."},"NETX":{"type":"integer","description":"Net pay after annual tax equalization or country-specific compensation logic, excluding child benefit effects, in minor units. Interpret by original request Land."},"NETXJ":{"type":"integer","description":"Actual annual available net income after country-specific annual adjustments, in minor units. Interpret by original request Land."},"GWV":{"type":"integer","description":"Taxable benefit or monetary advantage included in the calculation, in minor units. Country meanings include in-kind benefit, benefit in kind, taxable benefit, or imputed income."},"VTL":{"type":"integer","description":"Forecast, informational, or country-specific adjustment value in minor units. DE=tax refund/forecast info, AT=tax on 13th/14th salary, CH=withholding-tax info, US=401k/IRA info, UK=student loan, CA=RRSP/federal credit info, AU=employer superannuation, IE=USC or tax-credit info."},"Brutto":{"type":"integer","description":"Gross earnings used in the calculation, before country-specific taxes and payroll deductions, in minor units."}}},"faktor":{"type":"number","description":"Tax factor used for German tax class IV factor workflows when applicable."},"source_url":{"type":"string","description":"Canonical Obolus URL for the matching interactive calculator."},"visual_report":{"type":"string","description":"Deep link to the interactive report or calculator view."},"localized_cta":{"type":"object","additionalProperties":false,"properties":{"de":{"type":"string","description":"German CTA for the visual report link."},"en":{"type":"string","description":"English CTA for the visual report link."}},"required":["de","en"],"description":"Localized call-to-action labels for opening the visual Obolus report link."},"assumptions":{"type":"object","additionalProperties":true,"description":"Normalized user-facing assumptions used for the payroll calculation, including country, salary period, location, tax class, church tax, and German social-security choices. Use this to explain what the calculation assumed without exposing raw payroll-engine flags."},"warnings":{"type":"array","description":"Non-blocking warnings about suspicious inputs, such as annual gross sent with monthly LZZ, scaled German Zusatzbeitrag values, or raw German insurance combinations that may be intentional for non-standard cases.","items":{"type":"string","description":"Human-readable warning message."}}},"required":["source_url","visual_report","localized_cta"]},"TaxcompareRequest":{"type":"object","additionalProperties":false,"description":"Plain object input schema for Obolus country-to-country salary comparisons. If the user asks for one salary across multiple countries, always use taxcompare first. Use this tool for requests such as \"compare EUR 50,000 salary in USA, Ireland, Germany, Canada\". Prefer salary_ct=5000000, currency=\"EUR\", tax_year=2026, countries=[\"US\",\"IE\",\"DE\",\"CA\"], period=\"annual\", gross_mode=\"shared_gross\". If the user asks for one salary across multiple countries, always use taxcompare first. Use this endpoint for multi-country salary/tax comparisons. Select taxcompare when the user provides one salary or income amount, two or more countries, and wants tax, net salary, deductions, take-home pay, ranking, or 'where do I keep more money' results. Typical trigger phrases include: calculate tax for 50k in Germany, Ireland, USA, Canada; compare net salary across these countries; where do I pay less tax on EUR 80k; what is take-home pay in X, Y, Z; rank these countries by net income; how much do I keep after tax in Germany vs Ireland. Routing rule: if countries.length >= 2 and the same salary/income is used, use taxcompare. If countries.length === 1, use berechne. If the user provides detailed payroll assumptions such as tax class, province/state, health insurance, children, church tax, pension exemption, deductions, or benefits, use berechne unless taxcompare supports those fields explicitly. Do not use berechne repeatedly for simple multi-country comparisons unless taxcompare cannot accept the required inputs. Use shared_gross when the user wants to compare the same salary offer across countries. Prefer salary_ct in minor units, such as 5000000 for EUR 50,000. annual_gross is a backward-compatible annual major-unit alias, such as 50000 for EUR 50,000. Use local_median_gross when the user wants a local-market benchmark. In this mode Obolus fans out to country-specific editorial median gross benchmarks; annual_gross is optional and ignored when omitted. taxcompare is annual and country-level. It is not the right tool for detailed payroll inputs such as German KVZ, tax class IV factor, private health insurance, commuter allowance, or monthly gross; use berechne for that. countries accepts DE, AT, CH, US, UK, IE, CA, and AU. currency accepts EUR, USD, CHF, CAD, AUD, GBP and lower-case equivalents; results normalize currency codes to lower-case. joint_assessment and children are broad comparison assumptions. Country-specific filing details are simplified for comparability; for a precise single-country case, call berechne. Results are annual major-currency estimates. net is annual take-home pay; tax is annual tax burden; social_contributions are annual employee payroll/social deductions or the country-specific equivalent; effective_rate is a percentage-point burden value such as 37.7 for 37.7%. Country meanings differ: DE/AT emphasize income tax plus statutory social contributions, CH can include withholding and payroll social deductions but not private KVG/LAMal health bills, US includes federal/state and OASDI/Medicare-style items, UK includes PAYE/National Insurance, IE includes PAYE/USC/PRSI, CA includes federal/provincial tax plus CPP/QPP/EI, and AU includes PAYG/Medicare/super-related outputs.","properties":{"salary_ct":{"type":"integer","minimum":0,"description":"Preferred salary input for ChatGPT/MCP calls. Salary in minor units for the selected period, for example 5000000 for EUR 50,000. With period=annual this is annual salary; with period=monthly this is monthly salary and Obolus annualizes it for the comparison. Required for shared_gross mode unless annual_gross is provided as a legacy alias."},"annual_gross":{"type":"number","description":"Backward-compatible annual gross salary alias in major currency units, not cents. Prefer salary_ct. Example: 50000 means 50,000 in the selected currency. Required for shared_gross mode only when salary_ct is not provided; optional and ignored when omitted for local_median_gross."},"gross_mode":{"type":"string","enum":["shared_gross","local_median_gross"],"default":"shared_gross","description":"Comparison basis. Use shared_gross for the same user-provided annual gross across all countries. Use local_median_gross for country-specific editorial median gross benchmarks. Defaults to shared_gross when omitted."},"period":{"type":"string","enum":["annual","monthly"],"default":"annual","description":"Period for salary_ct. Use annual when salary_ct is the annual gross salary. Use monthly when salary_ct is one monthly gross salary; taxcompare annualizes it before comparing countries. annual_gross is always annual and ignores this field."},"person_type":{"type":"string","enum":["single","married"],"default":"single","description":"Broad household assumption for comparison. single maps to joint_assessment=false; married maps to joint_assessment=true unless joint_assessment is provided explicitly. For precise country-specific filing details, use berechne."},"joint_assessment":{"type":"boolean","default":false,"description":"Broad joint filing / joint assessment assumption for comparable country-level estimates. For precise country-specific filing details, use berechne."},"children":{"type":"integer","minimum":0,"default":0,"description":"Number of children or dependents used as a broad comparison assumption. Country-specific child allowance and credit rules are simplified for comparability."},"tax_year":{"anyOf":[{"type":"string"},{"type":"integer"}],"description":"Tax year, for example 2026. The same tax year is applied to every selected country."},"countries":{"type":"array","minItems":1,"items":{"type":"string","enum":["DE","AT","US","CH","CA","AU","UK","IE"]},"description":"List of country tax systems to compare. Use at least two countries for a comparison. Supported values: DE, AT, CH, US, UK, IE, CA, AU."},"currency":{"type":"string","enum":["eur","usd","chf","cad","aud","gbp","EUR","USD","CHF","CAD","AUD","GBP"],"description":"Input and output currency: EUR, USD, CHF, CAD, AUD, GBP, or lower-case equivalents. Results normalize currency codes to lower-case. Unlike berechne, taxcompare prefers salary_ct for salary input and returns major currency units."}},"required":["countries","currency"],"examples":[{"salary_ct":5000000,"gross_mode":"shared_gross","period":"annual","person_type":"single","joint_assessment":false,"children":0,"tax_year":2026,"countries":["US","IE","DE","CA"],"currency":"EUR"},{"salary_ct":7000000,"gross_mode":"shared_gross","period":"annual","person_type":"single","joint_assessment":false,"children":0,"tax_year":2026,"countries":["DE","AT","CH","US","UK","IE","CA","AU"],"currency":"EUR"},{"gross_mode":"local_median_gross","period":"annual","joint_assessment":false,"children":0,"tax_year":2026,"countries":["DE","AT","CH","US","UK","IE","CA","AU"],"currency":"eur"}]},"TaxcompareResponse":{"type":"object","additionalProperties":true,"description":"Annual country comparison response. Amounts are returned in major currency units in the requested lower-case currency, not cents. Results are meant for cross-country comparison; use berechne for detailed single-country payroll output.","properties":{"comparison_basis":{"type":"string","enum":["shared_gross","local_median_gross"],"description":"Basis used for the comparison: shared_gross for the same gross salary in each country, or local_median_gross for country-specific median benchmarks."},"gross_inputs":{"type":"object","description":"Annual gross salary input used for each country, keyed by country code and expressed in the selected major currency. In shared_gross mode these values are usually identical; in local_median_gross mode they differ by country benchmark.","additionalProperties":{"type":"number","description":"Annual gross salary used for this country in the selected major currency."}},"benchmark_method_version":{"type":"string","description":"Editorial benchmark method version used when comparison_basis is local_median_gross."},"benchmark_sources":{"type":"object","description":"Country-level benchmark source metadata used in local_median_gross mode, keyed by country code.","additionalProperties":{"type":"string","description":"Human-readable source note or source identifier for this country's median gross benchmark."}},"ranking_by_net":{"type":"array","description":"Countries ranked by estimated annual net salary, highest net first. Use this for 'where do I keep more money' and 'rank by net income' answers.","items":{"type":"object","additionalProperties":false,"properties":{"rank":{"type":"integer","description":"1-based rank by net salary, highest net first."},"country":{"type":"string","enum":["DE","AT","US","CH","CA","AU","UK","IE"],"description":"Country code for this ranked comparison result."},"net":{"type":"number","description":"Estimated annual net salary for this country in the requested major currency."},"total_deductions":{"type":"number","description":"Estimated annual tax plus social contributions for this country in the requested major currency."},"effective_rate":{"type":"number","description":"Total deduction rate as percentage points of gross income. Example: 37.7 means 37.7%."}},"required":["rank","country","net"]}},"results":{"type":"array","description":"Country-level comparison results with gross salary, net salary, income/payroll tax, social contributions, total deductions, and effective burden.","items":{"type":"object","additionalProperties":true,"properties":{"country":{"type":"string","enum":["DE","AT","US","CH","CA","AU","UK","IE"],"description":"Country code for this comparison result: DE, AT, CH, US, UK, IE, CA, or AU."},"net":{"type":"number","description":"Estimated annual net income after taxes and payroll/social deductions in the selected major currency. This is annual take-home pay, not monthly net."},"tax":{"type":"number","description":"Estimated annual tax burden in the selected major currency. Country meanings differ: for example PAYE/PAYG/income tax, federal plus state/provincial components, or withholding tax depending on system."},"social_contributions":{"type":"number","description":"Estimated annual employee social contributions or country-specific payroll deductions in the selected major currency. Examples include statutory social insurance, OASDI/Medicare, National Insurance, PRSI, CPP/QPP/EI, Medicare Levy, or Swiss payroll social deductions; private health bills may be outside payroll."},"total_deductions":{"type":"number","description":"Estimated annual tax plus employee social contributions/payroll deductions in the selected major currency."},"effective_rate":{"type":"number","description":"Combined tax and social contribution burden as percentage points of gross income. Example: 37.7 means 37.7%."},"input_annual_gross":{"type":"number","description":"Annual gross salary used for this country in the selected major currency. In local_median_gross mode this is the country-specific benchmark after currency conversion."},"input_currency":{"type":"string","enum":["eur","usd","chf","cad","aud","gbp"],"description":"Currency code for the gross input and result values, in lower-case ISO style."},"comparison_basis":{"type":"string","enum":["shared_gross","local_median_gross"],"description":"Comparison basis used for this country result."},"gross_source":{"type":"string","description":"Source or mode that produced the gross input, such as shared_user_input for same-salary comparisons or country_median_gross_benchmark for local-market benchmarks."}},"required":["country","net","tax","social_contributions","total_deductions","effective_rate","input_annual_gross","input_currency","comparison_basis"]}}},"required":["results","comparison_basis","gross_inputs","ranking_by_net"]}},"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"x-public-api-key"},"BearerAuth":{"type":"http","scheme":"bearer"}}},"x-mcp-version":"1.0.1"}