reference-data

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

With no annotations, the description fully discloses behavior: it returns verdict, margin, floor, and legal instrument; it handles missing floors and period mismatches honestly; it never guesses cross-period conversions. The payment handling is also transparent. This covers all relevant behavioral aspects.

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, using two well-structured sentences that front-load the key information (what the tool does) and follow with important constraints and payment details. Every part contributes meaningfully 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?

Given the tool has 4 parameters, no output schema, and no annotations, the description provides sufficient completeness. It explains the return values, edge cases (missing floor, period mismatch), and the payment method. The context is fully covered 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 description coverage is 100%, but the description adds significant value beyond the schema by explaining the overall function, the no-guessing policy on period conversion, and how the api_key parameter relates to payment. These additions enrich the semantic understanding of the parameters in context.

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 purpose: to check if a salary is at, above, or below a country's statutory minimum wage. It specifies the outputs (verdict, margin, floor, legal instrument) and distinguishes itself from sibling tools like compute_income_tax or compute_vat by focusing on minimum wage compliance.

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 usage context by mentioning the payment mechanism (api_key vs x402) and the constraint that cross-period conversion is never performed. However, it does not explicitly state when not to use this tool or contrast it with alternatives, missing an opportunity for fuller 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?

The description discloses the paid nature ($0.05), handling of inflation-indexed tax units, and scope limitations (e.g., no reliefs). Since no annotations are provided, the description carries the full burden and does so well, though it could mention any side effects (none expected).

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, starting with key attributes (cost, function) and then important caveats. It is slightly lengthy but every sentence contributes to clarity 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?

Given the lack of output schema, the description adequately describes the return value (per-bracket workings, effective/marginal rate, scope note). It provides sufficient context for an agent to understand the tool's behavior and limitations.

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?

With 100% schema coverage, the description adds context beyond the schema: it explains that taxable_income should be in the schedule's period basis and clarifies the api_key parameter's purpose. This adds meaningful value for the agent understanding how to supply valid inputs.

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 bracket schedules, and explicitly distinguishes itself from take-home pay calculations. This is specific and distinct from 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 explains that the tool only calculates tax on taxable income and does not handle reliefs, allowances, or social security contributions, making it clear when to use it. However, it does not explicitly mention 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?

The description discloses the cost ($0.02) and optional api_key usage, explaining behavior without an api_key. It also notes the use of current statutory rates and composite components. No annotations exist, so the description carries full burden; it is fairly transparent but lacks details on error handling or rate limits.

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 very concise, with no wasted words. It front-loads the cost and core functionality, then explains modes and api_key usage efficiently. Every sentence adds necessary 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?

Given no output schema, the description covers the tool's purpose, modes, and api_key usage. It could mention expected response format or error cases for invalid countries (though enum restricts values). Overall, it is reasonably complete for a simple computation 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?

The schema covers all parameters with descriptions, but the description adds meaning: explaining mode behavior more concretely ('treats the amount as net' vs 'backs VAT out of a gross amount') and the consequence of omitting api_key. This adds value 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 it computes VAT breakdown (net, tax, gross) using statutory rates, and distinguishes between 'add' and 'extract' modes. It also mentions composite rates (e.g., Ghana VAT+NHIL+GETFund), which adds specificity and differentiates it from sibling tools 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 explains the two modes (add/extract) and provides guidance on passing an api_key versus receiving payment instructions. However, it does not explicitly compare to alternative tools or state when not to use 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?

Without annotations, the description carries the full burden. It discloses the paid nature ($0.02), a 366-day max constraint, and output behavior (holidays hit by name and next working day). It does not cover rate limits or auth failure details, but cost and constraints are 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 paragraph that front-loads key details (cost, purpose, country-specific handling, constraint, payment guidance). It is moderately concise but could be more structured for faster scanning.

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 what the output includes (holidays hit by name and next working day). All parameters are described, and the paid nature and constraints are clear. The tool is complex enough to warrant these details, and the description covers them adequately.

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 value beyond schema by specifying a max range length for from/to, the optionality of api_key, and special weekend handling for Egypt via the country 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 the tool counts working days within a date range for a country, including handling weekends and statutory holidays. It distinguishes itself from siblings such as get_public_holidays by specifying that it returns a count and includes 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 range max of 366 days and provides instructions on passing an api_key for payment. However, it does not explicitly state when to use this tool over alternatives like get_public_holidays or check_minimum_wage.

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?

Description adds that it is free, includes movable holidays, and cites official source. Without annotations, this is moderate transparency; no mention of rate limits or authentication, but 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?

