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?

Beyond the annotations (readOnly/idempotent/openWorld), it discloses pricing ($0.50), the x402 payment flow, shared rate limits (3 free calls per IP per day), free refusals on incomplete coverage (coverage_gap, no_charge), and receipt issuance/verification semantics. This is unusually rich behavioral disclosure for a paid tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

It is front-loaded with the price and action, but the remainder is a dense run-on mixing pricing, payment, rate limits, receipt semantics, and verification. The receipt explanation partially duplicates the schema's own description, adding some 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?

With an output schema present, return values need not be described, and the description covers payment, refusals, limits, and receipt behavior. It is close to complete for a complex paid tool, missing only explicit sibling routing.

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 already 100%, so the baseline is 3, but the description adds genuine semantics: omitting buyer_country for single-country maths, api_key bypassing x402, and the receipt flag's effect on paid successes. It goes beyond restating 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?

The description states a specific verb and resource ('Charge this sale') and enumerates the deliverable precisely: VAT applicability, place of supply under EU/UK/South Africa rules, net/VAT/gross, registration threshold, and rule cited. It distinguishes the answer receipt from the certified extract, though it does not explicitly differentiate itself from the sibling compute_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?

It gives concrete invocation conditions: 'Omit buyer_country for single-country rate maths', 'Pass api_key if you have one; otherwise the result is the x402 payment requirement', and the free-refusal behavior. However, it never routes the agent explicitly between charge_sale and the sibling compute_vat or charge_sale_certified.

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 it discloses price ($0.75), the free-refusal policy and its reasons, rate limiting (3 free/IP/day), auth paths (api_key bypasses x402), and exactly when a receipt is and is not included. This is unusually rich behavioral disclosure for a paid tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

It front-loads the price and the core deliverable, then the refusal policy, then auth. Efficient but dense, with the receipt/certified-extract distinction repeated in both description and schema, which costs a little polish.

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, complex, high-stakes tool this covers cost, payment paths, refusal semantics, rate limits, and verification route, and an output schema exists so return values need no prose. 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 description coverage is 100%, so the schema already documents all 8 parameters including net/gross, buyer_type defaults and api_key bypass. The description largely restates the receipt flag rather than adding new parameter semantics, 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?

The opening line states a concrete verb, resource and price: 'charge_sale dossier plus an Ed25519-signed certified extract of the governing VAT rate.' It explicitly differentiates from the answer-receipt SKU and the non-MCP /v1/certified series extract, so an agent can situate it against sibling charge_sale and the answer 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?

