Afriref: cited government reference data

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

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

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

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

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

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

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

With an output schema present, return-shape details are correctly omitted, and the description still covers the failure modes, the calendar-coverage boundary, and the exclusions an agent must know to call this safely. Little is left for the agent to discover at runtime.

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

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

Schema coverage is 100%, so the baseline is 3, and the description genuinely adds semantics beyond the schema: the start date is day 0 and never counted, n=0 returns the date itself if it is a business day else the next one, and negative n walks backward. The only gap is that the +/-500 bound and country-code format are left entirely to the schema.

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

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

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

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

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

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

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

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

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

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

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

The description is front-loaded with the core purpose and key constraint, and most sentences are dense with useful detail. It is somewhat long and includes several illustrative country examples that, while relevant, could be trimmed for brevity, but the structure remains clear and purposeful.

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

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

Given the tool's complexity and the existence of an output schema, the description is complete enough for correct invocation. It covers calculation semantics, return contents, calendar limitations, and explicit error conditions, leaving no significant ambiguity for an agent to resolve.

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

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

Although schema coverage is already 100%, the description adds important semantic meaning: country selects a national public-holiday calendar and statutory weekend rule, from/to follow half-open interval semantics with potential negative counts, and regional holidays are excluded. This goes well beyond the schema's terse date and country-code descriptions.

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

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

The description states a precise verb and resource: counting business days between two dates. It distinguishes itself from the sibling add_business_days by explaining the inverse relationship and the interval convention '(from, to]', and it clarifies the inclusive-counting variant, so an agent can identify the tool's exact purpose without opening the schema.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Schema coverage is already 100%, so the baseline is 3, but the description adds genuine semantics: omitting buyer_country for single-country maths, api_key bypassing x402, and the receipt flag's effect on paid successes. It goes beyond restating the schema.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

For a paid, complex, high-stakes tool this covers cost, payment paths, refusal semantics, rate limits, and verification route, and an output schema exists so return values need no prose. Nothing an agent needs to invoke it correctly is absent.

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

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

Schema description coverage is 100%, so the schema already documents all 8 parameters including net/gross, buyer_type defaults and api_key bypass. The description largely restates the receipt flag rather than adding new parameter semantics, so the baseline 3 applies.

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

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

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

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

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

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

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

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

Annotations already declare readOnly/idempotent/non-destructive/openWorld, so the safety profile is covered. The description adds real behavioral context beyond that: pricing ($0.02, PAID), the x402/API-key payment paths, honest statuses when no enforceable floor exists, and the rule that cross-period conversion is never guessed. Some of this (receipt, api_key) duplicates the schema, keeping it from a 5.

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

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

Front-loaded with the core purpose, which is good, but the body is dense with pricing, payment mechanics, a legal disclaimer, and receipt caveats — much of which repeats the schema's receipt/api_key descriptions. Several sentences could be trimmed without losing decision-relevant information.

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

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

