reference-data

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

With no annotations, the description carries the full behavioral burden. It discloses paid status, honest statuses, refusal to guess cross-period conversions, receipt behavior, and the fact that output is not legal advice. This is unusually transparent.

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

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

The description is front-loaded with the paid status and the core verdict, then flows to outputs, edge cases, payment, and verification. It is dense but each sentence earns its place; only slight redundancy with the schema keeps it from a 5.

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

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

Given there is no output schema, the description adequately explains return contents, edge cases, payment path, and receipt verification. An agent has enough context to invoke the tool and interpret its responses correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds minor usage nuance around api_key fallback and period matching, but most parameter meaning already exists in the schema 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 specific compliance question: whether a salary is at, above, or below the statutory minimum wage, and lists the returned outputs (verdict, margin, statutory floor, legal instrument). This clearly distinguishes it from sibling tax, cost, and holiday 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?

The intended use case is clear: check a salary against a country's statutory minimum wage, with explicit paid-access and api_key guidance. It does not explicitly compare against sibling tools like compute_income_tax, but it does clarify what the answer receipt is not and how to verify it.

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?

With no annotations, the description carries the full behavioral burden, and it does so thoroughly: it discloses the $0.10 paid cost, the unknown-not-zero refused-list behavior, the fact that income tax is excluded, the api_key/x402 payment mechanism, receipt semantics, and the caveat that receipt is neither a certified extract nor legal advice.

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

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

The description is dense but well ordered: paid status and core behavior come first, followed by the tax exclusion, payment options, and receipt details. Some redundancy exists with the receipt parameter schema, and the parenthetical about the certified extract is long, but every sentence contributes operational 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?

For a paid, complex tool with 12 parameters and no output schema, the description is unusually complete: it describes the output format, payment/auth path, edge cases (refused list), limitations (no income tax, not legal advice), and verification pathway via verify_answer_receipt. An agent has enough context to select and invoke it correctly.

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

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

Schema description coverage is 100%, so the baseline is 3 and the schema already documents every parameter including enums and defaults. The description adds useful payment and receipt context, but it does not add material per-parameter semantics beyond what the schema 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 description leads with a specific verb and resource: 'Cost to employ: prices every statutory contribution on both the employee and employer sides for a gross salary.' It also states the exact output shape (line-by-line amounts, instrument citations, explicit refused list) and explicitly distinguishes itself from income-tax computation, making it easy for an agent to separate from siblings like compute_income_tax.

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 states what the tool does and does not do, and explicitly routes income-tax/gross-to-net requests to compute_payroll where supported. It also explains the payment path (api_key vs x402). It slightly weakens routing by naming compute_payroll, which is not among the provided sibling tools, and does not address when to prefer check_minimum_wage or compute_vat.

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

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

No annotations are provided, so the description carries the full burden. It discloses the $0.05 cost, payment via api_key or x402, receipt behavior, the scope_note in the response, and that it's not legal advice. However, the discrepancy between the mentioned indexed-unit countries and the actual enum is a transparency issue; the description implies support for countries not in the schema.

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 long (about 150 words) but dense with essential information: cost, scope, payment, receipt, and caveats. It front-loads the purpose and important constraints. Each sentence earns its place, though the country example list could be trimmed or corrected. It is structured with clear sections and emphasis.

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?

There is no output schema, so the description must explain the response. It mentions 'full per-bracket workings, effective rate and marginal rate' and a scope_note, plus receipt details. It also explains the payment flow. However, it doesn't specify the exact response structure or error cases, but given the complexity and payment context, it is largely complete. The country mismatch is a notable gap in completeness.

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 parameters are already well documented. The description repeats the taxable_income period basis and adds context about api_key and receipt, but these are also in the schema. It adds minimal new meaning beyond the schema, so a baseline 3 is appropriate.

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

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

The description clearly states the tool computes statutory income tax on taxable income with full per-bracket workings, effective and marginal rate. It distinguishes from siblings like compute_vat and compute_employment_cost. However, it lists Colombia, Chile, Peru, and Uruguay as examples of indexed tax units, but the schema's country enum only includes au, fj, nz, pg, sb, to, vu, ws. This mismatch could mislead an agent into thinking those countries are supported, so the purpose is clear but with a misleading example set.

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

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

