euroref — European government reference data

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

Annotations already establish read-only, idempotent, closed-world behavior, but the description goes well beyond them: it enumerates the country statutory weekend rules, discloses that regional holidays are NOT applied, and names two concrete refusal modes (year_not_held with years_held, holiday_date_pending). That is exactly the behavioral context an agent cannot get from structured fields alone.

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 metering status and the core operation, then progressively narrows to edge cases, refusal modes, and exclusions. It is dense and multi-clause, but nearly every sentence carries a distinct rule an agent needs; only the parenthetical country-rule laundry list is slightly over-packed.

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-shape details are correctly omitted, and the description still covers the failure modes, the calendar-coverage boundary, and the exclusions an agent must know to call this safely. Little is left for the agent to discover at runtime.

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 description genuinely adds semantics beyond the schema: the start date is day 0 and never counted, n=0 returns the date itself if it is a business day else the next one, and negative n walks backward. The only gap is that the +/-500 bound and country-code format are left entirely to 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?

Precise verb+resource: add N business days to a start date, with the direction (negative n walks backward) stated up front. This cleanly separates it from siblings like business_days_between, count_working_days, and is_business_day, which count or test rather than advance a date.

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 the day-0 convention and the n=0 edge case, which implies the correct usage context, but it never explicitly names an alternative tool or states when to prefer this over business_days_between/count_working_days. Usage is inferable rather than routed.

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

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

Beyond the annotations, the description adds substantial behavioral detail: it is free and unmetered, defines the counting semantics including negative ranges, explains that weekend days and public holidays are returned, lists specific statutory weekend rules, and documents error behaviors such as year_not_held and holiday_date_pending. These are all meaningful operational traits not covered by the readOnly/idempotent annotations.

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 and key constraint, and most sentences are dense with useful detail. It is somewhat long and includes several illustrative country examples that, while relevant, could be trimmed for brevity, but the structure remains clear and purposeful.

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 and the existence of an output schema, the description is complete enough for correct invocation. It covers calculation semantics, return contents, calendar limitations, and explicit error conditions, leaving no significant ambiguity for an agent to resolve.

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?

Although schema coverage is already 100%, the description adds important semantic meaning: country selects a national public-holiday calendar and statutory weekend rule, from/to follow half-open interval semantics with potential negative counts, and regional holidays are excluded. This goes well beyond the schema's terse date and country-code 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 states a precise verb and resource: counting business days between two dates. It distinguishes itself from the sibling add_business_days by explaining the inverse relationship and the interval convention '(from, to]', and it clarifies the inclusive-counting variant, so an agent can identify the tool's exact purpose 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?

The description clearly explains when the tool is appropriate: counting business days between two dates while accounting for national holidays and statutory weekends. It also notes limitations such as regional holidays not being applied and errors for unsupported years, but it does not explicitly contrast with other date-related siblings like is_business_day or count_working_days.

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

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

Annotations already cover readOnly/idempotent/non-destructive, and the description adds substantial behavior beyond them: a $0.02 price, the api_key-vs-x402 payment branch, honest statuses when no enforceable floor exists, an explicit refusal to guess cross-period conversions, and the receipt-vs-certified-extract distinction. It also disclaims legal advice, which matters for a compliance verdict.

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 core verdict question, then the return shape, then payment mechanics and caveats. Dense and mostly waste-free, though the receipt/certified-extract distinction is stated twice (once in the description body, once echoed in the schema), adding slight redundancy.

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 paid, open-world compliance tool with 5 params, an output schema, and full annotation coverage, the description supplies everything an agent needs: the question answered, the return shape, the payment path, edge-case statuses, and the receipt verification route. Nothing material 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, but the description adds real meaning: period 'must match the statutory floor's period' and cross-period conversion is never guessed, and the receipt flag's downstream effect (included only on paid success, not on 402/free refusals, not a certified extract) goes beyond the 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?

States a specific verb+resource+scope: 'is a salary at, above or below the country's statutory minimum wage?' and enumerates the return payload (verdict, margin, statutory floor, legal instrument). This is clearly distinguishable from siblings like compute_employment_cost or compute_income_tax, which cover different compliance questions.

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 practical invocation context (pass api_key, otherwise x402 flow; evaluation country is free; see list_series) and routes the agent to verify_answer_receipt for verification. However, it never states when to prefer this tool over neighboring compliance tools such as compute_employment_cost, so sibling selection is left to inference.

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

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