Single sentence with key info front-loaded (FREE). No wasted words, highly concise.

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

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

For a simple tool with one parameter and no output schema, the description adequately covers what the tool does and its scope. Could specify output format, but still informative.

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 'country' parameter description 'ISO country code' and enum. The description does not add extra meaning beyond the schema; 'supported country' already implied by enum.

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 retrieves an official public-holiday calendar for a supported country, including gazetted movable holidays, with source citation. It distinguishes well from sibling tools like compute_income_tax or 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?

Usage is implied (for getting holidays), but no explicit when-to-use vs. alternatives. The 'FREE' and 'official' hints provide some 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?

No annotations, but description discloses cost ($0.005), response contents (source citation, effective date, staleness flag), and payment behavior. Does not mention rate limits or destructive potential (though it's a read).

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, no fluff. Front-loaded with cost and purpose. 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?

With no output schema or annotations, the description covers cost, response fields, parameter examples, and payment methods. Lacks response structure details but sufficient for the tool's simplicity.

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 3. Description adds example values for 'series' and clarifies 'api_key' purpose, but adds little beyond 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?

Clearly states it returns the current value of reference series, with examples (policy-rate, vat, minimum-wage). Distinguishes from siblings like get_series_history by specifying 'current value'.

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

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

Gives explicit guidance on using api_key or x402 payment. Implicitly suggests use for getting series values, but lacks when-not-to-use or 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 provided, the description carries the full burden of behavioral disclosure. It explicitly states the tool is 'PAID ($0.005)' and explains payment fallback via x402. This is critical for an agent to avoid unexpected charges. However, it does not mention other traits like rate limits or data freshness, which prevents a perfect score.

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 with no wasted words. The cost information is front-loaded, and the filtering option is clearly stated. Every 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?

The description covers cost and basic filtering but lacks details about the response format, pagination, and error scenarios. Given the tool has an output schema (none) and moderate complexity (5 params, optional filters), this is a noticeable gap. Adequate but not comprehensive.

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 schema already describes all 5 parameters. The description adds minimal value beyond noting that from/to are optional filters and that api_key is optional; these are already implied by the schema's required list (only country and series are required). 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 returns 'historical values of a reference series with effective date ranges', which is specific and distinct from siblings like get_series (presumably current values) and get_snapshot (single point). The verb 'get' and resource 'series history' are 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 mentions optional filtering by from/to dates and advises passing an api_key, which provides some usage context. However, it does not compare to sibling tools or explain when to use this tool over alternatives like get_series or get_snapshot. Lack of when-not-to-use guidance limits the score.

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 cost ($0.02) and the x402 payment mechanism, which are critical behavioral traits. It does not mention potential errors or response size, but the core behaviors are well covered.

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

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

The description is two sentences, front-loading the cost and purpose, then covering parameter usage. Every word is necessary; 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?

Given the simple schema (one optional parameter) and no output schema, the description adequately covers what the tool does and how to use it. It could mention the response format or scope more explicitly, but it's 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% with a single 'api_key' parameter described as 'API key'. The description adds practical context: 'Pass api_key if you have one; otherwise the response explains how to pay via x402,' clarifying optionality and payment fallback, which enriches the semantic meaning.

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 a 'Snapshot of every series for every country in one call,' which is a specific verb+resource scope. It distinguishes from sibling tools like get_series (individual series) and list_series (listing without snapshot).

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 when to use: when you need a broad snapshot across all series and countries. It also provides guidance on the api_key parameter: pass one if you have it, otherwise the response will explain payment. This implies alternatives for paid vs. free usage.

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 mentions 'FREE' (possibly indicating no cost or rate limit) but does not disclose other behavioral traits such as authorization requirements, data volume, pagination, or side effects. Given no annotations, the description is insufficient for full 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 very concise: two sentences that front-load the key fact ('FREE') and clearly state the tool's purpose and usage advice. 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?

Given no output schema and no annotations, the description adequately explains what the tool returns and why to use it first. However, it could be more complete by describing the output structure (e.g., list of series objects) or any limitations.

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 tool has no parameters (schema coverage 100%), so the description need not add parameter info. Baseline for 0 parameters is 4, and the description does not add misleading information.

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 that the tool provides a catalog of all mearef reference-data series with specific fields (supported countries, series IDs, descriptions, freshness metadata, URLs). It also advises to 'call this first', clearly distinguishing it from siblings like get_series or get_series_history.

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 indicates that the tool should be used first for discovery ('Call this first to discover what data exists.'). It implies this is a preliminary step, but does not explicitly state when not to use it or mention alternatives.

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