reference-data

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

With no annotations, the description carries the full burden. It discloses payment, return fields, honest handling of missing floors, and no cross-period guessing. This is fairly transparent, though rate limits or further auth details are omitted.

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 two sentences, compact and front-loaded with key info. Every sentence adds value: payment, purpose, return values, edge cases, and payment method.

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 no output schema, the description explains return values and edge cases adequately. The tool is simple (4 params, 3 required), and the description covers all necessary aspects for correct invocation.

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

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

Schema description coverage is 100%, so baseline is 3. The description reinforces that period must match the floor's period and adds context about honest statuses, but does not add significant new parameter-level details beyond the schema.

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

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

The description clearly states the tool checks if a salary meets statutory minimum wage, returning verdict, margin, floor, and legal instrument. It distinguishes itself from sibling tools (like compute_income_tax) by focusing on compliance, not computation.

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 usage context: it's a paid tool ($0.05) and explains api_key vs x402 payment. It does not explicitly state when not to use it or name alternatives, but the purpose is distinct enough among 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?

With no annotations, the description carries full burden. It discloses the paid nature, the detailed output format (line-by-line with citations and refused list), and the explicit exclusion of income tax. It does not mention any side effects or data retention, but as a pure computation tool this is sufficient. It also notes the 'unknown, not zero' handling, which is a valuable behavioral detail.

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

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

The description is three sentences with zero redundancy. It front-loads the cost, then the purpose, then the exclusions and payment options. Every sentence contributes essential information, making it highly efficient.

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 11 parameters and no output schema, the description covers the core behavior, output structure, exclusions, and payment. It doesn't list all parameters, but the schema does. It also doesn't mention that only 'ae' is supported, but that is visible in the schema. Overall, the description provides sufficient context for correct usage without overloading.

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 description does not need to elaborate on parameters. It adds context about the gross salary and country implicitly but does not provide additional parameter-specific meaning beyond the schema's own descriptions. 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: pricing statutory contributions on both employee and employer sides for a gross salary, returning line-by-line amounts with citations and a refused list. It explicitly distinguishes itself from income tax computation via compute_payroll, making its scope 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 provides explicit when-to-use guidance and names the alternative tool (compute_payroll) for income tax scenarios. It also explains the payment requirement via api_key or x402, leaving no ambiguity about how to invoke the tool under different circumstances.

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 must carry the full burden. It discloses the cost ($0.05), payment via api_key or x402, and the method (marginal bracket schedule). It does not mention rate limits, error handling, or auth requirements beyond api_key. The behavioral disclosure is adequate but not exhaustive.

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 well-structured, leading with cost, then the main function, caveats, and payment info. Every sentence adds value, though the list of example tax units (Colombia UVT, etc.) could be slightly trimmed. Overall, it is efficient and front-loaded.

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

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

Given the tool's complexity (28 countries, marginal brackets, inflation-indexed units) and the absence of an output schema, the description covers key aspects: what it computes, what it excludes, and payment. However, it does not describe the exact output structure or error behavior, which limits completeness for an agent.

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

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

Schema coverage is 100% with good descriptions for each parameter. The description adds value beyond schema by explaining the api_key's role in bypassing x402, the need to pass local currency, and the context of inflation-indexed tax units. This additional context justifies a score above the baseline of 3.

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

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

The description clearly states it computes statutory income tax on taxable income using marginal brackets. It specifies the scope (taxable income, not net pay) and mentions handling specific tax units. However, it does not explicitly differentiate from sibling tools like compute_vat beyond the tool name.

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 explicitly warns that the tool computes tax on taxable income, not net take-home pay, and that reliefs/allowances/social-security are the caller's concern. It also specifies handling of inflation-indexed tax units and passing local currency. It does not compare directly with alternatives but provides clear context for appropriate use.

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 fully carries the burden of behavioral disclosure. It reveals the tool is paid (costs $0.02), explains authentication options, and describes the composite rate handling.

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 (two sentences) and efficient, covering the core function and key details without unnecessary wording.

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 parameter count and lack of output schema, the description adequately covers the tool's purpose, modes, authentication, and geographic scope, though it does not describe the return 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 coverage is 100%, and the description adds meaning beyond the schema by explaining the 'add' and 'extract' modes, clarifying that amount is in the country's currency, and providing context for the api_key parameter.

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

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

