reference-data

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

With no annotations, the description fully covers behavior: returns verdict, margin, floor, legal instrument. Discloses honest statuses for missing floor or period mismatch. Mentions payment flow, though no rate limits or auth details beyond payment.

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, each with distinct value: purpose, return details, payment guidance. No redundant or vague phrasing.

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?

Despite no output schema, the description explains return fields and edge cases. Covers payment and honest behavior. Lacks error handling details, but overall sufficient for agent 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 the baseline is 3. Description adds minor nuance (e.g., 'must match the floor's period' for period, 'metered for invoicing' for api_key) but largely repeats 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?

Description clearly states the tool checks a salary against statutory minimum wage and returns a compliance verdict. Distinguishes from sibling 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?

Provides context on when to pass an API key vs using x402 payment. Explains that cross-period conversion is never guessed, clarifying a constraint. Lacks explicit comparison with sibling tools but gives enough usage context.

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 fully bears the burden. It discloses a $0.05 cost, that it returns per-bracket workings, effective and marginal rates, a scope note for omitted items, and payment options (api_key or x402). This level of detail is exceptional for a paid tool.

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—four sentences—with critical information front-loaded (cost, core function, important caveat, payment). Every sentence adds value.

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 thoroughly explains what the response contains: per-bracket workings, effective/marginal rates, scope_note. It also covers payment. No gaps remain for an agent to understand behavior.

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 only the api_key usage context; for taxable_income and country, it largely echoes the schema. No additional parameter semantics 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 statutory income tax on taxable income using marginal brackets, and distinguishes itself from net pay calculations. It explicitly separates its scope from sibling tools like compute_vat.

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 an 'IMPORTANT' note clarifying that reliefs, allowances, and social security are not applied, and mentions handling of inflation-indexed units. However, it does not explicitly contrast with sibling tools or state when not to 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?

Without annotations, the description carries full burden. It discloses it's a paid tool ($0.10), explains assumptions (e.g., default 40/30/10 split), and mentions api_key vs x402 payment, providing good 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 dense but every sentence provides useful information. It is front-loaded with purpose and key details, though slightly long for rapid 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?

With 12 parameters and no output schema, the description adequately covers return value (net pay with workings), country-specific details, and assumptions, making it sufficiently complete for effective 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 pension base split assumption and the need for api_key vs x402, going beyond the 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?

The description clearly states it computes gross-to-net take-home pay for Nigeria or Kenya, listing specific deductions and reliefs. It distinguishes itself from sibling tools like compute_income_tax by being payroll-specific.

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 tells when to use the tool (payroll for Nigeria/Kenya) and gives prerequisites (e.g., passing basic/housing/transport for exact Nigeria calculation). It does not explicitly exclude alternatives but provides sufficient context.

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), authentication via api_key, and fallback payment flow (x402). No contradictory annotations. Lacks details on rate limits or idempotency, but 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?

Three focused sentences. First sentence states core purpose, second details modes, third addresses cost and auth. 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?

Covers all parameters, cost, authentication, special behavior (composite rates). No output schema, but description outlines response content (net, tax, gross, per-levy). Highly complete for a 4-param 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?

Schema coverage is 100%, so baseline 3. Description adds useful context: mode options explained, api_key optional with fallback, country codes are ISO. Raises score above baseline.

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 computes VAT breakdown (net, tax, gross) using statutory rates, including composite levies for countries like Ghana. Distinguishes from siblings which are about wages, holidays, and time 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?

Explicitly explains when to use mode=add vs mode=extract. No direct comparison to alternatives, but siblings are unrelated, so the guidance 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?

