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?

Goes well beyond the readOnly/idempotent/openWorld annotations: discloses the $0.02 cost, honest statuses when no enforceable floor exists, refusal to guess cross-period conversions, the receipt behavior (paid successes only), and that output is not legal advice. This is rich operational context an agent cannot infer from annotations 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?

Core purpose is front-loaded, but the description is long and dense, and the receipt/'certified extract is not an MCP tool' caveat is duplicated between the description and the receipt parameter's schema description. Some sentences could be trimmed without losing 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, return values need not be explained, and the description still covers everything else an agent needs: payment paths, receipt semantics, verification via verify_answer_receipt, and the legal caveat. Nothing material is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: api_key bypasses x402 for instant checkout, and receipt is an optional boolean that yields an Ed25519 receipt only on paid successes. It clarifies behavior of parameters beyond their schema definitions.

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 (check a salary against statutory minimum wage) and describes the output (verdict, margin, statutory floor, legal instrument). It is clearly distinct from siblings like compute_employment_cost or compute_income_tax, which are different computations.

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 payment context (pass api_key, otherwise x402), points to list_series for the free evaluation country, and distinguishes this from the $0.10 certified extract SKU. However, it never explicitly states when to prefer this over sibling computation tools, 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?

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 declare readOnly/idempotent/non-destructive/openWorld, and the description adds substantial non-annotation context: $0.05 cost, x402 vs api_key payment paths, the 'refused list' semantic where unknown is explicitly not zero, and receipt behavior on paid success. This is well beyond what the 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?

The core purpose is front-loaded and clear, but the text is long with several layered parentheticals, and the receipt/certified-extract discussion repeats material already in the schema's receipt description. It is information-dense rather than wasteful, but tighter editing would help.

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 still characterizes the response (line-by-line amounts, citations, refused list). Payment, verification, and scope-exclusion details are all covered, so an agent has everything needed to invoke it correctly.

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

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

Schema description coverage is 100% and each of the 12 params is documented (including receipt, api_key, and country-specific flags), so the schema carries the burden. The description largely restates the receipt param semantics already present in the schema and adds no new syntax or format guidance.

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 opens with a specific verb+resource: pricing statutory contributions on both employee and employer sides for a gross salary, returning line-by-line amounts with an explicit refused list. It also states what it is not ('Does NOT compute income tax') and names the sibling (compute_payroll), so an agent can distinguish it without opening schemas.

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

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

It gives explicit when-to-use (gross salary employment cost), when-not (income tax / gross-to-net), and the alternative (compute_payroll). It also flags the paid access model, the free evaluation country, and points to list_series, leaving little 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 establish read-only/idempotent/non-destructive, but the description adds substantial behavior beyond them: the $0.02 price, the api_key vs x402 payment paths, the free evaluation-country trial, receipt behavior on paid success only, and the 'not legal advice' disclaimer. This is exactly the kind of cost/auth/disclaimer 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?

