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 annotations: discloses paid cost ($0.02), the x402 fallback, honest-status behavior when no enforceable floor exists, the refusal to guess cross-period conversion, and the receipt's non-legal, non-certified nature. These are exactly the behavioral 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?

Purpose and verdict are front-loaded, and each sentence carries substantive information. It is dense and mixes pricing, receipt and disclaimer material, so it is longer than strictly needed, but no sentence is pure filler.

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

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

With an output schema present, return values need not be explained, and the description still covers payment, free tier, honest statuses, receipt behavior and the verification path via verify_answer_receipt. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema description coverage is 100%, so the schema already documents all five parameters. The description's notes on period matching, receipt defaults and api_key largely restate schema content, adding little beyond the baseline.

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

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

States a specific verb and resource ('is a salary at, above or below the country's statutory minimum wage?') and enumerates the concrete outputs (verdict, margin, statutory floor, legal instrument). This is clearly distinguishable from siblings like compute_employment_cost or compare_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?

Explains the payment path (api_key for instant checkout, otherwise x402) and notes the evaluation country is free to try, pointing to list_series. It also clarifies the boundary against the non-MCP certified-extract endpoint, but gives no explicit guidance on when to choose this over sibling wage/cost tools.

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

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

Goes well beyond the annotations by disclosing cost ($0.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 only give read/idempotent/openWorld hints, but the description adds substantial behavioral context beyond them: it is a paid ($0.05) operation, payment mechanics (api_key vs x402), the refused-list semantics ('unknown, not zero'), free evaluation country, and receipt behavior/verification. This is rich disclosure that the structured fields do not 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 purpose is front-loaded effectively, but the body accumulates pricing, payment-flow, receipt, and legal-disclaimer text that reads more like marketing/terms than tool-selection guidance. Several sentences (certified-extract SKU, not legal advice) are tangential to invoking the tool correctly.

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 and annotations cover the safety profile, the description is nearly complete: it covers cost, payment, refusal semantics, and exclusion of income tax. The only gap is the mismatch between the named alternative and the actual sibling tools.

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

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

Schema description coverage is 100%, so the schema already documents all 12 parameters, setting the baseline at 3. The description adds minor meaning around api_key (card checkout, metering) and receipt (Ed25519, no extra USDC), but most parameter detail is simply repeated from 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 and resource — 'prices every statutory contribution on both the employee and employer sides for a gross salary' — and explicitly scopes out what it is not ('Does NOT compute income tax'). It names a sibling alternative, so an agent can distinguish it without opening the schema.

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

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

Gives clear routing guidance: use compute_payroll for gross-to-net take-home, and the evaluation country is free to try via list_series. The only weakness is that the named alternative (compute_payroll) does not match the actual sibling (compute_income_tax), which could momentarily confuse a routing agent.

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

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

Goes well beyond the readOnly/idempotent annotations: discloses the $0.02 price, the x402 payment fallback and api_key bypass with /pricing checkout, the 402 behavior for unpaid calls, the optional Ed25519 receipt at no extra USDC, and the legal-advice disclaimer. These are operational traits 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?

Front-loaded with the core computation before billing mechanics, and each sentence is informative. It is dense and carries some commercial detail (pricing endpoint, certified-extract aside) that pushes length beyond the minimum an agent needs.

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, read-only compute tool with a full output schema, everything an agent needs is present: input basis, currency/period caveat, payment paths, receipt semantics, and scope exclusions. Return values need not be described since the output schema exists, and the description still previews them.

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

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

Schema description coverage is 100%, so the 3 baseline applies, but the description adds real framing: api_key is optional ('pass api_key if you have one') with an alternative payment path, and the receipt flag's paid-success-only scope is contextualized. Country/income semantics are largely restated from the schema rather than extended.

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

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

Names a specific verb (compute) and resource (statutory income tax) and defines the exact input basis ('tax on a TAXABLE-income figure using the country's verified marginal bracket schedule'). It also states the outputs (per-bracket workings, effective rate, marginal rate), which cleanly separates it from siblings like compute_vat and compute_employment_cost.

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

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

Explicitly states when NOT to expect results from this tool ('NOT net take-home pay — reliefs/allowances and social-security contributions are the caller's concern'), points to the scope_note, and names adjacent tools/paths (list_series for the free country, verify_answer_receipt for verification, the certified-extract endpoint as a separate non-MCP SKU). The free-vs-paid condition is also 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 only declare read-only/idempotent/non-destructive/open-world; the description adds the material behavior: $0.02 pricing, free refusals (non-answers are not sold), api_key vs x402 payment paths, optional Ed25519 receipt at no extra USDC, and the legal-advice disclaimer. That is substantial context beyond what the annotations provide.

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

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

Front-loaded with the core formula, which is good, but it then interleaves pricing, payment logistics, receipt mechanics and two separate 'not legal advice' disclaimers into a dense block. The receipt/certified-extract distinction is also duplicated in the schema's receipt description, so some sentences do not fully 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?

For a paid, multi-mode tool with an output schema, the description covers the payment model, both refusal paths, the optional receipt and its verification tool, and the legal/jurisdictional limits. An agent has everything needed to invoke it correctly or route elsewhere.

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 days, from, to, principal, country, api_key and receipt. The description largely restates this (the from/to/days conflict rule is already in the days schema description) and only marginally enriches it with checkout/refund framing. 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 (simple statutory interest on a principal at the cited statutory-interest series rate) and spells out the exact formula: principal × (rate/100) × (days/365), Actual/365 simple. This is clearly distinguishable from sibling series/tax tools, and the scope limits (no compounding, no jurisdiction-specific day-count statutes) sharpen it further.

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 how to supply the period (pass days, or from/to as YYYY-MM-DD), what happens on conflict (both sent and disagreeing → refused free), what happens when no numeric rate exists (refused free), and routes the agent to the correct alternative (the $0.10 certified extract is not an MCP tool; verify with verify_answer_receipt). When-to-use and when-refused are both 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 already mark this read-only, idempotent, non-destructive, but the description adds substantial context beyond them: explicit price ($0.01), the auth/payment branches, the free evaluation-country carve-out, the optional Ed25519 receipt semantics, and the recommended verification tool. No behavioral surprises remain for a caller.

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?

Payment/auth and mode semantics are front-loaded and the caveats are compressed into the tail. It is somewhat long and the receipt mechanics are duplicated verbatim between the description and the schema's receipt field, which is mild 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?

An output schema exists so return values need not be described, and the description still covers everything else an agent needs: cost, payment flow, mode semantics, receipt behavior, scope limits (not legal advice, not a certified extract), and a cross-reference to verify_answer_receipt.

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 enums (mode, country) are documented in-schema, so the baseline is 3. The description restates mode and receipt semantics usefully but adds little syntactic or format detail the schema does not already carry.

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

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

States a specific verb+resource (VAT breakdown for an amount) and enumerates the exact outputs: net, tax, gross, plus per-levy components for composite rates. This clearly separates it from siblings like compute_income_tax, compute_employment_cost, and compute_statutory_interest.

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

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

Gives concrete when-to-use guidance for the two modes (add = amount is net, extract = backs VAT out of gross) and explains the two payment paths (api_key vs x402) plus the free evaluation country. It does not, however, position itself against sibling tax tools or state exclusions beyond 'not legal advice'.

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 mark the tool read-only, idempotent, open-world, and non-destructive. The description adds substantial behavioral context beyond that: the $0.50 price, free refusal behavior with coverage_gap/no_charge, shared free-call limits, api_key versus x402 behavior, optional receipt behavior, and legal/certified-extract limitations. These details materially help an agent understand cost, payment, failure, and receipt semantics.

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 front-loads the paid nature and core purpose in the first sentence, which is good structure for a complex paid financial tool. It is dense and somewhat overpacked with receipt and certified-extract caveats in a single paragraph, but most sentences add relevant operational or legal context.

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 paid flow, nine-parameter schema, complete schema descriptions, output schema, and annotations, the description covers the important operational context: pricing, api_key/x402 behavior, free refusals, receipt semantics, verification, and legal caveats. It omits explicit sibling-tool routing, which keeps it from a 5.

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 nine parameters, including gross, country, period, start_date, taxable_income, receipt, and api_key. The description adds some context around api_key checkout and receipt non-equivalence, but most parameter meaning is already carried by the schema, making the baseline 3 appropriate.

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

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

The description states a specific verb and resource: it costs a hire as a cited dossier covering salary/wage-floor verdict, contributions, employer cost, optional income tax, and first working day. Scope is clear with 'Countries here: AU.' It does not explicitly distinguish itself from similar siblings such as compute_employment_cost or check_minimum_wage, keeping it below 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?

The description gives payment and access guidance: pass api_key if available, otherwise an x402 payment requirement applies, and unanswerable requests are refused free. It does not say when to choose cost_hire over sibling tools like compute_employment_cost, hire_compare, or check_minimum_wage, so usage is only implicitly guided.

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/destructive annotations: discloses the paid cost ($0.002), the free evaluation country, the 366-day range cap, weekend convention per country, holiday naming, the optional Ed25519 receipt at no extra USDC, and the boundary that a receipt is not a certified extract or legal advice. This is exactly the kind of pricing and authorization context annotations cannot carry.

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

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

The core purpose and pricing are front-loaded, and the dense single paragraph is largely justified by payment, receipt, and verification caveats. It runs slightly long with the legal-disclaimer sentence, but no sentence is pure filler.

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

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

An output schema exists, so return-value detail is not required. Combined with the annotations and full schema coverage, the description supplies everything an agent needs to call it correctly: cost, key handling, range cap, country set, and the receipt/verification path.

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

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

Schema coverage is 100%, so the baseline is 3; the description adds value by explaining the payment consequence of api_key (instant card checkout at /pricing) and by clarifying the receipt flag's semantics beyond the schema text (free refusals and 402s do not include one). It does not restate from/to/country/subdivision, but those are fully documented in 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 and resource (count working days in a date range for a country) and adds scope detail — weekend rules including Egypt's Fri–Sat, statutory holidays applied by name, and the next working day after the range. It is easily distinguished from siblings like business_days_between, is_business_day, and add_business_days.

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 conditional guidance about payment (pass api_key if you have one, otherwise the response explains x402) and names related tools/calls (list_series for the free country, verify_answer_receipt, GET /v1/certified). However it never says when to pick this over the sibling count tools (business_days_between, add_business_days), so applicability is only implied.

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

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

Annotations only cover the safety profile (readOnly, openWorld, idempotent, non-destructive), so the description carries behavior beyond them: the $0.25 charge, the x402 fallback when no api_key is passed, the free refusal path, the shared daily rate limit, the optional receipt behavior, and the verification path. It also flags a legal caveat, which is unusually informative for an agent deciding to invoke.

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 key fact ('PAID ($0.25)'), but the body is one dense run-on packed with parenthetical asides, price mentions, and cross-references that make it hard to parse on a first read. Most sentences carry information, yet the structure works against scanning.

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 does not need to explain returns, and it covers payment, refusal, receipts, and verification thoroughly. The remaining gap is that it never clarifies how the bundled brief relates to the standalone get_country_brief sibling.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real semantics on top: series defaults to 'the first certifiable of vat, policy-rate, minimum-wage', series must all be certifiable, api_key is metered for invoicing, and receipt is no-cost on paid success only. These details are not in 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 artifact: 'the full cited country brief plus up to 3 Ed25519-signed certified extracts', which tells an agent exactly what is produced. It is clear and concrete, but it never explicitly distinguishes itself from the sibling get_country_brief or charge_sale_certified, which appear to overlap in scope.

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 preconditions ('Named series must all be certifiable'), the payment path (api_key or x402 requirement), and the free-refusal condition (coverage_gap, no_charge), and it notes the shared 3 free calls per IP with the answer tools, implying those siblings as alternatives. It stops short of an explicit 'use X instead when Y' routing statement.

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 already cover read-only/idempotent/non-destructive/open-world, yet the description adds substantial behavioral context: the $0.01 cost, dual payment paths (api_key vs x402 explained in the response), and the reason to bind a follow-up tool (so a later gazette does not silently retire the value). This is exactly the kind of value-add annotations cannot supply.

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

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

Front-loads the cost and the resource, then detail. It is dense but each sentence carries information; the payment and follow-up clauses are long but functional rather than filler.

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

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

With an output schema present, the description need not describe return values, and it is complete on everything else an agent needs: price, auth/payment options, scope, and post-call workflow. 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 is optional and conditional on whether you have one, with card checkout at /pricing else x402, and the country scope is clarified as 'one country'. It adds some value beyond the schema's terse field descriptions.

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

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

States a specific verb+resource ('Country brief') and then enumerates exactly what is bundled (policy rate, VAT/GST, CPI, taxes, minimum wage, holidays) with per-series metadata (value, unit, effective/last-confirmed dates, source, confidence). This clearly distinguishes it from single-series 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?

Gives a concrete selection cue ('Cheaper than buying the series one by one') and prescribes a follow-up workflow ('bind get_changes ... or register_alert'). It stops short of naming a specific sibling to use instead when only one series is wanted, but the context is clear.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), and the description still adds substantial behavior: the paid price, the roll_unverified flag when a source is silent on weekend movement, listed skipped holidays, coverage_gap responses instead of invented data, and the get_changes/register_alert freshness mechanism. That is far beyond what annotations declare.

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

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

The content is valuable but the description is a dense run-on that opens with pricing ('PAID ($0.003, same as any series)') rather than the purpose, and stacks many clauses and parentheticals into single sentences. It is information-rich but not tightly structured or front-loaded.

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 pricing, verification/flagging semantics, coverage gaps, holiday rolling, year_end behavior, and value-freshness handling. 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%, so the baseline is 3. The description adds conceptual meaning for year_end (re-anchoring corporate-tax rules to the company's accounting year end) beyond the schema's terse note, but says nothing new about country, tax, from, to, or api_key.

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 (statutory filing deadlines) and enumerates the exact scope — VAT/GST returns, PAYE remittances, corporate income tax returns and provisional payments — as rules plus rolled due dates. This is clearly distinguishable from siblings like compute_vat, get_public_holidays, or get_calendar 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?

It gives useful context (free HTML page alternative, free AU series, post-200 freshness workflow via get_changes/register_alert) and explains when to pass year_end. However, it never explicitly routes the agent between this tool and the compute_* siblings for overlapping tax questions, so usage is implied rather than delimited.

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 safety (readOnly, idempotent, non-destructive, openWorld), so the bar is lower. The description still adds value beyond them: the cost signal ('FREE'), the provenance guarantee ('official government source cited'), and the merge behavior when a subdivision is supplied.

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

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

Front-loads the cost signal, then the core purpose, then the subdivision caveat. Dense but every sentence carries information; the second sentence is long but not padded.

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 country enum plus subdivision semantics are covered. The remaining gap is routing guidance against the worldwide/calendar siblings, which the description leaves to inference.

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

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

Schema coverage is 100%, so baseline is 3. The description goes further by explaining that the subdivisions field enumerates available sub-national calendars and by restating the ISO 3166-2 format and the national+regional merge semantics, which helps an agent decide whether to populate subdivision.

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 (public-holiday calendar) and scopes it to 'a supported country', which implicitly contrasts with the get_public_holidays_worldwide sibling. It stops short of naming that sibling explicitly, so the differentiation is inferred 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?

Gives a clear conditional for the optional parameter ('passing subdivision ... returns national + regional'; 'Omit for the national calendar'), which is real usage guidance. However, it never mentions when to prefer this over get_public_holidays_worldwide or get_calendar, both plausible alternatives for the same need.

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/non-destructive, so the safety profile is covered. The description adds meaningful behavior they do not: the call is free with any API key, never counts against the key's allowance, and the key can be supplied either via the api_key parameter or the X-API-Key header. That quota and auth context is exactly the kind of added value expected here.

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

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

Three tight sentences with no wasted clauses. The opening free-key/promo framing is slightly marketing-flavored and could be trimmed, but the scope distinction and auth note are front-loaded and easy to scan.

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 annotations cover the safety profile. The description supplies the scope, cost, and auth facts an agent needs; only a brief note on what subdivision omission implies is left entirely to the schema, which is acceptable.

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 documented in the schema, including the enum values and the national-vs-regional tagging semantics of subdivision. The description repeats the api_key dual-auth option but adds no syntax or meaning beyond the schema, making the baseline 3 appropriate.

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

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

The description anchors the tool to its sibling ('Same as get_public_holidays, but for every country'), which combined with the name makes the resource (public holidays) and scope (worldwide vs Australasian) unambiguous. It never states the retrieval verb directly, relying on the sibling reference, so it falls just short of a self-contained 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 clearly routes the agent between this tool and get_public_holidays by scope: use this one when the country is outside Australasia. It also flags the cost condition (free/unmetered), which is genuine selection guidance, but there are no explicit when-not-to-use statements or alternatives beyond the one sibling named.

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), and the description goes well beyond: paid cost ($0.003), x402/api_key payment paths, AU free trial, and the exact fields returned (source citation, effective date, last-confirmed date, staleness flag). This is rich operational context an agent needs before calling.

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?

Price and core purpose are front-loaded, and each subsequent sentence carries new information (payment, free trial, follow-up binding). It is dense and slightly overloaded with pricing details, but no sentence is wasted.

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

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

An output schema exists so return values need no explanation, yet the description still characterizes them usefully. Pricing, payment mechanics, free-trial scope, and next-step tools are all covered, leaving nothing essential an agent needs to call 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%, so the schema already documents series, country, and api_key. The description reinforces series examples and api_key behavior but adds no syntax or format detail beyond the schema. 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 ('Current value of a reference series') with concrete examples (policy-rate, vat, minimum-wage). The word 'current' implicitly separates it from get_series_history, but no sibling is named explicitly, so 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?

Gives clear routing guidance: after a 200, bind get_changes (free poll) or register_alert for push. Additive context on api_key vs x402 is explicit. It never states when to prefer this over get_series_history or list_series, but the follow-up alternatives are well specified.

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, openWorld, non-destructive), yet the description goes well beyond them: exact cost ($0.003), the api_key vs x402 payment paths, the free AU trial, and the consequences of not binding a downstream watcher. This is unusually rich behavioral context.

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

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

Front-loaded with the paid marker and the core purpose, then payment and downstream steps in priority order. It is dense and slightly run-on across payment, trial, and sibling-routing topics, but every clause carries information an agent needs.

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. Given the paid/auth complexity, the description covers payment mechanics, the free trial, and what to bind afterward — everything required to call this correctly.

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

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

Schema description coverage is 100%, so all five parameters (including the enum country and the from/to format) are already documented in the schema. The description restates the YYYY-MM-DD format and api_key usage but adds no syntax or constraint detail beyond what the schema provides — 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 — "Historical values of a reference series with effective date ranges" — and scopes the optional from/to filter. An agent can immediately distinguish this from get_series, compare_series, and get_changes without opening any schema.

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

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

Explicitly routes the agent downstream: "bind get_changes (free poll) or register_alert (HMAC push)" after a 200, and clarifies the free AU-series trial. It does not state when to prefer this over get_series/get_snapshot, but the alternative-tool guidance it does give is concrete and actionable.

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

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

Goes well beyond the annotations (which only cover readOnly/idempotent/openWorld) by disclosing the pricing model ($0.02, plus $0.05 alert delivery after trial), the payment/auth flow (api_key, card checkout vs x402 fallback), the AU trial scope, and the data-lifecycle risk that a gazette may retire an unbound value. This is unusually rich behavioral context for a paid read 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?

Front-loads the price and purpose, then proceeds to auth and follow-up routing. Dense but mostly earns its place, though the final sentence packs HMAC, trial pricing, and a gazette-lifecycle warning into one clause, slightly straining 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?

An output schema exists and annotations cover the safety profile, so the description is not obligated to explain return values. It completes the picture with pricing, auth fallback, and next-step tooling; the only minor omission is an explicit contrast with the single-series fetch siblings.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning beyond 'API key' by clarifying it is optional ('Pass api_key if you have one') and describing the fallback behavior (the response explains how to pay via x402) when it is omitted. That is genuine value over 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 and scope: 'Snapshot of every series for every country in one call.' This is distinguishable from siblings like get_series, list_series, and get_series_history because it fetches everything in one bulk call. However, it does not explicitly frame itself against those siblings, so the differentiation is inferred from scope 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?

The description gives strong guidance on what to do AFTER a 200, routing between get_changes ('free poll') and register_alert ('HMAC push'). But for this tool itself, the when-to-use is only implied by 'in one call' rather than stated against alternatives like get_series or list_series. Adequate but with a clear gap on the primary selection decision.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

States a specific verb+resource and enumerates the exact outputs (employer cost, employer/employee contributions, on-cost percent, wage-floor verdict) computed 'side by side and ranked' for 2-5 hires. This implicitly separates it from single-hire siblings like compute_employment_cost and cost_hire, but never names them, so the differentiation is inferred rather than explicit.

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

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

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

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

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

Goes well beyond the readOnly/idempotent annotations: discloses price ($0.60), the free-refusal policy on coverage_gap with no_charge, a shared rate limit of 3 free calls per IP per day across answer tools, the x402-vs-api_key payment path, and receipt behavior on paid success only. It also explicitly disclaims that an answer receipt is not a certified extract nor legal advice.

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

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

Front-loads price and purpose, then constraints, then payment and receipt mechanics — a sensible order with little filler. It is dense with parentheticals and the receipt/payment sentences are long, which costs some readability but not correctness.

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 tool it covers what the agent most needs: what is checked, supported countries, date input rules, refusal and pricing behavior, and payment modes; the output schema handles return shape. Buyer-side country coverage and the meaning of a partial/coverage-gap result are left 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 already 86%, so the schema carries most parameter meaning. The description adds genuine value beyond it by constraining seller_country to five supported jurisdictions and clarifying the due_date vs invoice_date+terms_days relationship, but it says nothing about amount_is, buyer_type, or as_of semantics.

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

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

States a specific verb and resource (check an invoice) and enumerates the three exact outputs: VAT correctness against vat_charged, overdue status plus statutory late interest, and seller/buyer tax ID format validation. This makes clear it is a composite one-call check rather than a single-purpose sibling like compute_vat or 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?

Gives concrete invocation guidance: 'Send due_date, or invoice_date with terms_days', and lists the supported seller countries (FJ, NZ, SB, TO, WS), which tells the agent when the tool is inapplicable. It implies but never explicitly names the alternative single-purpose siblings for the cases it cannot cover, so a 4 rather than 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?

Beyond the readOnly/idempotent annotations, the description discloses price ($0.40), the free-refusal rule (coverage_gap, no_charge), a shared rate limit (3 free calls per IP per day with the answer tools), auth paths (api_key vs x402 402 response), the receipt-issuance behavior on paid successes only, and explicit non-legal-advice / not-a-certified-extract caveats. That is unusually rich behavioral context.

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

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

Front-loaded with price and the core question, then inputs, then payment/refusal mechanics — a sensible order. It is dense but most sentences earn their place, with only mild duplication of the receipt explanation already present in the schema.

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

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

An output schema exists, so return values need not be described; the description still covers pricing, auth, refusal, receipt verification, and disclaimers thoroughly. The one missing piece is a comparison to the overlapping sibling tool, which leaves the selection decision under-supported for this complexity.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description adds the either/or rule for supplying the date (due_date, or invoice_date plus terms_days) and clarifies that receipt on an unpaid 402 or free refusal yields nothing. Those are semantic relationships the schema fields state only individually.

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

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

The opening sentence states a specific question set — is the invoice overdue, by how many days, and what statutory late-payment interest is owed — with the calculation method (Actual/365 simple) and supported regimes (FJ, NZ, SB, TO, WS). It is clear what the tool does, but it never distinguishes itself from the sibling compute_statutory_interest, which an agent would reasonably consider an overlapping 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 invocation guidance ('Send due_date, or invoice_date with terms_days') and a refusal policy for unanswerable inputs, which implies scope boundaries. However, it names no alternative tool and does not say when to prefer this over compute_statutory_interest or the certified/answer tools, so routing remains inferential.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), yet the description adds substantial behavior: the 'FREE, unmetered' cost signal, the refusal semantics (year_not_held with years_held, holiday_date_pending), the guarantee that results are never inferred from weekends alone, and the explicit exclusion of sub-national holidays. This is well beyond what structured fields convey.

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

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

Front-loaded with the cost signal and the core question, followed by returns and then edge-case behavior; every clause carries operational information. The dense weekend-rule parenthetical is long but earns its place by pre-empting surprising classifications.

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

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

For a two-parameter classification tool with an output schema and full annotations, the description covers purpose, return shape, error/refusal paths, cost, and scope exclusions. Nothing an agent needs to call it correctly or interpret a refusal is missing.

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

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

Schema coverage is 100% and both parameters (date YYYY-MM-DD, ISO alpha-2 country) are fully documented in the schema itself. The description reinforces the scope of 'country' (national calendar, accepted across brands) but adds no syntax or format detail beyond the schema, so the baseline 3 applies.

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

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

'Is this date a business day in this country?' is a precise verb+resource, and the stated single-date classification scope implicitly separates it from the range-based siblings (business_days_between, count_working_days, add_business_days). The return summary (reason code, holiday names, adjacent business days) makes the operation unambiguous.

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

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

The description sets clear usage boundaries — it explicitly says regional/supranational holidays are not applied, that unheld years are refused, and which weekend regimes apply, which tells an agent when the answer is authoritative. It does not, however, name an alternative sibling (e.g. get_public_holidays_worldwide or count_working_days) or state when to prefer them, so it stops short of full when/when-not routing.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered. The description adds one genuinely useful trait not in the annotations: that the call is FREE. However, the bulk of the behavioral prose (receipt system, certified extracts, other free tools) concerns sibling tools rather than list_series itself, so tool-specific disclosure beyond cost is thin.

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

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

The first sentence is well front-loaded, but the definition then spends four-plus sentences on paid answer tools, Ed25519 receipts, certified extracts, and which other tools are free — content that belongs in those tools' own descriptions and does not help an agent invoke list_series.

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

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

With an output schema present and 100% parameter coverage, the description need not explain return values, and the purpose plus the 'call first' guidance are sufficient to invoke it correctly. The trailing ecosystem prose is extraneous but does not leave a calling gap.

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

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

Schema coverage is 100%: both 'detail' and 'country' are fully documented in the schema, including the compact-vs-full catalog behavior. The description adds no syntax or format detail beyond what the schema already provides, 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?

Names the resource precisely ('Catalog of all ausref reference-data series') and enumerates its contents (supported countries, series ids, descriptions, freshness metadata, per-series URLs). An agent can immediately tell this discovery/index tool apart from get_series or get_series_history, which retrieve actual 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?

'Call this first to discover what data exists' gives explicit sequencing guidance for the discovery workflow. It does not name a specific alternative to use instead when the catalog is already known, but the when-to-use condition is stated clearly.

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?

Substantially exceeds the annotations: it discloses pricing ($0.35), partial-answer refusal semantics (coverage_gap, no_charge), a shared per-IP rate limit, the x402 fallback when no api_key is supplied, the optional Ed25519 receipt behavior, and what is NOT legal advice or a certified extract. This is exactly the auth/rate-limit/failure context annotations cannot carry.

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

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

Front-loads the price, which is useful, but the prose is a dense run-on packed with parentheticals, SKU cross-references and pricing caveats that dilute the core purpose. Several clauses (certified-extract pricing, verify_answer_receipt pointer) belong elsewhere.

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

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

An output schema exists, so return-value detail is correctly omitted, and the description covers payment, refusal, coverage and receipt semantics. The one real gap is failing to position the tool relative to the overlapping get_filing_deadlines sibling.

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

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

Schema coverage is 86%, so the schema already documents country, tax, from/to, api_key and receipt. The description adds only marginal meaning (card checkout at /pricing, receipt is free but not a certified extract), largely repeating the receipt default that the schema states verbatim. 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: 'Upcoming VAT, PAYE and corporate-tax due dates in a window', with scope details (default 90 days, weekend/holiday roll, cited rules). However, it never distinguishes itself from the near-identical sibling 'get_filing_deadlines', leaving the agent to guess which to pick.

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

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

Gives real operating context – verified coverage limited to AU and NZ, free refusal on coverage gaps, sharing of the 3 free calls per IP per day, and passing api_key vs falling back to x402. But there is no explicit when-to-use/when-not guidance against the many sibling tax tools (e.g. get_filing_deadlines, compute_vat), so selection remains implied.

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

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

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.