reference-data

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

With no annotations, description fully explains behavior: paid tool ($0.05), returns specific fields, honest about unenforceable floors, never guesses cross-period conversion, and details payment options (api_key or x402).

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?

Three efficient sentences with front-loaded payment indicator. Every sentence adds value: purpose, return details, edge cases, and payment instructions. 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 4 parameters, no output schema, and payment requirement, description covers all essential aspects: purpose, parameters, return values, edge cases (missing floor, period mismatch), and payment options. Comprehensive for an agent to invoke correctly.

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

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

Schema coverage is 100%, so baseline is 3. Description adds minimal extra context: amount in country's currency, period must match floor's period, and api_key bypasses payment. This is slightly helpful but does not significantly enhance schema-provided 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?

Description clearly states the tool's purpose: check if a salary is at/above/below statutory minimum wage, returning verdict, margin, floor, and legal instrument. It distinguishes itself from siblings (tax, holiday tools) by focusing on 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?

Description implies when to use (to check minimum wage compliance) but does not explicitly list when not to use or provide alternatives. It mentions cross-period conversion is never guessed, guiding usage, but lacks explicit context for selection 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?

No annotations are provided, so the description carries the full burden. It discloses the cost ($0.05), payment mechanism (x402), and the scope of computation. It could go further by noting idempotency or accuracy guarantees, but the given information is adequate for an agent to understand behavioral traits.

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

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

The description is two sentences, front-loaded with the core action, and every sentence adds value (function, important caveat, payment info). 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?

Given no output schema, the description partially covers return values (per-bracket workings, effective rate, marginal rate) and mentions a scope_note. It also explains what happens without an api_key (response explains payment). It is sufficient for an agent to understand inputs and outcomes, though the exact output format is not detailed.

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 meaningful context beyond the schema: it explains that taxable_income should be in local currency and period basis (annual for most, monthly for some), elaborates on the api_key parameter (bypasses x402, metered invoicing), and lists supported countries implicitly via the enum 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 computes statutory income tax on taxable income using marginal bracket schedule, with per-bracket workings, effective rate, and marginal rate. It also handles inflation-indexed tax units. The purpose is distinct from siblings like compute_vat or check_minimum_wage.

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 important usage context: it operates on taxable income (not net take-home pay), and reliefs/allowances and social-security are the caller's concern. It also mentions payment options. However, it does not explicitly state when to use this tool versus alternatives, though siblings are quite different.

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

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

No annotations provided, so description carries full burden. It discloses: paid tool ($0.02), uses country's current statutory rate, handles composite rates, and explains payment flow. This covers key behavioral traits beyond basic functionality.

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 cost, then operation, then details. Every sentence is essential and well-structured. No waste.

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 explains return value (net, tax, gross, per-levy components) and includes payment flow. For a 4-parameter paid tool, this is complete and actionable.

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 adds value by clarifying default mode (add), giving example of composite rates (Ghana VAT + NHIL + GETFund), and explaining api_key is optional with payment via x402. This exceeds schema detail.

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, including composite components. The verb 'compute' and resource 'VAT' are explicit, and the mode distinction (add/extract) distinguishes this from other 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 specifies when to use each mode (add for net, extract for gross) and mentions optional api_key and payment info. While it doesn't explicitly compare to siblings, the sibling tools are clearly different (wages, holidays, etc.), so context is sufficient.

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

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

Given no annotations, the description discloses key behaviors: cost ($0.02), weekend handling (e.g., Egypt's Fri-Sat), statutory holidays, max range, and payment instructions via api_key or x402. Does not mention rate limits or auth beyond the key, but covers essential behavior for a paid API.

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 with no redundancy. The first sentence packs the core functionality and constraints, the second addresses payment. Every part 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 is provided, so the description must explain return values. It states the output includes holiday names and next working day. However, it does not fully describe the structure (e.g., count of days, format of dates). The payment context is well-handled. Sufficient for basic 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?

Schema coverage is 100%, so baseline is 3. The description adds value by explaining the country parameter's weekend handling, clarifying that api_key is optional, and indicating the return includes holiday names and next working day. This enriches the schema definitions.

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 counts working days in a date range for a country, applying weekends and public holidays, and lists additional outputs (holidays hit, next working day). The description uniquely identifies the tool's purpose and distinguishes it from siblings like get_public_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?

Provides usage context such as max range of 366 days, payment requirement ($0.02), and api_key usage. Implicitly indicates when to use (e.g., for country-specific workday calculations), but lacks explicit guidance on when not to use or comparison to alternative 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?

With no annotations, description carries full burden. It states data is official and includes movable holidays, but omits disclosure of rate limits, data freshness, error handling, or behavior on unsupported countries. Basic transparency is present but insufficient.

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?

Description is a single, front-loaded sentence that conveys key info efficiently. No redundant phrases, but could benefit from a slight structural enhancement (e.g., listing features).

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 single-parameter tool with no output schema, the description adequately explains the data type (holidays, official, cited), but lacks details on response format (e.g., date objects, list structure) that would help an agent interpret results.

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 enum). Description adds no additional meaning beyond what schema provides; baseline score of 3 is appropriate.

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

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