With no annotations, the description carries full burden and discloses the paid nature ($0.02), weekend handling (Egypt's Fri-Sat), statutory holidays, return of holiday names and next working day, and range limit. This is good 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 concise, front-loading key info (PAID, range max, behavior). Every sentence adds value, though it could be slightly more structured.

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 (holidays hit by name, next working day). It also covers payment and range constraints. Missing details like response format are acceptable without output schema.

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 descriptions. The description adds that country codes are ISO and dates are YYYY-MM-DD, but does not significantly extend parameter meaning beyond the schema. 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 counts working days in a date range for a country, applying weekends and public holidays. It distinguishes from siblings like get_public_holidays by focusing on working days calculation.

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 context for usage: max 366-day range, mention of payment (api_key or x402), and handling of different weekend patterns. However, it doesn't explicitly contrast with similar tools like get_public_holidays.

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 mentions 'FREE' (implying no cost) and 'official', but lacks details on read-only nature, authentication requirements, rate limits, or output format. More behavioral context is needed.

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 16 words, efficiently conveying the tool's purpose and unique value (FREE, official, movable holidays, cited source). 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 the tool's simplicity (one parameter, no nested objects, no output schema), the description is adequate but incomplete. It does not explain what the output contains (e.g., list of dates, holiday names, source citation), which would help an agent use the result.

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 schema already describes the 'country' parameter as an ISO code with an enum. The description adds 'supported' but no new meaning beyond the schema. Baseline 3 applies.

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 supported countries, including movable holidays and cited source. The verb 'get' and resource 'public-holiday calendar' are specific, and the tool is distinct from unrelated 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?

No guidance on when to use this tool versus alternatives. The sibling tools are unrelated, so no explicit exclusions are needed, but the description lacks any context about appropriate usage scenarios or prerequisites.

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 discloses the tool's cost ($0.005 per call) and the response structure (source citation, effective date, staleness flag). It explains payment options (api_key vs x402). However, it does not mention idempotency or rate limits, which are minor gaps.

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 long, front-loading the cost and purpose. Every sentence adds essential information: cost, what it does, what the response contains, and how to pay. No redundant or filler content.

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?

Despite the lack of an output schema, the description sufficiently describes the return fields (source citation, effective date, staleness flag). The tool is simple with just 3 parameters, and the description covers payment, usage, and output, leaving no major gaps for an agent to invoke it 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%, so baseline is 3. The description adds value by providing concrete examples for the 'series' parameter ('policy-rate, vat, minimum-wage') and clarifying api_key usage. The 'country' parameter is not further elaborated 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 'Current value of a reference series' with examples like 'policy-rate, vat, minimum-wage', making the tool's purpose concrete. It distinguishes from siblings such as get_series_history (historical data) and list_series (listing 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 usage context by specifying it returns current values and includes payment instructions. It implies when to use (for current values) versus alternatives (e.g., get_series_history for historical data), though it does not explicitly name sibling 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 paid nature and filtering, but lacks details on output format, error behavior, or rate limits. With no annotations, description carries burden but covers only basics.

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

No output schema, so description should outline return structure; only vague 'historical values with effective date ranges'. Missing error cases and response 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 covers all 5 parameters with descriptions. Description adds minimal extra value beyond schema (cost context), so 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 retrieves historical values of a reference series with date ranges, distinct from sibling tools like get_series (current) or list_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 payment and api_key usage guidance but does not explicitly state when to use versus alternatives or mention prerequisites like country availability.

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. It discloses the cost ($0.02) and the payment mechanism (x402), which are key behavioral traits. It does not mention if the operation is read-only or any rate limits, but the payment 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?

The description is two sentences, no wasted words, front-loaded with the cost warning, then the purpose, then parameter guidance. Highly efficient.

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

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

The tool has one optional parameter and no output schema. The description covers the purpose and parameter usage but does not describe the return format or what the snapshot contains. For a simple tool, it is adequate but not fully 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 description adds meaning to the api_key parameter by stating it is optional and that the response explains payment if not provided. This goes beyond the schema's simple 'API key' description.

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

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

The description clearly states the tool provides a snapshot of every series for every country, using a specific verb 'snapshot' and resource. It distinguishes itself from siblings like get_series and list_series by offering a comprehensive, all-in-one call.

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 when you need a broad snapshot and explains how to provide an api_key or pay. However, it does not explicitly state when not to use it or compare with alternative tools like list_series or get_series_history.

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 that the tool is free ('FREE') and lists the metadata returned. However, it does not mention side effects, rate limits, or pagination behavior. For a parameterless listing tool, the transparency is good but could be improved with notes on response size or freshness guarantees.

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 zero wasted words. The first sentence lists the contents concisely, and the second provides usage guidance. It is front-loaded with 'FREE' and the core purpose, making it efficient for an AI agent to parse quickly.

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 no parameters, no output schema, and low complexity, the description is adequately complete. It explains what the tool returns and when to use it. However, without an output schema, a brief note on the response format (e.g., JSON object) would enhance completeness, but it is not essential.

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 no parameters, so the input schema has 100% coverage by default. The description adds value by explaining what the response contains, which goes beyond the schema. Per guidelines, 0 params baseline is 4, and this description meets that standard.

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 is a catalog of all afriref reference-data series, listing specific metadata fields (supported countries, series ids, descriptions, freshness metadata, per-series URLs). The verb 'list' and resource 'series' are unambiguous. It also distinguishes itself from siblings by being the first call to discover data, while other tools like get_series target 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?

The description explicitly says 'Call this first to discover what data exists,' providing clear when-to-use guidance. It does not explicitly mention when not to use or alternatives, but the context of sibling tools makes it obvious that this is the entry point before using more specific tools like get_series or get_series_history.

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