N American govt data, cited to source: rates, VAT, tax, wages, holidays, FX. 10 countries; USA free.
Scored across 11 tools
Each tool addresses a distinct concern: minimum wage, employment cost, income tax, VAT, working days, holidays, series retrieval/history/snapshot, catalog listing, and settlement date. There is minor overlap between get_series and list_series, but their purposes are clearly differentiated.
The naming uses a mix of verbs: check_, compute_, count_, get_, list_, and the noun-based settlement_date. While each name is understandable, the lack of a uniform verb convention reduces consistency.
With 11 tools, the set is well-scoped for a reference-data server covering taxes, holidays, time series, and settlement calculations. It is neither too sparse nor overwhelming.
The toolset covers the primary read-only reference data operations: tax computations, holiday calendars, working-day calculations, series lookup, and settlement dates. Minor gaps like currency conversion or rate lookups could exist, but the current coverage is strong for the apparent domain.
PAID ($0.05). Compliance verdict: is a salary at, above or below the country's statutory minimum wage? Returns verdict, margin, the statutory floor and the legal instrument it rests on. Honest statuses when no enforceable floor exists or the period doesn't match the floor's period (cross-period conversion is never guessed). Pass api_key if you have one; otherwise the response explains how to pay via x402.
| Name | Required | Description | Default |
|---|---|---|---|
| amount | Yes | Wage to check, in the country's own currency | |
| period | Yes | Period the amount covers — must match the statutory floor's period | |
| api_key | No | API key (bypasses x402; metered for invoicing) | |
| country | Yes | ISO country code |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description properly discloses the tool's behavior: returns verdict, margin, statutory floor, legal instrument, and honest statuses. It also mentions the x402 payment or api_key, adding transparency about how results are obtained.
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 concise with four sentences covering purpose, return values, edge cases, and payment. It is front-loaded with the verdict statement, though the structure could be slightly improved by separating core purpose from payment details.
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?
The tool has no output schema, but the description adequately explains return values (verdict, margin, floor, legal instrument) and handles edge cases (missing floor, period mismatch). It covers legal dependence, which is critical for compliance tools.
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 parameters are well-documented in the schema. The description only adds minor context (e.g., 'country's own currency' and period matching), but does not significantly enhance understanding beyond what the schema provides.
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?
Description clearly states the tool checks if a salary meets minimum wage and returns verdict, margin, floor, and legal instrument. The name 'check_minimum_wage' aligns perfectly, and it is distinct from sibling tools like compute_income_tax.
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?
The description explains when the tool is honest about missing floors or period mismatches, and notes that cross-period conversion is never guessed. It does not explicitly list alternatives but implies when not to rely on it, which is adequate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
PAID ($0.10). Cost to employ: prices every statutory contribution on both the employee and employer sides for a gross salary, returning line-by-line amounts with instrument citations and an explicit refused list for schemes that could not be priced (unknown, not zero). Does NOT compute income tax — use compute_payroll for gross-to-net take-home where supported. Pass api_key if you have one; otherwise the response explains how to pay via x402.
| Name | Required | Description | Default |
|---|---|---|---|
| gross | Yes | Gross pay in local currency | |
| period | No | Period the gross covers (default month) | |
| api_key | No | API key (bypasses x402; metered for invoicing) | |
| country | Yes | ISO country code with a costed contribution schedule | |
| contract | No | Contract type where rates differ | |
| nationality | No | Gulf nationality for pension reach | |
| subdivision | No | Optional ISO 3166-2 regional schedule (e.g. CA-QC, DE-SN) | |
| childless_over_23 | No | Germany care surcharge | |
| children_under_25 | No | Germany per-child care reduction | |
| workplace_pension | No | Auto-enrolment / PPK participation (default true) | |
| zusatzbeitrag_rate | No | Germany sickness-fund supplement |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses that the tool is paid ($0.10), requires an api_key for full usage, and explains that schemes that cannot be priced will appear in a 'refused list' rather than being silently zero. However, it does not mention other potential behaviors like error handling, rate limits, or side effects beyond cost and refusal lists.
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 concise and packed with essential information in two sentences. It covers the core function, output specifics, exclusions, and payment handling without any redundancy. The structure is efficient and immediately actionable.
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?
Given the lack of an output schema, the description adequately describes the return (line-by-line amounts, citations, refused list). It also clarifies what the tool does not do (income tax). While it could elaborate further on the computation logic or edge cases, the description provides sufficient context for an agent to decide on invocation.
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?
All 11 parameters have descriptions in the schema, achieving 100% coverage. Each description provides meaningful context (e.g., 'Germany care surcharge', 'Auto-enrolment / PPK participation'), going beyond mere labels. While some descriptions are terse, they collectively define each parameter's role clearly.
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 clearly states the tool computes employment cost (statutory contributions) for a gross salary, breaking down employee and employer sides. It explicitly distinguishes itself from income tax calculation by pointing to compute_payroll, ensuring the purpose 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?
The description provides direct guidance on when to use this tool versus alternatives (e.g., 'Does NOT compute income tax — use compute_payroll'). It also instructs on passing an api_key and what happens if it's not provided, giving clear usage direction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
PAID ($0.05). Statutory income tax on a TAXABLE-income figure using the country's verified marginal bracket schedule, with full per-bracket workings, effective rate and marginal rate. Handles inflation-indexed tax units (Colombia UVT, Chile UTA, Peru UIT, Uruguay BPC) — you pass local currency. IMPORTANT: this is tax on taxable income, NOT net take-home pay — reliefs/allowances and social-security contributions are the caller's concern and are not applied (see the response scope_note). Pass api_key if you have one; otherwise the response explains how to pay via x402.
| Name | Required | Description | Default |
|---|---|---|---|
| api_key | No | API key (bypasses x402; metered for invoicing) | |
| country | Yes | ISO country code | |
| taxable_income | Yes | Taxable income in the country's local currency, in the schedule's own period basis (annual for most; monthly for Côte d'Ivoire, Uganda, Ethiopia, Costa Rica) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, but description discloses it's a paid tool ($0.05), handles specific inflation-indexed units, and clarifies what it does not apply (reliefs/allowances, social security). Also mentions response includes scope_note and workings. Sufficient transparency for agent decision.
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?
Description is four sentences, front-loaded with purpose and cost. Efficient but could be more structured. However, no redundant information.
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?
No output schema, but description explains scope, inputs, limitations (not net pay, no reliefs), and response includes workings and scope_note. Adequate for agent to use 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 covers 100% parameters with descriptions. Description adds meaning: taxable_income is in local currency, period basis varies; api_key bypasses x402. Provides contextual value beyond 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?
Clearly states it computes statutory income tax on taxable income using marginal brackets, with full workings, effective rate, marginal rate, and handles inflation-indexed tax units. The verb 'compute' and resource 'income tax' are specific, and it distinguishes from siblings like compute_vat and check_minimum_wage.
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?
Provides important usage guidance: it's tax on taxable income, not net pay; reliefs/allowances are caller's concern; mentions api_key or x402 payment. Could offer more explicit when-to-use vs alternatives but given sibling tools, it's clear this is for income tax computation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
PAID ($0.02). VAT breakdown for an amount: net, tax and gross using the country's current statutory rate, including per-levy components where the rate is composite (e.g. Ghana VAT + NHIL + GETFund). mode=add treats the amount as net; mode=extract backs VAT out of a gross amount. Pass api_key if you have one; otherwise the response explains how to pay via x402.
| Name | Required | Description | Default |
|---|---|---|---|
| mode | No | add = amount is net (default); extract = amount is gross | |
| amount | Yes | Amount in the country's own currency | |
| api_key | No | API key | |
| country | Yes | ISO country code |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses the cost ($0.02), that rates are current statutory, and that composite rates are handled (e.g., Ghana). Also explains what happens without an api_key, providing transparency about payment.
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?
Three sentences, each providing key information: cost, purpose, mode options, and api_key guidance. Front-loaded with cost to set expectations. No wasted words.
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?
Given no output schema, the description explains the output components (net, tax, gross, and per-levy details). It covers cost and payment, but could mention error handling or rate update frequency.
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 baseline is 3. The description adds value by explaining the 'mode' parameter behavior (add vs extract) and the notion of composite rates tied to the 'country' 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?
The description clearly states it computes VAT breakdown (net, tax, gross) for an amount using current statutory rates, including composite rates for countries like Ghana. It distinguishes itself from siblings like compute_income_tax by focusing on VAT.
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?
Explicitly explains the two modes (add vs extract) and when to use each. Also mentions api_key usage. However, it does not explicitly contrast with sibling tools like compute_income_tax.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
PAID ($0.02). Working days in a date range for a country: weekends (Egypt's Fri–Sat handled) and statutory public holidays applied, with the holidays hit by name and the next working day after the range. Range max 366 days. Pass api_key if you have one; otherwise the response explains how to pay via x402.
| Name | Required | Description | Default |
|---|---|---|---|
| to | Yes | Range end, YYYY-MM-DD, inclusive | |
| from | Yes | Range start, YYYY-MM-DD, inclusive | |
| api_key | No | API key | |
| country | Yes | ISO country code | |
| subdivision | No | Optional ISO 3166-2 region code (e.g. 'DE-BY') to apply that region's statutory holidays on top of the national calendar. Regions are listed under `subdivisions` by get_public_holidays. Unknown code is refused free with the list. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully discloses behavioral traits: paid ($0.02), weekend handling (Egypt's Fri-Sat shown as example), holiday application, return of holiday names and next working day, max range of 366 days, and payment mechanism via api_key or x402.
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 fairly concise and front-loaded with key facts (cost). However, it is a single long sentence that could be better structured for readability.
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?
While there is no output schema, the description explains return values (holidays hit and next working day). It covers the main behavior and constraints, though could detail error cases.
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 parameters. The description only adds context about api_key usage for payment, adding minimal value beyond 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?
The description clearly states the tool counts working days in a date range for a country, applying weekends and statutory holidays, and returns holidays hit and next working day. It is specific and distinguishes from siblings like get_public_holidays.
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?
The description mentions payment but does not provide explicit guidance on when to use this tool versus alternatives. It is implied for counting working days but no exclusions or comparisons.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
FREE. Official public-holiday calendar for a supported country, including gazetted movable holidays, with the official government source cited. Some countries also carry sub-national calendars (e.g. the German Laender): the subdivisions field lists them, and passing subdivision (ISO 3166-2, e.g. 'DE-BY') returns the national calendar merged with that region's statutory days.
| Name | Required | Description | Default |
|---|---|---|---|
| country | Yes | ISO country code | |
| subdivision | No | Optional ISO 3166-2 region code (e.g. 'DE-BY'). Returns national + that region's statutory holidays, each tagged national/regional. Omit for the national calendar. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden of behavioral transparency. It discloses the tool is free and returns official data with source citation. It mentions the merged behavior for subdivisions. However, it does not explicitly state it is read-only, has no side effects, or any rate limits.
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 very concise: two sentences, no wasted words. The first sentence states the core purpose and key features, and the second elaborates on subdivisions. It is front-loaded and efficient.
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?
Given no output schema and no annotations, the description covers essential aspects: purpose, subdivision feature, official source, and free nature. It does not describe the output format but is reasonably complete for a simple holiday lookup tool. Minor gaps: no mention of error cases or country list.
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 parameters are documented. The description adds significant value beyond the schema: explains the 'subdivisions' field, gives an example (DE-BY), and clarifies that passing subdivision returns merged national+regional holidays tagged as such. This extra context helps usage.
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 clearly states it provides an official public-holiday calendar for supported countries with sub-national options. The tool name 'get_public_holidays' reinforces its purpose, and it is distinct from sibling tools which handle taxes, wages, and working days. However, the description does not explicitly start with a verb like 'Retrieve' to emphasize the action.
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?
The description explains when to use the subdivision parameter and notes the tool is free. It implies usage for fetching official holidays, but does not explicitly state when not to use it (e.g., for working days count) or compare to sibling tools like count_working_days.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
PAID ($0.005). Current value of a reference series — e.g. series=policy-rate, vat, minimum-wage. Every value carries its official source citation, effective date, last-confirmed date and staleness flag. Pass api_key if you have one; otherwise the response explains how to pay via x402.
| Name | Required | Description | Default |
|---|---|---|---|
| series | Yes | Series id, e.g. policy-rate, vat, minimum-wage | |
| api_key | No | API key (bypasses x402; metered for invoicing) | |
| country | Yes | ISO country code |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full transparency burden. It discloses the cost ($0.005), the data characteristics (source citation, effective date, last-confirmed date, staleness flag), and the authentication/payment options (api_key vs x402). This goes well beyond the schema and is substantive behavioral context.
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?
Two tightly written sentences convey price, purpose, output contents, and authentication details with no filler. The most critical information (cost and what it does) is front-loaded, making it easy for an agent to quickly assess relevance.
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?
Given the absence of an output schema, the description adequately describes what the return value contains (citation, effective dates, staleness flag). It also explains the payment flow. Minor gaps exist around error handling or edge cases, but for a simple lookup tool with clear schemas and examples, it is largely complete.
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?
The input schema provides descriptions for all three parameters (100% coverage), so the baseline is 3. The description repeats the series examples and adds the 'current value' context, but does not add significant new meaning beyond what the schema already states. It meets but does not exceed the baseline.
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 clearly identifies the tool as returning the current value of a reference series, with explicit examples (policy-rate, vat, minimum-wage). It distinguishes itself from siblings like get_series_history (which presumably returns historical values) and list_series (which lists available series). The verb and resource are specific and 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?
The description implies usage for retrieving current reference values, but does not explicitly contrast it with alternatives such as get_series_history for historical data. It provides examples and mentions payment, but no direct when-to-use or when-not-to-use guidance. Usage is inferable but not explicitly stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
PAID ($0.005). Historical values of a reference series with effective date ranges, optionally filtered by from/to (YYYY-MM-DD). Pass api_key if you have one; otherwise the response explains how to pay via x402.
| Name | Required | Description | Default |
|---|---|---|---|
| to | No | Latest effective date, YYYY-MM-DD | |
| from | No | Earliest effective date, YYYY-MM-DD | |
| series | Yes | Series id | |
| api_key | No | API key | |
| country | Yes | ISO country code |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses the cost, authentication/payment behavior, and the notion of effective date ranges. It does not describe output format or error handling, but the most critical behavioral traits (cost, auth, historical scope) are covered.
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?
Two sentences, front-loaded with the paid warning, no filler. All information is relevant and efficiently presented.
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?
Without an output schema, the description should more concretely explain the return shape (e.g., array of date-value pairs). 'Historical values with effective date ranges' gives the gist but not enough detail for a paid API. It also leaves the relationship to get_series implicit.
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 adds marginal value by explaining api_key's optionality and the YYYY-MM-DD format for from/to, but it does not elaborate on series or country beyond what the schema already provides.
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 clearly states the tool returns historical values of a reference series with effective date ranges, distinguishing it from sibling tools like get_series or get_snapshot by the 'historical' focus. Though it lacks an explicit imperative verb, the intent 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?
It provides clear context: the tool is paid ($0.005), supports optional from/to filtering, and explains the api_key vs x402 payment flow. However, it does not explicitly mention when to prefer this over get_series or list_series, leaving some use-case ambiguity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
PAID ($0.02). Snapshot of every series for every country in one call. Pass api_key if you have one; otherwise the response explains how to pay via x402.
| Name | Required | Description | Default |
|---|---|---|---|
| api_key | No | API key |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so the description carries full burden. It discloses the cost ($0.02) and the behavior when no api_key is provided (response explains payment). However, it doesn't mention whether the call is idempotent, rate limits, or response size. Adequate but not exhaustive.
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?
Two sentences, front-loaded with 'PAID ($0.02)'. Every word earns its place. No redundancy or fluff.
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?
No output schema exists, so the description should cover what the snapshot contains. It says 'snapshot of every series for every country' but doesn't specify the data format or structure. Also lacks potential response size warnings. Adequate for a simple tool but leaves some unknowns.
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?
The input schema has one parameter (api_key) with 100% coverage. The description adds that the api_key is optional and explains the fallback behavior (payment instructions). This gives context beyond the schema's simple 'API key' description.
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 clearly states it provides a snapshot of every series for every country. The verb 'snapshot' combined with the scope distinguishes it from siblings like get_series (single series) or list_series (list). However, it doesn't explicitly contrast itself with alternatives.
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 context about the paid nature and how to pass an api_key or get payment instructions. But it doesn't explicitly state when to use this tool vs siblings (e.g., 'use this to get all data at once; use get_series for a single series').
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
FREE. Catalog of all usaref reference-data series: supported countries, series ids, descriptions, freshness metadata and per-series URLs. Call this first to discover what data exists.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden of disclosure. It lists all output elements (countries, IDs, descriptions, freshness metadata, URLs) and notes 'FREE', indicating no cost. No contradictions or omissions for a read-only catalog.
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?
Two sentences, no wasted words. Front-loaded with 'FREE' and 'Catalog of all usaref reference-data series', and each phrase adds essential information.
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?
Despite lacking an output schema, the description fully details what the tool returns. For a zero-parameter catalog tool with good annotation coverage, no additional context is needed.
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?
The input schema has no parameters, and description coverage is 100%. The description adds value by clarifying the tool's role as an initial discovery step, which is appropriate for a parameterless tool.
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 clearly states the tool's purpose: catalog all usaref reference-data series, including supported countries, IDs, descriptions, freshness metadata, and URLs. It also advises to call this first, distinguishing it from sibling tools like get_series which fetches a specific series.
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?
Explicitly instructs to call this first to discover existing data, providing clear usage context. While it doesn't list when not to use, the simplicity of a no-parameter catalog tool makes this guidance sufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
PAID ($0.05). Settlement/value date: the date n business days after a trade date, computed on the INTERSECTION of the calendars you name, with a per-day trail showing every skipped day and why, on which calendar. Supply business_days for a cycle you are trading under, or market + instrument_class to have a settlement cycle applied that we cite to its primary source (e.g. US equities T+1 under 17 CFR 240.15c6-1(a); UK gilts T+1 by DMO convention, which is NOT the T+2 equity cycle; Japan equities T+2 but JGBs T+1). Calendars are NATIONAL statutory holiday calendars with researched statutory weekend rules (Israel Saturday-only, Gulf Friday+Saturday, India Sundays plus the 2nd and 4th Saturday), NOT CSD or exchange calendars — each response states the basis and any known divergence. Use 'eu.t2' for the euro cash leg. We refuse FREE rather than guess: beyond published calendar coverage, no cited cycle for the instrument (government bonds never inherit an equity cycle), a cycle not in force on the trade date, or FX spot value dates. Free companion: GET /settlement-conventions.
| Name | Required | Description | Default |
|---|---|---|---|
| market | No | ISO country of the market whose cited cycle should apply (with instrument_class) | |
| api_key | No | API key (bypasses x402; metered for invoicing) | |
| calendars | Yes | Calendar ids to intersect: two-letter ISO country codes, plus 'eu.t2' for the euro cash leg | |
| trade_date | Yes | Trade/reference date, YYYY-MM-DD. Day 0: never counted, never rolled. | |
| business_days | No | The offset you are trading under (T+n) | |
| instrument_class | No | Instrument class — a government bond never inherits an equity cycle |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Despite no annotations, the description fully discloses behavioral traits: it charges $0.05, shows a per-day trail, refuses to guess, uses national statutory holiday calendars (not CSD/exchange), and cites primary sources for cycles. It also notes known divergences and refusal conditions.
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 dense but front-loaded with the core purpose. It efficiently packs many details (pricing, cycle examples, calendar definitions, refusal conditions) into a single paragraph, making it comprehensive for a complex tool.
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?
Given the tool's complexity (6 parameters, no output schema, no annotations), the description is remarkably complete. It covers all essential aspects: how to invoke, what to expect, edge cases, pricing, and data sources, leaving no significant gaps for an AI agent.
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 baseline is 3. The description adds significant meaning beyond the schema by explaining how business_days and market+instrument_class interact, calendar codes like 'eu.t2', and the meaning of trade_date (day 0 never counted/rolled). This justifies a 4.
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 clearly states the tool computes settlement/value dates as n business days after a trade date using the intersection of specified calendars. It distinguishes itself from sibling tools (none of which handle settlement date computations), and provides specific examples of cycles and jurisdictions.
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?
The description explicitly tells when to use the tool (e.g., 'Supply business_days for a cycle you are trading under, or market + instrument_class') and when not (e.g., 'We refuse FREE rather than guess: beyond published calendar coverage, no cited cycle...'). It also explains how to specify calendars and the 'eu.t2' for euro cash leg.
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.
compute_employment_costcount_working_days1 field changedInput schema / properties / subdivisionAdded value: +{
+ "description": "Optional ISO 3166-2 region code (e.g. 'DE-BY') to apply that region's statutory holidays on top of the national calendar. Regions are listed under `subdivisions` by get_public_holidays. Unknown code is refused free with the list.",
+ "type": "string"
+}get_public_holidays1 field changedInput schema / properties / subdivisionAdded value: +{
+ "description": "Optional ISO 3166-2 region code (e.g. 'DE-BY'). Returns national + that region's statutory holidays, each tagged national/regional. Omit for the national calendar.",
+ "type": "string"
+}settlement_datecheck_minimum_wage1 field changedInput schema / properties / country / enumPrevious value: -[
- "ca",
- "cr",
- "do",
- "gt",
- "hn",
- "mx",
- "pa",
- "sv",
- "us"
-]New value: +[
+ "bs",
+ "ca",
+ "cr",
+ "do",
+ "gt",
+ "hn",
+ "mx",
+ "pa",
+ "sv",
+ "us"
+]compute_income_tax1 field changedInput schema / properties / country / enumPrevious value: -[
- "ca",
- "cr",
- "do",
- "gt",
- "hn",
- "mx",
- "pa",
- "sv",
- "us"
-]New value: +[
+ "bs",
+ "ca",
+ "cr",
+ "do",
+ "gt",
+ "hn",
+ "mx",
+ "pa",
+ "sv",
+ "us"
+]compute_vat1 field changedInput schema / properties / country / enumPrevious value: -[
- "ca",
- "cr",
- "do",
- "gt",
- "hn",
- "mx",
- "pa",
- "sv",
- "us"
-]New value: +[
+ "bs",
+ "ca",
+ "cr",
+ "do",
+ "gt",
+ "hn",
+ "mx",
+ "pa",
+ "sv",
+ "us"
+]count_working_days1 field changedInput schema / properties / country / enumPrevious value: -[
- "ca",
- "cr",
- "do",
- "gt",
- "hn",
- "mx",
- "pa",
- "sv",
- "us"
-]New value: +[
+ "bs",
+ "ca",
+ "cr",
+ "do",
+ "gt",
+ "hn",
+ "mx",
+ "pa",
+ "sv",
+ "us"
+]get_public_holidays1 field changedInput schema / properties / country / enumPrevious value: -[
- "ca",
- "cr",
- "do",
- "gt",
- "hn",
- "mx",
- "pa",
- "sv",
- "us"
-]New value: +[
+ "bs",
+ "ca",
+ "cr",
+ "do",
+ "gt",
+ "hn",
+ "mx",
+ "pa",
+ "sv",
+ "us"
+]get_series1 field changedInput schema / properties / country / enumPrevious value: -[
- "ca",
- "cr",
- "do",
- "gt",
- "hn",
- "mx",
- "pa",
- "sv",
- "us"
-]New value: +[
+ "bs",
+ "ca",
+ "cr",
+ "do",
+ "gt",
+ "hn",
+ "mx",
+ "pa",
+ "sv",
+ "us"
+]get_series_history1 field changedInput schema / properties / country / enumPrevious value: -[
- "ca",
- "cr",
- "do",
- "gt",
- "hn",
- "mx",
- "pa",
- "sv",
- "us"
-]New value: +[
+ "bs",
+ "ca",
+ "cr",
+ "do",
+ "gt",
+ "hn",
+ "mx",
+ "pa",
+ "sv",
+ "us"
+]check_minimum_wage1 field changedInput schema / properties / country / enumPrevious value: -[
- "ca",
- "mx",
- "us"
-]New value: +[
+ "ca",
+ "cr",
+ "do",
+ "gt",
+ "hn",
+ "mx",
+ "pa",
+ "sv",
+ "us"
+]compute_income_tax1 field changedInput schema / properties / country / enumPrevious value: -[
- "ca",
- "mx",
- "us"
-]New value: +[
+ "ca",
+ "cr",
+ "do",
+ "gt",
+ "hn",
+ "mx",
+ "pa",
+ "sv",
+ "us"
+]compute_vat1 field changedInput schema / properties / country / enumPrevious value: -[
- "ca",
- "mx",
- "us"
-]New value: +[
+ "ca",
+ "cr",
+ "do",
+ "gt",
+ "hn",
+ "mx",
+ "pa",
+ "sv",
+ "us"
+]count_working_days1 field changedInput schema / properties / country / enumPrevious value: -[
- "ca",
- "mx",
- "us"
-]New value: +[
+ "ca",
+ "cr",
+ "do",
+ "gt",
+ "hn",
+ "mx",
+ "pa",
+ "sv",
+ "us"
+]get_public_holidays1 field changedInput schema / properties / country / enumPrevious value: -[
- "ca",
- "mx",
- "us"
-]New value: +[
+ "ca",
+ "cr",
+ "do",
+ "gt",
+ "hn",
+ "mx",
+ "pa",
+ "sv",
+ "us"
+]get_series1 field changedInput schema / properties / country / enumPrevious value: -[
- "ca",
- "mx",
- "us"
-]New value: +[
+ "ca",
+ "cr",
+ "do",
+ "gt",
+ "hn",
+ "mx",
+ "pa",
+ "sv",
+ "us"
+]get_series_history1 field changedInput schema / properties / country / enumPrevious value: -[
- "ca",
- "mx",
- "us"
-]New value: +[
+ "ca",
+ "cr",
+ "do",
+ "gt",
+ "hn",
+ "mx",
+ "pa",
+ "sv",
+ "us"
+]check_minimum_wage1 field changedInput schema / properties / country / enumPrevious value: -[
- "ca",
- "us"
-]New value: +[
+ "ca",
+ "mx",
+ "us"
+]compute_income_tax1 field changedInput schema / properties / country / enumPrevious value: -[
- "ca",
- "us"
-]New value: +[
+ "ca",
+ "mx",
+ "us"
+]compute_vat1 field changedInput schema / properties / country / enumPrevious value: -[
- "ca",
- "us"
-]New value: +[
+ "ca",
+ "mx",
+ "us"
+]count_working_days1 field changedInput schema / properties / country / enumPrevious value: -[
- "ca",
- "us"
-]New value: +[
+ "ca",
+ "mx",
+ "us"
+]get_public_holidays1 field changedInput schema / properties / country / enumPrevious value: -[
- "ca",
- "us"
-]New value: +[
+ "ca",
+ "mx",
+ "us"
+]get_series1 field changedInput schema / properties / country / enumPrevious value: -[
- "ca",
- "us"
-]New value: +[
+ "ca",
+ "mx",
+ "us"
+]get_series_history1 field changedInput schema / properties / country / enumPrevious value: -[
- "ca",
- "us"
-]New value: +[
+ "ca",
+ "mx",
+ "us"
+]check_minimum_wagecompute_income_taxcompute_vatcount_working_daysget_public_holidaysget_seriesget_series_historyget_snapshotlist_seriesLatAm govt data, cited to source: rates, VAT, tax, wages, holidays, FX. 22 countries; Brazil free.
European govt data, cited: rates, VAT, tax, wages, holidays, FX. 35 countries; Germany free.
Asian govt data, cited to source: rates, VAT, tax, wages, holidays, FX. 28 countries; Japan free.
Mid-East govt data, cited to source: rates, VAT, tax, wages, holidays, FX. 9 countries; UAE free.
Add one secure layer between your agents and this server.
