Mid-East govt data, cited to source: rates, VAT, tax, wages, holidays, FX. 9 countries; UAE free.
Scored across 11 tools
Most tools target distinct operations: compute_* handles statutory calculations, get_*/list_series handles reference series, and count_working_days/settlement_date handle calendar math. The only real overlap is check_minimum_wage versus get_series, since both can surface minimum-wage data, though their purposes (verdict vs. value) are clarified.
The set is predominantly imperative verb_noun snake_case (check_, compute_, count_, get_, list_), which is predictable. settlement_date breaks the pattern as a bare noun, and list_series vs. get_series is a minor inconsistency, but nothing is chaotic.
Eleven tools is well-scoped for a reference-data server covering statutory rates, taxes, calendars, and series retrieval. Each tool has a distinct job, and the count feels neither thin nor bloated.
The core read-only and calculation workflows are covered, and CRUD operations are unnecessary for reference data. However, compute_employment_cost explicitly defers to a compute_payroll tool that is not present in the set, creating a visible dead end for gross-to-net workflows, and supported-country discovery relies on list_series.
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 fully discloses that the tool is paid ($0.05), returns a verdict, margin, statutory floor, and legal instrument, and handles edge cases like missing floors or period mismatches honestly. No contradictions.
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 well-structured, front-loading the tool's purpose and cost ('PAID ($0.05). Compliance verdict...'). Every sentence adds value, and no unnecessary words appear.
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 thoroughly explains what the tool returns (verdict, margin, floor, legal instrument) and addresses edge cases. With 4 parameters and 100% schema coverage, the description covers all necessary behavioral and constraint details for effective use.
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%, but the description adds significant value beyond schema: it clarifies that amount is in the country's currency (schema says same), period must match statutory floor's period (schema only says 'Period the amount covers'), and api_key bypasses x402 with metered invoicing (schema merely says 'API key'). This enhances agent understanding.
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 it checks if a salary meets the statutory minimum wage, using a specific verb ('compliance verdict') and resource ('statutory minimum wage'). It distinguishes from sibling tools like compute_income_tax or compute_vat, which deal with tax calculations.
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 guidance on when to pass an api_key (if available) and explains that cross-period conversion is never guessed. It does not explicitly state when to use this tool versus alternatives, but the tool's purpose is clear enough for an agent to choose appropriately.
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?
With no annotations, the description carries full burden. It discloses the paid nature, the detailed output format (line-by-line with citations and refused list), and the explicit exclusion of income tax. It does not mention any side effects or data retention, but as a pure computation tool this is sufficient. It also notes the 'unknown, not zero' handling, which is a valuable behavioral detail.
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 three sentences with zero redundancy. It front-loads the cost, then the purpose, then the exclusions and payment options. Every sentence contributes essential information, making it highly 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?
For a tool with 11 parameters and no output schema, the description covers the core behavior, output structure, exclusions, and payment. It doesn't list all parameters, but the schema does. It also doesn't mention that only 'ae' is supported, but that is visible in the schema. Overall, the description provides sufficient context for correct usage without overloading.
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 description does not need to elaborate on parameters. It adds context about the gross salary and country implicitly but does not provide additional parameter-specific meaning beyond the schema's own descriptions. Baseline 3 is appropriate.
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 function: pricing statutory contributions on both employee and employer sides for a gross salary, returning line-by-line amounts with citations and a refused list. It explicitly distinguishes itself from income tax computation via compute_payroll, making its scope 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 explicit when-to-use guidance and names the alternative tool (compute_payroll) for income tax scenarios. It also explains the payment requirement via api_key or x402, leaving no ambiguity about how to invoke the tool under different circumstances.
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?
With no annotations, description carries full burden. It discloses the tool is paid ($0.05), handles inflation-indexed tax units, and specifies the scope (only taxable income). Response contents are outlined (per-bracket workings, effective rate, scope_note).
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 moderately concise, starting with price and core purpose. Key details and important note about net pay are front-loaded. Slightly long but every sentence adds value.
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 adequately describes return values (workings, rates, scope_note). Parameters are fully covered. Sibling tools are unrelated, so no missing context.
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% of parameters, but description adds value: clarifies taxable_income is in local currency and period basis, and explains api_key bypasses x402 payment. This goes beyond schema descriptions.
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 computes statutory income tax on taxable income using marginal brackets. It uses specific verbs ('compute') and resource ('income tax'), and distinguishes itself 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?
Description explicitly notes this is tax on taxable income, not net take-home pay, and that reliefs/allowances are caller's concern. It also explains payment options (api_key or x402). No explicit alternatives but siblings are clearly different.
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?
With no annotations, the description carries the full burden. It discloses the paid nature ($0.02), the two modes of operation, and composite rate handling. It does not detail error handling or rate limits, but the core behavior is transparent.
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 three sentences, each serving a distinct purpose: function overview, mode explanation, and payment info. No wasted words; front-loaded with the main purpose.
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 (VAT with composite rates, paid), the description covers essential aspects: modes, payment, and country-specific behavior. No output schema is provided, but the description implies the result structure. A brief note on response format would improve completeness, but it's already substantial.
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 'add' vs 'extract' mode semantics, the api_key role, and the composite rate nuance for certain countries. It supplements the schema without redundancy.
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: computing VAT breakdown (net, tax, gross) using the country's statutory rate, including composite levies. It distinguishes from sibling tools like compute_income_tax by focusing specifically 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?
The description explains when to use 'add' vs 'extract' modes and mentions the api_key for paid users. It does not explicitly state when not to use the tool, but the context (paid tool, specific VAT calculation) is clear enough.
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?
No annotations are provided, so the description carries full burden. It discloses the tool is paid, applies weekends and holidays, and returns holiday names and next working day. It does not detail error behavior or idempotency, but covers the main behavioral traits adequately.
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 extremely concise, consisting of two sentences that cover cost, functionality, and constraints. It is front-loaded with key information and contains 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?
The description explains the core functionality and output summary (holidays hit by name and next working day). However, without an output schema, it lacks details on the exact return format. It is mostly complete for a calculation tool with good schema coverage.
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?
Input schema covers all parameters with 100% description coverage. The description adds context about country-specific weekends and holiday application but does not provide parameter-specific details beyond what the schema already offers. Baseline score of 3 is appropriate.
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 counts working days for a given country within a date range, applying weekends and statutory public holidays. It distinguishes from sibling 'get_public_holidays' by focusing on working day computation and returning the next working day.
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 usage context such as cost ($0.02) and api_key/payment flow, and specifies a range max of 366 days. However, it does not explicitly guide when to use this tool versus alternatives (e.g., get_public_holidays) or when not to use it.
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 full burden. It discloses that the tool is free, cites official government sources, and details subdivision merging behavior. This adds value beyond the schema, though response format or rate limits are not mentioned.
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 with no filler. First sentence fronts the main purpose, second sentence clarifies the subdivision feature. Efficient and well-structured.
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 a simple 2-parameter tool with no output schema, the description covers the essential behavior, supported countries, and subdivision logic. It omits return format but remains adequate for correct 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?
Schema coverage is 100%, but the description adds meaning by explaining the subdivision parameter's effect (merging national and regional holidays) and the 'subdivisions' field. This goes beyond the enum descriptions.
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 retrieves an official public holiday calendar for supported countries, including movable holidays and sub-national calendars. The verb 'get' combined with specific resource 'public holidays' and details about subdivisions distinguishes it from sibling financial tools.
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 public holidays but does not explicitly state when to use versus siblings. It provides context on subdivision behavior but lacks exclusion criteria or alternatives.
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?
No annotations are provided, so the description carries the full burden. It discloses the $0.005 cost, the return metadata (official source citation, effective date, last-confirmed date, staleness flag), and the api_key/x402 payment flow, which is valuable behavioral context beyond just saying 'get current value'.
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 compact sentences convey cost, purpose, return value composition, and authentication flow with no unnecessary words. Every sentence earns its place.
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 sufficiently explains what the return values contain and how payment works. It does not mention error handling or invalid inputs, but for a simple lookup tool with three params, the description 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 already covers all three parameters with descriptions (100% coverage), but the description adds value by giving examples for series, explaining api_key as a payment bypass, and implying the country enum with ISO codes. This goes beyond what the schema alone 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 states 'Current value of a reference series' with examples, clearly identifying the tool's action (fetch current value) and resource (reference series). This distinguishes it from siblings like get_series_history and list_series, which are for historical or listing purposes.
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 indicates this tool is for current values and mentions the payment process, but it does not explicitly contrast with alternative tools like get_series_history or list_series. The usage context is implied rather than fully spelled out.
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 openly discloses the cost ('PAID ($0.005)') and the payment/auth behavior ('Pass api_key if you have one; otherwise the response explains how to pay via x402'). This is valuable behavioral context, though it doesn't mention read-only nature or error handling.
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 concise, front-loaded sentences. The cost warning is first, followed by function and filters, then payment guidance. No fluff or redundancy; every sentence earns its place.
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 no output schema, the description covers the main functionality, optional filters, and payment behavior. It doesn't detail the response structure or error cases, but for a simple read tool it's sufficiently complete, especially with sibling context.
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%, but the description adds meaning by stating from/to are optional filters ('optionally filtered by from/to') and explaining api_key's role in payment. This goes beyond the schema's field-level descriptions.
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 'Historical values of a reference series with effective date ranges', which specifies what the tool does. It implicitly distinguishes from siblings like get_snapshot or get_series by focusing on historical data, though it doesn't explicitly name 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?
The description provides context (paid, optional from/to filters, api_key usage) but does not explicitly compare with other tools or state when NOT to use it. It implies use when historical data is needed but lacks sibling differentiation.
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 mearef 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?
No annotations are provided, so the description must cover behavioral traits. It discloses that the tool is FREE and returns a catalog of data, implying a read-only operation. It does not detail rate limits or authentication, but for a simple listing tool it is adequate.
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 two sentences, very concise, and front-loaded with 'FREE.' Every word adds value. No unnecessary 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?
Given no parameters, no output schema, and low complexity, the description fully covers what the tool does and how to use it. It tells the agent to call it first for discovery, which is complete context.
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?
There are zero parameters, and the schema coverage is 100% (empty). The description does not need to add parameter details beyond stating there are none. Baseline 4 is appropriate.
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 lists a catalog of mearef reference-data series, including specific details like supported countries, series IDs, descriptions, freshness metadata, and URLs. It distinguishes from siblings like get_series by implying this is for discovery.
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 states 'Call this first to discover what data exists,' providing clear usage context. It does not list explicit when-not-to-use scenarios or alternative tools, but the sibling context helps.
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_wagecompute_income_taxcompute_vatcount_working_daysget_public_holidaysget_seriesget_series_historyget_snapshotlist_seriesAsian govt data, cited to source: rates, VAT, tax, wages, holidays, FX. 28 countries; Japan free.
LatAm govt data, cited to source: rates, VAT, tax, wages, holidays, FX. 22 countries; Brazil free.
African govt data, cited to source: rates, VAT, tax, wages, holidays, FX. 34 countries; Ghana free.
N American govt data, cited to source: rates, VAT, tax, wages, holidays, FX. 10 countries; USA free.
Add one secure layer between your agents and this server.
