Free public tax MCP: GST/VAT, income, company & capital-gains tax for 50+ countries, source-cited.
Scored across 10 tools
Each tool targets a distinct tax concept or operation: cgt_estimate, income_tax_estimate, and company_tax_estimate split by taxpayer/type, while tax_rate_lookup, tax_rate_as_of, compute_gst_vat, and compare_countries cleanly separate lookup vs. historical vs. arithmetic vs. cross-country comparison. The descriptions even cross-reference each other to steer selection (e.g., 'for the current rate use tax_rate_lookup'), leaving almost no overlap.
Most names follow a predictable [subject]_[action] pattern (cgt_estimate, income_tax_estimate, tax_rate_lookup, tax_rate_as_of), with only a couple of verb-first deviations (compute_gst_vat, compare_countries). The convention is readable and internally coherent despite these minor inconsistencies.
Ten tools is well-scoped for a multi-jurisdiction tax engine, with each tool earning its place across distinct tax types and operations. No redundancy or filler.
The surface covers income, corporate, capital gains, and consumption taxes plus AU-specific super and student loan, with current/historical rate lookup and cross-country comparison. Minor gaps remain (non-resident rules, withholding taxes, property/inheritance taxes are out of scope), but core tax workflows are covered.
Estimate capital gains tax on one sale of shares or property by a resident individual, for 71 countries (AE, AR, AT, AU, BE, BG, BR, CA, CH, CL, CN, CO, CY, CZ, DE, DK, EE, EG, ES, FI, FR, GB, GH, GR, GT, HK, HR, HU, ID, IE, IL, IN, IS, IT, JM, JP, KE, KR, LI, LK, LT, LU, LV, MT, MU, MX, MY, NG, NL, NO, NZ, PH, PK, PL, PT, QA, RO, RS, RU, SA, SE, SG, SI, SK, TR, TW, TZ, UA, UG, US, ZA). Where the country's rule can be computed the answer is a figure; where it depends on facts the engine cannot model, the answer is the rule itself (rate, holding period, annual exemption, main residence) with the reason — never a borrowed number. Any other country returns 'not covered'. Pass income (other taxable income for the year) where the gain is taxed at marginal rates, and heldMoreThan12Months or holdingMonths where the holding period matters (the Australian 50% discount, the US long-term rate). capitalLosses apply before any discount. Finland (FI) adds its own detail: the better of the actual cost or the deemed acquisition cost (hankintameno-olettama: 20% of the price, 40% after 10 years), the 1 000 € small-disposals rule and 30%/34% capital income tax — pass yearsHeld, and otherCapitalIncome if there is any; costBase may be omitted there. Each answer cites the capital-gains source and date for that country — not the GST/VAT one. For pay without an asset sale use income_tax_estimate. Non-resident rules are out of scope. Results may include one sourced background fact (relatedFact); the figures do not depend on it.
| Name | Required | Description | Default |
|---|---|---|---|
| asset | No | What was sold: 'shares' (shares and funds) or 'property' (real estate). Rules differ by asset in many countries | shares |
| income | No | Other taxable income for the year, in local currency — sets the marginal rate where the gain is taxed as income (e.g. AU, US short-term). Required where the rule needs it; the answer says so | |
| country | No | 2-letter ISO code of a covered country (upper case); defaults to AU | AU |
| taxYear | No | FI: calendar tax year like '2026'; omit for the current year | |
| costBase | No | What the asset cost, in local currency, including eligible incidental costs. Required except for FI, where omitting it uses the deemed acquisition cost (pass FI buying and selling costs as saleExpenses) | |
| proceeds | Yes | Sale price of the asset, in local currency | |
| yearsHeld | No | FI: whole years owned — 10 or more raises the deemed acquisition cost from 20% to 40% of the price | |
| saleExpenses | No | FI: brokerage, fees and other costs of buying and selling | |
| capitalLosses | No | Capital losses to offset — applied before any discount; FI: from this year or carried forward (five years) | |
| holdingMonths | No | Whole months the asset was held; overrides heldMoreThan12Months | |
| otherCapitalIncome | No | FI: other capital income this year (dividends, rent, other gains) — decides how much of the gain falls above the 30 000 € threshold | |
| heldMoreThan12Months | No | True when the asset was held at least 12 months (e.g. the AU 50% discount, the US long-term rate). Shorthand for holdingMonths: true = 12, false = 0 | |
| totalProceedsThisYear | No | FI: the year's total sale prices, this sale included, for the 1 000 € small-disposals rule; omit when this is the only sale |
| Name | Required | Description |
|---|---|---|
| loss | No | FI: the loss on this sale, if any (only ever from the actual cost) |
| rule | No | The country's rule as written, for relaying — especially when status is rule-only |
| step | No | Which holding-period step applied, when the rule has steps |
| notes | No | FI: rules that decided the answer, in plain words |
| method | No | FI: whether the actual cost or the deemed acquisition cost was deducted |
| reason | No | Why no figure was computed (rule-only), in plain words |
| source | Yes | The national tax authority the figures were verified against (e.g. 'ATO — ato.gov.au') |
| status | Yes | 'computed' = a figure; 'rule-only' = the rule text and the reason no figure is given (cgtPayable and taxableGain are then null) |
| country | Yes | Country estimated (2-letter ISO code) |
| taxYear | Yes | Tax year whose rules were used, when the rule is year-based |
| currency | No | Currency of every monetary field |
| grossGain | Yes | Proceeds minus cost (FI: minus the larger of actual or deemed cost). Floored at 0, local currency |
| sourceUrl | No | https link to the authority page the rate was verified against. Present only on rate answers backed by a verified ledger row — absent (never empty) otherwise, so its presence is itself the claim |
| cgtPayable | Yes | Extra tax caused by the gain, in local currency; null when rule-only |
| disclaimer | Yes | General-information note that must accompany any figure shown to a person |
| lossOffset | Yes | Capital losses actually applied |
| mayBeStale | Yes | True once the verification date is over a year old — re-confirm with the authority |
| assumptions | No | Assumptions the answer depends on — relay them with the figure |
| relatedFact | No | One sourced background fact about the country's capital gains tax; the figures do not depend on it. Absent when no sourced fact fits. |
| taxableGain | Yes | Gain the tax was charged on; null when rule-only |
| costDeducted | No | FI: the cost deducted from the price |
| dataVerifiedOn | Yes | ISO date the rate data was last confirmed against the authority |
| lossDeductible | No | FI: whether that loss can be deducted |
| discountApplied | Yes | Whether a discount or inclusion rate reduced the taxable gain (e.g. the AU 50% discount). Always false for FI |
| exemptionApplied | No | Annual exempt amount or allowance used, where there is one |
| smallDisposalsExempt | No | FI: true when the year's sale prices total 1 000 € or less, making every gain tax-free |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the safety profile (readOnly, idempotent, non-destructive closed-world), but the description adds substantial behavior the annotations cannot: the answer is a figure only where computable and otherwise returns the rule with reasoning rather than a borrowed number, uncovered countries return 'not covered', every answer cites a country-specific capital-gains source and date (not the GST/VAT one), and one sourced background fact may accompany results without affecting figures.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Purpose, alternatives and exclusions are front-loaded, but the inline list of all 71 ISO codes is redundant with the country enum and consumes roughly half the description. The Finland-specific paragraph is dense but earns its place; the country enumeration does not.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 13-parameter, closed-world estimation tool with an output schema, the description covers scope, coverage limits, non-covered fallback, sourcing policy, sibling routing and the FI special case well. The one loose end is the 'costBase required except FI' claim that the schema does not enforce, leaving a slight mismatch about what the caller must supply.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3; the description goes beyond it by giving cross-parameter semantics the per-field descriptions do not, e.g. capitalLosses are applied before any discount, income sets the marginal rate where the gain is taxed as income, and costBase may be omitted for FI in favour of the deemed acquisition cost. Minor gap: it claims costBase is required except FI, which the schema does not enforce (only proceeds is marked required).
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a concrete verb+resource (estimate capital gains tax on one sale of shares or property) plus the actor and scope (resident individual, 71 enumerated countries), and explicitly distinguishes itself from income_tax_estimate. An agent can tell exactly what this computes without opening the schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Names the alternative tool and the condition that selects it ('For pay without an asset sale use income_tax_estimate'), states an explicit exclusion ('Non-resident rules are out of scope'), and tells when to supply income, heldMoreThan12Months/holdingMonths and capitalLosses. Routing and prerequisites are fully specified.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Estimate company/corporate income tax on an annual profit at the headline rate for 139 countries (28 verified against the national authority; the rest are indicative OECD headline rates, and the answer says "not verified — confirm with" the authority). Use it for company profit questions; individuals belong to income_tax_estimate. smallBusiness applies the small-company rate only where it covers all of the company's income (AU, IN); where the reduced rate is a profit band (UK small profits, the Canadian small-business deduction and similar) it is noted, not applied. Headline-rate arithmetic only: state and provincial tax, surcharges and marginal relief are named in the note, not computed. Each answer cites the company-tax source and date — not the GST/VAT one. A negative profit returns an explanation (losses carry forward), never a negative tax; a country not covered says so. Results may include one sourced background fact (relatedFact); the figures do not depend on it.
| Name | Required | Description | Default |
|---|---|---|---|
| profit | Yes | Annual taxable profit in local currency; a negative value (a loss) returns an explanatory message instead of tax | |
| country | Yes | 2-letter ISO code of a covered country (upper case) | |
| smallBusiness | No | Apply the small-company rate — honoured only where it covers all income (AU, IN); elsewhere the reduced rate is noted instead |
| Name | Required | Description |
|---|---|---|
| tax | Yes | Company tax on the profit (local currency, rounded) |
| note | Yes | What the headline calculation excludes (state/provincial tax, surcharge/cess, marginal relief …) |
| source | Yes | The national tax authority the figures were verified against (e.g. 'ATO — ato.gov.au') |
| country | Yes | Country estimated (2-letter ISO code) |
| afterTax | Yes | Profit after tax |
| taxLabel | Yes | The country's name for the tax, e.g. 'Corporation Tax' |
| sourceUrl | No | https link to the authority page the rate was verified against. Present only on rate answers backed by a verified ledger row — absent (never empty) otherwise, so its presence is itself the claim |
| disclaimer | Yes | General-information note that must accompany any figure shown to a person |
| mayBeStale | Yes | True once the verification date is over a year old — re-confirm with the authority |
| rateApplied | Yes | Rate actually applied, as a fraction |
| relatedFact | No | One sourced background fact about the country's company tax; the figures do not depend on it. Absent when no sourced fact fits. |
| standardRate | No | The standard (headline) rate, as a fraction |
| effectiveFrom | No | ISO date the rate set in use took effect |
| usedSmallRate | No | Whether the small-company rate was applied |
| dataVerifiedOn | Yes | ISO date the rate data was last confirmed against the authority |
| smallCompanyRate | No | The small-company rate on file, when there is one |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Adds substantial context beyond the read-only/idempotent annotations: verification status per country (28 verified vs indicative OECD headline rates), what is and isn't computed (state/provincial tax, surcharges, marginal relief named but not applied), negative-profit handling, uncovered-country handling, and the presence of an incidental relatedFact. This is unusually complete behavioral disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The core purpose and the sibling routing are front-loaded in the first sentence, and every subsequent clause carries real caveats. It is dense and long, with some hedging and quotation-heavy phrasing that could be tightened, but little is pure filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 3-parameter, enum-heavy estimate tool with an output schema already covering return values, the description supplies the remaining context an agent needs: accuracy tiers, citation behavior, computation boundaries, and edge-case outcomes for losses and unsupported countries.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all three parameters, including the negative-profit and smallBusiness semantics. The description largely restates those rules (the AU/IN small-company rule appears in both places), adding only corroborating nuance rather than new parameter-level meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb+resource ('Estimate company/corporate income tax on an annual profit') plus scope ('at the headline rate for 139 countries'). It explicitly contrasts itself with the sibling income_tax_estimate for individuals, so an agent can route without opening either schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives an explicit when-to-use ('company profit questions') and an explicit alternative ('individuals belong to income_tax_estimate'). It further scopes usage with the headline-rate limitation and the smallBusiness applicability rule (AU, IN only).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Compare headline tax rates — GST/VAT, top personal income tax and company tax — across several countries at once. Use it to shortlist or contrast jurisdictions (relocation, expansion, pricing); for one country's full detail use tax_rate_lookup, and to apply a rate to an amount use compute_gst_vat. Pass income to add, per country, the income_tax_estimate result for that income (income tax, total tax, take-home, average rate, with its own source). The same number is read in each country's own currency and is not converted between currencies. Income tax is estimated for 57 countries; any other row reports 'not covered' for that part and still shows its headline rates. Codes the dataset does not cover are reported back in unmatchedCodes rather than silently dropped; every matched row cites its national tax authority. Results may include one sourced background fact (relatedFact); the figures do not depend on it.
| Name | Required | Description | Default |
|---|---|---|---|
| income | No | Optional gross annual income, before tax. The same number is applied in EACH country's own local currency — it is NOT converted (120000 means AUD 120,000 in AU, GBP 120,000 in GB and SGD 120,000 in SG). When given, each row adds an income-tax estimate for that income | |
| taxYear | No | Optional, only with income: the tax-year label passed to the income-tax estimate for every country, e.g. '2025-26' (AU/NZ/GB/IN) or '2026' (calendar-year countries). Labels differ by country; a country without that year reports the years it has instead of a figure. Omit for each country's current tax year | |
| countries | Yes | Countries to compare — two or more makes a meaningful comparison |
| Name | Required | Description |
|---|---|---|
| rows | Yes | One row per matched country |
| source | Yes | The national tax authority the figures were verified against (e.g. 'ATO — ato.gov.au') |
| sourceUrl | No | https link to the authority page the rate was verified against. Present only on rate answers backed by a verified ledger row — absent (never empty) otherwise, so its presence is itself the claim |
| disclaimer | Yes | General-information note that must accompany any figure shown to a person |
| mayBeStale | Yes | True once the verification date is over a year old — re-confirm with the authority |
| relatedFact | No | One sourced background fact about the country's consumption tax; the figures do not depend on it. Absent when no sourced fact fits. |
| dataVerifiedOn | Yes | ISO date the rate data was last confirmed against the authority |
| unmatchedCodes | Yes | Requested codes with no data — nothing was guessed for these |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare a read-only, idempotent, non-destructive, closed-world read, but the description goes well beyond them: it explains that income is read in each country's own currency and never converted, that income tax is only estimated for 57 countries, that unknown codes come back in unmatchedCodes instead of being dropped, and that every row cites a tax authority. That is exactly the kind of edge-case behavior structured fields do not carry.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The core purpose and the income semantics are front-loaded, and every subsequent sentence adds an operational fact (alternatives, coverage limits, unmatched codes, currency handling, relatedFact) rather than padding. Dense but nothing is wasted.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With an output schema present the description need not restate return values, and instead covers the failure modes an agent must anticipate: uncovered codes, uncovered income-tax countries, tax-year label mismatches, and the non-converted income number. Nothing needed to call or interpret this tool is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3 and the schema already documents all three parameters including the non-conversion example. The description still adds real meaning: which output fields appear when income is passed (income tax, total tax, take-home, average rate, with source) and the limited 57-country coverage of the income parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (Compare) and resource (headline tax rates: GST/VAT, top personal income tax, company tax) plus scope (several countries at once). It explicitly contrasts itself with two named siblings, so an agent can distinguish it without opening any schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives concrete when-to-use scenarios (relocation, expansion, pricing) and names the alternative for the excluded case: tax_rate_lookup for one country's full detail, compute_gst_vat for applying a rate to an amount. Both routing conditions are explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add or remove a country's GST/VAT — or its other national consumption tax, such as Japan's consumption tax or Malaysia's SST — on a monetary amount, returning the net / tax / gross split. Use it to convert between tax-exclusive and tax-inclusive prices (invoices, quotes, receipts); for the rates themselves use tax_rate_lookup. Pure arithmetic on the current standard rate, rounded to 2 decimals, in the local currency. Pass region for a state or provincial rate (CA, US): in Canada that is GST plus the provincial tax, in the US the state sales tax. A country with no national rate (the US without a region, or a country with no consumption tax) returns an explanatory error instead of a wrong number. Results may include one sourced background fact (relatedFact); the figures do not depend on it.
| Name | Required | Description | Default |
|---|---|---|---|
| mode | No | 'add' puts tax on top of a net amount; 'remove' extracts the tax already inside a gross amount | add |
| amount | Yes | The monetary amount in the local currency — tax-exclusive when mode=add, tax-inclusive when mode=remove | |
| region | No | Optional state or province code, for sub-national sales tax. Held for CA (13 provinces and territories), US (51 states incl. DC). E.g. 'ON' (Ontario) with country CA, or 'CA' (California) with country US. Answered from that state's or province's own cited rate; US figures are the state rate only — local sales taxes are not included. | |
| country | Yes | 2-letter ISO 3166-1 code of the country whose GST/VAT rate applies (case-insensitive) |
| Name | Required | Description |
|---|---|---|
| net | Yes | Amount before tax (local currency, 2 dp) |
| tax | Yes | The GST/VAT portion (local currency, 2 dp) |
| code | Yes | 2-letter ISO country code |
| mode | Yes | Which conversion was performed |
| rate | Yes | Standard rate applied, as a fraction |
| gross | Yes | Amount including tax (local currency, 2 dp) |
| region | No | State or province whose rate was applied — present only when region was passed |
| source | Yes | The national tax authority the figures were verified against (e.g. 'ATO — ato.gov.au') |
| country | Yes | Country name |
| sourceUrl | No | https link to the authority page the rate was verified against. Present only on rate answers backed by a verified ledger row — absent (never empty) otherwise, so its presence is itself the claim |
| disclaimer | Yes | General-information note that must accompany any figure shown to a person |
| mayBeStale | Yes | True once the verification date is over a year old — re-confirm with the authority |
| regionName | No | What applies in that region, in a sentence |
| relatedFact | No | One sourced background fact about the country's consumption tax; the figures do not depend on it. Absent when no sourced fact fits. |
| taxLocalName | Yes | The tax's local name, e.g. 'GST', 'VAT' |
| dataVerifiedOn | Yes | ISO date the rate data was last confirmed against the authority |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations cover safety (readOnly, idempotent, non-destructive, closed-world), and the description still adds substantive behavior beyond them: 2-decimal rounding on the current standard rate, local-currency figures, Canadian regions meaning GST plus provincial tax, US meaning state rate only with local taxes excluded, and an explanatory error instead of a wrong number when no national rate exists. It even discloses that relatedFact is decorative and does not affect the computation — unusually candid.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Five tight sentences, each carrying distinct load: scope, use case plus alternative, arithmetic guarantees, region semantics, and failure behavior. The routing constraint and the sibling alternative are front-loaded, and nothing is repetitive filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only four-parameter calculator with a full output schema, the description covers everything an agent needs to call it correctly: inputs, edge-case failure behavior, and scoping of region. Return values need not be explained because the output schema exists, and the relatedFact caveat closes the remaining ambiguity about the response.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so 3 is the baseline, but the description adds meaning the schema does not spell out — that region in Canada yields GST plus provincial tax while US figures are the state sales tax only, and that a country with no national rate produces an explanatory error rather than a value. The mode and amount semantics largely restate the schema, so this is above baseline but not maximally additive.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource — add or remove a country's GST/VAT (or equivalent national consumption tax) on a monetary amount — and names the exact output shape (net/tax/gross split). It also explicitly distinguishes itself from the sibling tax_rate_lookup, so an agent can route without opening either schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives the use case directly (converting tax-exclusive to tax-inclusive prices on invoices, quotes, receipts) and names the alternative with the condition that selects it: 'for the rates themselves use tax_rate_lookup.' It also states the region prerequisite for sub-national rates, so the branch conditions are explicit rather than inferred.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Estimate personal income tax and take-home pay from gross annual income for 57 countries, using the engine's effective-dated brackets with each country's own levies, offsets and social contributions as its scheme defines them. Covered: AE, AR, AT, AU, BD, BE, BR, CA, CH, CL, CN, CO, CR, CZ, DE, DK, EE, EG, ES, FI, FR, GB, GR, GT, HU, ID, IE, IL, IN, IS, IT, JM, JP, KE, KR, LU, LV, MX, MY, NG, NL, NO, NZ, PH, PK, PL, PT, SA, SE, SG, SI, SK, TH, TR, US, VN, ZA. Any other country returns 'not covered' rather than a guess; its headline rates live in tax_rate_lookup. Pass region for a state, province or nation where the scheme has one (CA: 13 regions, e.g. AB, BC, MB; ES: 3 regions, e.g. AN, CT, MD; GB: SCT (Scotland); US: 51 regions, e.g. AK, AL, AR); without it the answer is national only and says so in its assumptions. For Finland pass municipality (Finnish or Swedish name, e.g. 'Tampere' or 'Helsingfors') for that municipality's own rate — otherwise the national average is used and the answer says so — plus church for a parish member and age where it changes the contributions; Finland also returns the tax-card rate (veroprosentti). The figure is for EMPLOYMENT income (salary or wages) wherever a country applies an employee-only item — India's salary standard deduction, UK Class 1 National Insurance, US FICA — and the first assumption says so. For freelance or self-employed profit pass incomeType "self-employed": India and the UK compute it, countries where it is taxed the same answer it, and the rest refuse with what differs rather than return a salaried figure. This is a resident-individual estimate, not a filing calculation: relay the assumptions it returns. Each answer cites the income-tax source and date for that country — not the GST/VAT one. For AU HELP/HECS use student_loan_repayment. Results may include one sourced background fact (relatedFact); the figures do not depend on it.
| Name | Required | Description | Default |
|---|---|---|---|
| age | No | Finland only: age at the end of the tax year. Changes the employee pension and unemployment contributions and, from 66, the earned-income credit; omit to assume a working age (18–64 from 2026, when the 53–62 pension surcharge ended; 18–52 for 2025) | |
| church | No | Finland only: parish membership, for church tax. Needs `municipality`, because each parish sets its own rate | none |
| income | Yes | Gross annual income in local currency, before tax | |
| region | No | Optional state, province or nation code, where the country's scheme has one: CA: 13 regions, e.g. AB, BC, MB; ES: 3 regions, e.g. AN, CT, MD; GB: SCT (Scotland); US: 51 regions, e.g. AK, AL, AR | |
| country | Yes | 2-letter ISO code of a covered country (upper case) | |
| taxYear | No | Tax year as people write it, e.g. '2026-27' or '2026/27' (AU/NZ/GB/IN), '2026' (calendar-year countries), 'YA 2027' (Singapore), 'Tax Year 2027' (Pakistan, which names a year by its end); omit for the current tax year. A year not on file is refused with the years on file | |
| incomeType | No | What the income is: "employment" (salary or wages, the default) or "self-employed" (freelance or sole-trader profit after business expenses). Countries that do not model self-employed income refuse it with what differs instead of returning the employment figure | |
| municipality | No | Finland only: the municipality (kunta) of residence on 31 December of the previous year, in Finnish or Swedish, e.g. 'Helsinki', 'Espoo', 'Tampere', 'Åbo'. Sets the municipal and parish tax rates; omit to use the national average municipal rate |
| Name | Required | Description |
|---|---|---|
| lito | Yes | Kept for compatibility: AU Low Income Tax Offset only, 0 for every other country. See `offsets` for the general figure. |
| gross | Yes | Gross annual income used |
| levies | Yes | Charges on top of the offset tax, by name (social contributions, regional tax) — empty array when none apply |
| region | No | State, province or nation whose tax was included — present only when region was passed |
| source | Yes | The national tax authority the figures were verified against (e.g. 'ATO — ato.gov.au') |
| country | Yes | Country estimated (2-letter ISO code) |
| offsets | Yes | Credits that reduced the tax, by name — empty array when none apply |
| taxYear | Yes | Tax year the brackets belong to |
| taxable | Yes | Income after any pre-band deduction (UK personal allowance, IN standard deduction, US standard deduction) |
| currency | Yes | Currency of every monetary field |
| takeHome | Yes | Gross minus total tax |
| totalTax | Yes | Total tax after levies and offsets |
| incomeTax | Yes | Income tax before levies and offsets |
| sourceUrl | No | https link to the authority page the rate was verified against. Present only on rate answers backed by a verified ledger row — absent (never empty) otherwise, so its presence is itself the claim |
| churchRate | No | Finland: church-tax rate applied, as a fraction (0 for a non-member) |
| disclaimer | Yes | General-information note that must accompany any figure shown to a person |
| mayBeStale | Yes | True once the verification date is over a year old — re-confirm with the authority |
| assumptions | No | Assumptions the figures depend on — relay them with the numbers; the first is always the income basis |
| averageRate | No | Total tax over gross, as a fraction |
| incomeBasis | No | What income the figure was computed for: employment (employee-only items applied), self-employed, or any (nothing depends on the income type). The first assumption says the same in words |
| relatedFact | No | One sourced background fact about the country's income tax; the figures do not depend on it. Absent when no sourced fact fits. |
| taxCardRate | No | Finland: the withholding percentage (veroprosentti) Vero would put on the tax card — rounded up to the next half point. Employee pension and unemployment contributions are withheld on top of it |
| marginalRate | No | Marginal rate on the next unit of income, as a fraction |
| medicareLevy | Yes | Kept for compatibility: AU Medicare levy only, 0 for every other country. See `levies` for the general figure. |
| municipality | No | Finland: the municipality whose rates were used, or "national average" |
| municipalRate | No | Finland: municipal income-tax rate applied, as a fraction |
| dataVerifiedOn | Yes | ISO date the rate data was last confirmed against the authority |
| taxCardWithheld | No | Finland: the tax the tax card covers for the year, to the cent (state, municipal, church, health insurance and YLE tax, less the credit) |
| separatelyWithheld | No | Finland: employee pension and unemployment contributions for the year, to the cent — withheld by the employer on top of the tax card |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent and non-destructive, so the safety profile is covered. The description adds genuine behavioral context beyond that: refusals with 'what differs' for unsupported cases, national-only fallback when region is omitted, assumption relay, and income-tax source citations. However it does not detail rate limits, latency, or error surfacing, so this is a solid but not exceptional addition over the annotation baseline.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The core purpose is front-loaded and the rest is dense, information-bearing prose with no filler sentences. It is long, but nearly every clause covers a distinct country rule, refusal path, or parameter interaction, so length is largely earned rather than padding.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, so return values need not be explained, and the description nonetheless covers coverage breadth, refusal behavior, assumptions, income-type handling, and regional/municipal caveats. For an 8-parameter, 57-country engine, an agent has everything needed to call it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3, and the schema already documents each parameter thoroughly. The description adds marginal-but-real semantics: region omission yields a national-only answer 'and says so in its assumptions,' church requires municipality, and Finland additionally returns the veroprosentti tax-card rate. These interaction rules exceed the per-field schema text.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Opens with a specific verb+resource+scope: 'Estimate personal income tax and take-home pay from gross annual income for 57 countries.' It explicitly differentiates from siblings by naming tax_rate_lookup (for uncovered countries' headline rates) and student_loan_repayment (for AU HELP/HECS), so an agent can route without opening schemas.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
States when to use it (employment salary/wages), the self-employed alternative via incomeType, and the fallback path for uncovered countries. Exclusions and edge conditions (municipality/church interaction, region-dependent results, refusal semantics) are all spelled out rather than left to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Estimate the compulsory annual study or training loan repayment (HELP, HECS, VSL, SFSS, SSL, AASL) for an Australian resident from their repayment income, using the marginal system introduced in 2025-26 with effective-dated thresholds that roll over each financial year. Use it for "how much HELP/HECS will I repay" questions in AU; it does not cover the loan balance, indexation or voluntary repayments, and applies to Australia only. Repayment income is broader than taxable income — it adds back reportable super contributions, reportable fringe benefits, net investment loss and exempt foreign income; pass that combined figure. Results may include one sourced background fact (relatedFact); the figures do not depend on it.
| Name | Required | Description | Default |
|---|---|---|---|
| taxYear | No | Financial-year label like '2025-26'; omit to use the current Australian financial year | |
| repaymentIncome | Yes | ATO repayment income in AUD (taxable income + reportable super + reportable fringe benefits + net investment loss + exempt foreign income) |
| Name | Required | Description |
|---|---|---|
| source | Yes | The national tax authority the figures were verified against (e.g. 'ATO — ato.gov.au') |
| country | Yes | Always AU — this tool is Australia-only |
| taxYear | Yes | Financial year whose thresholds were used |
| repayment | Yes | Compulsory repayment for the year (AUD) |
| sourceUrl | No | https link to the authority page the rate was verified against. Present only on rate answers backed by a verified ledger row — absent (never empty) otherwise, so its presence is itself the claim |
| disclaimer | Yes | General-information note that must accompany any figure shown to a person |
| mayBeStale | Yes | True once the verification date is over a year old — re-confirm with the authority |
| relatedFact | No | One sourced background fact about the country's study-loan repayment; the figures do not depend on it. Absent when no sourced fact fits. |
| minThreshold | Yes | Income at or below which the repayment is nil (AUD) |
| effectiveRate | Yes | repayment ÷ repayment income, as a fraction |
| dataVerifiedOn | Yes | ISO date the rate data was last confirmed against the authority |
| repaymentIncome | Yes | Repayment income used (AUD) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly/idempotent/non-destructive/openWorld=false, so safety is covered. The description adds real behavioral context beyond that: thresholds are effective-dated and roll over each financial year, a specific income-aggregation rule applies, and results may carry one sourced background fact (relatedFact) that does not affect the figures. Return values need not be described since an output schema exists.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Dense but front-loaded: capability first, then the use case, exclusions, geographic scope, and the input caveat. Nothing is padding, though the parenthetical loan-type list and the repayment-income restatement are slightly repetitive of the schema.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a two-parameter calculator with full schema coverage, an output schema, and complete annotations, the description leaves no material gap: scope, exclusions, input definition, and the relatedFact caveat are all present.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3, but the description still adds value by hammering that repaymentIncome is broader than taxable income and telling the agent to pass the combined figure — a real disambiguation for the most likely invocation error. It does not go further on taxYear formatting, which the schema already pins down via pattern and examples.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (Estimate) plus a precisely scoped resource (compulsory annual HELP/HECS/VSL/SFSS/SSL/AASL repayment) and the method (marginal system, 2025-26 effective-dated thresholds). This is clearly distinguishable from siblings like income_tax_estimate or superannuation_estimate without opening any schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit targeting ("Use it for 'how much HELP/HECS will I repay' questions in AU") plus explicit exclusions (loan balance, indexation, voluntary repayments) and a geographic limitation (Australia only). The agent knows both when to reach for it and when to look elsewhere.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Estimate Australian superannuation for an employee: the compulsory Superannuation Guarantee contribution (12% from 2025-26), concessional (before-tax) contributions cap usage, the 15% in-fund contributions tax, and the Division 293 high-earner surcharge — all effective-dated so a future budget year is picked automatically. Use it for "how much super will I get / can I contribute / will I be taxed" questions in AU; it does not model fund fees, insurance, investment returns, non-concessional contributions or carry-forward caps, and applies to Australia only. Salary sacrifice reduces salary; a personal deductible contribution is a deduction against total assessable income. Both add to the concessional total. The Division 293 threshold is tested against taxable income plus LOW-TAX contributions — that is, concessional contributions excluding any excess over the cap, since the excess is already counted inside taxable income. ordinaryEarnings therefore counts toward the threshold; pass otherTaxableIncome only for income beyond salary, such as investment or business income. Results may include one sourced background fact (relatedFact); the figures do not depend on it.
| Name | Required | Description | Default |
|---|---|---|---|
| taxYear | No | Financial-year label like '2025-26'; omit to use the current Australian financial year | |
| salarySacrifice | No | Voluntary before-tax (concessional) contributions in AUD | |
| ordinaryEarnings | Yes | Ordinary time earnings the Superannuation Guarantee applies to, in AUD (usually salary/wages) | |
| otherTaxableIncome | No | Other taxable income in AUD — only used to test the Division 293 high-earner threshold | |
| personalDeductible | No | Personal contributions claimed as a tax deduction in AUD (also concessional) |
| Name | Required | Description |
|---|---|---|
| sgRate | Yes | Superannuation Guarantee rate applied, as a fraction |
| source | Yes | The national tax authority the figures were verified against (e.g. 'ATO — ato.gov.au') |
| country | Yes | Always AU — this tool is Australia-only |
| taxYear | Yes | Financial year whose parameters were used |
| div293Tax | Yes | Division 293 surcharge (extra 15%), 0 when it does not apply (AUD) |
| sourceUrl | No | https link to the authority page the rate was verified against. Present only on rate answers backed by a verified ledger row — absent (never empty) otherwise, so its presence is itself the claim |
| assumption | No | A stated assumption that materially affects the figures, when one applies (e.g. no carried-forward concessional cap) |
| disclaimer | Yes | General-information note that must accompany any figure shown to a person |
| mayBeStale | Yes | True once the verification date is over a year old — re-confirm with the authority |
| relatedFact | No | One sourced background fact about the country's superannuation; the figures do not depend on it. Absent when no sourced fact fits. |
| div293Applies | Yes | Whether the Division 293 high-earner surcharge applies |
| dataVerifiedOn | Yes | ISO date the rate data was last confirmed against the authority |
| concessionalCap | Yes | Concessional contributions cap for the year (AUD) |
| guaranteeAmount | Yes | Compulsory employer SG contribution for the year (AUD) |
| contributionsTax | Yes | 15% contributions tax on concessional contributions within the cap (AUD) |
| excessConcessional | Yes | Concessional contributions above the cap (AUD) |
| guaranteeableEarnings | Yes | Earnings the SG applied to after the maximum contribution base cap (AUD) |
| concessionalContributions | Yes | SG + salary sacrifice + personal deductible, all concessional (AUD) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the safety profile (readOnly, idempotent, non-destructive), and the description adds substantial behavior beyond them: automatic effective-dating so a future budget year is selected, the Division 293 threshold being tested against taxable income plus low-tax contributions, and the note that results may carry one sourced background fact that does not affect the figures. These are non-obvious behavioral traits an agent could not infer.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Purpose and computation list are front-loaded, and the second paragraph carries only the modelling semantics that genuinely change how an agent fills parameters. It is dense and long for a tool description, but no sentence is redundant or restates the schema.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, so return values need not be explained; the description instead covers the domain nuance an agent needs: effective dating, scope exclusions, the salary-sacrifice/deduction distinction, the Division 293 base, and the relatedFact caveat. Nothing material for correct invocation is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3, but the description adds real semantic value the schema does not: ordinaryEarnings counts toward the Division 293 threshold, otherTaxableIncome should be passed only for income beyond salary, and salary sacrifice versus personal deductible contributions both add to the concessional total with different tax mechanics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific verb (Estimate) and resource (Australian superannuation) and enumerates the exact computations: Superannuation Guarantee, concessional cap usage, 15% in-fund tax, and Division 293 surcharge. This is clearly distinct from siblings like income_tax_estimate, company_tax_estimate or student_loan_repayment without opening any schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives explicit usage routing ("how much super will I get / can I contribute / will I be taxed" questions in AU) and a firm when-not list (fund fees, insurance, investment returns, non-concessional contributions, carry-forward caps, Australia only). What it lacks is naming an alternative sibling tool to use instead when the question falls outside scope, so it is clear context rather than full alternative routing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Sourced facts about a country's tax system: when and why its GST/VAT was introduced, what it replaced, and memorable, true stories (court cases, elections, odd rulings) — each fact linked to its own source. Omit country for a primer on what a consumption tax is plus famous tax stories from history. Pass topic to keep only facts about one tax (each fact lists its topics). Use it for background, explainers, teaching or a conversation opener; for any rate or amount use tax_rate_lookup, compute_gst_vat or the estimate tools, because facts are dated stories, not live figures. Countries without curated facts return the list of countries that have them rather than an invented one.
| Name | Required | Description | Default |
|---|---|---|---|
| topic | No | Optional: only facts about this tax — 'gst' (GST/VAT and other consumption taxes), 'income', 'company', 'cgt', 'super', 'studentloan' or 'general'. Omit for every fact | |
| country | No | 2-letter ISO code, e.g. AU, GB, JP. Omit for the global primer and famous tax stories |
| Name | Required | Description |
|---|---|---|
| code | No | 2-letter ISO code (country scope only) |
| facts | Yes | The facts, each with its own source. Show the source alongside any fact you repeat |
| scope | Yes | Whether these are one country’s facts or the global set |
| topic | No | The topic filter applied, when one was passed |
| primer | No | What a consumption tax is (global scope only) |
| country | No | Country name (country scope only) |
| replaced | No | The tax it replaced, when on record |
| disclaimer | Yes | Note that must accompany facts shown to a person |
| originYear | No | Year the country’s GST/VAT began, when on record |
| originStory | No | How it came to be, in a paragraph |
| countriesWithFacts | Yes | Every country code that has curated facts |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations, it discloses that facts are dated stories rather than live figures, that each fact is source-linked, and that countries without curated facts return a list instead of an invented answer. These are meaningful behavioral traits for a read-only, closed-world tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core purpose, then adds filtering, usage routing, and edge-case behavior. Every sentence carries actionable information and none reads as filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With an output schema present and annotations covering safety, the description supplies what remains needed: scope, filters, alternatives, and fallback behavior. Nothing essential for correct invocation is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the parameters are already documented. The description adds some useful semantics, such as topic filtering keeping facts about one tax and each fact listing its topics, though it largely repeats the schema's omit-country behavior.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific resource and scope: sourced facts about a country's tax system, including introduction dates, replacements, and true stories, each linked to a source. It also distinguishes itself from rate/estimate siblings by naming tax_rate_lookup, compute_gst_vat, and estimate tools for live figures.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives explicit use cases (background, explainers, teaching, conversation opener) and explicit exclusions for rates/amounts, routing to named alternatives. It also clarifies behavior when country is omitted and when topic is passed.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Look up the GST/VAT standard rate that applied in a country ON A GIVEN DATE, rather than today's rate. Use it when reconciling or amending a past transaction, invoice or return — several countries changed rate recently (Estonia twice since 2024, Finland, Kazakhstan, Russia, Romania, Slovakia, Ghana, Israel, Ecuador), so the rate today is not the rate that applied then. For the current rate use tax_rate_lookup. The answer states plainly whether a real dated change backs it or whether only the present rate is on record. Results may include one sourced background fact (relatedFact); the figures do not depend on it.
| Name | Required | Description | Default |
|---|---|---|---|
| date | Yes | The date to resolve the rate for, as YYYY-MM-DD, e.g. '2024-06-30' | |
| country | Yes | 2-letter ISO country code, e.g. FI, EE, KZ |
| Name | Required | Description |
|---|---|---|
| date | Yes | The date resolved |
| source | Yes | The national tax authority the figures were verified against (e.g. 'ATO — ato.gov.au') |
| country | Yes | Country the rate applies to |
| isCurrent | Yes | True when this is also the rate in force today |
| rateSince | Yes | ISO date this standard rate took effect — the start of the unbroken run at this rate, which can be earlier than effectiveFrom |
| rateUntil | Yes | ISO date this standard rate stops applying, or null when no change is on record |
| sourceUrl | No | https link to the authority page the rate was verified against. Present only on rate answers backed by a verified ledger row — absent (never empty) otherwise, so its presence is itself the claim |
| disclaimer | Yes | General-information note that must accompany any figure shown to a person |
| mayBeStale | Yes | True once the verification date is over a year old — re-confirm with the authority |
| datedChange | Yes | True when a real recorded rate change backs this answer. FALSE means only the present rate is on record for this country, so an earlier change would not be visible here. |
| effectiveTo | Yes | ISO date that record closed, or null if it is still open |
| relatedFact | No | One sourced background fact about the country's consumption tax; the figures do not depend on it. Absent when no sourced fact fits. |
| standardRate | Yes | Standard rate in force on that date, as a fraction (0.24 = 24%) |
| effectiveFrom | Yes | ISO date the dated record that answered took effect. A new record can open without the standard rate moving (a reduced-rate change, or a new instrument restating the same rate), so for when THIS rate took effect read rateSince |
| dataVerifiedOn | Yes | ISO date the rate data was last confirmed against the authority |
| standardRateDisplay | Yes | The same rate formatted for reading |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent, non-destructive, closed-world, so the safety profile is covered. The description adds genuine non-obvious behavior: the answer states whether a real dated change backs the result or only the present rate is on record, and that a sourced relatedFact may appear without affecting figures.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the purpose and the sibling alternative before elaborating. The country list is long but justifies why dated lookup matters; a sentence could still be trimmed without losing meaning.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With an output schema present, the description need not explain return values, yet it still flags the relatedFact field and the confidence distinction. Nothing needed to invoke this correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and both parameters have format, pattern and example documented in the schema. The description adds no syntax or format detail beyond what the schema already provides, so baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('look up the GST/VAT standard rate') with the crucial qualifier 'ON A GIVEN DATE, rather than today's rate', immediately separating it from the current-rate sibling. The date-scoped scope is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Names the trigger scenario ('reconciling or amending a past transaction, invoice or return') and explicitly routes the current-rate case to tax_rate_lookup. When-to-use and the alternative are both stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Look up one country's headline tax rates: GST/VAT standard and reduced rates, top personal income tax rate, and company tax rate — national rates for 193 countries, plus state and provincial sales tax for CA and US when you pass region. Use it for a single country; to see several countries side by side use compare_countries, and to apply GST/VAT to an amount use compute_gst_vat. Rates come from a fixed dataset verified against the national tax authority — every answer names its source and verification date, and an unsupported country returns a clear error rather than a guess. Results may include one sourced background fact (relatedFact); the figures do not depend on it.
| Name | Required | Description | Default |
|---|---|---|---|
| region | No | Optional state or province code, for sub-national sales tax. Held for CA (13 provinces and territories), US (51 states incl. DC). E.g. 'ON' (Ontario) with country CA, or 'CA' (California) with country US. Answered from that state's or province's own cited rate; US figures are the state rate only — local sales taxes are not included. | |
| country | Yes | 2-letter ISO 3166-1 code of the country to look up (case-insensitive) |
| Name | Required | Description |
|---|---|---|
| code | Yes | 2-letter ISO country code |
| region | No | Present only when region was passed: the state or provincial sales tax, with its OWN source and date |
| source | Yes | The national tax authority the figures were verified against (e.g. 'ATO — ato.gov.au') |
| country | Yes | Country name |
| sourceUrl | No | https link to the authority page the rate was verified against. Present only on rate answers backed by a verified ledger row — absent (never empty) otherwise, so its presence is itself the claim |
| taxFamily | Yes | Consumption-tax family, e.g. 'GST', 'VAT' or a non-VAT system like retail sales tax |
| disclaimer | Yes | General-information note that must accompany any figure shown to a person |
| mayBeStale | Yes | True once the verification date is over a year old — re-confirm with the authority |
| companyRate | Yes | Headline company tax rate (display string) |
| relatedFact | No | One sourced background fact about the country's consumption tax; the figures do not depend on it. Absent when no sourced fact fits. |
| reducedRates | Yes | Reduced rates as fractions; empty when none |
| standardRate | Yes | Standard consumption-tax rate as a fraction (0.1 = 10%) |
| taxLocalName | Yes | The tax's local name, e.g. 'GST', 'USt' |
| incomeTopRate | Yes | Top personal income tax rate (display string; may note surcharges) |
| dataVerifiedOn | Yes | ISO date the rate data was last confirmed against the authority |
| standardRateDisplay | Yes | Standard rate formatted for display |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare the read-only, idempotent, closed-world, non-destructive profile, but the description adds real behavioral context: a fixed dataset verified against national tax authorities, answers that name their source and verification date, and a clear error for unsupported countries instead of a guess. It also flags that a sourced relatedFact is non-load-bearing for the figures.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The scope statement, sub-national region behavior, sibling routing, and data-provenance caveat are all front-loaded and dense with no filler. Each clause carries decision-relevant information for the agent.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With an output schema present, return-value shape needn't be explained, and the description still covers scope, the region caveat (state rate only, no local taxes), error behavior for unsupported countries, and provenance. Nothing needed to invoke it correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3; the schema already documents the 2-letter ISO country code and the region code's CA/US applicability. The description only restates that region yields CA/US sub-national sales tax without adding syntax or edge-case detail beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb+resource ('Look up one country's headline tax rates') and enumerates exactly which rates are returned (GST/VAT standard and reduced, top personal income tax, company tax). It also names the sibling tools it is not, so an agent can distinguish it from compare_countries and compute_gst_vat without opening any schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit routing: 'Use it for a single country; to see several countries side by side use compare_countries, and to apply GST/VAT to an amount use compute_gst_vat.' Both the when-to-use condition and the two alternatives with their own selection conditions are stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
income_tax_estimate5 fields changedInput schema / properties / age / descriptionPrevious value: -"Finland only: age at the end of the tax year. Changes the employee pension and unemployment contributions and, from 66, the earned-income credit; omit to assume a working age of 18–52"New value: +"Finland only: age at the end of the tax year. Changes the employee pension and unemployment contributions and, from 66, the earned-income credit; omit to assume a working age (18–64 from 2026, when the 53–62 pension surcharge ended; 18–52 for 2025)"Input schema / properties / incomeTypeAdded value: +{
+ "description": "What the income is: \"employment\" (salary or wages, the default) or \"self-employed\" (freelance or sole-trader profit after business expenses). Countries that do not model self-employed income refuse it with what differs instead of returning the employment figure",
+ "enum": [
+ "employment",
+ "self-employed"
+ ],
+ "type": "string"
+}Input schema / properties / taxYear / descriptionPrevious value: -"Tax-year label as the country uses it, e.g. '2025-26' (AU/NZ/GB/IN) or '2026' (calendar-year countries); omit for the current tax year. An unknown year is refused with the years on file"New value: +"Tax year as people write it, e.g. '2026-27' or '2026/27' (AU/NZ/GB/IN), '2026' (calendar-year countries), 'YA 2027' (Singapore), 'Tax Year 2027' (Pakistan, which names a year by its end); omit for the current tax year. A year not on file is refused with the years on file"Output schema / properties / assumptions / descriptionPrevious value: -"Assumptions the figures depend on — relay them with the numbers"New value: +"Assumptions the figures depend on — relay them with the numbers; the first is always the income basis"Output schema / properties / incomeBasisAdded value: +{
+ "description": "What income the figure was computed for: employment (employee-only items applied), self-employed, or any (nothing depends on the income type). The first assumption says the same in words",
+ "enum": [
+ "employment",
+ "self-employed",
+ "any"
+ ],
+ "type": "string"
+}cgt_estimate43 fields changedInput schema / properties / assetAdded value: +{
+ "default": "shares",
+ "description": "What was sold: 'shares' (shares and funds) or 'property' (real estate). Rules differ by asset in many countries",
+ "enum": [
+ "shares",
+ "property"
+ ],
+ "type": "string"
+}Input schema / properties / capitalLosses / descriptionPrevious value: -"Capital losses to offset, in AUD — applied against the gross gain before any discount"New value: +"Capital losses to offset — applied before any discount; FI: from this year or carried forward (five years)"Input schema / properties / costBase / descriptionPrevious value: -"Cost base in AUD — what the asset cost, including eligible incidental costs"New value: +"What the asset cost, in local currency, including eligible incidental costs. Required except for FI, where omitting it uses the deemed acquisition cost (pass FI buying and selling costs as saleExpenses)"Input schema / properties / countryAdded value: +{
+ "default": "AU",
+ "description": "2-letter ISO code of a covered country (upper case); defaults to AU",
+ "enum": [
+ "AE",
+ "AR",
+ "AT",
+ "AU",
+ "BE",
+ "BG",
+ "BR",
+ "CA",
+ "CH",
+ "CL",
+ "CN",
+ "CO",
+ "CY",
+ "CZ",
+ "DE",
+ "DK",
+ "EE",
+ "EG",
+ "ES",
+ "FI",
+ "FR",
+ "GB",
+ "GH",
+ "GR",
+ "GT",
+ "HK",
+ "HR",
+ "HU",
+ "ID",
+ "IE",
+ "IL",
+ "IN",
+ "IS",
+ "IT",
+ "JM",
+ "JP",
+ "KE",
+ "KR",
+ "LI",
+ "LK",
+ "LT",
+ "LU",
+ "LV",
+ "MT",
+ "MU",
+ "MX",
+ "MY",
+ "NG",
+ "NL",
+ "NO",
+ "NZ",
+ "PH",
+ "PK",
+ "PL",
+ "PT",
+ "QA",
+ "RO",
+ "RS",
+ "RU",
+ "SA",
+ "SE",
+ "SG",
+ "SI",
+ "SK",
+ "TR",
+ "TW",
+ "TZ",
+ "UA",
+ "UG",
+ "US",
+ "ZA"
+ ],
+ "type": "string"
+}Input schema / properties / heldMoreThan12Months / descriptionPrevious value: -"True when the asset was held over 12 months, which halves the taxable gain (the 50% CGT discount)"New value: +"True when the asset was held at least 12 months (e.g. the AU 50% discount, the US long-term rate). Shorthand for holdingMonths: true = 12, false = 0"Input schema / properties / holdingMonthsAdded value: +{
+ "description": "Whole months the asset was held; overrides heldMoreThan12Months",
+ "minimum": 0,
+ "type": "integer"
+}Input schema / properties / income / descriptionPrevious value: -"Other taxable income for the year in AUD (salary etc.) — sets the marginal rate the gain stacks on"New value: +"Other taxable income for the year, in local currency — sets the marginal rate where the gain is taxed as income (e.g. AU, US short-term). Required where the rule needs it; the answer says so"Input schema / properties / otherCapitalIncomeAdded value: +{
+ "default": 0,
+ "description": "FI: other capital income this year (dividends, rent, other gains) — decides how much of the gain falls above the 30 000 € threshold",
+ "minimum": 0,
+ "type": "number"
+}Input schema / properties / proceeds / descriptionPrevious value: -"Sale price of the asset in AUD"New value: +"Sale price of the asset, in local currency"Input schema / properties / saleExpensesAdded value: +{
+ "default": 0,
+ "description": "FI: brokerage, fees and other costs of buying and selling",
+ "minimum": 0,
+ "type": "number"
+}Input schema / properties / taxYearAdded value: +{
+ "description": "FI: calendar tax year like '2026'; omit for the current year",
+ "pattern": "^\\d{4}$",
+ "type": "string"
+}Input schema / properties / totalProceedsThisYearAdded value: +{
+ "description": "FI: the year's total sale prices, this sale included, for the 1 000 € small-disposals rule; omit when this is the only sale",
+ "minimum": 0,
+ "type": "number"
+}Input schema / properties / yearsHeldAdded value: +{
+ "description": "FI: whole years owned — 10 or more raises the deemed acquisition cost from 20% to 40% of the price",
+ "minimum": 0,
+ "type": "number"
+}Input schema / requiredPrevious value: -[
- "income",
- "proceeds",
- "costBase",
- "heldMoreThan12Months"
-]New value: +[
+ "proceeds"
+]Output schema / properties / assumptionsAdded value: +{
+ "description": "Assumptions the answer depends on — relay them with the figure",
+ "items": {
+ "type": "string"
+ },
+ "type": "array"
+}Output schema / properties / cgtPayable / descriptionPrevious value: -"Extra tax caused by the gain (AUD)"New value: +"Extra tax caused by the gain, in local currency; null when rule-only"Output schema / properties / cgtPayable / typePrevious value: -"number"New value: +[
+ "number",
+ "null"
+]Output schema / properties / costDeductedAdded value: +{
+ "description": "FI: the cost deducted from the price",
+ "type": "number"
+}Output schema / properties / country / descriptionPrevious value: -"Always AU — this tool is Australia-only"New value: +"Country estimated (2-letter ISO code)"Output schema / properties / country / enumRemoved value: -[
- "AU"
-]Output schema / properties / currencyAdded value: +{
+ "description": "Currency of every monetary field",
+ "type": "string"
+}Output schema / properties / discountApplied / descriptionPrevious value: -"Whether the 50% discount halved the taxable gain"New value: +"Whether a discount or inclusion rate reduced the taxable gain (e.g. the AU 50% discount). Always false for FI"Output schema / properties / exemptionAppliedAdded value: +{
+ "description": "Annual exempt amount or allowance used, where there is one",
+ "type": [
+ "number",
+ "null"
+ ]
+}Output schema / properties / grossGain / descriptionPrevious value: -"Proceeds minus cost base, floored at 0 (AUD)"New value: +"Proceeds minus cost (FI: minus the larger of actual or deemed cost). Floored at 0, local currency"Output schema / properties / grossGain / typePrevious value: -"number"New value: +[
+ "number",
+ "null"
+]Output schema / properties / lossAdded value: +{
+ "description": "FI: the loss on this sale, if any (only ever from the actual cost)",
+ "type": "number"
+}Output schema / properties / lossDeductibleAdded value: +{
+ "description": "FI: whether that loss can be deducted",
+ "type": "boolean"
+}Output schema / properties / lossOffset / descriptionPrevious value: -"Capital losses actually applied (AUD)"New value: +"Capital losses actually applied"Output schema / properties / lossOffset / typePrevious value: -"number"New value: +[
+ "number",
+ "null"
+]Output schema / properties / methodAdded value: +{
+ "description": "FI: whether the actual cost or the deemed acquisition cost was deducted",
+ "enum": [
+ "actual",
+ "deemed"
+ ],
+ "type": "string"
+}Output schema / properties / notesAdded value: +{
+ "description": "FI: rules that decided the answer, in plain words",
+ "items": {
+ "type": "string"
+ },
+ "type": "array"
+}Output schema / properties / reasonAdded value: +{
+ "description": "Why no figure was computed (rule-only), in plain words",
+ "type": [
+ "string",
+ "null"
+ ]
+}Output schema / properties / relatedFactAdded value: +{
+ "additionalProperties": false,
+ "description": "One sourced background fact about the country's capital gains tax; the figures do not depend on it. Absent when no sourced fact fits.",
+ "properties": {
+ "context": {
+ "description": "Present on a state or provincial answer: the fact is about the country as a whole",
+ "enum": [
+ "national"
+ ],
+ "type": "string"
+ },
+ "country": {
+ "description": "2-letter ISO code of the country the fact is about",
+ "type": "string"
+ },
+ "detail": {
+ "description": "Longer supporting detail, when the corpus has it",
+ "type": "string"
+ },
+ "fact": {
+ "description": "The fact, in one or two sentences",
+ "type": "string"
+ },
+ "kind": {
+ "description": "'origin' = when the tax began and what it replaced; 'anniversary' = the same, on the anniversary of its start date; 'story' = a dated story from the facts corpus",
+ "enum": [
+ "origin",
+ "story",
+ "anniversary"
+ ],
+ "type": "string"
+ },
+ "more": {
+ "description": "The tool that returns the full sourced fact set for this country",
+ "enum": [
+ "tax_facts"
+ ],
+ "type": "string"
+ },
+ "sourceName": {
+ "description": "Who the fact is sourced to",
+ "type": "string"
+ },
+ "sourceUrl": {
+ "description": "Link to that source — always present",
+ "type": "string"
+ },
+ "topic": {
+ "description": "Which tax the fact is about",
+ "enum": [
+ "gst",
+ "income",
+ "company",
+ "cgt",
+ "super",
+ "studentloan",
+ "general"
+ ],
+ "type": "string"
+ },
+ "verifiedDate": {
+ "description": "ISO date the fact was last checked against its source, when recorded",
+ "type": "string"
+ }
+ },
+ "required": [
+ "kind",
+ "topic",
+ "country",
+ "fact",
+ "sourceName",
+ "sourceUrl",
+ "more"
+ ],
+ "type": "object"
+}Output schema / properties / ruleAdded value: +{
+ "description": "The country's rule as written, for relaying — especially when status is rule-only",
+ "properties": {
+ "annualExemption": {
+ "type": "string"
+ },
+ "holdingPeriod": {
+ "type": "string"
+ },
+ "mainResidence": {
+ "type": "string"
+ },
+ "notes": {
+ "type": "string"
+ },
+ "rule": {
+ "type": "string"
+ }
+ },
+ "type": [
+ "object",
+ "null"
+ ]
+}Output schema / properties / smallDisposalsExemptAdded value: +{
+ "description": "FI: true when the year's sale prices total 1 000 € or less, making every gain tax-free",
+ "type": "boolean"
+}Output schema / properties / sourceUrlAdded value: +{
+ "description": "https link to the authority page the rate was verified against. Present only on rate answers backed by a verified ledger row — absent (never empty) otherwise, so its presence is itself the claim",
+ "type": "string"
+}Output schema / properties / statusAdded value: +{
+ "description": "'computed' = a figure; 'rule-only' = the rule text and the reason no figure is given (cgtPayable and taxableGain are then null)",
+ "enum": [
+ "computed",
+ "rule-only"
+ ],
+ "type": "string"
+}Output schema / properties / stepAdded value: +{
+ "description": "Which holding-period step applied, when the rule has steps",
+ "type": [
+ "string",
+ "null"
+ ]
+}Output schema / properties / taxYear / descriptionPrevious value: -"Financial year whose brackets were used"New value: +"Tax year whose rules were used, when the rule is year-based"Output schema / properties / taxYear / typePrevious value: -"string"New value: +[
+ "string",
+ "null"
+]Output schema / properties / taxableGain / descriptionPrevious value: -"Gain added on top of other income (AUD)"New value: +"Gain the tax was charged on; null when rule-only"Output schema / properties / taxableGain / typePrevious value: -"number"New value: +[
+ "number",
+ "null"
+]Output schema / requiredPrevious value: -[
- "country",
- "taxYear",
- "grossGain",
- "lossOffset",
- "discountApplied",
- "taxableGain",
- "cgtPayable",
- "source",
- "dataVerifiedOn",
- "mayBeStale",
- "disclaimer"
-]New value: +[
+ "country",
+ "status",
+ "taxYear",
+ "grossGain",
+ "lossOffset",
+ "discountApplied",
+ "taxableGain",
+ "cgtPayable",
+ "source",
+ "dataVerifiedOn",
+ "mayBeStale",
+ "disclaimer"
+]company_tax_estimate11 fields changedInput schema / properties / country / descriptionPrevious value: -"Country with source-verified company-tax data"New value: +"2-letter ISO code of a covered country (upper case)"Input schema / properties / country / enumPrevious value: -[
- "AU",
- "US",
- "GB",
- "IN",
- "CA"
-]New value: +[
+ "AD",
+ "AE",
+ "AG",
+ "AL",
+ "AM",
+ "AO",
+ "AR",
+ "AT",
+ "AU",
+ "AZ",
+ "BA",
+ "BB",
+ "BE",
+ "BF",
+ "BG",
+ "BH",
+ "BJ",
+ "BN",
+ "BR",
+ "BS",
+ "BT",
+ "BW",
+ "BZ",
+ "CA",
+ "CD",
+ "CG",
+ "CH",
+ "CI",
+ "CL",
+ "CM",
+ "CN",
+ "CO",
+ "CR",
+ "CV",
+ "CY",
+ "CZ",
+ "DE",
+ "DJ",
+ "DK",
+ "DM",
+ "DO",
+ "EC",
+ "EE",
+ "EG",
+ "ES",
+ "FI",
+ "FJ",
+ "FR",
+ "GA",
+ "GB",
+ "GD",
+ "GE",
+ "GH",
+ "GR",
+ "GT",
+ "HK",
+ "HN",
+ "HR",
+ "HT",
+ "HU",
+ "ID",
+ "IE",
+ "IL",
+ "IN",
+ "IS",
+ "IT",
+ "JM",
+ "JO",
+ "JP",
+ "KE",
+ "KN",
+ "KR",
+ "KW",
+ "KZ",
+ "LC",
+ "LI",
+ "LK",
+ "LR",
+ "LT",
+ "LU",
+ "LV",
+ "MA",
+ "MC",
+ "MD",
+ "ME",
+ "MK",
+ "MN",
+ "MO",
+ "MR",
+ "MT",
+ "MU",
+ "MV",
+ "MX",
+ "MY",
+ "NA",
+ "NG",
+ "NL",
+ "NO",
+ "NZ",
+ "OM",
+ "PA",
+ "PE",
+ "PG",
+ "PH",
+ "PK",
+ "PL",
+ "PT",
+ "PY",
+ "QA",
+ "RO",
+ "RS",
+ "RU",
+ "SA",
+ "SC",
+ "SE",
+ "SG",
+ "SI",
+ "SK",
+ "SL",
+ "SM",
+ "SN",
+ "SZ",
+ "TG",
+ "TH",
+ "TN",
+ "TR",
+ "TT",
+ "TW",
+ "UA",
+ "UG",
+ "US",
+ "UY",
+ "UZ",
+ "VC",
+ "VN",
+ "WS",
+ "ZA",
+ "ZM",
+ "ZW"
+]Input schema / properties / smallBusiness / descriptionPrevious value: -"Apply the small-business/concessional rate — only honoured where it covers all income (AU base-rate entity, IN s.115BAA); GB/CA thresholds are noted instead"New value: +"Apply the small-company rate — honoured only where it covers all income (AU, IN); elsewhere the reduced rate is noted instead"Output schema / properties / country / descriptionPrevious value: -"Country estimated"New value: +"Country estimated (2-letter ISO code)"Output schema / properties / country / enumRemoved value: -[
- "AU",
- "US",
- "GB",
- "IN",
- "CA"
-]Output schema / properties / effectiveFromAdded value: +{
+ "description": "ISO date the rate set in use took effect",
+ "type": "string"
+}Output schema / properties / relatedFactAdded value: +{
+ "additionalProperties": false,
+ "description": "One sourced background fact about the country's company tax; the figures do not depend on it. Absent when no sourced fact fits.",
+ "properties": {
+ "context": {
+ "description": "Present on a state or provincial answer: the fact is about the country as a whole",
+ "enum": [
+ "national"
+ ],
+ "type": "string"
+ },
+ "country": {
+ "description": "2-letter ISO code of the country the fact is about",
+ "type": "string"
+ },
+ "detail": {
+ "description": "Longer supporting detail, when the corpus has it",
+ "type": "string"
+ },
+ "fact": {
+ "description": "The fact, in one or two sentences",
+ "type": "string"
+ },
+ "kind": {
+ "description": "'origin' = when the tax began and what it replaced; 'anniversary' = the same, on the anniversary of its start date; 'story' = a dated story from the facts corpus",
+ "enum": [
+ "origin",
+ "story",
+ "anniversary"
+ ],
+ "type": "string"
+ },
+ "more": {
+ "description": "The tool that returns the full sourced fact set for this country",
+ "enum": [
+ "tax_facts"
+ ],
+ "type": "string"
+ },
+ "sourceName": {
+ "description": "Who the fact is sourced to",
+ "type": "string"
+ },
+ "sourceUrl": {
+ "description": "Link to that source — always present",
+ "type": "string"
+ },
+ "topic": {
+ "description": "Which tax the fact is about",
+ "enum": [
+ "gst",
+ "income",
+ "company",
+ "cgt",
+ "super",
+ "studentloan",
+ "general"
+ ],
+ "type": "string"
+ },
+ "verifiedDate": {
+ "description": "ISO date the fact was last checked against its source, when recorded",
+ "type": "string"
+ }
+ },
+ "required": [
+ "kind",
+ "topic",
+ "country",
+ "fact",
+ "sourceName",
+ "sourceUrl",
+ "more"
+ ],
+ "type": "object"
+}Output schema / properties / smallCompanyRateAdded value: +{
+ "description": "The small-company rate on file, when there is one",
+ "type": "number"
+}Output schema / properties / sourceUrlAdded value: +{
+ "description": "https link to the authority page the rate was verified against. Present only on rate answers backed by a verified ledger row — absent (never empty) otherwise, so its presence is itself the claim",
+ "type": "string"
+}Output schema / properties / standardRateAdded value: +{
+ "description": "The standard (headline) rate, as a fraction",
+ "type": "number"
+}Output schema / properties / usedSmallRateAdded value: +{
+ "description": "Whether the small-company rate was applied",
+ "type": "boolean"
+}compare_countries9 fields changedInput schema / properties / incomeAdded value: +{
+ "description": "Optional gross annual income, before tax. The same number is applied in EACH country's own local currency — it is NOT converted (120000 means AUD 120,000 in AU, GBP 120,000 in GB and SGD 120,000 in SG). When given, each row adds an income-tax estimate for that income",
+ "examples": [
+ 120000
+ ],
+ "minimum": 0,
+ "type": "number"
+}Input schema / properties / taxYearAdded value: +{
+ "description": "Optional, only with income: the tax-year label passed to the income-tax estimate for every country, e.g. '2025-26' (AU/NZ/GB/IN) or '2026' (calendar-year countries). Labels differ by country; a country without that year reports the years it has instead of a figure. Omit for each country's current tax year",
+ "type": "string"
+}Output schema / properties / relatedFactAdded value: +{
+ "additionalProperties": false,
+ "description": "One sourced background fact about the country's consumption tax; the figures do not depend on it. Absent when no sourced fact fits.",
+ "properties": {
+ "context": {
+ "description": "Present on a state or provincial answer: the fact is about the country as a whole",
+ "enum": [
+ "national"
+ ],
+ "type": "string"
+ },
+ "country": {
+ "description": "2-letter ISO code of the country the fact is about",
+ "type": "string"
+ },
+ "detail": {
+ "description": "Longer supporting detail, when the corpus has it",
+ "type": "string"
+ },
+ "fact": {
+ "description": "The fact, in one or two sentences",
+ "type": "string"
+ },
+ "kind": {
+ "description": "'origin' = when the tax began and what it replaced; 'anniversary' = the same, on the anniversary of its start date; 'story' = a dated story from the facts corpus",
+ "enum": [
+ "origin",
+ "story",
+ "anniversary"
+ ],
+ "type": "string"
+ },
+ "more": {
+ "description": "The tool that returns the full sourced fact set for this country",
+ "enum": [
+ "tax_facts"
+ ],
+ "type": "string"
+ },
+ "sourceName": {
+ "description": "Who the fact is sourced to",
+ "type": "string"
+ },
+ "sourceUrl": {
+ "description": "Link to that source — always present",
+ "type": "string"
+ },
+ "topic": {
+ "description": "Which tax the fact is about",
+ "enum": [
+ "gst",
+ "income",
+ "company",
+ "cgt",
+ "super",
+ "studentloan",
+ "general"
+ ],
+ "type": "string"
+ },
+ "verifiedDate": {
+ "description": "ISO date the fact was last checked against its source, when recorded",
+ "type": "string"
+ }
+ },
+ "required": [
+ "kind",
+ "topic",
+ "country",
+ "fact",
+ "sourceName",
+ "sourceUrl",
+ "more"
+ ],
+ "type": "object"
+}Output schema / properties / rows / items / properties / dataVerifiedOnAdded value: +{
+ "description": "ISO date this country's rate was last confirmed against the authority",
+ "type": "string"
+}Output schema / properties / rows / items / properties / incomeTaxEstimateAdded value: +{
+ "additionalProperties": false,
+ "description": "Present only when income was passed: income_tax_estimate's result for this country, in this country's own currency",
+ "properties": {
+ "assumptions": {
+ "description": "Assumptions the figures depend on",
+ "items": {
+ "type": "string"
+ },
+ "type": "array"
+ },
+ "averageRate": {
+ "description": "Total tax over gross, as a fraction",
+ "type": "number"
+ },
+ "currency": {
+ "description": "Currency of every monetary field",
+ "type": "string"
+ },
+ "dataVerifiedOn": {
+ "description": "ISO date that source was last checked",
+ "type": "string"
+ },
+ "gross": {
+ "description": "Gross annual income used",
+ "type": "number"
+ },
+ "incomeTax": {
+ "description": "Income tax before levies and offsets",
+ "type": "number"
+ },
+ "mayBeStale": {
+ "description": "True when that date is over a year old, or the source is unverified",
+ "type": "boolean"
+ },
+ "reason": {
+ "description": "Why there is no figure (not-covered / unavailable only)",
+ "type": "string"
+ },
+ "source": {
+ "description": "The income-tax source for this country — says 'not verified' when it was not",
+ "type": "string"
+ },
+ "sourceUrl": {
+ "description": "https link to the income-tax source — present only when verified",
+ "type": "string"
+ },
+ "status": {
+ "description": "'computed' = figures below; 'not-covered' = income tax is not estimated for this country; 'unavailable' = covered, but not for these inputs (reason says why)",
+ "enum": [
+ "computed",
+ "not-covered",
+ "unavailable"
+ ],
+ "type": "string"
+ },
+ "takeHome": {
+ "description": "Gross minus total tax",
+ "type": "number"
+ },
+ "taxYear": {
+ "description": "Tax year the brackets belong to",
+ "type": "string"
+ },
+ "totalTax": {
+ "description": "Total tax after levies and offsets",
+ "type": "number"
+ }
+ },
+ "required": [
+ "status"
+ ],
+ "type": "object"
+}Output schema / properties / rows / items / properties / mayBeStaleAdded value: +{
+ "description": "True when that date is over a year old, or the row is unverified",
+ "type": "boolean"
+}Output schema / properties / rows / items / properties / source / descriptionPrevious value: -"National tax authority for this row"New value: +"Authority this country's GST/VAT rate was verified against — says 'citation pending — not verified' when it was not"Output schema / properties / rows / items / properties / sourceUrlAdded value: +{
+ "description": "https link to the authority page for the GST/VAT rate — present only for verified rows",
+ "type": "string"
+}Output schema / properties / sourceUrlAdded value: +{
+ "description": "https link to the authority page the rate was verified against. Present only on rate answers backed by a verified ledger row — absent (never empty) otherwise, so its presence is itself the claim",
+ "type": "string"
+}compute_gst_vat5 fields changedInput schema / properties / regionAdded value: +{
+ "description": "Optional state or province code, for sub-national sales tax. Held for CA (13 provinces and territories), US (51 states incl. DC). E.g. 'ON' (Ontario) with country CA, or 'CA' (California) with country US. Answered from that state's or province's own cited rate; US figures are the state rate only — local sales taxes are not included.",
+ "examples": [
+ "ON",
+ "CA",
+ "NY"
+ ],
+ "maxLength": 2,
+ "minLength": 2,
+ "pattern": "^[A-Za-z]{2}$",
+ "type": "string"
+}Output schema / properties / regionAdded value: +{
+ "description": "State or province whose rate was applied — present only when region was passed",
+ "type": "string"
+}Output schema / properties / regionNameAdded value: +{
+ "description": "What applies in that region, in a sentence",
+ "type": "string"
+}Output schema / properties / relatedFactAdded value: +{
+ "additionalProperties": false,
+ "description": "One sourced background fact about the country's consumption tax; the figures do not depend on it. Absent when no sourced fact fits.",
+ "properties": {
+ "context": {
+ "description": "Present on a state or provincial answer: the fact is about the country as a whole",
+ "enum": [
+ "national"
+ ],
+ "type": "string"
+ },
+ "country": {
+ "description": "2-letter ISO code of the country the fact is about",
+ "type": "string"
+ },
+ "detail": {
+ "description": "Longer supporting detail, when the corpus has it",
+ "type": "string"
+ },
+ "fact": {
+ "description": "The fact, in one or two sentences",
+ "type": "string"
+ },
+ "kind": {
+ "description": "'origin' = when the tax began and what it replaced; 'anniversary' = the same, on the anniversary of its start date; 'story' = a dated story from the facts corpus",
+ "enum": [
+ "origin",
+ "story",
+ "anniversary"
+ ],
+ "type": "string"
+ },
+ "more": {
+ "description": "The tool that returns the full sourced fact set for this country",
+ "enum": [
+ "tax_facts"
+ ],
+ "type": "string"
+ },
+ "sourceName": {
+ "description": "Who the fact is sourced to",
+ "type": "string"
+ },
+ "sourceUrl": {
+ "description": "Link to that source — always present",
+ "type": "string"
+ },
+ "topic": {
+ "description": "Which tax the fact is about",
+ "enum": [
+ "gst",
+ "income",
+ "company",
+ "cgt",
+ "super",
+ "studentloan",
+ "general"
+ ],
+ "type": "string"
+ },
+ "verifiedDate": {
+ "description": "ISO date the fact was last checked against its source, when recorded",
+ "type": "string"
+ }
+ },
+ "required": [
+ "kind",
+ "topic",
+ "country",
+ "fact",
+ "sourceName",
+ "sourceUrl",
+ "more"
+ ],
+ "type": "object"
+}Output schema / properties / sourceUrlAdded value: +{
+ "description": "https link to the authority page the rate was verified against. Present only on rate answers backed by a verified ledger row — absent (never empty) otherwise, so its presence is itself the claim",
+ "type": "string"
+}income_tax_estimate32 fields changedInput schema / properties / ageAdded value: +{
+ "description": "Finland only: age at the end of the tax year. Changes the employee pension and unemployment contributions and, from 66, the earned-income credit; omit to assume a working age of 18–52",
+ "maximum": 100,
+ "minimum": 15,
+ "type": "integer"
+}Input schema / properties / churchAdded value: +{
+ "default": "none",
+ "description": "Finland only: parish membership, for church tax. Needs `municipality`, because each parish sets its own rate",
+ "enum": [
+ "none",
+ "evangelical-lutheran",
+ "orthodox"
+ ],
+ "type": "string"
+}Input schema / properties / country / descriptionPrevious value: -"Country with bracket data: AU (Australia) or NZ (New Zealand)"New value: +"2-letter ISO code of a covered country (upper case)"Input schema / properties / country / enumPrevious value: -[
- "AU",
- "NZ"
-]New value: +[
+ "AE",
+ "AR",
+ "AT",
+ "AU",
+ "BD",
+ "BE",
+ "BR",
+ "CA",
+ "CH",
+ "CL",
+ "CN",
+ "CO",
+ "CR",
+ "CZ",
+ "DE",
+ "DK",
+ "EE",
+ "EG",
+ "ES",
+ "FI",
+ "FR",
+ "GB",
+ "GR",
+ "GT",
+ "HU",
+ "ID",
+ "IE",
+ "IL",
+ "IN",
+ "IS",
+ "IT",
+ "JM",
+ "JP",
+ "KE",
+ "KR",
+ "LU",
+ "LV",
+ "MX",
+ "MY",
+ "NG",
+ "NL",
+ "NO",
+ "NZ",
+ "PH",
+ "PK",
+ "PL",
+ "PT",
+ "SA",
+ "SE",
+ "SG",
+ "SI",
+ "SK",
+ "TH",
+ "TR",
+ "US",
+ "VN",
+ "ZA"
+]Input schema / properties / income / descriptionPrevious value: -"Gross annual income in local currency (AUD for AU, NZD for NZ), before tax"New value: +"Gross annual income in local currency, before tax"Input schema / properties / municipalityAdded value: +{
+ "description": "Finland only: the municipality (kunta) of residence on 31 December of the previous year, in Finnish or Swedish, e.g. 'Helsinki', 'Espoo', 'Tampere', 'Åbo'. Sets the municipal and parish tax rates; omit to use the national average municipal rate",
+ "maxLength": 60,
+ "type": "string"
+}Input schema / properties / regionAdded value: +{
+ "description": "Optional state, province or nation code, where the country's scheme has one: CA: 13 regions, e.g. AB, BC, MB; ES: 3 regions, e.g. AN, CT, MD; GB: SCT (Scotland); US: 51 regions, e.g. AK, AL, AR",
+ "maxLength": 8,
+ "type": "string"
+}Input schema / properties / taxYear / descriptionPrevious value: -"Financial-year label like '2025-26'; omit to use the current financial year in that country's timezone"New value: +"Tax-year label as the country uses it, e.g. '2025-26' (AU/NZ/GB/IN) or '2026' (calendar-year countries); omit for the current tax year. An unknown year is refused with the years on file"Input schema / properties / taxYear / examplesRemoved value: -[
- "2025-26"
-]Input schema / properties / taxYear / patternRemoved value: -"^\\d{4}-\\d{2}$"Output schema / properties / assumptionsAdded value: +{
+ "description": "Assumptions the figures depend on — relay them with the numbers",
+ "items": {
+ "type": "string"
+ },
+ "type": "array"
+}Output schema / properties / averageRateAdded value: +{
+ "description": "Total tax over gross, as a fraction",
+ "type": "number"
+}Output schema / properties / churchRateAdded value: +{
+ "description": "Finland: church-tax rate applied, as a fraction (0 for a non-member)",
+ "type": "number"
+}Output schema / properties / country / descriptionPrevious value: -"Country estimated"New value: +"Country estimated (2-letter ISO code)"Output schema / properties / country / enumRemoved value: -[
- "AU",
- "NZ"
-]Output schema / properties / currency / descriptionPrevious value: -"Currency of every monetary field (AUD or NZD)"New value: +"Currency of every monetary field"Output schema / properties / leviesAdded value: +{
+ "description": "Charges on top of the offset tax, by name (social contributions, regional tax) — empty array when none apply",
+ "items": {
+ "properties": {
+ "amount": {
+ "type": "number"
+ },
+ "name": {
+ "type": "string"
+ }
+ },
+ "required": [
+ "name",
+ "amount"
+ ],
+ "type": "object"
+ },
+ "type": "array"
+}Output schema / properties / lito / descriptionPrevious value: -"Low Income Tax Offset applied (AU only; 0 otherwise)"New value: +"Kept for compatibility: AU Low Income Tax Offset only, 0 for every other country. See `offsets` for the general figure."Output schema / properties / marginalRateAdded value: +{
+ "description": "Marginal rate on the next unit of income, as a fraction",
+ "type": "number"
+}Output schema / properties / medicareLevy / descriptionPrevious value: -"Medicare levy (AU only; 0 for NZ)"New value: +"Kept for compatibility: AU Medicare levy only, 0 for every other country. See `levies` for the general figure."Output schema / properties / municipalRateAdded value: +{
+ "description": "Finland: municipal income-tax rate applied, as a fraction",
+ "type": "number"
+}Output schema / properties / municipalityAdded value: +{
+ "description": "Finland: the municipality whose rates were used, or \"national average\"",
+ "type": "string"
+}Output schema / properties / offsetsAdded value: +{
+ "description": "Credits that reduced the tax, by name — empty array when none apply",
+ "items": {
+ "properties": {
+ "amount": {
+ "type": "number"
+ },
+ "name": {
+ "type": "string"
+ }
+ },
+ "required": [
+ "name",
+ "amount"
+ ],
+ "type": "object"
+ },
+ "type": "array"
+}Output schema / properties / regionAdded value: +{
+ "description": "State, province or nation whose tax was included — present only when region was passed",
+ "type": "string"
+}Output schema / properties / relatedFactAdded value: +{
+ "additionalProperties": false,
+ "description": "One sourced background fact about the country's income tax; the figures do not depend on it. Absent when no sourced fact fits.",
+ "properties": {
+ "context": {
+ "description": "Present on a state or provincial answer: the fact is about the country as a whole",
+ "enum": [
+ "national"
+ ],
+ "type": "string"
+ },
+ "country": {
+ "description": "2-letter ISO code of the country the fact is about",
+ "type": "string"
+ },
+ "detail": {
+ "description": "Longer supporting detail, when the corpus has it",
+ "type": "string"
+ },
+ "fact": {
+ "description": "The fact, in one or two sentences",
+ "type": "string"
+ },
+ "kind": {
+ "description": "'origin' = when the tax began and what it replaced; 'anniversary' = the same, on the anniversary of its start date; 'story' = a dated story from the facts corpus",
+ "enum": [
+ "origin",
+ "story",
+ "anniversary"
+ ],
+ "type": "string"
+ },
+ "more": {
+ "description": "The tool that returns the full sourced fact set for this country",
+ "enum": [
+ "tax_facts"
+ ],
+ "type": "string"
+ },
+ "sourceName": {
+ "description": "Who the fact is sourced to",
+ "type": "string"
+ },
+ "sourceUrl": {
+ "description": "Link to that source — always present",
+ "type": "string"
+ },
+ "topic": {
+ "description": "Which tax the fact is about",
+ "enum": [
+ "gst",
+ "income",
+ "company",
+ "cgt",
+ "super",
+ "studentloan",
+ "general"
+ ],
+ "type": "string"
+ },
+ "verifiedDate": {
+ "description": "ISO date the fact was last checked against its source, when recorded",
+ "type": "string"
+ }
+ },
+ "required": [
+ "kind",
+ "topic",
+ "country",
+ "fact",
+ "sourceName",
+ "sourceUrl",
+ "more"
+ ],
+ "type": "object"
+}Output schema / properties / separatelyWithheldAdded value: +{
+ "description": "Finland: employee pension and unemployment contributions for the year, to the cent — withheld by the employer on top of the tax card",
+ "type": "number"
+}Output schema / properties / sourceUrlAdded value: +{
+ "description": "https link to the authority page the rate was verified against. Present only on rate answers backed by a verified ledger row — absent (never empty) otherwise, so its presence is itself the claim",
+ "type": "string"
+}Output schema / properties / taxCardRateAdded value: +{
+ "description": "Finland: the withholding percentage (veroprosentti) Vero would put on the tax card — rounded up to the next half point. Employee pension and unemployment contributions are withheld on top of it",
+ "type": "number"
+}Output schema / properties / taxCardWithheldAdded value: +{
+ "description": "Finland: the tax the tax card covers for the year, to the cent (state, municipal, church, health insurance and YLE tax, less the credit)",
+ "type": "number"
+}Output schema / properties / taxYear / descriptionPrevious value: -"Financial year the brackets belong to"New value: +"Tax year the brackets belong to"Output schema / properties / taxableAdded value: +{
+ "description": "Income after any pre-band deduction (UK personal allowance, IN standard deduction, US standard deduction)",
+ "type": "number"
+}Output schema / requiredPrevious value: -[
- "country",
- "currency",
- "taxYear",
- "gross",
- "incomeTax",
- "medicareLevy",
- "lito",
- "totalTax",
- "takeHome",
- "source",
- "dataVerifiedOn",
- "mayBeStale",
- "disclaimer"
-]New value: +[
+ "country",
+ "currency",
+ "taxYear",
+ "gross",
+ "taxable",
+ "incomeTax",
+ "medicareLevy",
+ "lito",
+ "offsets",
+ "levies",
+ "totalTax",
+ "takeHome",
+ "source",
+ "dataVerifiedOn",
+ "mayBeStale",
+ "disclaimer"
+]student_loan_repayment2 fields changedOutput schema / properties / relatedFactAdded value: +{
+ "additionalProperties": false,
+ "description": "One sourced background fact about the country's study-loan repayment; the figures do not depend on it. Absent when no sourced fact fits.",
+ "properties": {
+ "context": {
+ "description": "Present on a state or provincial answer: the fact is about the country as a whole",
+ "enum": [
+ "national"
+ ],
+ "type": "string"
+ },
+ "country": {
+ "description": "2-letter ISO code of the country the fact is about",
+ "type": "string"
+ },
+ "detail": {
+ "description": "Longer supporting detail, when the corpus has it",
+ "type": "string"
+ },
+ "fact": {
+ "description": "The fact, in one or two sentences",
+ "type": "string"
+ },
+ "kind": {
+ "description": "'origin' = when the tax began and what it replaced; 'anniversary' = the same, on the anniversary of its start date; 'story' = a dated story from the facts corpus",
+ "enum": [
+ "origin",
+ "story",
+ "anniversary"
+ ],
+ "type": "string"
+ },
+ "more": {
+ "description": "The tool that returns the full sourced fact set for this country",
+ "enum": [
+ "tax_facts"
+ ],
+ "type": "string"
+ },
+ "sourceName": {
+ "description": "Who the fact is sourced to",
+ "type": "string"
+ },
+ "sourceUrl": {
+ "description": "Link to that source — always present",
+ "type": "string"
+ },
+ "topic": {
+ "description": "Which tax the fact is about",
+ "enum": [
+ "gst",
+ "income",
+ "company",
+ "cgt",
+ "super",
+ "studentloan",
+ "general"
+ ],
+ "type": "string"
+ },
+ "verifiedDate": {
+ "description": "ISO date the fact was last checked against its source, when recorded",
+ "type": "string"
+ }
+ },
+ "required": [
+ "kind",
+ "topic",
+ "country",
+ "fact",
+ "sourceName",
+ "sourceUrl",
+ "more"
+ ],
+ "type": "object"
+}Output schema / properties / sourceUrlAdded value: +{
+ "description": "https link to the authority page the rate was verified against. Present only on rate answers backed by a verified ledger row — absent (never empty) otherwise, so its presence is itself the claim",
+ "type": "string"
+}superannuation_estimate3 fields changedOutput schema / properties / assumptionAdded value: +{
+ "description": "A stated assumption that materially affects the figures, when one applies (e.g. no carried-forward concessional cap)",
+ "type": "string"
+}Output schema / properties / relatedFactAdded value: +{
+ "additionalProperties": false,
+ "description": "One sourced background fact about the country's superannuation; the figures do not depend on it. Absent when no sourced fact fits.",
+ "properties": {
+ "context": {
+ "description": "Present on a state or provincial answer: the fact is about the country as a whole",
+ "enum": [
+ "national"
+ ],
+ "type": "string"
+ },
+ "country": {
+ "description": "2-letter ISO code of the country the fact is about",
+ "type": "string"
+ },
+ "detail": {
+ "description": "Longer supporting detail, when the corpus has it",
+ "type": "string"
+ },
+ "fact": {
+ "description": "The fact, in one or two sentences",
+ "type": "string"
+ },
+ "kind": {
+ "description": "'origin' = when the tax began and what it replaced; 'anniversary' = the same, on the anniversary of its start date; 'story' = a dated story from the facts corpus",
+ "enum": [
+ "origin",
+ "story",
+ "anniversary"
+ ],
+ "type": "string"
+ },
+ "more": {
+ "description": "The tool that returns the full sourced fact set for this country",
+ "enum": [
+ "tax_facts"
+ ],
+ "type": "string"
+ },
+ "sourceName": {
+ "description": "Who the fact is sourced to",
+ "type": "string"
+ },
+ "sourceUrl": {
+ "description": "Link to that source — always present",
+ "type": "string"
+ },
+ "topic": {
+ "description": "Which tax the fact is about",
+ "enum": [
+ "gst",
+ "income",
+ "company",
+ "cgt",
+ "super",
+ "studentloan",
+ "general"
+ ],
+ "type": "string"
+ },
+ "verifiedDate": {
+ "description": "ISO date the fact was last checked against its source, when recorded",
+ "type": "string"
+ }
+ },
+ "required": [
+ "kind",
+ "topic",
+ "country",
+ "fact",
+ "sourceName",
+ "sourceUrl",
+ "more"
+ ],
+ "type": "object"
+}Output schema / properties / sourceUrlAdded value: +{
+ "description": "https link to the authority page the rate was verified against. Present only on rate answers backed by a verified ledger row — absent (never empty) otherwise, so its presence is itself the claim",
+ "type": "string"
+}tax_factstax_rate_as_oftax_rate_lookup4 fields changedInput schema / properties / regionAdded value: +{
+ "description": "Optional state or province code, for sub-national sales tax. Held for CA (13 provinces and territories), US (51 states incl. DC). E.g. 'ON' (Ontario) with country CA, or 'CA' (California) with country US. Answered from that state's or province's own cited rate; US figures are the state rate only — local sales taxes are not included.",
+ "examples": [
+ "ON",
+ "CA",
+ "NY"
+ ],
+ "maxLength": 2,
+ "minLength": 2,
+ "pattern": "^[A-Za-z]{2}$",
+ "type": "string"
+}Output schema / properties / regionAdded value: +{
+ "additionalProperties": false,
+ "description": "Present only when region was passed: the state or provincial sales tax, with its OWN source and date",
+ "properties": {
+ "code": {
+ "description": "State or province code",
+ "type": "string"
+ },
+ "combinedRate": {
+ "description": "What a buyer pays in total: in Canada the provincial rate plus the 5% GST (or the single HST); in the US the state rate (local taxes not included)",
+ "type": "number"
+ },
+ "dataVerifiedOn": {
+ "description": "ISO date the regional rate was last checked",
+ "type": "string"
+ },
+ "effectiveFrom": {
+ "description": "ISO date the rate took effect",
+ "type": "string"
+ },
+ "mayBeStale": {
+ "description": "True when that date is over a year old, or the rate is unverified",
+ "type": "boolean"
+ },
+ "name": {
+ "description": "What applies there, in a sentence",
+ "type": "string"
+ },
+ "source": {
+ "description": "Authority the regional rate was verified against — says 'not verified' when it was not",
+ "type": "string"
+ },
+ "sourceUrl": {
+ "description": "https link to the authority page — present only for verified rates",
+ "type": "string"
+ },
+ "standardRate": {
+ "description": "The state or provincial rate alone, as a fraction",
+ "type": "number"
+ },
+ "taxName": {
+ "description": "The tax's name, e.g. 'Ontario HST'",
+ "type": "string"
+ }
+ },
+ "required": [
+ "code",
+ "name",
+ "taxName",
+ "standardRate",
+ "combinedRate",
+ "effectiveFrom",
+ "source",
+ "dataVerifiedOn",
+ "mayBeStale"
+ ],
+ "type": "object"
+}Output schema / properties / relatedFactAdded value: +{
+ "additionalProperties": false,
+ "description": "One sourced background fact about the country's consumption tax; the figures do not depend on it. Absent when no sourced fact fits.",
+ "properties": {
+ "context": {
+ "description": "Present on a state or provincial answer: the fact is about the country as a whole",
+ "enum": [
+ "national"
+ ],
+ "type": "string"
+ },
+ "country": {
+ "description": "2-letter ISO code of the country the fact is about",
+ "type": "string"
+ },
+ "detail": {
+ "description": "Longer supporting detail, when the corpus has it",
+ "type": "string"
+ },
+ "fact": {
+ "description": "The fact, in one or two sentences",
+ "type": "string"
+ },
+ "kind": {
+ "description": "'origin' = when the tax began and what it replaced; 'anniversary' = the same, on the anniversary of its start date; 'story' = a dated story from the facts corpus",
+ "enum": [
+ "origin",
+ "story",
+ "anniversary"
+ ],
+ "type": "string"
+ },
+ "more": {
+ "description": "The tool that returns the full sourced fact set for this country",
+ "enum": [
+ "tax_facts"
+ ],
+ "type": "string"
+ },
+ "sourceName": {
+ "description": "Who the fact is sourced to",
+ "type": "string"
+ },
+ "sourceUrl": {
+ "description": "Link to that source — always present",
+ "type": "string"
+ },
+ "topic": {
+ "description": "Which tax the fact is about",
+ "enum": [
+ "gst",
+ "income",
+ "company",
+ "cgt",
+ "super",
+ "studentloan",
+ "general"
+ ],
+ "type": "string"
+ },
+ "verifiedDate": {
+ "description": "ISO date the fact was last checked against its source, when recorded",
+ "type": "string"
+ }
+ },
+ "required": [
+ "kind",
+ "topic",
+ "country",
+ "fact",
+ "sourceName",
+ "sourceUrl",
+ "more"
+ ],
+ "type": "object"
+}Output schema / properties / sourceUrlAdded value: +{
+ "description": "https link to the authority page the rate was verified against. Present only on rate answers backed by a verified ledger row — absent (never empty) otherwise, so its presence is itself the claim",
+ "type": "string"
+}student_loan_repaymentsuperannuation_estimatecgt_estimatecompany_tax_estimatecompare_countriescompute_gst_vatincome_tax_estimatetax_rate_lookupCited official data: tax, VAT, CPI, policy rates, wages, holidays, FX. 128 countries+EU, 7 regions.
Deterministic cross-border tax engine: PE, GAAR, Indian TP, rule-level lookup. Compiled law, no LLM.
Official tax law at the date of the facts, with official links: 9 European countries, EU, OECD.
European govt data, cited: rates, VAT, tax, wages, holidays, FX. 34 countries + EU; Germany free.
Add one secure layer between your agents and this server.
