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 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?

Discloses cost ($0.02), paywall via x402, and fallback behavior when no api_key is provided. With no annotations, this provides valuable behavioral context for a read-like operation.

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 action and cost, no redundant information. Every word earns its 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?

No output schema, so description should clarify what the snapshot contains (e.g., fields, structure). Lacks details on return format or limits, but for a simple one-call tool it is minimally adequate.

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?

Single parameter api_key is described in schema but the description adds value by clarifying it is optional and its role in bypassing the payment explanation. This goes beyond the schema's minimal 'API key' label.

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

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

Description clearly states it returns a snapshot of series per country, distinguishing it from siblings like get_series (specific series) and list_series (list without snapshot). The term 'snapshot' is slightly vague but adequate.

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 on when to use this tool versus alternatives, such as get_series or get_series_history. The paid nature is mentioned, but no explicit when-not-to-use or trade-offs.

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?

Discloses cost ($0.05), calendar type (national statutory, not CSD), refusal behavior, and output details (date with trail). With no annotations, carries full burden and performs excellently.

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?

Packed with useful information but slightly verbose. Front-loads purpose and cost, then details. Every sentence adds value, though could be slightly more concise without losing substance.

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?

Fully covers all aspects: computation method, edge cases, pricing, constraints, and output expectation (date + trail). No output schema, but description sufficiently explains what the tool returns.

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?

Adds significant meaning beyond schema: explains business_days vs market+instrument_class interaction, calendar id format, trade_date base (day 0 never counted), and refusal conditions. Schema coverage 100% gives baseline 3, but description far exceeds.

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?

Clearly states it computes the settlement/value date using intersection of calendars with per-day trail. Distinguishes from sibling tools like count_working_days by specifying business-day offset and cycle citation.

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 describes when to use (specify business_days or market+instrument_class), provides examples of cycles, and states refusal conditions (no published coverage, no cited cycle, FX spot). Mentions free companion endpoint.

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