Goes well beyond the annotations by disclosing cost ($0.02), that malformed requests are refused free, that missing countries are surfaced under a 'missing' key, that each row carries its own source/dates/labels, and the api_key vs x402 payment path. Annotations cover safety/idempotency, but this adds concrete pricing, error and auth behavior.

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 paid cost and the core one-series-many-countries scope, and each clause carries operational detail. It is a dense run-on paragraph and includes sibling pricing ('Register: $0 · Delivery after trial: $0.05') that is arguably outside this tool's remit.

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 paid, open-world read tool with an output schema, the description covers cost, payment/auth paths, error handling, the missing-countries behavior, and the recommended follow-up binding. Nothing an agent needs to invoke it correctly is absent.

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, and the description adds value by giving concrete series examples (vat, policy-rate, minimum-wage, corporate-tax) and restating the 10-country cap, plus explaining the api_key alternative path. It stops short of documenting any format 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 (compare) and resource (one series across countries) with scope bounded to 'up to 10 countries of this brand in one call'. It is clearly distinguishable from siblings like get_series (single fetch) and get_series_history (time series) because it frames the multi-country, single-call dimension.

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 clear context for when it applies (one series, many countries) and names the correct follow-up tools (get_changes or register_alert) to use after a 200. It does not, however, explicitly contrast itself with get_series/get_snapshot, so the 'when not to use' side is left to inference.

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

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

Annotations cover the safety profile (readOnly, idempotent, non-destructive). The description adds substantive behavior annotations do not: it is a paid call ($0.05), payment can be settled either by api_key or via x402, refusals are explicit and mean "unknown, not zero", the evaluation country is free to try, and receipts are only issued on paid successes. That is exactly the extra context the annotations cannot 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 description is front-loaded and every clause is informative, but the receipt/certified-extract/legal-advice passage is repeated nearly verbatim from the schema's receipt description, adding length without new information. A dense single paragraph also makes the payment-mechanics detail harder to scan than it needs to be.

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 no further explanation, yet the description still characterizes them usefully (line-by-line amounts, citations, refused list). Payment paths, receipt semantics, free-trial scope, and the income-tax boundary are all covered, leaving nothing an agent needs to invoke 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 description coverage is 100% across all 12 parameters, so the schema already documents gross, country, period, receipt, and the country-specific knobs. The description restates the receipt parameter at length but adds no format or syntax detail beyond the schema, which is the baseline-3 case.

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 — pricing every statutory contribution on both employee and employer sides for a gross salary — and specifies the output shape (line-by-line amounts, instrument citations, explicit refused list). It also explicitly bounds the scope by excluding income tax, so an agent can separate it from compute_income_tax at a glance.

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 a clear when-not rule ("Does NOT compute income tax — use compute_payroll for gross-to-net") and routes payment questions to api_key vs x402 and to list_series for the free evaluation country. The only weakness is that the named alternative, compute_payroll, does not appear in the sibling list (which offers compute_income_tax), which could misdirect an agent.

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

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

Adds substantial context beyond the readOnly/idempotent/openWorld annotations: the tool is paid ($0.02), explains x402 fallback vs api_key, the scope_note in the response, the receipt behavior on paid success, and that it is not legal advice. This is rich disclosure of cost, auth, and output-scope traits.

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-loads the paid aspect and the core purpose, then covers scope and payment. It is dense and information-rich, though the payment/receipt/verification sentences are somewhat sprawling and could be tightened.

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 re-explained, and the description fully covers cost, auth, scope limits, receipt semantics, and verification path. Nothing material to 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 description coverage is 100%, so the schema already documents all four parameters including the currency/basis caveats. The description adds only marginal detail ('You pass the amount in local currency') that largely restates the schema, so the baseline 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?

