reference-data

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

With no annotations, the description fully discloses behavior: returns verdict, margin, floor, instrument; handles missing floors and period mismatches honestly; never guesses cross-period conversion; explains payment via 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 sentences with no waste. The first sentence front-loads the core purpose and outcome. Each sentence adds unique 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?

For a tool with 4 parameters, no output schema, and no annotations, the description is highly complete. It covers purpose, constraints, return values, and payment model, fully compensating for missing structured fields.

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%, providing baseline 3. The description adds value by clarifying 'amount' is in the country's currency, 'period' must match statutory floor's period, and 'api_key' bypasses x402 and is metered.

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 a specific verb ('check'), resource ('minimum wage'), and clearly states it returns a compliance verdict, margin, legal floor, and instrument. It distinguishes itself from siblings (tax, holiday, series 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?

The description explicitly states when to use (checking minimum wage compliance) and when not (no enforceable floor or period mismatch, returns honest status). However, it does not explicitly name alternative tools for related tasks like salary assessment.

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

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

Discloses cost ($0.05), handling of inflation-indexed tax units, and what the tool does not apply. Given no annotations, the description fully informs about behavior.

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

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

Description is detailed and front-loads key info. Some minor redundancy but every sentence adds value, making it 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?

Covers cost, input requirements, output details (per-bracket workings, rates), and scope limitations. Without output schema, it still provides sufficient context.

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?

100% schema coverage, so baseline 3. Description adds context on period basis (annual/monthly) and local currency. However, country enum lists only au/nz but description mentions other countries, causing slight inconsistency.

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. It differentiates from sibling tools like check_minimum_wage and compute_vat by its specific focus.

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 notes that tax is on taxable income, not net take-home pay, and that reliefs/allowances are caller's responsibility. Also explains api_key usage for bypassing x402.

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

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

With no annotations, the description carries the full burden. It discloses the cost ($0.02), explains the two modes, and mentions the composite rate behavior. It does not cover rate limits, error handling, or authentication details beyond api_key, but provides sufficient behavioral context for a read-like operation.

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

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

The description is two sentences plus a brief api_key note. It is front-loaded with the cost, efficiently uses words, and contains no unnecessary 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 explains the return components (net, tax, gross, per-levy items) and modes. It lacks details on error cases or unsupported countries beyond the schema enums, but covers the core functionality 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 by clarifying the 'mode' parameter's semantics ('add' treats amount as net, 'extract' from gross) and the composite rate handling, which helps the agent use the tool correctly.

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

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

The description clearly states that the tool computes VAT breakdown for an amount, including net, tax, and gross, with per-levy components for composite rates. It distinguishes between 'add' and 'extract' modes, and is distinct 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 when to use the api_key parameter and that without it the response instructs how to pay. It does not explicitly list when not to use this tool or provide alternatives, but the context is clear enough for an agent to decide between VAT and income tax 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, the description carries full burden. It discloses paid nature, weekend/holiday handling, and return items (holidays by name, next working day). It lacks details on error behavior, rate limits, or timezone handling.

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

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

The description is three sentences and fairly concise, with no wasted words. It includes essential context (range, payment) but could be 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?

No output schema, but description explains return includes holidays and next working day. It covers range limit and payment but lacks details on error handling or complete return structure. Adequate for a simple 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 description coverage is 100%, so the description adds marginal value beyond schema. It adds range limit context and payment note, providing some parameter semantics improvement.

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 statutory holidays. It distinguishes itself from sibling tools like get_public_holidays by focusing on counting, and specifies handling of Egypt's Fri–Sat weekend.

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 a max range of 366 days and payment instructions, implying usage context. However, it does not explicitly state when to use this tool over alternatives (e.g., get_public_holidays) or provide 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?

The description discloses that it is free, provides official data, includes movable holidays, and cites sources. Without annotations, this provides adequate behavioral transparency, though it could mention data recency or caching.

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?

A single sentence conveys all key points: free, official, supported countries, movable holidays, and source citation. 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?

For a simple one-parameter tool without output schema, the description covers the main aspects: what it provides, for which countries, and that it includes movable holidays. Could mention that output includes the source citation, but overall complete enough.

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 'country' has full schema documentation with enum and description. The description adds no additional parameter semantics beyond what the schema provides, so 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?

The description clearly states the tool provides official public-holiday calendars for supported countries, including gazetted movable holidays and citing government sources. This distinguishes it from sibling tools like tax and wage calculators.

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

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

The description does not explicitly state when to use this tool vs alternatives, though the sibling tools are clearly different domains. No guidance on unsupported countries or limitations beyond the country enum.

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 bears full responsibility for behavioral disclosure. It details the return data (source citation, effective date, last-confirmed date, staleness flag) and explains the authentication/payment mechanism (api_key or x402). This is sufficient for a read-only lookup 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 a single paragraph of three sentences, with the cost and purpose front-loaded. Every sentence adds essential information (cost, function, return data, payment options) without any 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?

Given the tool's simplicity (3 parameters, no output schema), the description covers key aspects: data returned, payment methods, and example series. It does not detail error handling or rate limits, but these are less critical for a straightforward lookup 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% with all three parameters described. The description adds value by providing concrete series examples (policy-rate, vat, minimum-wage) and explaining the api_key parameter's role in bypassing x402 and metered invoicing. This enriches understanding 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 returns the current value of a reference series, with specific examples (policy-rate, vat, minimum-wage). It distinguishes itself from sibling tools like get_series_history (historical data) and list_series (listing 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 mentions the cost ($0.005) upfront, which is crucial for usage decisions. It explains when to use the tool (to get current values of reference series) and provides context about payment options (api_key vs x402). However, it does not explicitly state when not to use it or compare directly to alternatives.

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

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

With no annotations, the description should fully disclose behavioral traits. It mentions cost and payment model but lacks details on read-only nature, return format, authentication requirements, or error handling.

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

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

The description is very concise: two sentences that efficiently convey cost, purpose, filtering, and payment instructions. 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 complexity (5 params, paid, no output schema), the description could be more complete. It doesn't explain the return structure or what 'historical values' entails, leaving ambiguity.

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%, baseline 3. The description adds value by specifying date format ('YYYY-MM-DD'), clarifying optional filtering, and explaining the api_key parameter's role in payment.

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 optional date range filtering. It distinguishes from siblings like 'get_series' (current value) and '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?

The description provides clear context on usage: it's for historical values, optionally filtered by from/to dates. It explains payment and that api_key is optional. However, it does not explicitly contrast with similar tools like 'get_snapshot'.

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 burden. It discloses the tool costs $0.02 and requires payment via x402 if no api_key. However, it does not describe data freshness, rate limits, response size, or other 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?

Two sentences: first conveys purpose and cost, second explains api_key usage. Every word earns its place; no filler.

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 could be more complete about what the snapshot contains or its structure. It covers payment and scope but leaves questions about response format and potential data volume.

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 (api_key) having a basic description. The description adds meaning by stating the api_key is optional and that omitting it triggers a payment explanation, which is valuable context 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?

Description clearly states the tool provides a snapshot of every series for every country in one call. The verb 'get' and resource 'snapshot' are specific, and the scope distinguishes it from sibling tools like get_series or list_series which are likely more filtered.

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 this tool is for obtaining a broad dataset, but it does not explicitly state when to use this over alternatives, nor does it mention prerequisites or usage exclusions. Only a hint about payment is given.

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

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

With no annotations, the description carries full burden. It mentions 'FREE' implying no cost, but does not explicitly state idempotency, auth requirements, or rate limits. Adequate for a read-only listing 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 a single, efficient sentence that front-loades the key attribute 'FREE' and packs all necessary information without 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?

For a parameterless listing tool with no output schema, the description explains the return fields and usage order. It is nearly complete, though it could mention if results are paginated or if there is a limit.

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, so the baseline is 4. The description adds value by detailing what the response contains (countries, series ids, descriptions, freshness metadata, URLs).

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 lists all ausref reference-data series, including specific fields. It also differentiates from sibling tools like get_series by positioning itself as the initial discovery step.

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 includes explicit usage guidance: 'Call this first to discover what data exists.' This tells the agent to use this tool before others, but does not provide explicit when-not-to-use scenarios.

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