Dense and front-loaded, leading with the computation and its scope before payment mechanics. It loses a little to repetition — the receipt/certified-extract distinction appears in both the description body and the schema's receipt description, and the MCP-vs-SKU note is made twice.

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 spelled out, and the description still points at the response scope_note. Combined with full parameter documentation, payment semantics, and the free/paid split, an agent has everything needed 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 the schema already documents all four parameters including the period-basis caveat. The description still adds useful interpretive meaning by stressing that taxable_income is a taxable figure, not gross pay or take-home, and by contextualizing receipt/api_key use, though it largely restates the currency/period note.

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 using the country's verified marginal bracket schedule') plus the outputs it produces (per-bracket workings, effective and marginal rate). It explicitly carves itself out from adjacent siblings like compute_vat, compute_employment_cost and compute_statutory_interest by naming what it is not (net take-home pay).

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 when-not guidance ('this is tax on taxable income, NOT net take-home pay — reliefs/allowances and social-security contributions are the caller's concern and are not applied') and routes to alternatives (list_series for the free country, verify_answer_receipt for validation, the non-MCP certified extract SKU). An agent knows the scope boundary and the escape hatches without opening the schema.

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

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

Annotations already cover safety (readOnly, idempotent, non-destructive), and the description adds substantial context they cannot carry: $0.02 price, x402 card checkout, free refusals for bad inputs and mechanism-only series, free BR series, and that a non-answer is never billed. It also discloses the receipt mechanism and how to verify it, which materially affects how an agent should handle failures.

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

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

The price tag is front-loaded, which is good, but the body is a dense run-on block mixing formula, payment rails, refusal policy, legal disclaimers, and receipt mechanics. 'Not legal advice' and the certified-extract caveat are each stated twice (once in the body, once in the receipt parameter), so it is longer 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?

For a 7-parameter paid tool with a full schema and an output schema, the description covers pricing, payment, failure modes, and receipts thoroughly. The notable gap is that it never explains how the statutory-interest series/rate is selected — there is no series parameter, so 'the cited statutory-interest series rate' leaves the rate-selection path implicit.

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

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

Schema coverage is 100%, so every parameter (days, from, to, api_key, receipt, principal, country) is already documented in the schema, including the days/from/to disagreement refusal and the receipt semantics. The description largely restates those rules and the formula rather than adding new per-parameter meaning, 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 simple statutory interest on a principal at a statutory-interest series rate — and gives the exact formula (Actual/365, principal × (rate/100) × (days/365)), which no sibling tool duplicates. An agent can distinguish it from compute_income_tax, compute_vat, and compute_employment_cost 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?

Gives clear operating context: pass days or from/to, refusal when they disagree, refusal of mechanism-only series, optional api_key or x402 payment path, and a pointer to a separate certified-extract endpoint when a certified extract is actually needed. It does not explicitly route the agent against sibling calculators (e.g. when to use this vs compute_income_tax), 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 cover the read-only/idempotent safety profile, but the description adds substantial behavior beyond them: exact price ($0.01), the two payment paths, what happens when unpaid, that a receipt is only on paid success, that paid refusals behave differently, and that the receipt is not a certified extract nor legal advice. These are exactly the kind of non-obvious traits 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?

Front-loaded with the core purpose before payment mechanics and disclaimers. It is on the longer side and duplicates receipt details that also appear in the schema description, but nearly every sentence carries distinct information (pricing, payment flow, free-trial country, verification tool).

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

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

Output schema exists, so return values need not be explained, and the description still covers payment behavior, receipt semantics, the certified-extract distinction, the free evaluation tier, and the companion verify_answer_receipt tool. An agent has everything needed to invoke and interpret this correctly.

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

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

Schema coverage is 100%, so the schema already documents mode, amount, country, api_key, and receipt semantics. The description largely restates these (mode add/extract, receipt default false) rather than adding new format or constraint detail, so the baseline 3 is appropriate.

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

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

States a specific verb and resource ('VAT breakdown for an amount: net, tax and gross') and defines the calculation basis ('country's current statutory rate'), including composite-rate handling (Ghana VAT + NHIL + GETFund). This is clearly distinct from sibling tools like compute_income_tax and compute_employment_cost 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 explicit mode-selection guidance ('mode=add treats the amount as net; mode=extract backs VAT out of a gross amount') and explains the payment path (api_key vs x402). It also notes the evaluation country is free to try. It stops short of contrasting against sibling tax-computation tools, so it earns 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 past the annotations (readOnly/idempotent/openWorld) by disclosing pricing, the free-refusal contract, rate-limit sharing, the x402 payment fallback when no api_key is passed, and receipt issuance behavior on paid success only. These are exactly the operational traits an agent needs before invoking a paid endpoint.

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 price and core purpose in the first clause, then layers payment, refusal, and receipt details. It is dense but each sentence carries distinct information, with minor waste from repeating the certified-extract caveat in both the description and the receipt parameter.

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

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

With an output schema present and full parameter/annotation coverage, the description completes the picture by covering payment mechanics, refusal semantics, quota sharing, and receipt verification routing. Nothing material for correct invocation is missing.

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

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

Schema description coverage is 100%, so the baseline is 3. The description mostly restates schema semantics ('income tax on taxable_income', 'first working day on or after start_date', receipt default false) rather than adding new per-parameter meaning 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?

States a specific verb and resource plus the full deliverable set: 'Cost this hire: one cited dossier for a salary - wage-floor verdict, employer and employee contributions..., employer cost, optional income tax...'. It also scopes the geography ('Countries here: MX'). It stops short of naming the nearest siblings (compute_employment_cost, compute_income_tax, check_minimum_wage) that it apparently bundles, so differentiation is inferential 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 conditions: it is a paid tool ('PAID ($0.50)'), only MX is covered, incomplete answers are refused free with coverage_gap/no_charge, and api_key vs x402 is spelled out. It also notes the 3-free-calls-per-IP quota is shared with the answer tools. No explicit when-not-to-use guidance against the sibling compute_* tools, which is the only gap.

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 substantially more: a stated price ($0.002), auth/payment mechanics (api_key vs x402 402 responses), the refusal behavior for unknown subdivisions and free tier, and the receipt option including what it is not. This is exactly the kind of 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?

Purpose and price are correctly front-loaded, but the single paragraph crams in payment mechanics, receipt/legal disclaimers, an unrelated $0.10 certified-extract SKU, and a verification pointer, with the receipt explanation largely restating the schema field. Several sentences do not earn their place in a tool-selection 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?

Given an output schema exists, the description need not explain returns; it instead covers the open-world concerns an agent actually needs — cost, auth path, free tier, 366-day cap, receipt semantics, and how to verify. Nothing required 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; the description still adds value by explaining that api_key enables instant paid access, that the evaluation country is free, and by cross-referencing where subdivision codes originate (get_public_holidays). Some receipt text is duplicated verbatim from the schema, which limits the net gain.

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 clause names a specific verb+resource ('Working days in a date range for a country') and enumerates the exact computation (weekends with Egypt's Fri–Sat, statutory holidays) plus the ancillary outputs (holidays hit by name, next working day after the range). This is clearly distinguishable in substance from sibling add_business_days, though it never explicitly names the closest sibling business_days_between as the alternative.

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 operating guidance: pass api_key if available, the evaluation country is free to try, range is capped at 366 days, and unpaid calls return an x402 payment explanation rather than an error. It does not, however, state when to prefer this over overlapping siblings like business_days_between, so it stops short of a full when/when-not routing rule.

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, openWorld, idempotent, non-destructive) the description discloses pricing ($0.25), the two payment paths (api_key vs x402), the shared 3-calls-per-IP-per-day quota, the exact refusal behavior (coverage_gap, no_charge), and receipt semantics with a verification pointer. These are material operational traits 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?

Long but justified by genuine payment and receipt complexity; the paid price and core purpose are front-loaded. Some redundancy exists, since the receipt semantics are restated in both the description and the schema entry, but every clause otherwise carries 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, return values need not be re-explained. For a paid, rate-limited, refund-capable tool the description covers cost, payment flow, refusal handling, quota sharing, receipts, and verification, which is complete enough for an agent 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 the parameters are already documented, establishing a baseline of 3. The description goes beyond it by explaining the series default ('first certifiable of vat, policy-rate, minimum-wage'), the all-must-be-certifiable constraint, and the receipt's paid-success-only condition, adding genuine meaning to two of the four 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?

The description states a specific resource and composition: a country evidence pack bundling the full cited country brief plus up to 3 Ed25519-signed certified extracts. It is far more specific than a tautology and names the constituent parts. It stops short of explicitly contrasting with the sibling get_country_brief or the standalone certified-extract SKU, so sibling differentiation is only implicit.

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

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

It gives real use-time context: series must all be certifiable, anything unanswerable is refused free, api_key should be passed if held, otherwise expect the x402 payment requirement. It also distinguishes the answer receipt from the $0.10 certified extract endpoint. It does not explicitly say when to prefer this pack over get_country_brief or the compute_* / check_* siblings, so the alternative-selection rule is left to inference.

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

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

Annotations cover the safety profile (readOnly, idempotent, 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 only cover the safety profile (readOnly/idempotent/openWorld); the description adds the material facts an agent actually needs: it is paid ($0.01), how auth works (pass api_key, card at /pricing, or x402 flow explained in the response), and that binding get_changes/register_alert prevents a later gazette from silently retiring a value. That is substantial disclosure beyond 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?

Front-loads the critical fact (PAID $0.01) and packs high information density per sentence. The parenthetical pricing fragments ('Register: $0 · Delivery after trial: $0.05') and the '...' enumeration are slightly noisy, 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?

Output schema exists so return shape need not be described, and the description still covers cost, auth, error path, alternatives and recommended follow-up calls. Against a 2-param idempotent read tool, an agent has everything needed to invoke and chain 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 country is enum-constrained, so baseline is 3. The description goes further by explaining what api_key actually does and what happens when it is absent (x402 payment path), which the schema's bare 'API key' description does not.

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

'Cheaper than buying the series one by one' implicitly routes the agent away from per-series calls, and the closing sentence names concrete follow-ups (get_changes for polling, register_alert for push) with their conditions and prices. It lacks an explicit 'do not use when you need only one series' statement, so it falls just short of a full 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 declare read-only/idempotent/non-destructive, yet the description adds substantial behavior: paid metering ($0.003), weekend and public-holiday rolling with every skipped day listed, roll_unverified flagging instead of guessing, and coverage_gap returns rather than invented countries. That is exactly the value-add structured fields don't 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?

It is front-loaded with pricing then purpose, and nearly every sentence carries a caveat, payment fact, or follow-up instruction. It runs long and includes some promotional framing ('same as any series', 'Every BR series is free to try') that an agent doesn't strictly need, keeping 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?

For a six-parameter tool with an output schema, the description covers everything an agent needs: scope, coverage-gap semantics, unverified-date handling, year_end re-anchoring, pricing, and post-call follow-ups. Return-value shape is left to the output schema, which is correct.

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

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

Schema coverage is 100%, so the baseline is 3. The description goes further by explaining that year_end re-anchors corporate-tax rules on the company's own accounting year end and applies to rules marked year_end_variable, which is meaning beyond the terse schema 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?

The description names a specific resource (recurring statutory tax deadlines for a country) and enumerates exactly what it returns: VAT/GST returns, PAYE remittances, CIT returns and instalment payments, as cited rules plus actual due dates. It also separates itself from the follow-up siblings get_changes and register_alert, so an agent can place it 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?

It states the operating context clearly: pass year_end to re-anchor corporate-tax rules, use the free HTML page if you only want the rules, and bind get_changes or register_alert after a 200 so a later gazette doesn't silently retire the value. There is no explicit when-not/exclusion beyond the free-page pointer, so it falls just 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 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 cover readOnly/idempotent/non-destructive, so the description's job is to add context — and it does: cost ('FREE'), data provenance ('official government source cited'), coverage caveat ('gazetted movable holidays'), and the merge semantics of a regional request. It does not discuss rate limits or response shape, but the output schema covers the latter.

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

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

Two sentences, front-loaded with cost and purpose, with the subdivision mechanics in the second. Dense but no wasted filler; the parenthetical '(e.g. the German Laender)' is arguably the only removable clause.

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

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

The output schema carries return-value detail, so that gap is excused, but the description's worked example ('DE-BY', German Laender) is not among the enumerated country codes in the schema, which could mislead an agent into requesting an unsupported subdivision. That inconsistency plus the absent alternative-tool guidance leaves it adequate but not complete.

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

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

Schema description coverage is 100%, so both parameters are already documented; the description's ISO 3166-2 example and national+regional merge behavior largely restate the schema text for `subdivision`. Only the pointer to a `subdivisions` field in the response adds marginal value, 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+resource ('Official public-holiday calendar for a supported country') and scopes it to a single country, which implicitly separates it from the sibling get_public_holidays_worldwide. It never names that sibling, so the differentiation is left to inference rather than stated.

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?

Usage is only implied: 'for a supported country' and 'Omit for the national calendar' tell the agent when to pass subdivision, but there is no when-to-use guidance and no routing to get_public_holidays_worldwide or get_calendar for multi-country or other calendar needs.

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

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

Annotations already cover readOnly, idempotent, openWorld and non-destructive behavior, so the bar is lower. The description adds genuinely non-obvious traits: it is free/unmetered and never counts against the key allowance, plus it explains both auth paths (api_key param or X-API-Key header on /mcp), which the annotations do not 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?

Four short sentences, front-loaded with the free-access incentive, then the sibling comparison, then auth. The free-key URL is slightly promotional but each sentence carries usable calling 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?

An output schema exists, so return values need not be described, and annotations carry the safety/idempotency profile. The description fills the remaining gaps an agent needs: cost/quota behavior and how to authenticate, making it complete for a simple read 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?

Schema description coverage is 100%, so country, subdivision and api_key are already fully documented, making 3 the baseline. The description only restates the api_key/header alternative and the worldwide country scope, adding no syntax or format detail beyond the schema.

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

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

The description defines the tool by comparison ("Same as get_public_holidays, but for every country across all seven brands"), which tells an agent the verb+resource and how it differs from a real sibling. It never independently says it returns public holidays, so it leans on the sibling for its core meaning, keeping it just 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 scopes this tool to worldwide coverage versus the Latin-America-only get_public_holidays, giving a clear selection signal between the two. It stops short of stating an explicit when-not condition or naming the sibling by exact tool name for 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?

Beyond the annotations (readOnly, idempotent, non-destructive, open-world), the description discloses pricing ($0.003), two distinct auth/payment paths (api_key card checkout vs x402), a free tier (BR series), and what each returned value contains (source citation, effective date, last-confirmed date, staleness flag). This is rich, non-redundant behavioral detail.

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

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

The price and core purpose are front-loaded, and sentences are dense with real information. The trailing sentence carries pricing detail for other tools ($0.05 delivery) that is marginally relevant to calling this tool, slightly diluting focus.

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 endpoint with two auth paths, the description covers cost, payment mechanics, free-tier scope, and follow-on actions, and an output schema already documents return values. The one remaining gap is that it never explicitly contrasts this tool with get_series_history or list_series.

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 series, api_key and the country enum; baseline is 3. The description only mildly enriches this — it restates the series examples already present in the schema and adds the x402 fallback context — and says nothing about the country parameter.

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

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

The description states a specific verb and resource — 'Current value of a reference series' — and lists concrete series examples (policy-rate, vat, minimum-wage). The word 'Current' implicitly differentiates it from the sibling get_series_history, but it never names that sibling, so the differentiation is left to inference.

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

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

It gives clear operational context: pass api_key if you have one, otherwise pay via x402, and after a 200 bind get_changes or register_alert. However, it offers no explicit guidance on when to call get_series versus get_series_history, list_series, compare_series, or 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 only declare it as a read-only, idempotent, open-world read. The description adds genuinely new behavior: the $0.003 price, the two auth paths (api_key vs. x402 pay-per-call), the free BR-series trial, and what happens on non-payment (a response explaining how to pay). It also warns that unbound series values can be silently retired by a later gazette, which is a real behavioral caveat.

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

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

Purpose and price are front-loaded in the first clause and the payment/auth details follow logically. The final sentence is overloaded with promotional pricing ('Register: $0 · Delivery after trial: $0.05') and cross-sell detail that is somewhat dense for a tool description, though it does serve the workflow guidance.

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

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

With an output schema present and full parameter coverage, return-value explanation isn't needed, and the description covers cost, auth, and next-step tools. The remaining gap is discovery — nothing says where series ids come from (presumably list_series/get_series), which an agent needs before it can call this successfully.

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: api_key is described as an optional credential with a documented alternative (x402 card checkout at /pricing), and the BR free-trial note gives the country parameter commercial significance not visible in the enum. The from/to date format is repeated from the schema rather than added.

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?

It gives a specific verb+resource — retrieving historical values of a reference series with effective-date ranges — plus the optional from/to filtering, so an agent knows exactly what it returns. It does not, however, distinguish itself from siblings like get_series or get_snapshot, which look like competing ways to fetch series data.

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

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

It clearly states the usage context: this is a paid call, pass api_key if available, otherwise the response itself explains the x402 payment path, and BR series are free to try. It also prescribes a next step after success (bind get_changes or register_alert). It stops short of saying when to choose 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?

Beyond the annotations, it discloses that the tool is paid ($0.02), how authentication/payment works, that BR series are free to try, and how to persist the snapshot via get_changes or register_alert. These are material behavioral details not present in the structured 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 paid cost and snapshot scope, and most sentences carry useful invocation context. However, it includes some sibling-specific pricing detail ('Register: $0 · Delivery after trial: $0.05') and marketing phrasing that is not essential for selecting or invoking get_snapshot.

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 output schema exists and annotations cover read-only/idempotent/openWorld behavior, the description supplies the remaining critical context: cost, auth/payment path, bulk scope, and recommended follow-up tools. Nothing essential for calling the tool correctly appears to be 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?

The only parameter is api_key, and the schema already describes it at 100% coverage. The description adds useful conditional semantics: pass it if you have one, otherwise the response explains x402 payment, which meaningfully clarifies the parameter beyond the schema's 'API key' label.

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 capability and scope: 'Snapshot of every series for every country in one call.' This clearly distinguishes it from narrower siblings such as get_series and get_series_history, which do not promise a full multi-country bulk snapshot.

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 clear payment/auth context and follow-up choices: pass api_key if available, otherwise follow the x402 payment instructions, then bind get_changes or register_alert after a 200. It does not explicitly state when to choose get_snapshot instead of a narrower series endpoint, so an important alternative-selection guideline is missing.

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?

Beyond the readOnly/idempotent/non-destructive annotations, it discloses the price ($0.60), the free-refusal policy (coverage_gap with no_charge for anything unanswerable), the shared rate limit of 3 free calls per IP per day, both auth paths (api_key vs x402 402 response), and that receipts are only issued on paid successes. This is exactly the operational context annotations cannot 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?

The cost and the composite purpose are front-loaded and nearly every clause carries information (pricing, refund policy, rate limit, auth, receipt caveat). It runs long and the receipt/certified-extract distinction is repeated in both description and schema, which is slight redundancy rather than waste.

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

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

For a 14-parameter paid composite tool with an output schema and full annotations, the description covers the remaining gaps: billing model, free-refusal semantics, rate limits, regional coverage, the receipt concept and how to verify it via verify_answer_receipt, and the explicit non-legal-advice / non-certified-extract disclaimers.

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 86% the schema already does most of the work, but the description adds real meaning: the enumerated seller-country universe constrains seller_country beyond 'ISO country code', and the due_date vs invoice_date+terms_days alternation is stated as a usage rule. It also explains the api_key bypass and that receipt defaults to false with no extra USDC charge.

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 plus the exact sub-checks performed: VAT correctness (place of supply, rate, expected vs vat_charged), overdue status and statutory late interest, and tax-ID format validation. Listing supported seller countries (BO, BZ, CL, CO, CR, EC, HN, MX, NI, PA, SV, TT, UY) further narrows what the tool is, letting an agent distinguish this composite check from siblings like compute_vat, compute_statutory_interest, and validate_tax_id.

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

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

It gives explicit invocation context: use it as a one-call invoice check, supply due_date or invoice_date with terms_days, and pass api_key if available or expect the x402 payment requirement. However, it never explicitly says when NOT to use it — e.g., use compute_vat alone if only the VAT rate is wanted, or validate_tax_id for a standalone ID check — so the routing to siblings 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, so the bar is low, yet the description adds substantial non-schema behavior: $0.40 pricing, x402 payment requirement vs api_key bypass, free refusals with no charge on coverage gaps, a shared 3-free-calls-per-IP-per-day quota, and receipt semantics. It also clarifies the receipt is not a certified extract and not legal advice, which prevents misuse of the returned artifact.

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?

Most sentences carry load-bearing information about payment, refusals, quotas, and receipts, so it is not padding. But it opens with a price tag rather than the tool's purpose, and the certified-extract and legal-advice caveats could be compressed, making it dense and hard to scan for an agent.

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

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

An output schema exists, so return values need no explanation, and annotations cover the safety profile. The description handles the remaining agent-facing concerns (payment path, coverage-gap refusals, quota sharing, receipt verification via verify_answer_receipt). It is close to complete, with only minor gaps such as the effect of the debtor and as_of inputs, which the schema already documents.

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

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

Schema coverage is 100%, so the schema already documents all nine parameters and a baseline of 3 would be defensible. The description still adds meaning the schema does not carry cleanly: the due_date-versus-(invoice_date + terms_days) choice, the api_key bypass effect, and that receipt defaults to false and only appears on a paid success.

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 compound job: determine whether an invoice is overdue, by how many days, and the statutory late-payment interest owed under Actual/365 with rate and workings cited. This is far more than a restatement of the name and separates it from generic calculation siblings. It stops short of naming the sibling it most overlaps with (compute_statutory_interest), so sibling differentiation is only partial.

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 invocation conditions ('Send due_date, or invoice_date with terms_days') and states that unanswerable cases are refused free with coverage_gap, which tells the agent what to expect. However, it never says when to prefer this tool over compute_statutory_interest or the other interest/deadline siblings, leaving routing to inference.

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

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

Annotations already 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 readOnly, idempotent, openWorld and non-destructive, so the safety profile is covered. The description adds real value beyond that: the call is free, the response is a metadata catalog, and detail=true yields a large payload. It also clarifies that paywalled answer receipts and certified extracts are distinct, non-legal-advice artifacts.

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 opening two sentences are tight and front-loaded, but the bulk of the text is about unrelated tools — paid answer receipts, Ed25519 verification, certified extract pricing, and which other tools are free. Those sentences do not earn their place in a listing tool's description and dilute the signal.

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

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

An output schema exists, so return values need not be explained, and the rich annotations plus the 'free' and payload-size disclosures give an agent enough to call it correctly. The main gap is the absence of an explicit contrast with get_series, which would complete the discovery-vs-fetch story.

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 both parameters (detail, country) are fully documented in the schema, including the compact-vs-full tradeoff and the per-country metadata behavior. The description adds no parameter syntax or format detail beyond the schema, so the baseline of 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 concrete verb+resource — a catalog of all latamref reference-data series — and enumerates what it returns (countries, series ids, descriptions, freshness metadata, URLs). '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 a clear sequencing directive, and the mentions of verify_answer_receipt, get_changes, get_calendar and register_alert being free imply routing. However, there is no explicit when-not-to-use guidance and no statement of how this differs from get_series, so usage is more implied than spelled out.

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

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

Annotations already cover the read-only/idempotent/non-destructive profile, and the description adds substantially more: price ($0.35), a shared 3-free-calls-per-IP-per-day quota, the free refusal path (coverage_gap, no_charge), the receipt opt-in mechanics, and an explicit 'not legal advice' disclaimer. That is exactly the extra context annotations 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?

The purpose and price are front-loaded in the first sentence, and every later sentence carries a real constraint (refusal, quota, receipt, verification). It is dense and parenthetical-heavy, and the receipt/certified-extract disclaimer is partly duplicated in the schema, but nothing is genuinely wasted.

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

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

With an output schema present, return values need not be described, and the description covers the remaining agent-facing concerns: payment, refusal semantics, rate limiting, receipt behavior, and verification path. Nothing needed to invoke it correctly is missing.

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

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

Schema coverage is already 86%, so the schema documents most parameters. The description still adds meaning the schema lacks: the default window of 90 days and the pricing/behavioral consequence of passing api_key versus relying on x402.

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

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

The description names a concrete verb and resource — upcoming VAT, PAYE and corporate-tax due dates within a window, with weekend/holiday rolling and cited rules — so the agent knows exactly what comes back. It does not, however, distinguish itself from the close sibling get_filing_deadlines, so a sibling-selection ambiguity remains.

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 clear applicability context: verified rules exist for BR, CL, DO, the default window is 90 days, and anything unanswerable is refused free with coverage_gap. It also lays out the payment path (api_key vs x402 card checkout). It stops short of naming when to prefer a sibling such as get_filing_deadlines or compute_vat.

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.