States a specific verb and resource — computing statutory income tax on a taxable-income figure — with the exact basis (country's verified marginal bracket schedule) and delivered outputs (per-bracket workings, effective rate, marginal rate). This clearly distinguishes it from siblings like compute_vat and compute_employment_cost.

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 scopes what the tool does and does NOT do: 'this is tax on taxable income, NOT net take-home pay — reliefs/allowances and social-security contributions are the caller's concern.' It also routes to alternatives (list_series for the free country, verify_answer_receipt for verification, the non-MCP certified-extract endpoint).

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

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

Far exceeds the annotations: it discloses the price ($0.02), that refusals are free, the non-answer policy, the legal-advice disclaimer, the free DE-series trial, x402 payment flow, and receipt mechanics. This behavioral context (cost, failure policy) is not available anywhere in the annotations.

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 calculation is front-loaded well, but the text is bloated with marketing/payment content and repeats itself ('not legal advice' twice; the certified-extract caveat is restated). Several clauses about the certified extract and receipt could 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 and full annotation coverage, the description still accounts for pricing, payment fallback, refusal behavior, and receipt verification via the verify_answer_receipt sibling. Nothing an agent needs 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 most semantics (from/to inclusive-exclusive, days conflict, receipt default, principal > 0, country enum) are already in the schema. The description largely restates these, adding only framing rather than new per-parameter meaning, so 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?

States a precise verb+resource and the exact calculation: simple statutory interest on a principal at the statutory-interest series rate using Actual/365. An agent can immediately tell this apart from sibling compute_* tax/VAT/wage tools because the domain (statutory interest on principal) and method are named.

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?

Explains how to supply the period ('Pass days, or from and to'), what happens on conflict (refused free), when a series is unusable (mechanism-only), and how payment works (api_key vs x402). It stops short of explicitly contrasting against sibling tools, but the routing conditions it gives are clear and actionable.

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

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

Annotations only declare safety/idempotency, so the description carries cost and flow context: a $0.01 paid call, api_key vs. x402 payment paths, the free evaluation-country exception, and the optional Ed25519 receipt on paid successes. It also flags legal-advice disclaimers and the verify_answer_receipt verification path, well beyond the structured hints.

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 mode behavior are front-loaded in the first two sentences, which is ideal. The middle sentence on payment logistics and the trailing disclaimer/receipt caveats are dense, but each conveys a distinct, call-relevant fact rather than 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, return values needn't be spelled out, and the description fills the remaining gaps: payment mechanics, country enumeration pointer (list_series), receipt semantics, and post-call verification. Nothing an agent needs 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 3 baseline applies, but the description meaningfully elaborates: it restates and explains mode=add/extract behavior, describes the receipt toggle's effect on output and pricing, and clarifies the currency context. This adds real meaning over the enum/field labels, though it mostly mirrors 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?

States a specific verb+resource ('VAT breakdown for an amount: net, tax and gross') and clarifies the statutory-rate basis, including composite rates like Ghana VAT+NHIL+GETFund. An agent can distinguish it from siblings such as compute_income_tax or compute_employment_cost 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?

Explicitly defines the two operating modes (mode=add treats amount as net, mode=extract backs VAT out of gross) and when to pass api_key vs. paying via x402. It also routes the agent away from a lookalike ('answer receipt is not a certified extract; that SKU is not an MCP tool'), but stops short of enumerating when VAT is needed over other tax tools.

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

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

Goes well beyond the annotations by disclosing cost ($0.002), the payment path, the free evaluation-country tier, the 366-day range cap, Egypt's Fri–Sat weekend handling, and the receipt semantics (included at no extra USDC on paid success, verify with verify_answer_receipt). This is exactly the extra context annotations cannot 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 purpose leads, but the paragraph then mixes pricing, receipt mechanics, the certified-extract SKU, and a legal-advice disclaimer in one dense block. The pricing and legal-receipt asides are relevant but verbose, so not every sentence is tightly earning 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?

An output schema exists, so return values need no explanation. The description still covers cost, payment, free tier, range limits, weekend/holiday behavior, and receipt verification, leaving nothing an agent needs in order 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, but the description adds meaning the schema lacks: the 366-day maximum on from/to, the free-evaluation-country retry behavior, and the guidance to pass api_key when available. It does not add much on subdivision beyond what the schema already states.

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 resource and scope: working days in a date range for a country, with weekends and statutory public holidays applied. It does not, however, explicitly distinguish itself from the closely named sibling business_days_between, so the differentiation falls to inference.

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 useful operational guidance (the evaluation country is free to try, pass api_key if you have one, otherwise pay via x402) but never says when to choose this over business_days_between or add_business_days. Usage is implied rather than stated.

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

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

Annotations cover the safety profile (readOnly, idempotent, openWorld, non-destructive), yet the description adds substantial context beyond them: no metering/cost, 400/404 responses are free, and a 402 is flagged as a gate bug that should not be paid. It also exposes derivation rules (reverify_by from last_confirmed + update_cycle_days), the conditional emission of next_effective_known, and anti-hallucination guarantees (never parses notes, does not invent MPC/budget/wage-review dates).

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?

Cost and endpoint are sensibly front-loaded, but the text then runs into a dense stream of caveats with undefined jargon (last_confirmed, update_cycle_days, stale, MPC) that assumes prior knowledge, harming readability. Several clauses are genuinely useful, but the run-on construction and internal shorthand could be tightened.

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 values need not be re-explained, yet the description still covers derived fields, conditional omissions, error-code economics, and where historical data lives. The main omission is a plain statement of what the calendar contains for a first-time caller, but overall an agent has enough to invoke 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% and the two parameters are fully documented in the schema (ISO 3166-1 alpha-2 format, series example policy-rate, omission semantics, free-on-mismatch behavior). The description reinforces the same facts but adds little syntax or format detail the schema lacks, so this lands at the baseline 3.

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 the concrete resource/endpoint (GET /v1/calendar) and scope (this brand's continent, optional country/series), and it names the sibling that owns past data (get_changes), so it is distinguishable from adjacent tools. It stops short of plainly saying 'returns upcoming compliance/effective-date events with reverify windows', leaving the actual subject matter to be inferred from field names like reverify_by and next_effective_known.

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 clear operating context: FREE and unmetered, omit country for all series on the continent, valid-but-unmatched country stays free, and past changes belong on get_changes. This routes the agent to the right tool for historical vs current data. It lacks an explicit 'use this when you need X' framing and does not contrast with the many compute_* siblings.

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

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

Annotations already cover read-only, idempotent, open-world, and non-destructive traits, and the description still adds substantial behavioral context beyond them: return ordering (newest first), per-row fields (last_confirmed, stale), the 1/7/30/90-day freshness buckets, and pricing/metering ($0 free, alternatives at $0.05/$0.10). Nothing is left for the agent to infer about cost or shape.

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 key fact ('FREE unmetered') and well organized, but it carries some non-essential weight: the slogan 'Freshness is checkable or it is marketing' does no routing work, and pricing parentheticals add length. Still, most sentences earn their place by steering the agent away from paid alternatives.

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 needn't be fully enumerated, yet the description still describes the shape (per-series freshness fields plus a dataset summary). Combined with the alternatives and cost model, an agent has everything needed to select and invoke this 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% for the single `since` parameter, so the baseline is 3, but the description adds genuine semantic meaning beyond the schema's format note: it defines what `since` filters on (series whose current value *took effect* on or after that date) and restates the default window. The added value is real, though modest for a one-param 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?

States a specific verb+resource combination ('FREE unmetered change + freshness feed') and precisely what it returns: every series whose current value took effect on or after `since`, plus a dataset-wide freshness summary. It differentiates itself from siblings by naming get_series, register_alert, and the certified endpoint as distinct things to use instead.

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 trigger ('After any paid series or answer call, call this before you assume the cached value is still the law'), an explicit anti-pattern ('Do not re-pay get_series to discover a diff'), and named alternatives with conditions ('For a push bind, use register_alert', 'For a filing freeze ... GET /v1/certified/...'). When/when-not/alternatives are all covered.

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

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

Annotations cover the safety profile (readOnly, idempotent, non-destructive, openWorld), but the description goes further: it discloses the $0.01 cost, the payment fallback behavior, the shape of each returned series (value, unit, effective/last-confirmed dates, source, confidence), and the risk of values being silently retired without an alert.

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: purpose and price come first, then payment, then follow-up. Nearly every sentence carries unique information, though the long parenthetical list of series types and the pricing aside make it slightly heavier than needed.

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?

Covers purpose, cost, auth path, return contents, and downstream sibling routing; with an output schema present it is more than complete for an agent to call this 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 both parameters are already documented. The description still adds value by clarifying api_key is optional and what happens without it (x402 payment instructions), which is not in the schema's terse 'API key' 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?

Names a specific resource (a bundled country brief of every reference series held for one country) and enumerates what it includes, so an agent can instantly distinguish it from get_series/list_series which fetch individual 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 says it is cheaper than buying series one by one, explains the api_key vs x402 payment paths, and prescribes follow-up actions (bind get_changes or register_alert) after a 200. Clear when-to-use and what-to-do-next guidance.

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

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

Annotations already declare read-only, idempotent, non-destructive and closed-world, so the bar is low, yet the description adds substantial nuance: weekend/holiday rolling with every skipped day listed, a roll_unverified flag instead of guessing direction, and coverage_gap entries for unverifiable countries/taxes. Pricing and the change-tracking workflow are also disclosed. This is unusually rich behavioral context beyond the annotations.

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 substantive content is dense and useful, but the description is front-loaded with a pricing note and padded with cross-sell copy (get_changes poll, register_alert HMAC push with two price points, the free HTML page). Those sentences serve commerce more than tool selection, so the structure is not tight even though little is factually wrong.

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 6-parameter tool with an output schema, the description covers what an agent needs: output shape (rules with verbatim citations plus dated deadlines), uncertainty handling (roll_unverified, coverage_gap), and the effect of the key optional parameter. Nothing essential about calling 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 coverage is 100%, so the baseline is 3; the description adds meaning by explaining what year_end actually does (re-anchors corporate-tax rules on the company's own accounting year end) rather than just naming the field. It does not, however, clarify from/to defaults or the 400-day cap beyond what the schema already states.

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 and enumerates exactly what is returned: VAT/GST returns and payments, PAYE remittances, CIT returns and instalments, delivered as cited rules plus rolled due dates. That is clearly distinguishable from siblings like get_public_holidays or compute_vat. The only dilution is the leading pricing note, but the purpose is unmistakable.

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 context for the optional parameters (year_end to re-anchor corporate-tax rules, tax to narrow to one regime) and points to a free HTML alternative for the rules. It also suggests binding get_changes/register_alert after a 200. What it lacks is any explicit exclusion – e.g. when this is the wrong tool versus get_calendar or the individual compute_* tax tools.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive, and openWorld. The description adds real value beyond them: the pricing behavior ('FREE', 'Never metered') and the dual auth path. It does not mention pagination or error behavior, but with an output schema present the return shape is 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?

Dense but front-loaded: cost and return contents come first, then auth mechanics. Every phrase carries information, though the parenthetical '(free, card or metered)' packs three concepts into a fragment that reads slightly telegraphically.

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?

Complete for a zero-required-parameter, single-purpose read tool: it covers cost, return fields, plan/coverage semantics, and both authentication paths, while the output schema handles return structure. 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 description coverage is 100% and the schema already explains api_key is optional when sent as a header. The description reinforces this by stating the alternative header mechanism explicitly, adding marginal convenience rather than new semantics.

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 (get key balance) and enumerates exactly what is returned: plan, quota, used, remaining, reset date, coverage. No sibling tool overlaps this domain, and the name alone would be ambiguous without this detail.

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 says 'FREE' and 'Never metered', telling the agent this is a no-cost, non-billing call, and explains the two calling conventions (api_key param or X-API-Key header). It stops short of naming alternatives or when-not-to-call, but for a one-purpose utility tool there is little ambiguity.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false, so the safety profile is covered. The description adds useful context beyond them: the tool is free, results carry an official government source citation, and subdivision requests return a merged national+regional result set.

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 tight sentences with the cost and core purpose front-loaded, then the subdivision nuance. No filler, though the subdivision explanation is dense enough that it slightly crowds the second sentence.

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 values need no explanation, and the description covers cost, scope, source citation, and the optional regional behavior. The only gap is the absence of explicit routing against nearby calendar/business-day siblings.

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 both parameters are already documented in the schema. The description reinforces the subdivision merge semantics ('national calendar merged with that region's statutory days') and mentions the subdivisions field, but adds little beyond what the schema and output schema already convey.

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 ('Official public-holiday calendar for a supported country') and adds scope detail (gazetted movable holidays, cited government source). It does not name the obvious sibling get_public_holidays_worldwide, so the single-country vs worldwide distinction is only implicit.

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?

Explains the subdivision behavior and that omitting it yields the national calendar, which implies when to use the optional parameter. But it never states when to prefer this tool over get_public_holidays_worldwide, is_business_day, or count_working_days, leaving sibling routing to inference.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so safety is covered. The description adds real behavioral context beyond that: it is free and unmetered (never counts against the allowance) and documents the two auth paths (api_key param or X-API-Key header). No return-format detail, but the output schema covers that.

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?

Four short sentences, with the strongest selection signal (free/unmetered) front-loaded and the sibling comparison immediately after. The free-key URL is slightly promotional but functional, and no sentence 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?

An output schema exists, so return values need not be described. Combined with annotations and the description's cost, auth and scope coverage, an agent has what it needs to call the tool correctly; only a note on behavior with an invalid/unsupported country would improve it.

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 enum country list and the subdivision semantics are already fully documented by the schema. The description's auth note about api_key largely repeats the schema's own api_key description, adding no new meaning for country or subdivision. 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 states the resource (public holidays) and its distinguishing scope (every country across all seven brands, not only European) and explicitly names the sibling get_public_holidays as the narrower variant. The verb is only implied via 'Same as get_public_holidays', but the resource and scope are unambiguous and the agent can separate it from siblings.

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 clearly frames when to pick this over get_public_holidays (worldwide vs European-only) and notes the cost condition (free/unmetered with any key). It stops short of explicit exclusions or a full alternative-selection rule, but the routing signal is clear.

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

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

Annotations already cover read-only/idempotent safety, but the description adds substantial context they cannot: pricing ($0.003), two payment paths (api_key vs x402), the free DE-series trial, and the exact payload contents (source citation, effective date, last-confirmed date, staleness flag). It even warns about a real failure mode ('a later gazette does not silently retire the 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?

Front-loads the cost and core purpose, and every sentence carries operational information. It is dense and slightly run-on with several parenthetical clauses, but nothing is truly 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?

An output schema exists, yet the description still tells the agent what a value contains, how payment works, and what to do after success. For a paid, open-world read tool, nothing an agent needs to call 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 coverage is 100%, so the schema already documents all three parameters, and the series examples in the description duplicate the schema's own example. The only added nuance is the role of api_key ('Pass api_key if you have one'), which is marginal; baseline 3 is appropriate when the schema carries the semantics.

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 ('Current value of a reference series') with concrete examples (policy-rate, vat, minimum-wage). The word 'Current' implicitly distinguishes it from get_series_history and compare_series, so an agent can place it among siblings 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?

Gives clear follow-up routing — bind get_changes for free polling or register_alert for HMAC push after a 200 — which tells the agent how this tool fits into a workflow. It does not, however, explicitly name when to prefer this over get_series_history or compare_series for the primary read, so the when-not guidance is only implied.

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

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

Annotations already declare readOnly, idempotent and non-destructive, so the description is free to spend its words on things annotations cannot express: the $0.003 price, the two payment paths (api_key vs x402), the free DE trial, and the warning that unbound values can be silently retired by a later gazette. That is substantive operational context rather than restatement.

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 price and paid status are front-loaded, followed by purpose and then follow-up routing, so an agent can triage quickly. It is dense and slightly cluttered by pricing fragments ('Register: $0 · Delivery after trial: $0.05'), but no sentence 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?

With an output schema present, return values need no explanation, and the description covers the gaps that matter for a paid, multi-country, date-ranged tool: cost, auth/payment path, free tier and recommended follow-up calls. Only failure/error behavior is left to inference, which is a minor omission.

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 all five parameters are already documented with types, formats and a country enum. The description only echoes the YYYY-MM-DD date format and the api_key option, adding essentially nothing beyond the schema; 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 ('Historical values of a reference series with effective date ranges') and the optional from/to scoping, so the agent knows it returns a dated value history rather than a snapshot. It does not explicitly contrast itself with close siblings like get_series or get_snapshot, which keeps it short of a 5.

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 real invocation context (pass api_key, otherwise the response explains x402 payment, DE series are free to try) and routes the agent to follow-up tools (get_changes, register_alert). However it never says when to prefer this over get_series/get_snapshot, so the when-to-use selection guidance is only implied.

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

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

Annotations already cover readOnly/idempotent/non-destructive/openWorld, so safety is handled. The description adds genuinely new behavior: a $0.02 cost, x402 fallback payment flow, a free DE trial, and the warning that an unbound series can be 'silently retired' by a later gazette. This is strong added context beyond annotations.

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 critical 'PAID ($0.02)' signal in the first token, which is the right priority. It is a single dense paragraph mixing purpose, pricing, auth and follow-up advice, so some promotional phrasing ('instant card checkout at /pricing') is not strictly necessary, but little is outright waste.

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 described, and annotations cover the safety profile. The description supplies the missing commercial and lifecycle context (cost, payment, follow-up binding). It is essentially complete for correct invocation, with only the when-to-call routing gap remaining.

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?

Only one parameter at 100% schema coverage, so the baseline is 3. The description adds meaning beyond the schema's bare 'API key': it explains the optional-vs-paid path ('Pass api_key if you have one... otherwise the response explains how to pay via x402'), which tells the agent what happens when the param is omitted.

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 resource and an unusual scope: 'Snapshot of every series for every country in one call.' The phrase 'every series for every country in one call' distinguishes it from siblings like get_series/list_series/get_series_history without needing to open their 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?

Gives clear operating context (pass api_key or pay via x402) and explicitly names the follow-up alternatives get_changes and register_alert with their cost model. It stops short of stating when to prefer this tool over list_series/get_series for a first call, so routing is implied rather than spelled out.

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

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), yet the description adds substantial behavior: the 'FREE, unmetered' cost signal, the refusal semantics (year_not_held with years_held, holiday_date_pending), the guarantee that results are never inferred from weekends alone, and the explicit exclusion of sub-national holidays. This is well beyond what structured fields convey.

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 cost signal and the core question, followed by returns and then edge-case behavior; every clause carries operational information. The dense weekend-rule parenthetical is long but earns its place by pre-empting surprising classifications.

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 classification tool with an output schema and full annotations, the description covers purpose, return shape, error/refusal paths, cost, and scope exclusions. Nothing an agent needs to call it correctly or interpret a refusal 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 (date YYYY-MM-DD, ISO alpha-2 country) are fully documented in the schema itself. The description reinforces the scope of 'country' (national calendar, accepted across brands) but adds no syntax or format detail beyond the schema, so the 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?

'Is this date a business day in this country?' is a precise verb+resource, and the stated single-date classification scope implicitly separates it from the range-based siblings (business_days_between, count_working_days, add_business_days). The return summary (reason code, holiday names, adjacent business days) makes the operation 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 sets clear usage boundaries — it explicitly says regional/supranational holidays are not applied, that unheld years are refused, and which weekend regimes apply, which tells an agent when the answer is authoritative. It does not, however, name an alternative sibling (e.g. get_public_holidays_worldwide or count_working_days) or state when to prefer them, so it stops short of full when/when-not routing.

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

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

Annotations already cover safety (readOnlyHint, idempotentHint, destructiveHint=false), and the description adds genuinely useful traits beyond them: the call is free, and detail=true returns 'a large' full catalog versus a compact index. The remaining receipt/certified-extract text concerns other tools rather than this one.

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 purpose is front-loaded, but the bulk of the text is off-topic for this tool — receipts, Ed25519 signatures, certified-extract URLs, verify_answer_receipt, and the free status of get_calendar/get_changes/register_alert. Much of it does not describe list_series at all and dilutes the signal.

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 discovery role of the tool is adequately conveyed. However, the description spends most of its length on unrelated receipt and pricing mechanics, leaving the description padded rather than complete on this tool's own behavior.

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 both parameters (detail, country) are already fully documented, including the compact-vs-full catalog behavior and per-country expansion. The description adds no parameter detail beyond the schema, making 3 the correct 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 first sentence names a concrete verb and resource ('Catalog of all euroref reference-data series') and enumerates what the catalog contains. It distinguishes itself functionally from sibling get_series via 'Call this first to discover what data exists', though it never names that sibling directly.

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 sequencing instruction: call this first to discover available data. It also notes which other tools are free (get_changes, get_calendar, register_alert), which aids routing, but it does not state when NOT to use list_series or contrast it with get_series/get_snapshot.

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

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

Beyond the annotations (openWorld, non-idempotent, non-destructive), the description discloses cost structure ($0 register, $0.05 delivery after trial, first 3 free, refunded on send failure), HMAC-SHA256 signing, hard limits (20 series + 20 sources), and refusal behavior (source_not_fingerprinted for unknown URLs). This is exactly the extra behavioral context an agent needs and cannot get from the structured fields.

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 purpose is front-loaded and the watch-type bullets are useful, but pricing is repeated ('REGISTERING IS FREE', '$0 · Delivery after trial: $0.05', 'First 3 deliveries are free'), and asides like 'not a FRED-macro subscription' and 'This is retention, not a new data product' are editorial noise. Several sentences do not earn their 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?

An output schema exists, so return values need not be explained, and the description covers costs, limits, signing, and error behavior well. It omits lifecycle details an agent would want: idempotency of repeated registrations (annotations flag idempotent=false) and how to remove or update a subscription. Minor but real gaps for a subscription-creating tool.

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?

With schema coverage at 100%, the baseline is 3, but the description adds genuine meaning: it explains that series watches fire on value/effective-date movement (and contrasts statutory watches vs a FRED-macro subscription), that sources watches fire on document BYTES change with old/new sha256, and that api_key funds deliveries without being metered by this call. That goes meaningfully beyond the 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?

The description states a specific verb+resource (bind a webhook / register an alert) and spells out two watch types (series → series.changed, sources → source.changed). It even differentiates from the sibling get_changes. The opening sentence ('so the next gazette does not silently stale a value you already paid for') is indirect and marketing-flavored, delaying the actual purpose, which keeps it short of a 5.

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 explicitly routes the agent: 'Prefer this over polling get_changes if you are a long-running agent,' naming the alternative and the condition that selects it. It also implies the monitoring use case via the two watch types, but gives no explicit when-not guidance (e.g. one-shot checks or short-lived agents), so it falls short of full when/when-not coverage.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description adds substantial context beyond them: the $0.02 paid nature, the free-refusal policy, the statutory-vs-CSD calendar basis with stated divergence disclosure, and the optional Ed25519 receipt mechanics. This is exactly the kind of behavioral detail annotations cannot 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 definition is front-loaded, which is good, but the body is an overstuffed block that folds pricing, receipt semantics, legal disclaimers, and verification instructions into one paragraph. The receipt explanation is largely duplicated in the schema description, and the wall-of-text form hurts scannability.

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 no prose, and the description still covers pricing, refusal behavior, calendar provenance, the receipt option, and how to verify it. For a paid, citation-bearing computation tool this leaves no material gap for an 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 the schema already documents every parameter; the description still adds meaning by explaining the market+instrument_class pairing, the 'eu.t2' pseudo-id for the euro cash leg, and the rule that government bonds never inherit an equity cycle. That is more than a restatement of the schema, though it does not add syntax detail for every field.

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: compute a settlement/value date n business days after a trade date on the intersection of named calendars, with a per-day audit trail. The scope is precise enough to separate it from generic siblings like add_business_days or is_business_day, since it layers cited settlement cycles on top of plain calendar arithmetic.

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 explicit routing between the two input paths (business_days for a cycle you are trading under vs market + instrument_class for a cited cycle) and enumerates the refusal conditions (uncovered calendars, no cited cycle, cycle not in force, FX spot). It does not compare itself against sibling MCP tools, only a non-MCP companion endpoint, so it falls short of a 5.

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

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

Goes well past the annotations: pricing ($0.003), the free 'unknown' status for countries without a sourced rule, the x402 payment fallback, the meaning of check level (checksum only where the authority publishes the algorithm), and the post-200 alerting model with its own costs. Idempotency/read-only safety is already covered by annotations; this adds cost, coverage-gap, and result-shape 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?

The price and core purpose are front-loaded in the first clause, and each subsequent sentence carries operational information (coverage gaps, payment, follow-up binding). It is dense and long-winded with several stacked parentheticals, which slightly hurts scannability.

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-value explanation is unnecessary; the description instead covers the non-obvious essentials an agent needs — cost, auth/payment path, coverage limitations, and next-step tools. Nothing material is missing 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% and all three parameters carry descriptions (including accepted id formatting and the ISO enum), so the schema does the heavy lifting. The description adds only indirect value via output concepts like 'normalised form' and 'why it failed', not parameter-level guidance, so 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?

States a specific verb and resource ('Offline format and check-digit validation of a business tax ID or VAT number for one country of this brand') with explicit scope (offline, per-country, checksum-only-where-published). An agent can distinguish it from calculation siblings like compute_vat or list_series 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 explicit boundaries: 'Does not confirm registration; follow official_lookup for that', plus the free path for unsourced countries and the follow-up routing ('bind get_changes ... or register_alert'). It also states the payment condition ('Pass api_key if you have one; otherwise ... x402'), which tells the agent exactly how to proceed.

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

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

Annotations already declare readOnly, idempotent, openWorld and non-destructive. The description adds real context beyond them: it discloses that the tool may perform a network GET of /certified/public-key when the PEM is absent, that it is FREE, and that a private key must never be sent. It does not discuss failure modes or error behavior, so it is useful 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?

Front-loaded with 'FREE. Verify...' and dense with no filler, though the closing 'Same key and canonical-JSON rule as /certified/public-key' and the repeated canonical-JSON instruction are mildly redundant. Appropriate length for a cryptographic verification 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?

With an output schema present, return values need not be explained, and the description covers offline vs. online verification, cost, security constraints, and scope limits. Nothing an agent needs 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 description largely restates what the schema documents (public_key_pem requirement, public_key_url only used when the PEM is absent, signature_value overriding a nested signature) and adds only the canonical-JSON rule and the private-key refusal warning.

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 (verify) plus resource (answer receipt) and the exact cryptographic method (Ed25519 public key only). It also sharply bounds the claim of what a valid result means, so an agent can distinguish this from any sibling 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?

Explicitly says what to pass (receipt object or canonical JSON, signature_value when the signature is not nested, public_key_pem for offline) and what happens when public_key_pem is omitted. It names the alternative path (GET /v1/certified/{country}/{series} at $0.10, explicitly not an MCP tool) and states the exclusion that a valid signature is not a certified extract.

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