It gives strong operating context: use 'for a filing', refusal is free for coverage_gap/no_charge, 3 free calls per IP per day shared with answer tools, and api_key vs x402 fallback. What is missing is an explicit routing statement against the sibling charge_sale (when to pay $0.75 for certification vs the plain charge).

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 the description layers on real behavioral context: honest statuses when no enforceable floor exists, refusal to guess cross-period conversions, the paid-vs-free distinction, and what the optional receipt does and does not represent. This is materially more than the annotations provide.

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 price and purpose, then outputs, then payment mechanics — a sensible order. It is dense and somewhat repetitive (the receipt's nature is restated from the schema, plus legal and certified-extract disclaimers), but nearly every sentence carries operational value for a paid 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?

For a paid, open-world lookup with an output schema, the description covers cost, payment fallback, receipt semantics, verification path, and honest-failure behavior. Return values need not be detailed since an output schema exists, and nothing an agent needs to invoke it correctly is missing beyond the unnamed free country.

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: api_key bypasses x402 and is metered for invoicing, and it clarifies the receipt's pricing and non-legal-advice status. It also implies the free-country nuance, though it never names which enum value is free, leaving a small gap.

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 ('Compliance verdict: is a salary at, above or below the country's statutory minimum wage?') and names the exact outputs (verdict, margin, floor, legal instrument). It is unmistakable against siblings like compute_income_tax or get_series, and the price is front-loaded so the agent knows the cost model immediately.

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 payment path (pass api_key, otherwise x402 via the response) and routes the agent to list_series for the free evaluation country and to verify_answer_receipt for receipt verification. It does not explicitly state when NOT to use it or which sibling to prefer for adjacent questions, so it stops 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?

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 already cover the read-only/idempotent/no-destructive profile, but the description adds materially new behavior: it is PAID ($0.05), needs api_key or x402 payment, returns an explicit refused list where schemes are 'unknown, not zero', and explains receipt emission on paid successes only. These auth/payment and output-semantics disclosures are value beyond 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 core purpose and payment constraint are front-loaded, but the paragraph sprawls into certified-extract SKU pricing, legal-advice disclaimers, and receipt verification that dilute the main message. Every sentence has some purpose, yet several are meta-documentation that could be trimmed without loss for tool selection.

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 100% schema coverage, return values need not be explained; the description still adds the refused-list semantics, payment paths, and receipt behavior needed to call it correctly. The only real omission is that routing language references compute_payroll, which is not a listed sibling.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so parameters are already documented; the description's receipt explanation closely mirrors the schema's own receipt description rather than adding new meaning. It mentions api_key usage but not the remaining ten parameters, so it neither compensates nor detracts — baseline 3 is right when the schema does the heavy lifting.

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 (prices statutory contributions on both employer and employee sides for a gross salary) and describes the returned line-by-line amounts plus a refused list. It explicitly carves out what it does NOT do relative to compute_income_tax/compute_payroll, so an agent can separate it from sibling tax 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?

Gives clear routing: 'Does NOT compute income tax — use compute_payroll for gross-to-net take-home.' It also tells the agent how to preview for free via list_series and how to pay. It stops short of a full when-not matrix and routes to a tool (compute_payroll) not present in the sibling list.

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 substantially more: pricing ($0.02), api_key bypass of x402, the free tier, optional receipt behavior on paid success only, and the explicit scope_note pointer. Payment/auth and output-composition traits are disclosed, not left to inference.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The core purpose and the taxable-vs-take-home warning are front-loaded well. However, the back half drifts into receipt-vs-certified-extract distinctions, legal disclaimers, and verification instructions that are verbose and not needed to select or invoke the 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, full annotations, and 100% schema coverage, the description covers the remaining gaps an agent needs — what it computes, what it deliberately excludes, how to pay, and what the optional receipt represents. It is complete for this tool's complexity.

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 country enum, currency basis, api_key, and receipt. The description reinforces receipt (default false, free on paid success) and local-currency input, but adds little beyond the schema, matching the baseline 3 when the schema does the heavy lifting.

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 ('Statutory income tax on a TAXABLE-income figure') and precisely scopes the input ('tax on taxable income, NOT net take-home pay'). This clearly distinguishes it from siblings like compute_vat, compute_employment_cost, 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?

Explicitly states what the tool does and does not do — reliefs/allowances and social-security contributions are the caller's concern and are not applied, so it is not a take-home-pay calculator. It also explains payment paths (api_key vs x402) and where to find the free evaluation country (list_series). It stops short of naming sibling tools directly, but the boundary 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 declare a safe read (readOnly/idempotent/non-destructive), and the description adds rich behavior beyond them: $0.02 pricing, free refusals for mechanism-only series, the x402 vs api_key payment paths, free US series trials, and the receipt option. It also discloses limitations (no jurisdiction compounding/day-count statutes, not legal advice).

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?

Leads with pricing and is dense but mostly front-loaded and information-bearing. There is some redundancy, e.g. the receipt-not-certified-extract caveat appears both in the body and repeated in the schema description of 'receipt', which slightly bloats an already long paragraph.

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. Given a 7-param tool with complex payment/refusal semantics, the description covers formula, operand choice, refusals, pricing, payment, and receipt verification, with no critical gap.

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 already 100%, but the description still adds real meaning: days vs from/to mutual exclusivity with free refusal on disagreement, from-inclusive/to-exclusive day counting, receipt default, and api_key bypassing x402. This goes beyond the schema baseline of 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 a specific verb+resource and even the exact formula: 'principal × (rate/100) × (days/365)' on a 'cited statutory-interest series rate'. It is clearly distinguishable from sibling compute tools (income tax, VAT, employment cost) which deal with different regimes.

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 strong operand-level guidance (pass 'days' OR 'from'/'to'; disagreement is refused) and routes the receipt-verification need to verify_answer_receipt. However, it offers no explicit when-to-use-this-vs-sibling-tool guidance among the other compute_* tools, leaving tool selection to inference from the domain.

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 readOnly/idempotent/non-destructive annotations: it discloses the $0.01 cost, the two payment routes, that the evaluation country is free, receipt behavior on paid success only, and explicit legal/scope caveats ('not a series certified extract', 'not legal advice') with the verification tool named. This is exactly the kind of non-obvious 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?

Front-loads the cost and the purpose, then covers mode, payment, and receipt in tightly packed sentences with no filler. Dense but every sentence carries information; only the slight jamming of pricing, receipt, and legal caveats into one paragraph keeps it from a 5.

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, and the description still covers pricing, payment flow, receipt semantics, disclaimers, and the verification path. Nothing an agent needs to invoke this paid tool 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 schema already documents every parameter including mode, receipt, country, and amount. The description restates mode semantics rather than adding new detail (e.g., rounding, currency handling, rate vintage), 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?

States a specific verb and resource (compute VAT breakdown for an amount) and enumerates the outputs (net, tax, gross) plus composite-rate handling. It is clearly distinguishable from siblings like compute_income_tax, compute_employment_cost, and compute_statutory_interest without opening a 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?

Explains the two operating modes (add = amount is net, extract = backs VAT out of gross) and the payment paths (api_key for instant checkout, otherwise the response explains x402), and routes the agent to list_series for the free evaluation country. It stops short of explicitly contrasting itself with the neighboring tax/cost calculators, so it gets a 4 rather than 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 beyond the annotations (readOnly/idempotent/openWorld/destructive=false) by disclosing pricing, the free-refusal policy, the shared 3-calls-per-IP-per-day quota, api_key metering, x402 fallback, and the optional Ed25519 receipt with its no-extra-charge behavior. It also explicitly disclaims legal advice and points to verify_answer_receipt for verification.

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 price and purpose, which is good, but the prose is dense and the receipt/certified-extract caveat is repeated in both the description body and the receipt parameter schema. Several clauses (certified extract SKU, verification route) are useful but inflate the definition.

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 still covers pricing, coverage limits, refusal semantics, authentication paths, receipt behavior, and verification. Nothing an agent needs to decide or invoke this tool is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: it explains the optional receipt behavior on paid success (and that free refusals/unpaid 402 do not include one), and ties taxable_income to the income-tax schedule and start_date to the first working day. It adds value beyond the schema without fully documenting every parameter.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Cost this hire') and enumerates the concrete outputs of the dossier: wage-floor verdict, employer/employee contributions, employer cost, optional income tax and first working day. It also scopes the tool geographically ('Countries here: CA, MX, US'), which separates it from broader siblings like compute_employment_cost 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?

Gives clear operational context: paid at $0.50, shares the 3 free calls per IP per day, pass api_key if you have one otherwise you get the x402 payment requirement, and anything unanswerable is refused free. It does not explicitly name a sibling alternative or a 'use this instead of X' condition, so it stops 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?

Annotations already cover read-only/idempotent/non-destructive, and the description adds materially beyond them: unit price ($0.002), the hard 366-day range cap, the x402 payment fallback, the optional Ed25519 receipt and its exact scope ('not a series certified extract', 'not legal advice'), and how to verify via verify_answer_receipt. This is genuinely useful operational context an agent 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 correctly front-loaded in the first clause, but the body is overstuffed — pricing, checkout URL, receipt SKU, certified-extract comparison, and legal disclaimers crowd the core behavior. Several clauses are compliance boilerplate rather than information an agent needs to invoke the tool, so not 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?

Auth, pricing, range limits, receipt behavior, and verification path are all covered, and an output schema exists so return format need not be restated. The one gap is the Egypt reference, which contradicts the enum of supported countries and could mislead an agent about 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?

Schema description coverage is 100%, so baseline is 3, but the description adds meaning the schema lacks: the 366-day maximum on from/to, and the payment semantics of api_key (unpaid 402 vs instant card checkout). It does not add much for country or subdivision beyond what the schema already documents.

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 opening sentence names a specific verb+resource ('Working days in a date range for a country') and specifies distinguishing output content (weekends handled, statutory holidays applied, holidays hit named, next working day after the range), which separates it from siblings like business_days_between or is_business_day. It never names those alternatives explicitly, and the Egypt Fri–Sat aside is confusing since the country enum contains no Egypt entry.

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 real usage context for payment and auth ('Pass api_key if you have one... otherwise the response explains how to pay via x402', 'The evaluation country is free to try'). However it offers no when-to-use vs when-not guidance against the many overlapping sibling tools (add_business_days, business_days_between, is_business_day), leaving the agent to infer tool selection.

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 it discloses substantial behavior: exact price ($0.25), the shared 3-free-calls-per-IP-per-day quota, the free-refusal path (coverage_gap, no_charge), the auth model (api_key vs x402), and that receipt=true adds an Ed25519 answer receipt at no extra cost only on paid success. It also notes the tool is not legal advice.

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?

One dense paragraph, front-loaded with price and purpose, and every clause carries operational information. There is some duplication with the schema (receipt semantics restated) and the parenthetical asides make it heavy, but nothing is 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?

An output schema exists, so return values need not be described; the description covers the payment, refusal, quota, auth, and verification (verify_answer_receipt against /certified/public-key) aspects an agent needs to call and interpret 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 already 100%, but the description adds real meaning: series must all be certifiable and default to the first certifiable of vat/policy-rate/minimum-wage; receipt semantics (unpaid 402 and free refusals exclude one). This goes beyond the schema's per-field 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?

States a specific verb+resource: a paid 'Country evidence pack' containing the full cited country brief plus up to 3 Ed25519-signed certified extracts. It explicitly distinguishes itself from the free brief, from the $0.10 /v1/certified SKU (noting that SKU is not an MCP tool), and from the answer tools it shares quota with, so an agent can place it relative to 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?

Gives clear conditions: named series must all be certifiable, otherwise refused free with coverage_gap/no_charge; pass api_key if you have one, else the result is the x402 payment requirement. It does not explicitly route the agent to a free alternative (e.g. get_country_brief or get_series) for non-paid needs, so it stops short of full when/when-not 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 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 safety (readOnly, idempotent, non-destructive), and the description adds genuinely non-derivable context: a $0.01 paid call, two auth paths (api_key vs x402), and a staleness caveat that a later gazette can silently retire a value, which motivates following up with get_changes or register_alert. The follow-up push costs are informative, though slightly promotional in tone.

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 price and the core scope, then packs payment mechanics and follow-up guidance into dense clauses. It is long for a two-parameter tool and the parenthetical price list ('Register: $0 · Delivery after trial: $0.05') is clutter, but nearly every clause carries actionable 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?

With an output schema present, the description need not restate return values, yet it still summarizes the returned fields. It covers cost, both authentication paths, the staleness risk, and the recommended follow-up tools, leaving no obvious gap 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%, so the country enum already documents itself; the baseline would be 3. The description goes beyond the terse schema description for api_key ('API key') by explaining what happens with and without one, adding real meaning for the weaker of the two parameters.

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 ('Country brief: every reference series we hold for one country') and enumerates the contents (policy rate, VAT/GST, CPI, taxes, minimum wage, holidays) plus the per-series fields returned. This clearly distinguishes it from siblings like get_series and list_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?

It contrasts itself with the alternative ('Cheaper than buying the series one by one'), implicitly routing the agent away from individual series calls, and gives concrete prerequisites for payment (pass api_key, or the response explains x402). It stops short of an explicit when-to-use/when-not rule, but the context 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/non-destructive, so the description clears a low bar — and then adds substantial context beyond it: weekend/holiday rolling with every skipped day listed, the roll_unverified flag when a source is ambiguous, coverage_gap for unverifiable countries/taxes, no-invention guarantees, and post-call freshness advice. This is unusually rich behavioral disclosure.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The core purpose is buried behind a pricing clause ('PAID ($0.003, same as any series)'), so the description is not front-loaded with what the tool does. Most content earns its place (roll_unverified, coverage_gap), but the trailing free-trial and register_alert pricing copy is promotional padding in an already dense block.

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 format needn't be explained, and the description still covers scope, flags, caveats, and freshness guidance thoroughly for a 6-param tool. The only real gap is the absence of explicit routing versus sibling computation tools.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3, but the description adds semantic meaning: year_end is described as re-anchoring corporate-tax rules on the company's own accounting year end (not just the schema's terse 'year_end_variable' note), and country/tax scoping is explained in prose. This slightly exceeds the schema-only 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?

States a specific verb+resource — recurring statutory filing deadlines for a country — and enumerates the tax types (VAT/GST, PAYE, CIT, provisional instalments) it covers. An agent can distinguish it from compute_vat or get_public_holidays without opening any schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives situational hints: pass year_end to re-anchor corporate-tax rules, use the free HTML page if you only want the rules, and bind get_changes/register_alert afterward. However it never states when NOT to use this tool or names a sibling alternative (e.g. compute_vat) as the route for computing amounts rather than deadlines, so usage is implied rather than explicit.

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 readOnly, idempotent, openWorld and non-destructive, so the safety profile is covered. The description adds real context beyond that: cost (FREE), that gazetted movable holidays are included, that an official government source is cited, and the exact merge semantics when a subdivision is passed.

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 cost and purpose, then a focused second sentence on subdivision behavior. Dense but every clause carries information; only the 'official government source cited' detail is close to 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?

An output schema exists, so return values need no explanation, and annotations are rich. But the description's example uses 'DE-BY' / German Laender while the country enum contains only bs, ca, cr, do, gt, hn, mx, pa, sv, us — an agent could reasonably try country='de' and fail, which is a real completeness gap.

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, and the description largely restates the subdivision merge behavior rather than extending it. The added value is the concrete ISO 3166-2 example format ('DE-BY'), which is marginal.

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: the official public-holiday calendar for a supported country, with an explicit note on subdivisions. Scope is clear, and 'for a supported country' implicitly separates it from the worldwide sibling, but that sibling is never 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?

Gives concrete guidance on the optional `subdivision` parameter ('omit for the national calendar') and notes the tool is FREE, which is useful for selection. However, it never states when to prefer this over get_public_holidays_worldwide or get_calendar, so tool-level routing 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 already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false. The description goes beyond them with billing behavior ('FREE', 'Unmetered: never counts against the key's allowance') and the auth mechanism (api_key param or X-API-Key header on /mcp), which are real operational traits not derivable from 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?

Four sentences, each carrying information, but the lead is the pricing/free-key URL rather than the tool's purpose, which is deferred to sentence two. Front-loading the scope statement ahead of the billing note would make scanning faster.

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 the remaining gaps: global vs North American scope, auth paths, and cost. The subdivision option is left entirely to the schema, which is acceptable but leaves a small amount of context on the table.

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 api_key, the country enum, and the subdivision semantics (national vs regional tagging). The description only restates the api_key/header alternative and adds nothing about subdivision, 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?

The description establishes scope precisely by anchoring to a named sibling: 'Same as get_public_holidays, but for every country across all seven brands, not only North American.' That lets an agent separate it from get_public_holidays without opening either schema, though the core verb+resource ('return public holidays') is inherited from the sibling rather than stated 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?

The 'not only North American' contrast gives clear selection context against get_public_holidays, and the FREE/unmetered note is a decision factor an agent may weigh. There is no explicit when-not-to-use clause (e.g. latency or rate tradeoff for the worldwide variant), 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 beyond the read-only/idempotent annotations by disclosing cost ($0.003), the payment mechanics, the free-to-try US carve-out, and exactly what each returned value carries (source citation, effective date, last-confirmed date, staleness flag). This is the behavioral context an agent needs before committing to a paid call.

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 cost is front-loaded and the sentences are dense but purposeful, moving from purpose to return contents to payment to next steps. Slightly over-packed with pricing/promo detail, 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?

For a paid, open-world lookup with an output schema, the description covers cost, auth path, error/payment fallback, and recommended next tools. Since return shape is handled by the output schema, 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 all three parameters are already documented. The description merely repeats the series examples and restates api_key usage that the schema itself explains, adding no new syntax or constraint. Baseline 3 applies when the schema does the work.

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 id examples (policy-rate, vat, minimum-wage). It clearly separates itself from siblings like get_series_history (history) and list_series (enumeration) without the agent needing to open 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?

Explicitly tells the agent how to pay (api_key for card checkout, otherwise x402) and routes to follow-on tools get_changes and register_alert after a 200. It stops short of stating when to prefer get_series over get_series_history or list_series, so a small gap remains.

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 layers on substantial extra context the annotations cannot convey: pricing ($0.003), the payment/auth mechanics (api_key vs x402), the free US trial, and the silent-retirement risk that motivates binding a follow-up.

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 price and purpose before the payment and follow-up details, and each sentence carries information. However the final sentence crams get_changes, register_alert, HMAC, and two price points into one long clause, making it denser 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?

With an output schema present, return values need no explanation. For a paid, multi-param read tool the description covers payment, auth, filtering, trial scope, and lifecycle follow-up – everything 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 coverage is 100%, so country/series/from/to are already fully documented, and the description's 'YYYY-MM-DD' simply repeats the schema. The one additive note is that api_key is optional ('if you have one'), which approaches a 4 but is thin against otherwise redundant parameter 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: 'Historical values of a reference series with effective date ranges, optionally filtered by from/to.' Clear what it retrieves, though it never explicitly contrasts itself with close siblings like get_series or get_snapshot, leaving the agent to infer the distinction.

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 operational context: pass api_key if you have one, otherwise the response explains x402 payment, and 'every US series is free to try.' It also routes the agent to follow-ups (get_changes, register_alert) after a 200. It stops short of saying explicitly when to pick this over 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?

Annotations cover the safety profile (readOnly, idempotent, openWorld, non-destructive), and the description layers on the genuinely non-inferable operational facts: a $0.02 cost, two payment paths depending on whether you hold an api_key, and a free US-series trial. This is exactly the auth/cost context the structured fields cannot express.

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 most decision-relevant fact (price) and keeps the payment/auth mechanics tight. The trailing sentence about binding get_changes/register_alert is dense and slightly tangential, but each sentence carries operational information 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?

An output schema exists, so return values need no exposition, and the description covers cost, auth, and the failure-path response. Missing only explicit guidance on when this bulk snapshot beats the narrower sibling tools, which for a single-parameter read tool is a minor gap.

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% (baseline 3), but the description adds real meaning to the sole optional parameter: supplying api_key vs omitting it changes the response into a payment instruction via /pricing or x402. That conditional behavior is not captured by the schema's bare 'API key' string.

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 with an explicit scope: 'Snapshot of every series for every country in one call.' The 'every series ... in one call' framing implicitly distinguishes it from the per-series siblings (get_series, get_series_history) without needing to name them.

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 — optional api_key, x402 fallback, free US trial, downstream binding of get_changes/register_alert — but never says when to choose this over get_series or list_series, and get_changes/register_alert are described as follow-ups rather than alternatives. Usage is implied rather than delineated.

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 the safe read-only/idempotent profile, and the description adds substantial behavioral context on top: cost tiers, the api_key-vs-x402 payment branch, free coverage_gap refusals, quota sharing with the answer tools, the optional Ed25519 receipt only on paid success, and the verification path. This is exactly the beyond-annotation detail an agent needs.

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?

A single dense paragraph that leads with pricing rather than the tool's purpose, and repeats the receipt/certified-extract distinction that also appears verbatim in the schema. Every fact is relevant, but the ordering and duplication cost readability.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With an output schema present, the description needn't explain return values, and it still covers pricing, coverage limits, refusal semantics, payment flow, and receipt verification. Nothing an agent needs to call this correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3, and the description goes further by stating gross is in each country's own currency with no conversion, listing the allowed country brands, and confirming 2-5 hires. Those currency and range clarifications are genuine meaning beyond the schema fields.

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 the exact outputs (employer cost, employer/employee contributions, on-cost percent, wage-floor verdict) computed 'side by side and ranked' for 2-5 hires. This implicitly separates it from single-hire siblings like compute_employment_cost and cost_hire, but never names them, so the differentiation is inferred rather than explicit.

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: 2-5 countries from a fixed list, pricing tiers ($0.75 for 2, $1.00 for 3-5), free refusal for unanswerable requests, and shared 3-free-calls-per-IP quota. It stops short of telling the agent when to prefer a sibling tool (e.g. compute_employment_cost for a single hire) or when not to call this at all.

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 readOnly/idempotent annotations: discloses the $0.60 price, that unanswerable cases are refused free with coverage_gap and no_charge, the shared 3-free-calls-per-IP-per-day quota, the x402 fallback behavior, and the receipt guarantee. It also bounds expectations by disclaiming that the receipt is not a certified extract or legal advice.

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 price and purpose, and every clause carries information (pricing, refusal policy, quota, receipt caveats). It is a dense single paragraph with heavy parentheticals and the certified-extract aside is slightly digressive, which costs a point on scannability, but nothing is pure filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 14-parameter paid composite tool with an output schema, the description covers the gaps that matter: cost, quota, failure mode, payment mechanics, receipt semantics, and verification path via verify_answer_receipt. An agent has everything needed to decide and pay 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 86% so the baseline is already high, but the description still adds real meaning: the mutually exclusive due_date vs invoice_date+terms_days pattern, the semantics of receipt on paid successes, and api_key as a metering bypass. The seller-country allowlist (BS, CA, CR, HN, MX, PA, SV) is a constraint the schema does not encode.

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 and enumerates the three checks it performs (VAT correctness, overdue/late interest, tax ID format), which is enough for an agent to tell it apart from the narrower siblings compute_vat and validate_tax_id. The 'in one call' framing makes the composite nature explicit.

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 invocation routing ('Send due_date, or invoice_date with terms_days') and the payment path (pass api_key, otherwise x402 requirement). It never explicitly says when to prefer this over calling compute_vat + validate_tax_id + compute_statutory_interest separately, so the alternative-selection guidance 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 already declare readOnly/idempotent/non-destructive/openWorld, so the safety profile is covered; the description goes well beyond that with pricing ($0.40), the free-refusal contract (coverage_gap, no_charge), the shared 3-calls-per-IP-per-day quota, x402 fallback behavior when no api_key is passed, and the optional Ed25519 receipt with its verification path. These are real behavioral traits an agent cannot get from 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 content is dense and largely useful, but the opening token 'PAID ($0.40).' front-loads a payment status rather than the purpose, and the certified-extract disclaimer is repeated in both the description and the receipt parameter schema. The result is a wall of choppy sentences where the purpose sentence is buried after pricing metadata.

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 computation tool with a full output schema and complete param coverage, the description supplies the pricing, the refusal policy, the auth path, the quota, and the receipt/verification contract. It does not need to explain return values because an output schema exists, and nothing material to correct invocation appears 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 genuine meaning on top: the alternative input pattern (due_date OR invoice_date+terms_days), the as_of default of today, and the receipt flag's no-extra-cost semantics on paid successes. The only omission is that it does not explain debtor or currency expectations, which the schema covers only thinly.

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 outcome set: whether an invoice is overdue, by how many days, and the statutory late-payment interest owed (Actual/365 simple). It names the supported regime countries explicitly, which scopes the tool concretely. However, it never distinguishes itself from the sibling 'compute_statutory_interest', which appears to overlap on the interest-computation half of this tool's job.

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 tells the agent exactly what to supply ('Send due_date, or invoice_date with terms_days') and what happens when the answer is not achievable ('refused free (coverage_gap, no_charge)'). Payment context (api_key vs. x402, shared 3 free calls/IP/day) is spelled out. It stops short of naming an alternative tool when the invoice is outside the supported regimes.

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 declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered. The description adds that the call is FREE and what metadata is returned, which is genuinely useful, but most of the remaining text discusses paid answer receipts, certified extracts and verification of OTHER tools rather than the behavior of 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 first two sentences are well front-loaded and on-topic, but the remainder is off-topic filler about receipt semantics, certified-extract pricing, public-key verification, and a list of which sibling tools are free. Those sentences do not earn their place in a catalog-listing tool's description.

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. Purpose and discovery sequencing are complete; the only gap is that the noise about other tools slightly dilutes rather than fills anything an agent needs.

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 'detail' and 'country' are already fully documented in the schema, including the compact-vs-full index distinction and the ISO country code. The description adds nothing about parameters, 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?

States a specific verb and resource ('Catalog of all usaref reference-data series') and enumerates the payload (countries, series ids, descriptions, freshness metadata, URLs). The imperative 'Call this first to discover what data exists' cleanly separates it from data-fetching siblings like get_series and get_series_history.

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?

'Call this first to discover what data exists' gives clear, actionable when-to-use guidance for a discovery tool. It stops short of explicitly naming the alternative it feeds into (get_series), so the agent must infer the follow-up step, but the sequencing is unambiguous.

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 (which only cover read-only/idempotent/open-world safety) by disclosing price ($0.35), the free refusal path with a coverage_gap/no_charge outcome, the shared IP rate limit, the payment requirement when api_key is absent, and that the output is neither a certified series extract nor legal advice. Verification via verify_answer_receipt is also named.

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 critical facts — PAID at $0.35 and the resource — before pricing, coverage, and receipt details. It is dense with parenthetical asides and runs long, but each clause carries information an agent needs, so the length is largely earned.

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; for a paid, open-world, idempotent query tool the description covers pricing, coverage boundaries, free-refusal behavior, auth/payment paths, and receipt verification. Nothing needed 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 description coverage is already 86%, so the schema documents country, from/to, tax, api_key and receipt on its own. The description restates the receipt default and api_key/x402 behavior and adds the certified-extract distinction, but adds little operational meaning beyond what the schema already provides.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource — upcoming VAT, PAYE and corporate-tax due dates in a window — with scope details (weekend/holiday rolling, per-rule citations, verified countries CA/DO/US). An agent knows exactly what comes back. It does not, however, differentiate itself from the close sibling get_filing_deadlines, so it falls 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?

Useful conditions are given (free refusal via coverage_gap when the answer cannot be complete, 3 free calls/IP/day shared with the answer tools, pass api_key or expect an x402 requirement). But it never states when to pick this over the sibling get_filing_deadlines or the other tax tools, so guidance is implied rather than explicit.

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.