It explicitly states this is tax on taxable income, NOT net take-home pay, and that reliefs/allowances and social-security contributions are the caller's concern. It also mentions alternative endpoints (certified extract) and verification via verify_answer_receipt. The guidance is clear, but the country mismatch could cause an agent to attempt unsupported countries, so it's not perfect.

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?

With no annotations, the description carries the full burden and delivers: $0.05 paid cost, free refusals on day-count disagreement or mechanism-only series, no charge for non-answers, simple-interest-only calculation, legal disclaimer, receipt behavior, and verification path. This discloses cost, failure modes, and boundaries of the calculation.

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 $0.05 cost and formula, then covers parameter modes, free refusals, payment, receipt, and verification. It is long but warranted for a paid call; however, 'not legal advice' appears twice and the certified-extract aside adds minor redundancy.

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

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

For a paid tool with seven parameters, no annotations, and no output schema, the description covers cost, when calls are refused free, how to authenticate/pay, optional receipt semantics, and verification. An agent has enough information to invoke the tool correctly and interpret the transaction behavior.

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

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

Schema description coverage is 100%, so the schema already documents all parameters. The description reinforces the days vs from/to relationship and adds the formula and fee context, but does not materially extend per-parameter semantics beyond what the schema 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 action and resource — computing simple statutory interest on a principal at a cited statutory-interest series rate — and even gives the formula (principal × rate/100 × days/365). This clearly differentiates it from sibling compute_* tools, which target other calculations.

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 clear invocation context: use days, or from/to in YYYY-MM-DD, with explicit inclusive/exclusive semantics, payment via api_key or x402, and receipt option. It lacks an explicit 'when not to use' or named alternative, though the formula and domain make the intended use obvious.

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?

With no annotations available, the description carries the full disclosure burden and meets it: it declares the $0.02 cost, the x402 payment fallback, receipt conditions, the non-certified/non-legal status of the receipt, and the verification route. This goes well beyond what the schema alone reveals.

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 cost and purpose and contains no filler. However, the receipt/certified-extract caveat largely repeats the input schema's receipt description, and the unsupported Ghana example adds noise, so it is not maximally economical.

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?

There is no output schema, so the description must convey return semantics, and it does: net/tax/gross plus per-levy components for composite rates. Payment, auth, receipt, verification, and limitations are all covered, leaving no obvious gap for an agent to call 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 coverage is 100% and the schema already documents mode and receipt semantics, so the baseline is 3. The description adds useful api_key/payment behavior and output composition context, but its Ghana example is not in the country enum (au/fj/nz/pg/sb/to/vu/ws), which could mislead an agent choosing a country; this prevents a higher score.

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

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

The description opens with a concrete action and resource: it produces a VAT breakdown (net, tax, gross) at the country's statutory rate and explains mode behavior. This clearly separates it from siblings like compute_income_tax and compute_employment_cost. The composite-rate mention adds useful product specificity.

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

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

It gives explicit mode-selection rules (add vs extract), explains the payment and api_key flow, and warns that an answer receipt is not a certified extract nor legal advice. It also routes verification to verify_answer_receipt, making the when-to-use and when-not-to-use guidance concrete.

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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It comprehensively reveals that the tool is paid ($0.02), handles country-specific weekends, applies statutory holidays, caps the range at 366 days, requires an api_key or explains payment via x402, and optionally returns an Ed25519 answer receipt. It also clarifies that the receipt is not a certified extract and not legal advice, and that verification is possible via verify_answer_receipt. This is exceptionally transparent.

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 dense but each sentence earns its place, front-loading the paid status and core purpose. It covers payment, range limits, receipt details, and caveats without fluff. While it could be broken into paragraphs for readability, it is not overly verbose and is well-structured for an agent to parse.

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 (paid, receipt, subdivision, country-specific weekends), the description covers the essential behaviors, output (holidays hit and next working day), payment mechanism, and verification. It doesn't explicitly state the return format, but that's minor. It also handles edge cases like unpaid 402 and free refusals. The description is sufficiently complete for an agent to use correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds meaning beyond the schema by explaining the 366-day range limit for from/to, detailing the receipt parameter's behavior and verification path, and connecting the subdivision parameter to get_public_holidays. It also clarifies the country-specific weekend handling. This goes beyond what the schema 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 description clearly states the tool counts working days in a date range for a country, applying weekends (with special handling for Egypt's Fri-Sat) and statutory public holidays. It also specifies the output: holidays hit by name and the next working day after the range. This is a specific verb+resource that distinguishes it from siblings like get_public_holidays and settlement_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 provides no explicit guidance on when to use this tool versus alternative siblings. It does not mention when not to use it, or how it compares to settlement_date or get_public_holidays. The only reference to an alternative is the note about the certified extract, which is not an MCP tool and is about the receipt, not the tool's usage context.

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?