The description clearly states that the tool computes VAT breakdown (net, tax, gross) for a given amount and country, and distinguishes itself from sibling tools like compute_income_tax by specifying VAT-specific behavior and modes.

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 explicit guidance on using the api_key parameter, explains the two modes (add/extract), and implies when to use each. However, it does not explicitly mention when not to use the tool or alternative approaches.

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 fully discloses behavior: handles weekends (including Egypt's Fri-Sat), applies statutory holidays, returns holidays hit by name and next working day, and imposes a max range of 366 days.

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 (two sentences) with key information front-loaded (paid, core function) and no unnecessary words.

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?

While it covers key aspects, the output structure is slightly ambiguous (whether the main return is a count or a list) and lacks explicit error handling, but overall adequate for a parameterized 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?

Although schema coverage is 100%, the description adds important constraints (max 366 days range, special weekend handling) that are not in the schema, enhancing parameter understanding.

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 and public holidays. It distinguishes from sibling tool 'get_public_holidays' by focusing on counting and returning the next working day.

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 mentions the tool is paid ($0.02) and provides guidance on payment via api_key or x402, but does not explicitly compare to siblings or state when to use this vs. alternatives.

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 'FREE' and explains subdivision behavior, but lacks details on rate limits, error handling, or data freshness.

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 key purpose and free status. Every sentence adds value; no wasted words.

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 main functionality and subdivision parameter well, but lacks description of response format (fields like date, name, type). With no output schema, this information would aid an AI agent.

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

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

The description adds significant value beyond the schema: explains ISO 3166-2 format for subdivision, describes behavior for national vs merged calendars, and mentions the subdivisions field. This is crucial for correct parameter usage.

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 explicitly states 'Official public-holiday calendar for a supported country', including gazetted movable holidays and government source. This clearly distinguishes it from sibling tools like 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?

The description does not explicitly state when to use vs alternatives, but implies usage for retrieving public holidays. No exclusions or comparative guidance are given.

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 of behavioral disclosure. It discloses the paid nature ($0.005), the response fields (source citation, effective date, last-confirmed date, staleness flag), and the x402 payment alternative. This is substantive, though it does not mention rate limits or error 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?

Two concise sentences, front-loaded with the essential cost and purpose, followed by response details and payment instructions. Every clause adds value without 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?

The description covers the key contextual facets: cost, payment, response content, and staleness behavior. It does not explicitly mention the required 'country' parameter or output format, but the schema covers country and the response fields are enumerated. For a simple look-up tool, this is sufficiently complete.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds the series examples, but these are already present in the schema's series description. It does not clarify the country parameter further or add new parameter semantics beyond what 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 returns the current value of a reference series, with concrete examples (policy-rate, vat, minimum-wage), distinguishing it from sibling tools like get_series_history and list_series. The verb and resource are specific and 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?

No guidance is given on when to use this tool versus siblings such as get_series_history or list_series. The description provides parameter examples but no selection criteria or exclusions, leaving the agent without context for choosing among related 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?

No annotations are provided, so the description carries the full burden. It discloses the $0.005 cost, the need for an api_key, and that without one the response explains x402 payment. This is valuable behavioral context. It does not mention rate limits or response structure, but the paid nature is the most critical trait.

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 cost warning, and every word earns its place. It packs purpose, filtering, and payment information without 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 data-retrieval tool with 5 parameters and no output schema, the description covers the essential aspects: purpose, date filtering, cost, and payment flow. It does not describe the return format or pagination, but the effective date ranges and historical values give a clear enough picture. Sibling context further clarifies its role.

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 a baseline of 3 is appropriate. The description adds meaning by explaining the from/to parameters are YYYY-MM-DD filters, and that api_key is optional with a specific fallback behavior. This goes beyond the schema descriptions and clarifies parameter usage.

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 'Historical values of a reference series' with a specific verb ('get') and resource, and distinguishes itself from siblings like get_series (likely current values) and get_snapshot by focusing on historical data with effective date ranges. The '$0.005' cost flag and date-filter mention add unique scope.

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

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

It provides clear usage context: use for historical values, optionally filter by from/to, and how to pay. However, it does not explicitly name sibling tools as alternatives or state when not to use, leaving some inference to the reader. Still, the date-range and historical framing give good 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?

No annotations provided, so the description carries full burden. It discloses the cost ($0.02) and the behavior when no api_key is provided (response explains payment). However, it doesn't mention whether the call is idempotent, rate limits, or response size. Adequate but not exhaustive.

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 'PAID ($0.02)'. Every word earns its place. No redundancy or fluff.

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?

No output schema exists, so the description should cover what the snapshot contains. It says 'snapshot of every series for every country' but doesn't specify the data format or structure. Also lacks potential response size warnings. Adequate for a simple tool but leaves some unknowns.

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 input schema has one parameter (api_key) with 100% coverage. The description adds that the api_key is optional and explains the fallback behavior (payment instructions). This gives context beyond the schema's simple 'API key' description.

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 it provides a snapshot of every series for every country. The verb 'snapshot' combined with the scope distinguishes it from siblings like get_series (single series) or list_series (list). However, it doesn't explicitly contrast itself with alternatives.

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 context about the paid nature and how to pass an api_key or get payment instructions. But it doesn't explicitly state when to use this tool vs siblings (e.g., 'use this to get all data at once; use get_series for a single 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?

No annotations provided, but description notes 'FREE' and lists output contents. Sufficient for a read-only catalog tool, though could mention no destructive effects or authentication 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?

Two sentences; first gives essential information about output, second gives usage advice. No extraneous words, efficiently front-loaded.

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

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

No output schema, but description enumerates the types of data returned (countries, IDs, descriptions, freshness, URLs). Combined with usage hint, fully informs agent of what to expect and how to use.

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?

No parameters in schema (0 params), so description doesn't need to add parameter info. Baseline of 4 applies as schema coverage is 100%.

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 explicitly states 'Catalog of all asiaref reference-data series' and lists what it provides, distinguishing it from sibling tools like get_series which likely target a specific 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?

Clearly instructs 'Call this first to discover what data exists,' giving a preferred usage order. Does not explicitly mention when not to use, but context with siblings implies alternatives.

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?

Despite no annotations, the description fully discloses behavioral traits: it charges $0.05, shows a per-day trail, refuses to guess, uses national statutory holiday calendars (not CSD/exchange), and cites primary sources for cycles. It also notes known divergences and refusal conditions.

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 front-loaded with the core purpose. It efficiently packs many details (pricing, cycle examples, calendar definitions, refusal conditions) into a single paragraph, making it comprehensive for a complex 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?

Given the tool's complexity (6 parameters, no output schema, no annotations), the description is remarkably complete. It covers all essential aspects: how to invoke, what to expect, edge cases, pricing, and data sources, leaving no significant gaps for an AI agent.

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

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

Schema coverage is 100%, so baseline is 3. The description adds significant meaning beyond the schema by explaining how business_days and market+instrument_class interact, calendar codes like 'eu.t2', and the meaning of trade_date (day 0 never counted/rolled). This justifies 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 computes settlement/value dates as n business days after a trade date using the intersection of specified calendars. It distinguishes itself from sibling tools (none of which handle settlement date computations), and provides specific examples of cycles and jurisdictions.

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 explicitly tells when to use the tool (e.g., 'Supply business_days for a cycle you are trading under, or market + instrument_class') and when not (e.g., 'We refuse FREE rather than guess: beyond published calendar coverage, no cited cycle...'). It also explains how to specify calendars and the 'eu.t2' for euro cash leg.

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