Description clearly specifies the tool retrieves an official public-holiday calendar for a supported country, including movable holidays and source citation. It distinguishes itself from siblings like compute_income_tax or check_minimum_wage.

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. The description mentions 'FREE' but does not provide context on prerequisites, fallback options, or cases where another tool might be more appropriate.

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 bears the burden. It discloses cost, payment methods, and response contents (source citation, effective date, last-confirmed, staleness flag). 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?

Three sentences, front-loaded with cost and purpose. Every sentence adds essential information with 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?

The description covers payment, response content, and basic purpose. For a simple tool with no output schema and 100% parameter coverage, it is fairly complete, though it omits details on errors or rate limits.

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 value by explaining the api_key payment context and providing series examples beyond the schema's description. This enhances 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 returns the current value of a reference series, with examples like 'policy-rate, vat, minimum-wage'. This distinguishes it from siblings such as get_series_history (historical data) and list_series (list available 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 provides payment context ($0.005 cost, api_key to bypass x402) but does not explicitly state when not to use this tool versus alternatives. It implies usage for current values 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?

No annotations provided, so description carries full burden. It discloses that the tool is paid ($0.005) and explains the payment flow if no api_key is provided. However, it does not mention other behavioral aspects like rate limits 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: first states core purpose and filter options, second provides authentication/payment guidance. No redundant words, front-loaded with key 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 and 5 parameters, the description covers purpose, filtering, and payment but does not describe the return format, pagination, or error conditions. Some additional detail on what the historical values look like would be beneficial.

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. Description adds context for the api_key parameter (payment explanation) and reiterates the from/to filter format, adding value beyond the schema's own 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?

Description clearly states the tool retrieves historical values of a reference series with optional date filtering. It distinguishes from siblings like get_series (current values) and list_series (list of available series) by specifying 'historical values with effective date ranges'.

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?

Description provides clear context for authentication/payment (api_key vs x402) but 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, the description carries full weight. It transparently discloses the cost ($0.02) and the fallback payment flow via x402. This is valuable for a paid tool. However, it does not mention idempotency, rate limits, 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?

Two sentences, no wasted words. The critical 'PAID ($0.02)' is front-loaded, immediately informing the agent of cost. The structure is efficient and easy to parse.

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

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

Given the simple input (one optional param) and no output schema, the description covers purpose, cost, and payment behavior. It lacks details on the response structure (what a 'snapshot' contains), but for a straightforward tool, it is nearly complete.

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

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

The only parameter, api_key, is optional and described in the schema as 'API key'. The description adds meaningful context: passing the key enables paid access, and omitting it leads to a payment explanation. This clarifies the parameter's role in the payment model.

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 states it provides a 'Snapshot of every series for every country in one call', clearly identifying the resource and scope. However, it lacks an explicit verb (e.g., 'get' or 'retrieve'), slightly reducing clarity. But it is clearly distinct from siblings like get_series and list_series by being a paid bulk operation.

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 notes it is paid and explains behavior when no api_key is provided. However, it does not explicitly state when to prefer this tool over siblings, such as when needing a complete cross-country snapshot versus single-series data. Usage guidance is implicit but not directive.

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 burden of disclosure. It mentions 'FREE' and describes the returned fields (countries, IDs, freshness, URLs), indicating a read-only operation. It does not discuss side effects or limits, but for a list operation this is adequate.

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 extremely concise: one sentence with all essential information. It front-loads the 'FREE' qualifier and clearly states the output contents and recommended usage order.

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 simplicity (no parameters, no output schema), the description fully covers what the agent needs to know: what the tool returns (countries, series IDs, descriptions, freshness, URLs) and that it should be used first for discovery.

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

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

There are zero parameters, so schema coverage is effectively 100%. The description does not need to explain parameters, and the baseline score of 4 is appropriate. It could note that no input is needed, but the implicit message is clear.

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 specifies the tool's purpose: listing all usaref reference-data series. It mentions key fields (countries, series IDs, descriptions, freshness metadata, URLs) and distinguishes itself from siblings like 'get_series' by being a discovery catalog.

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 advises 'Call this first to discover what data exists,' providing clear guidance on when to use it. It could be improved by explicitly stating when not to use it, but the instruction is sufficient for a discovery tool.

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