reference-data

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

No annotations provided, so description fully discloses behavior: never guesses cross-period conversion, handles missing floors honestly, and clarifies payment flow. No contradictions.

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 information, no redundancy. Efficient and clear.

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 inputs, behavioral quirks, and payment; returns mentioned. No output schema but described sufficiently. Minor gap: could detail output more.

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%, but description adds value by clarifying amount in local currency, period must match floor's period, and api_key bypasses x402.

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 the tool checks salary against statutory minimum wage and returns verdict, margin, floor, and legal instrument. Distinguishable from sibling tools (tax, holidays, 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?

Provides context for compliance use, mentions honest handling of missing floors and cross-period conversion, and explains payment options. No explicit alternative guidance but 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?

No annotations are provided, so the description carries full burden. It discloses that the tool is paid ($0.05), explains the computation scope (marginal brackets, effective rate, marginal rate), and warns about what is not included. It also clarifies the payment workflow if no api_key. This is thorough but could mention idempotency or side effects.

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, front-loading the most critical information (paid, statutory, taxable income). Every sentence adds value, and warnings are highlighted with all caps. It is concise yet comprehensive.

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 lack of output schema, the description fills the gap by mentioning response contents (per-bracket workings, effective rate, marginal rate, scope_note). It covers input requirements, payment, and data scope. No obvious missing context for an agent to use 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 coverage is 100%, but the description adds extra context: it clarifies the period basis for taxable_income (annual vs monthly for specific countries) and explains the purpose of api_key (bypasses x402). This enriches the schema's description without redundancy.

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 uses specific verbs ('compute', 'Handles') and clearly identifies the resource ('income tax on a TAXABLE-income figure'). It distinguishes itself from sibling tools like compute_vat by specifying it's for statutory income tax and mentioning handling of inflation-indexed tax units.

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 states explicit caveats: 'this is tax on taxable income, NOT net take-home pay' and clarifies that reliefs and social-security are the caller's concern. It also instructs on using api_key or x402. However, it does not explicitly contrast with sibling tools like compute_vat or when to prefer this tool.

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

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

With no annotations, the description bears full responsibility. It mentions cost ($0.02), mode behavior, auth (api_key or x402 payment), and composite levy example (Ghana). However, Ghana is not in the country enum, which could mislead users about supported countries, reducing 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?

The description is three sentences, efficient, and front-loaded with cost and purpose. Every sentence adds value with no unnecessary 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?

The description explains output (breakdown) and auth, but lacks output format details, error handling, and has a misleading example (Ghana not in enum). For a 4-param tool with no output schema, more completeness is needed.

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. The description adds value by explaining composite levy example (Ghana) and clarifying mode semantics, though it largely reiterates schema info.

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 VAT breakdown for an amount, including net, tax, gross, and per-levy components. It distinguishes itself from sibling tools like compute_income_tax by focusing on VAT specifically.

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

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

The description explains when to use mode=add vs mode=extract, but does not explicitly exclude use cases for siblings (e.g., income tax). However, the context makes it clear this is for VAT only.

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 covers cost ($0.02), range limit (366 days), weekend handling (Egypt's Fri-Sat), holiday application, and output details. It does not mention idempotency or side effects, but provides key behavioral info.

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 a single sentence with important details upfront (PAID, range). Every clause adds value, no 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 4 parameters and no output schema, the description covers cost, range, holiday logic, and output structure. It could mention input validation or rate limits, but is largely 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%, so baseline is 3. The description adds context for api_key (payment handling) and hints at output, adding value beyond the schema's parameter 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 clearly states it counts working days in a date range for a country, applying weekends and statutory holidays. It distinguishes from siblings like compute_income_tax or get_public_holidays by its specific purpose.

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 implies usage for counting working days and explains payment via api_key or x402. It lacks explicit exclusions or alternatives, but the purpose is sufficiently clear to differentiate from 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 the burden of transparency. It discloses that the service is free and cites official government sources, which adds context. However, it does not describe return format, pagination, or limitations beyond the country enum.

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 a single, well-structured sentence with no redundant information. Key attributes (free, official, movable holidays, source citation) are 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 simplicity of the tool (one parameter, no output schema), the description is sufficiently complete. It covers the purpose, scope, and key features without needing elaboration.

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 one parameter 'country' already documented. The description adds no extra meaning beyond what the schema provides (e.g., it does not explain country codes or format). 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 provides an official public-holiday calendar for a supported country, including movable holidays and government source citations. It effectively distinguishes itself from sibling tools like 'check_minimum_wage' or 'compute_vat' by focusing on holidays.

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 lacks explicit guidance on when to use this tool versus alternatives. It does not mention conditions, prerequisites, or when not to use it. The word 'FREE' hints at cost, but there is no comparison with 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?

Discloses cost, return fields (source citation, effective date, last-confirmed date, staleness flag), and payment methods. Lacks details on failure modes or rate limits, but with no annotations, this covers key 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?

Two sentences that are mostly front-loaded with critical info (cost and purpose). Somewhat dense but no wasted words; could be slightly more structured 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?

Covers return fields and payment options, which is adequate given the lack of output schema. However, lacks details on error handling or response format, leaving minor gaps.

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

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

Schema coverage is 100% for all parameters. Description adds value beyond schema by providing examples for 'series' and explaining the purpose of 'api_key' for bypassing x402. Country parameter is sufficiently described by 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?

Clearly states the tool retrieves the current value of a reference series, with specific examples like 'policy-rate, vat, minimum-wage'. Distinguishes from siblings by indicating it returns only the current value, not history or lists.

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?

Mentions payment ($0.005) and options to pay via api_key or x402, but does not explicitly state when to use this tool versus alternatives like get_series_history or list_series. Provides context but no exclusions.

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 paid nature ($0.005) and x402 payment process. No annotations, so description carries burden. Lacks details on success/failure, rate limits, or response format.

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?

One concise sentence with a brief payment note. Efficient and front-loaded with key info (paid tag). 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?

For a 5-param tool with no output schema and no annotations, the description covers payment and basic filtering but lacks explanation of response behavior or what 'reference series' means. Adequate but incomplete.

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 parameters are already documented. Description repeats from/to (YYYY-MM-DD) and mentions api_key, but adds no new semantic meaning beyond 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?

Clearly states it provides historical values of a reference series with effective date ranges. Distinguished from siblings like get_series (likely current) and list_series (list of 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?

Mentions optional from/to filtering and passing api_key, but does not explicitly state when to use this tool vs alternatives like get_series or get_snapshot. No prerequisites or exclusions.

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?

Without annotations, the description carries full behavioral burden. It transparently discloses that the tool is paid ($0.02) and explains the api_key/payment flow. It does not mention other traits like rate limits, but the cost disclosure is valuable.

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. No wasted words, efficient and clear.

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 simple tool with one optional parameter, the description is fairly complete. It covers cost, usage, and payment flow. However, it does not describe the output format or data returned, which could be inferred but is not explicit.

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 covers the api_key parameter 100%, but the description adds meaning by stating it is optional and that the response guides payment if not provided. This adds context beyond the raw 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 identifies the tool as providing a snapshot of every series for every country in one call, which is a specific verb+resource. It distinguishes from sibling tools like get_series and list_series by emphasizing comprehensiveness.

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 guidance on using the API key and explains that the response explains payment if not provided. However, it does not explicitly state when to use this tool versus alternatives or when not to use 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 provided, the description carries the full disclosure burden. It declares the tool is free and returns catalog information, implying it is safe and read-only. It could mention if any authentication or rate limits apply, but overall it is 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 a single sentence plus a call-to-action, no wasted words. It front-loads key info (FREE) and 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?

Given zero parameters and no output schema, the description fully covers what the tool returns (supported countries, series IDs, descriptions, freshness metadata, URLs). It is sufficient for an agent to understand and use 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?

The input schema has zero parameters, so baseline is 4. The description adds value by explaining what the output contains, compensating for the lack of output 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 it returns a catalog of all asiaref reference-data series with specific details (countries, IDs, descriptions, freshness metadata, URLs). It explicitly says 'Call this first to discover what data exists,' distinguishing it from sibling tools like get_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?

The description marks the tool as 'FREE' and advises to call it first to discover available data, making its usage clear and setting context relative to other series-related siblings.

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