An output schema exists, so return values needn't be spelled out, yet the description still summarizes them usefully. Combined with payment, receipt, and edge-case behavior (no floor, period mismatch), the definition is nearly complete for invoking the tool 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, but the description adds meaning beyond the schema: it stresses that the period must match the floor's period and that mismatches are surfaced honestly rather than converted, and it clarifies the api_key bypass and receipt-at-no-extra-cost 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 ('Compliance verdict: is a salary at, above or below the country's statutory minimum wage?') and explicitly enumerates the returned artifacts (verdict, margin, statutory floor, legal instrument). It also distinguishes itself from the certified-extract SKU, so an agent can tell it apart from siblings without opening a schema.

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

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

Gives clear context for use: the evaluation country is free to try (routing to list_series), api_key bypasses x402, and the paid receipt path is optional. It names adjacent tools (list_series, verify_answer_receipt) and the non-MCP certified endpoint, but stops short of explicit when-to-use/when-not guidance versus the 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?

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

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

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

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

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

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

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

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

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

Schema coverage is 100%, so baseline is 3, and the description adds value by giving concrete series examples (vat, policy-rate, minimum-wage, corporate-tax) and restating the 10-country cap, plus explaining the api_key alternative path. It stops short of documenting any format beyond the schema.

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

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

States a specific verb (compare) and resource (one series across countries) with scope bounded to 'up to 10 countries of this brand in one call'. It is clearly distinguishable from siblings like get_series (single fetch) and get_series_history (time series) because it frames the multi-country, single-call dimension.

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

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

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

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

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

Annotations cover the safety profile (readOnly, idempotent, openWorld), and the description adds substantial context beyond them: the $0.02 price, the api_key/x402 payment paths, that unpaid 402 and free refusals omit a receipt, that scope_note appears in the response, and the legal-advice disclaimer. This is the kind of billing and response-shape disclosure annotations cannot convey.

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

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

Front-loads price and purpose, but is dense and packs several cross-references (certified endpoint, verify_answer_receipt, list_series) into one block. Nearly every sentence earns place, though the pricing/receipt detail is verbose enough to slightly reduce 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?

With an output schema present, return values need not be described, and the description still covers pricing, payment, receipt semantics, scope limitations, and verification path. Nothing an agent needs in order to call it correctly is missing.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds contextual meaning, especially around the receipt parameter (paid-success-only Ed25519 receipt, not a certified extract) and the taxable-income period basis caveat (monthly for a subset of countries), above what the schema already states.

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

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

States a specific verb (compute) and resource (statutory income tax on a taxable-income figure) and names the concrete scope: marginal bracket schedule with per-bracket workings, effective and marginal rates. It explicitly distinguishes its input from a related but different quantity (net take-home pay) and thus differentiates itself from siblings like compute_payroll.

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

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

Gives explicit when-to-use and when-NOT: 'this is tax on taxable income, NOT net take-home pay — reliefs/allowances and social-security contributions are the caller's concern and are not applied.' It also routes payment decisions (api_key vs x402, /pricing) and points to list_series for free-country evaluation.

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 on top: a $0.05 price, two payment paths (api_key vs x402), disclosed fallback assumptions when pay composition is omitted, receipt behavior (Ed25519, only on paid success, no extra USDC), and explicit scope disclaimers (not a certified extract, not legal advice). This is exactly the beyond-annotation disclosure the dimension asks for.

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 enough and dense with useful information, but the receipt/certified-extract explanation appears twice (once in the description body, again nearly verbatim in the receipt parameter), and leading with 'PAID ($0.05).' before the purpose is a slightly awkward opener. Still largely earns its length for a 13-parameter paid tool.

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

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

With an output schema present, the description need not explain returns, and it still covers pricing, both authentication paths, country scope, assumption disclosure, receipt semantics and legal boundaries. Nothing an agent needs to invoke this correctly — including the free-trial escape hatch via list_series — 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 the schema does not carry: the 40/30/10 fallback convention for Nigeria's pension base and what happens when basic/housing/transport are omitted, plus the api_key-vs-x402 behavior attached to that parameter. The receipt and certified-extract distinction is also disambiguated beyond the schema text.

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

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

States a specific verb and resource — gross-to-net take-home pay computation — and names the exact statutory machinery (PAYE, pension/NHF/NHIS for Nigeria; NSSF/SHIF/AHL for Kenya) plus the return content (net pay with workings and citations). An agent can immediately tell this apart from compute_income_tax, compute_vat or check_minimum_wage.

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

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

Gives conditional input guidance: pass basic/housing/transport for an exact Nigeria pension base or a 40/30/10 market convention is assumed and disclosed; pass api_key for instant card checkout, otherwise x402 explains payment; the evaluation country is free. It lacks explicit when-not-to-use guidance relative to siblings like compute_income_tax, so it falls short of a 5.

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

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

Annotations already declare readOnly/idempotent/openWorld/no-destructive, and the description adds substantial context beyond them: price ($0.02), free refusal semantics for mechanism-only series and conflicting dates, x402 payment flow, optional Ed25519 receipt behavior, and explicit scope limits (jurisdiction compounding/day-count not applied, not legal advice).

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

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

Front-loads the pricing and the formula, which is the most decision-relevant content. It is dense and repeats the receipt/certified-extract distinction that also lives in the schema, but every sentence carries genuine information and none is filler.

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

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

For a paid, open-world computation tool with an output schema already defined, the description covers the computation method, refusal conditions, payment paths, receipt verification, and scope limitations. An agent has everything needed to call and interpret it correctly.

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

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

Schema description coverage is 100%, so the fields (days, from, to, api_key, receipt, principal, country) are already documented in the schema. The description restates the days-vs-from/to rule and receipt semantics but adds little syntax beyond what the schema 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?

States a specific verb and resource (compute statutory interest) and goes further by giving the exact formula and day-count convention (Actual/365 simple, principal × (rate/100) × (days/365)). This clearly separates it from siblings like compute_vat, compute_income_tax, and compute_payroll without requiring the schema.

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

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

Explicitly tells the agent how to supply the period (pass days, or from/to, with disagreement refused) and how payment works (api_key vs x402), and it names related SKUs (certified extract, verify_answer_receipt). It stops short of explicit when-to-use/when-not guidance against the compute_* siblings, but the context is otherwise 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?

Goes well beyond the readOnly/idempotent annotations: discloses the $0.01 price, the x402 pay-per-call flow, optional api_key for instant card checkout, free evaluation country, the receipt opt-in at no extra USDC, and explicitly that the output is not a certified extract nor legal advice. This is exactly the extra context annotations cannot carry.

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

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

Front-loads the core purpose and mode semantics in the first two sentences, then handles payment and receipt details. Slightly overloaded with parenthetical asides and repeated receipt explanation (also present in the schema), but every sentence still carries actionable information.

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

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

An output schema exists, so return-value detail is not required. Given that, the description covers pricing, payment paths, mode selection, receipt semantics, verification route and legal caveats—everything an agent needs to invoke and interpret a paid, open-world compute tool.

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

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

Schema coverage is already 100%, so the baseline is 3; the description adds value by framing mode in terms of net-vs-gross semantics and by clarifying what the receipt flag actually returns and when it is absent. It does not add much beyond the schema for amount or country, which are self-explanatory.

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

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

States a specific verb and resource (VAT breakdown: net, tax, gross) plus the rate basis (country statutory rate) and composite-levy handling. This clearly separates it from siblings like compute_income_tax, compute_payroll and compute_statutory_interest without needing to open any schema.

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

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

Explains the two operating modes (add treats amount as net, extract backs VAT out of gross) and the api_key/payment fork, plus points to list_series for the free evaluation country. It gives clear context for calling it, but never states when to prefer it over adjacent siblings or when it is the wrong tool.

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

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

Annotations only cover the safety profile (readOnly, idempotent, non-destructive, openWorld). The description goes well beyond that with price ($0.50), the no-charge refusal path, rate-limit sharing, auth mechanics (api_key bypassing x402, card checkout at /pricing), receipt semantics, and an explicit disclaimer that a receipt is not a certified extract or legal advice.

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

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

Front-loads the paid price and the core verdict, which is the right ordering for an agent deciding whether to call it. It is dense and information-rich, but the receipt paragraph is nearly duplicated verbatim 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 9-parameter paid tool with an output schema and full annotation coverage, nothing material is missing: cost, refusal behavior, auth paths, rate limits, country scope, and receipt/verification flow are all stated. Return values are covered by the output schema, so the description need not restate 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 coverage is 100%, so the baseline is 3; the description still adds value beyond the schema by explaining the api_key bypass/metering context and the receipt's conditions (only on paid success, not on 402 or free refusals, no extra USDC) plus the verify_answer_receipt follow-up. It largely restates taxable_income, start_date, and hours_per_week, which the schema already documents.

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

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

Opens with a specific verb+resource ("Cost this hire") and enumerates exactly what the dossier contains: wage-floor verdict, employer/employee contributions, employer cost, optional income tax, and first working day. This cleanly separates it from siblings like check_minimum_wage, compute_payroll, and hire_compare, and it scopes the resource to KE and NG.

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 operative context: the two supported countries, the free-refusal contract (coverage_gap, no_charge), the shared 3-calls-per-IP-per-day budget with the answer tools, and the api_key-vs-x402 path. It does not explicitly contrast against the nearest sibling tools (e.g. hire_compare or check_minimum_wage), so routing between them is still left to inference.

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

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

Annotations already cover safety (read-only, idempotent, non-destructive), yet the description adds substantial behavior: the $0.002 price, api_key vs x402 payment paths, the 366-day range limit, the free evaluation country, and precisely what the receipt flag does and does not yield. It also warns the output is not legal advice.

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

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

The core purpose is buried after a parenthetical price tag, and the text is a dense run-on packed with payment and legal caveats that crowd the operational facts. Everything is arguably relevant, but the structure is cluttered rather than front-loaded and clean.

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 covers pricing, payment fallbacks, range limits, subdivision behavior, and receipt semantics. It is essentially complete for a paid read tool, with only sibling-disambiguation 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 100%, so the baseline is 3, but the description meaningfully extends two fields: api_key gains payment mechanics (card checkout at /pricing vs x402) that the schema stub lacks, and the description clarifies that the receipt is an answer receipt, not a certified extract.

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 — counting working days in a date range for a country — and specifies the inputs it accounts for (weekends incl. Egypt's Fri–Sat, statutory holidays). It does not, however, differentiate itself from the very close sibling business_days_between, leaving overlap unexplained.

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

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

It gives clear context: free evaluation country, paid otherwise, and routes the agent to list_series and verify_answer_receipt explicitly. It also distinguishes itself from the non-MCP certified-extract SKU. It stops short of saying when to prefer this over business_days_between or add_business_days.

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

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

Annotations already declare readOnly/idempotent/non-destructive/openWorld, and the description adds substantial context on top: paid pricing, free refusal for non-RDAP registries, fail/warn thresholds (under 30 days, under 180 days, expiring within 30 days, on hold), and an explicit auth failure mode (api_key_required when no key is supplied over MCP). This is rich, non-obvious behavioral detail beyond the annotations.

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

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

The description repeats itself: the $0.005 price appears twice and the non-RDAP free-refusal (422) is stated twice. The lead opens with pricing and exclusions before stating the core purpose, so it is not fully front-loaded. Still, each block is on-topic and no filler content is present.

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 lookup tool with an output schema already covering return values, the description covers everything an agent needs: purpose, price, auth path (api_key vs HTTP x402), failure modes, TLD exclusions, and the fail/warn decision thresholds. There is no material gap affecting correct invocation.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds real meaning for api_key: that it is an Afriref key with card credit, that per-call x402/MPP payment is HTTP-only, and that omitting it over MCP yields an api_key_required error naming the HTTP endpoint. That materially explains the second parameter beyond the schema's one-line note.

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

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

The description states precisely what the tool returns: registrar name and IANA ID, created/expires/changed dates, status flags, DNSSEC, and nameservers, all from the registry's RDAP. It also frames the use case (registrar ownership, domain age, risky newly-registered domains), which differentiates it in practice from a generic check. It never names the sibling domain_check, so sibling differentiation is implicit 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?

It gives clear when-to-use ("when you need to know which registrar holds a domain, how old it is, and whether it is a risky newly-registered domain") and a concrete when-not (registries without RDAP, listing .za/.co.za, .me, .de, .io, .eu, which are refused with 422). It stops short of naming the alternative tool to use for those cases, so the routing is incomplete.

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

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

Annotations already declare readOnly/idempotent/non-destructive/openWorld, and the description still adds substantial behavioral context: it is PAID at $0.01 per domain, non-intrusive, refuses invalid/nonexistent/private-only domains for free, and the MCP path requires an api_key (x402 payment is HTTP-only, otherwise an api_key_required error names the HTTP endpoint). That is exactly the auth/cost/error disclosure structured fields cannot carry.

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

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

Dense but front-loaded — cost, then use cases, then the check inventory, then the return shape, then payment mechanics. Minor redundancy: the $0.01 price is stated twice ('PAID ($0.01)' and '$0.01 per domain'), and the long parenthetical listing every check code is heavy.

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 external-scan tool this is complete: cost, auth path, refusal behavior, return shape (0-100 score plus per-check pass/warn/fail/info grades with fix records) and the note that info checks don't move the score. An output schema exists, yet the description still frames the result usefully.

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, but the description adds real meaning: api_key is an Afriref key purchasable at https://afriref.dev/pricing, it bypasses x402, is metered for invoicing, and its absence produces a specific api_key_required error. domain format detail (no URL, no IP) is left 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?

The description names a specific verb+resource — a domain/email security check that grades SPF, DKIM, DMARC, MX, MTA-STS, DNSSEC, CAA, TLS, domain age, BIMI and blocklists. It is unmistakably distinct from the sibling domain_age, which covers only one of the many signals enumerated here.

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 scenarios are given: 'when mail lands in spam, before an email campaign, for vendor due diligence or to confirm a Microsoft 365 tenant.' That is strong when-to-use guidance, but it offers no when-not conditions and never references the domain_age sibling as an alternative.

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, yet the description adds pricing, the free-refusal path (coverage_gap, no_charge), the shared rate limit, the payment flow, and receipt semantics. This is unusually rich behavioral disclosure for a read-only tool and materially de-risks an unexpected charge.

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 payload is front-loaded well ('PAID ($0.25). Country evidence pack...'), but it reads as a single dense run-on with a long parenthetical and repeats the receipt-vs-certified-extract distinction that the schema already states. Every fact is relevant, yet the packaging is not tight.

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, and the description covers payment, refusal, defaults, rate limits, and verification path (verify_answer_receipt against /certified/public-key). An agent has enough to call this correctly and anticipate cost outcomes.

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

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

Schema coverage is 100% so the baseline is 3, but the description adds meaning the schema lacks: what happens when series is omitted (default first certifiable of vat/policy-rate/minimum-wage) and the constraint that all named series must be certifiable. It also restates the receipt caveat, which the schema already covers.

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

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

States a specific resource and composition: 'the full cited country brief plus up to 3 Ed25519-signed certified extracts.' It also gives the default series set (vat, policy-rate, minimum-wage), which lets an agent distinguish this bundle from get_country_brief and from the non-MCP certified-extract endpoint.

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 usage context — it is paid ($0.25), requires certifiable series, shares 3 free calls/IP/day with the answer tools, and returns an x402 payment requirement without an api_key. However, it never explicitly says when to prefer this over siblings like get_country_brief or get_series, so routing is left to inference.

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

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

Annotations 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 readOnly/idempotent/openWorld/non-destructive, so the description earns credit for adding the non-obvious commercial and auth behavior: $0.01 cost, two payment paths (api_key or x402), and the post-call binding recommendation. It omits error/rate-limit behavior, and the register_alert pricing line reads as cross-sell rather than behavior of this 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 purpose and value in the first sentence, then cost/auth, then follow-up — a sensible order with little waste. The trailing register_alert pricing parenthetical adds length that serves the vendor's upsell more than the caller's decision, slightly diluting an otherwise tight paragraph.

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

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

Covers what the payload contains (value, unit, effective and last-confirmed dates, official source, confidence label), the cost, the auth paths, and the recommended next step. With an output schema present the return shape need not be restated, so the only real omission is failure-mode behavior (e.g., what happens without payment or for an unsupported country code).

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 country enum is self-documenting, so the baseline is 3. The description goes slightly beyond by explaining the role of api_key ('if you have one; card checkout at /pricing') and the fallback payment flow, which the schema's bare 'API key' label does not convey.

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

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

States a concrete verb+resource ('Country brief: every reference series we hold for one country') and enumerates the content types (policy rate, VAT/GST, CPI, taxes, minimum wage, holidays). This clearly separates it from single-series siblings like get_series/get_series_history, so an agent can pick it without opening any schema.

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

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

Gives clear context ('Cheaper than buying the series one by one') that positions it against per-series calls, plus the auth prerequisite ('Pass api_key if you have one... otherwise the response explains how to pay via x402'). It also prescribes a follow-up ('bind get_changes or register_alert'). It stops short of an explicit when-not or a named alternative tool, so not a 5.

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

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

Annotations already declare readOnly/idempotent/non-destructive, yet the description adds substantial behavioral context beyond them: pricing, holiday and weekend rolling with every skipped day listed, the roll_unverified flag instead of guessing, coverage_gap for unverifiable countries with explicit 'never invented' guarantee, and post-response polling/alert guidance. That is materially richer than the annotations.

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

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

The core purpose is front-loaded and dense with useful detail, but the description is padded with pricing/marketing text ('PAID ($0.003, same as any series)', 'Every GH series is free to try', the register_alert price breakdown) that does not help an agent select or invoke the tool. Several sentences earn their place; several do not.

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

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

For a six-parameter, high-complexity tool with an output schema and annotations present, the description covers what an agent needs: scope, the year_end re-anchoring behavior, integrity flags (roll_unverified, coverage_gap), and follow-up polling. Return-value shapes are handled by the output schema, so nothing critical is missing.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds real meaning for year_end (re-anchors corporate-tax rules on the company's accounting year end, targeting year_end_variable rules) and reinforces the from/to window semantics and the tax filter. This exceeds what the schema alone conveys, though most parameters remain 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+resource: recurring statutory tax deadlines for a country, and enumerates the content precisely (VAT/GST returns and payments, PAYE remittances, CIT returns and provisional instalments) as cited RULES plus rolled DUE DATES. This is clearly distinguishable from calculation siblings like compute_vat or compute_statutory_interest, which produce amounts rather than deadlines. An agent can identify the tool's output shape 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 context for optional behavior (pass year_end to re-anchor corporate-tax rules) and for follow-up actions (bind get_changes to poll, register_alert for HMAC push after a 200), plus a free alternative view via the HTML page. It does not explicitly say when to prefer this over sibling tax tools or name any exclusion, 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 readOnlyHint, idempotentHint, non-destructive, and openWorld. The description adds real value beyond them: the pricing behavior ('FREE', 'Never metered') and the dual auth path. It does not mention pagination or error behavior, but with an output schema present the return shape is covered.

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

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

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

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

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

Complete for a zero-required-parameter, single-purpose read tool: it covers cost, return fields, plan/coverage semantics, and both authentication paths, while the output schema handles return structure. An agent has everything needed to call it correctly.

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

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

Schema description coverage is 100% and the schema already explains api_key is optional when sent as a header. The description reinforces this by stating the alternative header mechanism explicitly, adding marginal convenience rather than new semantics.

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

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

States a specific verb+resource (get key balance) and enumerates exactly what is returned: plan, quota, used, remaining, reset date, coverage. No sibling tool overlaps this domain, and the name alone would be ambiguous without this detail.

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

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

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

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

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

Annotations already cover readOnly/idempotent/non-destructive/openWorld, so the bar is lower. The description still adds real behavioral context: the call is FREE, results cite an official government source, sub-national calendars exist where available, and passing `subdivision` returns national plus regional days tagged national/regional. No freshness/rate-limit or error behavior is mentioned, keeping it below 5.

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 sentences, front-loaded with the free/country-scope framing before the subdivision detail. Every clause carries information (source citation, merge semantics, code format) with no filler.

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

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

An output schema exists, so return values need no explanation, and the two parameters are fully covered in the schema. The description supplies the remaining context an agent needs, the country scope, the data provenance, and the sub-national merge behavior, making it complete for this read-only tool.

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

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

Schema description coverage is 100%, so both parameters are already documented in the schema, including the exact merge behavior and the 'DE-BY' style example that the description repeats. The description's only added nuance is pointing at the response's `subdivisions` field to discover valid region codes, which is marginal given full schema coverage.

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

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

States a specific verb+resource ('Official public-holiday calendar for a supported country') and adds scope detail (gazetted movable holidays, official government source cited). It implicitly separates itself from get_public_holidays_worldwide by emphasizing a single supported country, but never names that sibling explicitly.

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 for the `subdivision` parameter ('omit for the national calendar'), which is useful. However, it offers no tool-selection guidance against nearby siblings such as get_public_holidays_worldwide, is_business_day, or get_calendar, leaving when-to-use-this-vs-that to inference.

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

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

Annotations already declare readOnly, idempotent, openWorld, and non-destructive, so the safety profile is covered. The description adds genuinely useful non-annotation context: it is free/unmetered, never counts against the key's allowance, and supports auth via either the api_key parameter or the X-API-Key header. That quota and auth detail earns credit above the annotation baseline.

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 tightly packed sentences with the value proposition front-loaded. The free-key URL and 'seven brands' phrasing lean promotional but stay short, and no sentence is wasted.

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

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

With an output schema present, return values need not be explained. The description covers scope, sibling routing, cost/quota, and auth mechanism, which is what an agent needs to invoke it. Only the optional subdivision behavior is left entirely to the schema, a minor gap.

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

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

Schema description coverage is 100%, so all three parameters (api_key, country, subdivision) are already documented in the schema, including the enum and the subdivision format. The description only restates the api_key/header auth option and adds nothing about the subdivision parameter. Baseline 3 applies when the schema carries the load.

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 scope by direct analogy: 'Same as get_public_holidays, but for every country across all seven brands, not only Pan-African.' Combined with the name, an agent knows this returns public holidays globally. It stops short of a standalone verb+resource statement, relying on the sibling for the base meaning.

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 establishes when to pick this over get_public_holidays (all countries vs. Pan-African only), which is the key routing decision between the two siblings. There is no explicit when-not-to-use or mention of non-holiday alternatives, but the primary selection condition is 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 declare read-only, idempotent, open-world, non-destructive, but the description goes well beyond them: it discloses the $0.003 cost, both payment paths (api_key vs x402 fallback), the free trial for GH series, and the exact fields each value carries (source citation, effective date, last-confirmed date, staleness flag). This is rich, actionable 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-loads price and purpose, then packs payment, return-field, and follow-up details into a single dense paragraph. Every sentence carries information, though the follow-up-tool sentence with its pricing parenthetical is slightly overloaded.

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, payment-gated tool this covers everything an agent needs: cost, auth options, payment fallback, what the response contains, and what to do next. An output schema exists, so return-value explanation is a bonus rather than a requirement.

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, but the description adds meaning the schema lacks — the api_key parameter's fallback behavior (response explains x402 payment) and the 'every GH series is free to try' caveat. The series-id examples largely duplicate 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+resource ('Current value of a reference series') and gives concrete series examples (policy-rate, vat, minimum-wage). The word 'Current' implicitly separates it from get_series_history and list_series, but neither sibling is named, so the differentiation is inferential rather than explicit.

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

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

Gives clear operational context: pass api_key if you have one, otherwise the response explains x402 payment, and it tells the agent to bind get_changes or register_alert after a 200. It does not explicitly route to get_series_history for past values, so the alternative-selection guidance is incomplete.

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: discloses the $0.003 cost, that an api_key is optional, the x402 fallback payment path, that every GH series is free to try, and recommended follow-up bindings. This is exactly the kind of cost/auth/behavioral context annotations cannot express.

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

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

Front-loads the PAID marker and purpose, which is good, but then rambles into payment checkout mechanics and alert-delivery pricing that is dense and partly tangential to the tool's core function. Several clauses could be trimmed without loss.

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

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

With an output schema present, return values needn't be explained, and the description covers cost, auth, filtering, and follow-up options. It is close to complete, though it omits any explicit statement of what the series values represent or pagination/size expectations.

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 restates the from/to YYYY-MM-DD format already present in the schema and adds only marginally that api_key is optional; it adds little semantic meaning 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+resource ('Historical values of a reference series with effective date ranges'), which an agent can act on. It distinguishes the temporal/history nature implicitly, but never explicitly contrasts itself with siblings like get_series or compare_series, so an agent must infer which returns history vs. current values.

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 post-call guidance (bind get_changes or register_alert after a 200) and payment workflow context, but provides no guidance on when to choose this tool over get_series, get_snapshot, or compare_series. Usage is implied rather than stated as a selection rule.

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

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

Annotations cover readOnly/idempotent/destructive, but the description adds highly relevant behavior the annotations cannot convey: PAID ($0.02), optional api_key, an x402 payment fallback, and the free-trial scope for GH series. It also warns that series values can be silently retired, motivating the alert chaining. Lacks rate/limit or response-shape detail, but that is largely covered elsewhere.

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 is front-loaded as the first token, which is the right priority. Four dense sentences carry distinct payloads (pricing, auth, free trial, chaining), though 'so a later gazette does not silently retire the value' is jargon-heavy and could be plainer.

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

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

With an output schema present, return values need no explanation, and the description fills the genuinely missing pieces: cost, auth mechanics, and recommended post-call chaining. It omits any note on response size or ordering for a tool that returns 'every series for every country,' a minor gap for a bulk endpoint.

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

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

Only one parameter at 100% schema coverage, so baseline is 3. The description meaningfully exceeds the bare 'API key' schema description by establishing that api_key is optional and describing the alternative payment path (card checkout at /pricing or x402 instructions in the response).

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 with scope: 'Snapshot of every series for every country in one call.' The 'every series / every country / one call' scope implicitly distinguishes it from single-series siblings like get_series or get_series_history, but no sibling is named explicitly, so an agent must infer the contrast.

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?

Clear context for use: pass api_key if available, otherwise x402 payment, and GH series are free to try. It also routes the agent to follow-on tools (get_changes, register_alert) after a 200. It stops short of stating when NOT to use it versus alternatives such as get_series.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Beyond the readOnly/idempotent annotations, the description discloses price ($0.60), the free-refusal behavior (coverage_gap, no_charge), the shared 3-free-calls-per-IP-per-day quota, the x402 fallback, and the receipt semantics including what a receipt is NOT (not a certified extract, not legal advice) plus how to verify it. This is exactly the behavioral 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 cost and purpose are front-loaded well, but the prose is dense and run-on, packing pricing, quotas, receipts, disclaimer language, and a pointer to a non-MCP SKU into long sentences. Much of the receipt/legal-advice caveat duplicates the receipt parameter description in the schema, so some sentences don't 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?

With an output schema present, return values needn't be explained, and the description covers the remaining agent-facing concerns: cost, quotas, payment modes, refusal semantics, and receipt verification. It is thorough for a 14-parameter, high-complexity composite tool, with only minor redundancy against the parameter docs.

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 most parameters; the description still adds cross-field constraints the schema only hints at (due_date vs. invoice_date+terms_days) and, critically, enumerates the supported seller countries, which is a real usage constraint not expressible via the free-form country field. It adds genuine meaning over the schema baseline.

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

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

The description names a concrete action ("Check an invoice") and enumerates the three checks it bundles: VAT correctness, overdue status plus statutory late interest, and tax-ID format validation. It implicitly distinguishes itself from the granular siblings (compute_vat, compute_statutory_interest, validate_tax_id) by framing itself as "in one call," though it never names those siblings explicitly.

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 explains the payment path (api_key if you have one, otherwise the x402 payment requirement). It also states the coverage boundary — unsupported seller countries are refused free with coverage_gap. What's missing is an explicit statement of when to prefer this composite over the individual sibling tools.

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

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

Annotations only cover read-only/open-world/idempotent safety. The description adds payment requirement ($0.40/x402), shared free-call limits, no_charge refusal behavior, receipt issuance details, legal disclaimer, and verification path, which is rich context beyond structured fields.

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

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

It front-loads the purpose, but the wall of sentences mixes pricing, free calls, receipt mechanics, legal disclaimers, and verification. The 'PAID ($0.40).' opening and overall length are noisy rather than concise.

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 details need not be repeated. The description covers inputs, country coverage, refusal semantics, payment model, and receipt behavior, making it nearly complete for a paid read-only computation tool, though not elegantly organized.

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

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

Schema description coverage is 100%, so baseline is 3. The description restates the due_date vs invoice_date+terms_days alternative and the country list, but adds little syntax or format detail beyond what the schema already provides.

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

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

The question-form first sentence names the computation: invoice overdue status/days and statutory late-payment interest, with covered countries listed. It distinguishes from certified extracts and legal advice, but does not explicitly contrast with sibling 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?

Provides an input recipe (due_date or invoice_date with terms_days) and payment/free-call constraints, plus refusal behavior. It does not state when to choose this tool over compute_statutory_interest or other interest 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 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/destructiveHint=false, so safety is covered, and the description adds the useful "FREE" cost signal. The detail-size warning lives in the schema rather than the description. Most of the remaining text (receipts, certified extracts, other free tools) describes other endpoints rather than this tool's behavior, adding noise more than transparency. No contradiction with 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 first two sentences are tight and front-loaded, but they are followed by a long, off-topic block covering answer receipts, certified extracts, verify_answer_receipt, get_changes, get_calendar, and register_alert. This unrelated material bloats the definition and buries the tool's actual behavior.

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 essential purpose, cost, and discovery-first role are all present. Nothing critical to calling a read-only catalog tool is missing; the main defect is the volume of extraneous cross-tool content rather than an omission.

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

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

Schema description coverage is 100%, so both parameters (detail, country) are already fully documented in the schema, including the compact-vs-full behavior. The description adds no syntax or format detail beyond that, so the baseline of 3 applies.

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

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

Opens with a specific verb+resource: a catalog of afriref reference-data series, enumerating what it returns (countries, series ids, descriptions, freshness metadata, per-series URLs). This clearly separates it from get_series, which fetches one series. The purpose is clear, though the definition is diluted by a large block of text about receipts and other tools that has nothing to do with listing 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?

"Call this first to discover what data exists" is an explicit, actionable directive that positions the tool as the entry point before other calls. However, it never names the alternative for retrieving an individual series (get_series) or explains when not to use this tool, so the routing guidance is partial rather than complete.

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

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

Far exceeds the annotations: it discloses price ($0.35), the free coverage_gap/no_charge refusal path, the shared 3-free-calls-per-IP-per-day limit, the x402 fallback when no api_key is passed, and that a paid success can include an Ed25519 receipt verifiable via verify_answer_receipt. The 'not legal advice' disclaimer and the distinction from certified extracts are exactly the behavioral context an agent needs.

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

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

Front-loaded with the paid price and the core purpose, and every sentence carries a distinct obligation (coverage, refusal, billing, receipt). Some redundancy remains: the receipt/certified-extract caveat appears in both the description body and the schema, and the pricing/verification sentences 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 no prose, and the description still covers everything else an agent needs: price, payment modes, rate limits, coverage boundaries, refusal semantics, and receipt verification. Nothing material about invoking this tool correctly is left unstated.

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%, but the description still adds meaning: receipt is tied to paid successes only (unpaid 402 and free refusals exclude it) and api_key is described as bypassing x402 while remaining metered. It does not clarify country/tax/date interaction beyond what the enum and descriptions provide.

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

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

The description names a specific verb and resource (upcoming VAT/PAYE/cit due dates in a window) with concrete scope: weekend/holiday rolling and an enumerated country set. It differentiates itself from related SKUs like the series certified extract, but never explicitly distinguishes itself from the close sibling get_filing_deadlines or get_calendar.

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

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

It states the conditions that make the tool usable: the verified-country list, the default 90-day window, the free refusal path for anything not answerable in full, and how api_key vs x402 payment works. It stops short of naming an alternative tool for callers whose country is not covered, so the routing guidance is implied rather than explicit.

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