With no annotations, the description carries full responsibility and excels: it discloses derivation logic for reverify_by and next_effective_known, conditionality on effective_to, handling of 'status unknown', negative behaviors (never parses notes, does not invent dates), and error semantics (402 gate bug). This goes far beyond a typical description.

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 information-dense and every clause is useful, but it is written as a single run-on paragraph, making it harder to scan. It front-loads the main action and cost signal, but would benefit from bullet points or clearer sentence breaks.

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 no output schema, the description explains key derived fields and error codes, but does not give a high-level statement of the return structure (e.g., a list of calendar entries). It is adequate for an informed agent, but a bit more would make it fully complete.

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

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

Schema coverage is 100% and both parameter descriptions already include detailed semantics (options, free error codes). The tool description only restates that country and series are optional and adds no new meaning beyond the schema, so a baseline 3 is appropriate.

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

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

The description identifies a specific endpoint ('GET /v1/calendar') and scope (this brand's continent), and differentiates from get_changes by stating 'Past changes stay on get_changes.' It is not a tautology and clearly indicates the tool retrieves a calendar, though it does not explicitly name all sibling 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?

The description provides explicit cost/free guidance ('FREE, unmetered'), optional parameters, and a direct when-not reference to get_changes for past changes. It also warns about 402 being a gate bug. However, it does not fully enumerate use cases against all siblings, so it stops short of a 5.

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

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

With no annotations provided, the description carries the full burden, and it delivers: it discloses the sorting order (newest first), the default window (last 30 days), the fields returned (last_confirmed, stale), the freshness summary contents, and that it is free/unmetered. Nothing contradicts the annotations because there are none.

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 contains valuable routing and alternative instructions. It is slightly wordy with promotional flourishes like 'Freshness is checkable or it is marketing' and redundant pricing details, but overall it is organized and each major sentence serves a purpose.

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 read-only feed tool with one optional parameter and no output schema, the description is complete: it explains the default behavior, return contents, freshness summary, usage timing, and alternative tools. An agent has enough to select and invoke this 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 schema already fully documents 'since' with format and default. The description only restates 'Args: since? (YYYY-MM-DD)' and adds usage context rather than new parameter-specific semantics, so baseline 3 is appropriate.

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

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

The description clearly states the tool's function: it returns changed series since a given date plus a dataset-wide freshness summary. It explicitly distinguishes itself from siblings by saying 'Do not re-pay get_series to discover a diff' and by naming alternatives like register_alert and the certified 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?

The description gives explicit when-to-use guidance: 'After any paid series or answer call, call this before you assume the cached value is still the law.' It also provides exclusions and alternatives: do not use get_series for diffs, use register_alert for push, and use the certified endpoint for a filing freeze.

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?

No annotations provided, so description carries full burden. It discloses that the tool is free, cites official sources, and explains behavior with subdivisions (merged calendar). It does not mention rate limits or auth, but for a read-only holiday tool this is sufficient. Missing details on response format, but the explanation of sub-national calendars adds transparency.

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

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

Two sentences, front-loaded with the core purpose in the first sentence. The second sentence provides essential sub-national detail. No fluff or 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 2 parameters and no output schema, the description covers the main functionality (national and sub-national calendars). However, it does not clarify the limited set of supported countries (the enum shows only 8 Pacific nations), nor does it describe the expected response structure (e.g., list of holiday objects). This could leave the agent uncertain about handling unsupported countries or the output format.

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%, baseline 3. Description adds value by explaining that 'country' is an ISO code with examples, and that 'subdivision' returns merged national+regional holidays. It also mentions the existence of the 'subdivisions' field in the response, which goes 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?

Description clearly states it provides official public holiday calendars, including movable holidays and sub-national calendars. It uses specific verbs like 'get' and 'returns', and distinguishes from siblings like count_working_days or settlement_date by focusing on holiday data.

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

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

Explicitly marked as 'FREE', and explains when to use the subdivision parameter. It implies usage for obtaining holiday data but does not state when not to use it or provide direct comparison to sibling tools. However, given sibling tools are about wage, tax, working days, etc., the context is clear.

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

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

With no annotations provided, the description carries the full behavioral burden and does so thoroughly. It discloses the $0.005 cost, the x402 payment/auth flow, response contents (official source citation, effective date, last-confirmed date, staleness flag), and the risk that later gazettes can silently retire the value. This is far richer than a typical read-hint.

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 dense but tightly organized: it front-loads the paid/current-value identity, then adds only decision-relevant details about response fields, payment path, and follow-up actions. Every sentence earns its place and there is no repetition of schema content.

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 tool with no output schema and no annotations, the description covers cost, authentication, return-value semantics, and required post-call follow-up. Required parameters are already fully documented in the schema, so nothing needed to invoke the tool correctly is missing.

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

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

The schema already documents all three parameters at 100% coverage, so the baseline is 3. The description adds real value by giving valid series examples and explaining api_key's behavioral effect (bypasses x402, metered for invoicing), which goes beyond what the schema 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?

The description opens with a specific verb and resource: 'Current value of a reference series', with concrete examples like policy-rate, vat, and minimum-wage. The 'current' qualifier helps distinguish it from get_series_history, and the mention of get_changes clarifies its downstream role, though it does not explicitly contrast all sibling 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?

The description clearly sets the call context: the tool is paid, api_key bypasses x402, and after a 200 the agent should bind get_changes or register_alert to avoid silent retirement. It does not explicitly state when to prefer this over get_series_history or list_series, but the current-value framing provides enough practical guidance.

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

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

With no annotations, the description carries the full burden. It discloses the monetary cost ($0.005), the payment mechanism (api_key or x402), and a behavioral caution about silent retirement of the value, suggesting follow-up actions. It does not detail the response format or error handling, but the cost and payment disclosure are significant behavioral traits.

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

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

The description is concise relative to the information it conveys: cost, purpose, filtering, payment, and follow-up steps are all packed into three sentences. It is front-loaded with the paid flag and purpose. Each sentence earns its place, though it is dense and could be split for 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?

For a paid tool with no output schema and no annotations, the description covers the essential usage: cost, payment, date filtering, and post-call actions. It does not describe the exact response structure (fields like effective date ranges), but it gives a high-level picture. The absence of pagination or error handling is a minor gap, but overall it is complete enough for an agent to call it correctly.

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

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

Schema coverage is 100% and each parameter already has a description. The description adds minor value by specifying the date format (YYYY-MM-DD) and clarifying the api_key's optional role and payment fallback, but it does not materially enhance the schema beyond that, so a baseline of 3 is appropriate.

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

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

The description clearly states the tool returns 'Historical values of a reference series with effective date ranges', which is a specific verb+resource and distinct from siblings like get_snapshot or get_changes. It also mentions optional date filtering, leaving no ambiguity about what the tool does.

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 provides clear context: it is a paid operation, requires an api_key or payment via x402, and includes post-call guidance to bind get_changes or register_alert. It does not explicitly contrast with alternatives like get_series or get_snapshot, but the purpose and follow-up instructions give enough situational guidance.

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

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

With no annotations provided, the description carries the full burden. It discloses the cost (PAID $0.02), payment options (api_key or x402 explanation), and the behavioral consequence of not binding follow-ups ('a later gazette does not silently retire the value'). This is substantial transparency beyond what a generic schema would convey, though it doesn't detail return format or safety guarantees.

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 cost and purpose, and every sentence adds value: cost, what it does, payment method, and follow-up binding. It is compact but dense, and the 'this series' reference creates slight ambiguity, but overall it is well-structured and not overly verbose.

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 tool with one optional parameter and no output schema, the description covers purpose, cost, payment, and post-call actions. The only gap is ambiguity around 'this series' – the snapshot returns multiple series, yet the follow-up binding refers to a singular series, which could confuse an agent. Otherwise it is quite complete.

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

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

The schema describes api_key simply as 'API key' (100% coverage), but the description adds meaningful semantics: it clarifies that api_key is optional and explains the fallback behavior when omitted ('otherwise the response explains how to pay via x402'). This goes beyond the schema, so a 4.

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 clearly states the tool returns 'Snapshot of every series for every country in one call' – a specific verb, resource, and scope. It doesn't explicitly contrast with siblings like get_series or list_series, but the phrase 'every series for every country' makes the bulk nature evident, so a 4 is appropriate.

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 provides follow-up guidance ('After a 200, bind get_changes ... or register_alert') and cost context, but does not explicitly say when to use this over alternatives like get_series or list_series. The guidance is implicit rather than explicit exclusions, so a 3.

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?

No annotations are provided, so the description must carry the full burden. It states the tool is FREE, which is a cost-related behavior, and implies it is a read-only catalog operation. However, it does not disclose potential side effects, rate limits, authentication needs, or what happens if the catalog is empty or unavailable. The description also mixes in behaviors of other tools, which could confuse the agent about what list_series itself does. For a simple listing tool, this is acceptable but not thorough.

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 excessively long and includes a significant amount of irrelevant information about paid answer tools, receipts, certified extracts, and other free tools. The core purpose is in the first sentence, but the rest is a tangent that does not help an agent use list_series correctly. This violates the principle of front-loading and conciseness. Every sentence should earn its place; here, most of the latter half is unnecessary for understanding this specific tool.

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

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

For a zero-parameter catalog tool with no output schema, the description provides the essential information: what the catalog contains (countries, series ids, descriptions, freshness metadata, per-series URLs) and that it is free. However, it is not fully complete because it does not explain how to interpret the results, any potential limitations, or how this tool integrates with the paid answer tools mentioned. The inclusion of unrelated tool info could mislead an agent into thinking those are part of list_series. A cleaner, more focused description would be more complete for the agent's needs.

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

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

There are zero parameters in the input schema, so the baseline for this dimension is 4. The description does not need to explain any parameter semantics because there are none. It could have mentioned that no parameters are required, but the schema already reflects that, and the description's mention of 'Call this first' implicitly signals no inputs are needed. No additional value is lost.

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 clearly states the tool lists all ausref reference-data series and what fields it returns, and explicitly says 'Call this first to discover what data exists.' However, it is cluttered with unrelated information about paid answer tools, receipts, and other endpoints, which dilutes the primary message and makes the purpose less immediately obvious. It does distinguish from siblings by being the discovery entry point, but the extra text muddies it.

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 a clear directive to 'Call this first,' which establishes a primary usage scenario. However, it does not explicitly say when not to use it or compare it to alternatives beyond mentioning other tools are free. The mention of paid answer tools, verify_answer_receipt, and other free tools is tangential and does not provide clear routing logic. There is no explicit 'use X instead when...' guidance.

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

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

With no annotations, the description carries the full burden and does so well: it discloses pricing (free trial, $0.10 later, refunded on send failure), HMAC-SHA256 signing, the difference between series.changed and source.changed, that unknown source URLs are refused, and that api_key is not metered. This level of disclosure is thorough for a webhook registration 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?

The description is long but densely packed with essential information. It uses bullets for the two watch types and front-loads the core purpose. Every sentence contributes to usage clarity; the structure helps parsing despite the length.

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 (pricing, security, two modes, constraints), the description covers the essentials: required and optional params, limits, event types, and its relationship to polling. No output schema is present, but the description does not need to explain return values since it's a registration call. Missing details like webhook payload structure are minor given the scope.

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% with descriptions already present. The description adds significant semantic value beyond the schema: it explains the meaning of series vs sources, gives examples, clarifies that source URLs must be exact and fingerprinted, and states max limits. This is more than the baseline 3 for full 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?

The description states a specific purpose: binding a webhook to receive notifications when served values or source document bytes change, preventing silent staleness. It also differentiates itself from sibling tools like get_changes by explicitly being a push alternative (retention, not polling).

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 usage guidance is provided: it says 'Prefer this over polling get_changes if you are a long-running agent,' and explains the two watch types (series vs sources) with distinct semantic triggers. It also notes constraints (max 20 each, required url). It doesn't explicitly list when NOT to use it, but the alternative guidance is sufficient.

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?

With no annotations present, the description carries the full burden, and it delivers: it discloses the $0.05 fee, free-refusal policy, receipt behavior, verification path, and the legal disclaimer that receipts are not legal advice. It also explains what each response contains ('a per-day trail showing every skipped day and why' and 'the basis and any known divergence').

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 long and dense, but nearly every sentence earns its place given the tool's complexity. Core purpose and cost are front-loaded, with refusal conditions, calendar semantics, and receipt details following logically. A small amount of redundancy with the schema's receipt parameter keeps it from a perfect score.

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, refusal-prone tool with no output schema, the description is remarkably complete: it covers pricing, input modes, calendar semantics, citation behavior, refusal grounds, receipt handling, and verification. An agent has enough context to decide whether to call it, how to call it, and what to expect back.

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 100%, the description adds meaning the schema cannot convey: business_days and market+instrument_class are alternative modes, calendars are national statutory calendars with researched weekend rules, 'eu.t2' is the euro cash leg, and trade_date day 0 is 'never counted, never rolled.' This goes far beyond the baseline and materially improves correct invocation.

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

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

The description opens with a specific outcome — 'Settlement/value date: the date n business days after a trade date' — and immediately distinguishes this from calendar-only tools by emphasizing the INTERSECTION of calendars and the per-day trail. It also clarifies what the tool is not ('NOT CSD or exchange calendars'), which separates it from siblings like get_public_holidays and count_working_days.

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

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

It explicitly tells the caller how to configure the two input modes: 'Supply business_days for a cycle you are trading under, or market + instrument_class to have a settlement cycle applied.' It also states concrete refusal conditions ('We refuse FREE rather than guess'), directs users to a free companion endpoint, and points to verify_answer_receipt for receipt verification.

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?

With no annotations available, the description carries the full behavioral burden, and it delivers. It discloses cost ('FREE'), network behavior ('may GET signature.public_key'), a security constraint ('Never send a private key'), a semantic guarantee ('A valid signature shows this service issued that exact receipt'), and a limitation (does not produce a certified extract). This is far beyond what a bare schema would convey.

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

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

The description is front-loaded with 'FREE' and the core verb, then branches into usage details. It is longer than the high-calibration example but every sentence earns its place. The only mild bloat is the parenthetical '($0.25, not an MCP tool)' and the aside about legal advice, which could be trimmed without losing essential meaning.

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

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

For a tool with no output schema and no annotations, the description is remarkably complete. It covers purpose, parameter relationships, offline/online modes, security, cost, and non-goals. The only minor omission is the exact return type (e.g., boolean or object), but the phrase 'A valid signature shows...' effectively defines the success result. The description leaves no critical gap for an agent to call 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?

Even though the schema already documents all four parameters at 100% coverage, the description adds conditional logic that the schema lacks: when signature_value is needed (receipt lacks a nested signature), when public_key_pem is required (offline verification), how public_key_url is used (only when public_key_pem is omitted), and the override rule for signature_value. It also clarifies the canonical-JSON rule and prohibits private-key PEMs—meaningful semantics beyond the raw JSON 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 opens with an imperative verb and a specific resource: 'Verify an answer receipt (kind answer_receipt) with the Ed25519 public key only.' It immediately distinguishes this from the other tools, which deal with wages, taxes, holidays, and series snapshots, and it scopes the operation to verification rather than issuance or extraction.

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 explicit when-to-use guidance: it explains the offline path, the optional online fetch, and the exact conditions for passing signature_value. It also names what this tool is not for (turning a receipt into a certified extract at $0.25) and warns against private keys. No alternative MCP tool is needed—this is a dedicated verifier—and the exclusion prevents misuse.

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