ProofPrice

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

Read-only/idempotent safety is already covered by annotations, but the description adds genuinely useful behavior: freshness cadence per country, the 5–6 month publication lag with a concrete example, that range fields are null and there is no sample size, and that the source and licence are returned. The only gap is that return shape detail overlaps with the output schema, which is acceptable.

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?

Usage guidance is front-loaded and there is no wasted topic, but the text is one very long run-on sentence with repeated parentheticals ("Australia (domestic routes)", "the United States (domestic flights within the contiguous 48 states)" appearing multiple times) and could be trimmed substantially without losing 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?

With an output schema present, the description need not describe return fields, and it still covers the essentials an agent needs: what is returned, freshness/lag, non-applicable cases, and country-specific caveats. Nothing material is missing for correct invocation.

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% and the parameter descriptions already explain from/to semantics, the AU-vs-US differences, and the quarters trend. The description reinforces a few points (every answer states its quarter, US trend newest-first) but adds little parameter-level meaning beyond the schema, so the baseline 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 names a specific resource (average airfare paid per passenger each way between two cities/airports) and a specific verb-like scope (returns the published quarterly average), and it is clearly distinguishable from the many other pricepaid_* sibling tools because it names airfare, routes and carriers. It even disambiguates the misleading title by noting that AU figures are advertised fares rather than fares paid.

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 gives explicit when-to-use triggers ("what people actually pay for a flight between two cities", "average airfare out of a city") and a thorough exclusion list (today's fare, specific date/airline/cabin, booking, price alerts, international flights, hotels, other countries). It also scopes geography precisely to AU domestic routes and the contiguous US.

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?

Annotations already declare readOnlyHint=true, idempotentHint=true and openWorldHint=true, so the safety profile is covered. The description adds genuinely useful behavioral context: results are pre-buyer-premium winning bids, not confirmed receipts, and nothing is returned for fewer than 5 lots. That suppression rule is helpful, but the lengthy per-source freshness recital is closer to provenance documentation than to call-shaping 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?

It is front-loaded correctly, with the use case first and the exclusion last, which is the right shape. But the middle is a single dense run-on that repeats each country label three times across the scope and freshness passages, making it harder to scan than it needs to be for a five-parameter tool.

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?

An output schema exists, yet the description still summarizes the return shape (median final bid, 10th–90th percentile range, lot count, period, source and licence) and the anonymity caveat (no seller or lot named). Combined with per-source staleness and the minimum-lot threshold, an agent has everything needed to set expectations and decide when not to call.

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 defines country enums, city, state, what and months in detail, and baseline is 3. The description goes slightly beyond by tying each country to its actual source (GCSurplus, Prozorro.Sale, GLD auctions) and by implying the country scope constraint, which helps an agent pick the right enum value and reject out-of-scope requests.

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?

Opens with a concrete trigger and a specific resource: winning bids on used/surplus/seized goods at public auction, with the exact list of covered countries and sources. It explicitly separates itself from the nearest sibling concept by stating these are 'winning bid levels on lots marked sold ... not retail prices', which distinguishes it from pricepaid_car_prices and similar retail 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?

Both directions are stated: 'Use this when a user asks what used, surplus or seized goods ... went for' and 'Do not use for new goods, shop prices or other countries.' The excluded cases map directly onto the sibling tools an agent could otherwise confuse it with.

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?

Annotations already cover readOnly/idempotent/openWorld, but the description adds substantive context: the metric is a value-weighted average of customs value over net weight in the reporting country's currency, with a 10th–90th percentile band weighted by weight, and it deliberately has no sample size. Freshness is disclosed with concrete publication lags (Eurostat ~2.5 months, HMRC ~6 weeks) and the source/licence are named as part of the response.

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 when-to-use framing is front-loaded and valuable, but the sentence enumerating all twelve countries as 'the EU member states listed (country FR), the EU member states listed (country DE)…' is pure noise that duplicates the schema enum, and the publication-lag explanation is repeated twice in near-identical wording. The delivery is a single dense block rather than separated concerns.

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?

An output schema exists, so return values need not be re-explained, and the description nonetheless tells the agent what comes back (unit value, percentile range, months covered, top partners, source/licence). Combined with freshness, currency semantics, and the exclusion list, nothing material is missing for a correct call.

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 every parameter (months, period, country, partner, product, direction) is already documented in the schema, including EU vs GB differences and enum meanings. The description only restates the partner and product hints at a high level and adds no syntax or default behaviour beyond what the schema provides, so the 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?

States a specific verb (what traded goods are worth at the border, per kilogram, as declared to customs) and resource (customs unit values), with concrete product examples. It also draws a hard boundary against neighbouring price concepts ('not a shelf price, not a wholesale quote, not a receipt'), which is exactly what an agent needs to separate this from the many other pricepaid_* 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?

Opens with the triggering user question ('when a user asks what traded goods are worth at the border') and closes with an explicit exclusion list: not shopper prices, not a single contract or shipment, not futures/spot quotes, not services, not unlisted countries. Both when-to-use and when-not-to-use are spelled out rather than implied.

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?

Beyond the annotations (readOnly, destructiveHint), the description details critical behavioral traits such as data latency ('annual figures with a lag of about two years') and methodology ('cheapest posted offer,' 'not what customers actually paid'). This is highly valuable context.

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?

While it is lengthy, the description is dense with crucial information, and nearly every sentence adds necessary context regarding data source, limitations, or usage constraints. The structure logically flows from purpose to limitations.

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 of scraping/curating official economic data (Eurostat), the description is remarkably complete. It covers what the data is, how fresh it is, what it is NOT (e.g., actual customer payment), and which providers/lines are excluded.

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 baseline is high. The description adds semantic meaning by explaining that the `offer` parameter uses 'friendly names' that map to specific technical specifications like 'fixed_100_200 (fixed internet 100-200 Mbps, the default),' aiding interpretation.

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 defines the purpose as providing official mobile and broadband prices for fixed and mobile plans within the EU. It specifically distinguishes its focus on the 'cheapest posted offer of the largest operators,' providing a clear operational scope.

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?

This tool provides exceptionally strong usage guidelines by establishing hard boundaries. It explicitly instructs agents 'Do not use for a quote from one provider, for business lines, or for countries that are not listed,' which prevents incorrect tool selection or data misuse.

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?

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, openWorld). The description adds meaningful context beyond them: the payload includes a confidence label and official source/licence, signalling data provenance and reliability. It stops short of noting bidding cadence, freshness, or empty-result behaviour, so not a 5.

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?

Front-loaded with the use case and followed by a crisp exclusion sentence. The parenthetical gloss on 'entitlement or quota certificate, a sale or an auction result' is slightly convoluted and could be tightened.

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 an output schema present, the description needn't enumerate return fields, yet it summarises them for quick judgement. Parameters, safety annotations and usage boundaries are all covered; only bidding freshness/cadence and empty-result behaviour are unaddressed.

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% and all three enums (country, product, vehicle_class) are documented in the schema, so the baseline is 3. The description only reinforces the country scoping (SG, not other countries) and adds no detail on months, product, or vehicle class beyond structured fields.

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 names a specific verb and resource: what people actually paid for Singapore COE entitlements, including the exact statistic returned (median winning price). It is clearly separable from siblings such as pricepaid_auction_prices or pricepaid_home_sales because it scopes to Singapore car COE bidding results.

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?

Explicit 'Use this when...' trigger plus explicit exclusions ('Do not use for asking prices, dealer listings, or other countries'), which routes the agent away from the most likely wrong siblings and from the common misconception about listings vs. paid prices.

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?

Far exceeds the annotations: it discloses the percentile basis (10th–90th), the 5% band for averages, the three cannot_judge causes with the no-conversion rule, what cautions come back (posted vs paid prices, stale periods), and full payment mechanics (20 free calls/day, USD 0.10 via x402 USDC, 402 reply, free for insufficient records or errors). No contradiction with readOnlyHint=true or idempotentHint=true.

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?

Information-dense with essentially no filler, but it is delivered as one long multi-clause block, and the 33-item category list inside the prose makes it hard to scan. The key guidance ('Use this before paying', the do-not-use clause) is front- and back-loaded correctly, so the structure is defensible if not clean.

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 109-parameter meta-tool with an output schema, the definition covers everything an agent needs before calling: eligibility condition, required inputs, verdict semantics, failure modes, cost and payment flow. Return-value detail is arguably redundant given the output schema, but its presence does not leave any operational question open.

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 per-parameter meaning is already carried by the schema; the description still adds the governing model that the caller must supply the category, the country, 'the same parameters that category's own tool takes', and the price, plus the non-conversion rule that drives cannot_judge. It does not explain the price/unit/currency interaction beyond what the schema says, so it sits above the baseline rather than at the top.

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?

Names a specific action (check a proposed price against official evidence) and a specific output (a within/above/below verdict), which distinguishes it cleanly from the 33 sibling category tools that merely report prices. The opening 'Use this before paying' plus the enumerated verdict states make the tool's role unmistakable.

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 an explicit triggering condition ('when a user or agent has a proposed price ... and wants to know whether it is typical') and three explicit exclusions: valuing one specific item/address, financial/legal advice, and cross-currency or cross-unit comparison. The gap is that it never tells the agent when to skip this and call a sibling category tool directly, even though it acknowledges that 'the category's own tool' exists.

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?

Annotations already declare readOnly/idempotent/non-destructive, yet the description adds substantive context: the answers are official averages or medians (price_type official_statistic) with null range fields and only optional sample sizes, every answer carries a unit, reference year, confidence label and source/licence, and the data are pre-subsidy. The per-country freshness block (Canada April 2024, England CY2025 published 11 Dec 2025, Ireland 2016 only, Norway annual Jan figures, Singapore rolling, US 2022) plus the 'read the period, some data is years old' warning is exactly the behavioural disclosure an agent needs.

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?

Use case and exclusions are front-loaded, but the middle is a dense single run-on paragraph mixing source provenance, subsidy caveats, unit/confidence metadata and per-country publication schedules, some of which duplicates the country parameter description in the schema (e.g. April 2024, 2016 Ireland, 2022 US). Minor typos ('april', 'Tromso') and the length make it harder to scan than it needs to be, even though most content is genuinely useful.

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?

An output schema exists, so return values need no explanation, and the description still covers everything an agent needs to call correctly: which countries, which geographies are published per country, what the numbers represent (pre-subsidy official averages/medians), and how stale each source is. Nothing material is missing for a 7-parameter, 6-country 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 description coverage is 100% and the per-parameter text is exceptionally detailed, including per-country rules for area, age_group, care_type and the 'ignored' semantics for hours/care_type in several countries. The description mainly repeats the country list and the daily-fee/unit framing rather than adding syntax or selection rules beyond the schema, so it sits at the baseline for a fully documented 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?

States a precise use case (what childcare costs parents), the specific settings covered (nursery, daycare, childminder, after-school), the geographies (county/region/state/city) and the six countries, so the resource is unambiguous. It also explicitly separates itself from adjacent resources such as tuition fees, subsidies and nanny wages, which is what an agent needs to choose among the many pricepaid siblings.

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 an explicit when-to-use trigger ('when a user asks what childcare costs parents') and an explicit when-not list: specific nursery fees, advertised or waiting-list prices, subsidy values, school/university tuition, babysitting/nanny wages, and other countries. It also warns that the data are official statistics rather than adverts or listings, and that figures are pre-subsidy, which prevents misuse of the numbers.

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?

Annotations already declare read-only, idempotent, open-world and non-destructive, but the description adds substantial behavioral context: it lists return fields, source/licence, and country-specific freshness/coverage caveats such as SG's 1992 to mid-2016 file and TW's 30-day lag. That is exactly the extra context an agent needs before calling.

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 'Use this when' trigger is front-loaded, and most details such as freshness, exclusions and return fields are operationally relevant for a multi-country tool. However, the freshness block is a very long run-on sentence with repeated country caveats and some overlap with the schema's months descriptions, so it is more verbose than necessary.

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?

An output schema exists, so return values need not be explained, but the description still supplies the essential coverage map: supported countries, property-type caveats and freshness per source. For a nine-parameter, multi-country tool with irregular publication schedules, that is 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?

Schema coverage is 100% and each parameter has detailed country-specific guidance, so the description does not need to re-document them. The description only reinforces the town/postcode and country scope; it adds little 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 opens with a concrete use case (shops, offices, workshops, warehouses, building plots) and states the unit (price per square metre) and geographic scope, so an agent can distinguish it from home, rent or farmland price tools. The 'actually sold for / prices paid, not asking prices' phrase further pins down the resource.

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 gives an explicit 'Use this when' trigger and a clear 'Do not use for...' exclusion list covering homes, farmland, rents, asking prices, single-building valuations and other countries. It does not name a specific sibling alternative for excluded categories, so it stops short of the top 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?

Annotations already declare readOnly and idempotent, but the description adds substantive context beyond them: it is a published survey average, not invoice-derived; range fields are null and there is no sample size; data is monthly with a concrete freshness example (latest month September 2026 on 16 Oct 2026); and it names the official source and licence.

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?

Front-loaded with the core purpose and trigger, followed by return shape, caveats about null ranges, freshness, and exclusions. It is slightly long and the 'How fresh: monthly; the latest month on...' phrasing is a touch discursive, but nearly every sentence carries actionable 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?

An output schema exists so return-value structure need not be explained, and annotations cover safety profile. For a read-only statistical lookup, the description covers scope, source, units, null-field expectations, freshness, and exclusions — everything an agent needs to call 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 coverage is 100% and the enum descriptions already document country, area and component semantics in detail. The description adds modest value by framing the component split (materials vs labour) and regional comparison in user-facing terms, but does not add syntax or format detail 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?

States a specific verb, resource and scope: official average building cost per square metre in Brazil, split into materials and labour, with regional comparison. This clearly separates it from siblings like home_sales (finished homes) and home_upgrade_prices (renovation) without needing their schemas.

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?

Opens with explicit trigger conditions ('Use this when a user asks what it costs to build...') and closes with explicit exclusions: not for finished home prices, builder quotes, renovation, or unlisted countries. The agent knows both when to select it and when to route elsewhere.

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?

Annotations already declare readOnly/idempotent/non-destructive, but the description adds substantive behaviour the annotations cannot: a hard minimum of 5 awards before anything is returned, supplier anonymisation, the total-per-contract vs unit-price caveat, and per-source freshness cadence. The only gap is that the freshness wall is buried rather than summarised as a general rule.

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 'Use this when' hook and the 'Important:' caveat are well front-loaded, but the body is a very long wall of text in which the country roster appears three times (opening sentence, freshness list, schema enum) and the phrase 'and our copy is collected once a day' is repeated verbatim for roughly ten sources. Much of this could be a single table or a summarised freshness rule; many sentences do not earn their 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?

For a five-parameter, multi-source, open-world query tool, the description covers eligibility, caveats, thresholds, and source-specific coverage windows; an output schema exists so return fields need no explanation. An agent has everything required to decide whether to call it and how to interpret the answer.

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; the description earns a bump because the per-country freshness notes tell the agent that `months` is ignored on many sources (e.g. ES covers only the newest one to two days, DE six months) — information that materially changes how the parameter should be set and is not in the schema. Some of the country enumeration simply duplicates the enum 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 opening sentence gives a concrete verb ('what ... actually paid for') and a concrete resource (award notices from public buyers), with example purchases and named official sources. It explicitly distinguishes the tool from neighbouring price tools by scoping to public procurement rather than consumer/private prices, asking prices, or open tenders.

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 states the trigger ('Use this when a user asks what governments, councils, hospitals or other public buyers actually paid') and then a full exclusion list: consumer/private prices, tenders still open (estimates not prices), single named suppliers, asking prices, other countries. That is explicit when-to-use, when-not-to-use, and implied alternatives in one place.

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?

Annotations already cover readOnly, idempotent, openWorld. The description adds real behavioral detail: what the overview contains (countries per tool, number of official sources, update frequency) and what the detail mode contains (publisher, licence, attribution line, limits, example requests). The trailing bulk-JSON endpoint sentence is useful but slightly unclear in intent.

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?

Front-loaded with the purpose, then the default output, then the parameter-driven alternative. Only the final bare URL sentence feels unintegrated and slightly ambiguous, keeping it from a 5.

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 an output schema present the description needn't define return shapes, yet it still characterizes both output modes well enough for an agent to pick the right call. Only the bulk-JSON URL mention is left unexplained.

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. The description goes beyond the schema by tying the parameters to a mode switch — passing country and/or category changes the result from a summary to full source records — which the schema's per-parameter text only implies.

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 states a specific function: a coverage/discovery tool showing which countries and kinds of price the other tools cover. That is clearly distinguishable from every sibling, all of which return actual price data. The two modes (overview vs. source detail) are named up front.

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 gives a clear default behavior ('It returns a short overview') and an explicit trigger for the alternative mode ('Give category and/or country to get the full detail'). It doesn't spell out when not to use this tool or point at a sibling for a related need, but the context is clear enough.

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?

Goes well past the annotations by disclosing that this is a modelled national estimate (`price_type official_statistic`), explicitly not a shop receipt or household bill, that range fields are null and there is no sample size, and that data is yearly with version 5.0 updated 2026-07-21 covering 2017–2025. It also states the official source/licence accompanies each answer, which is exactly the kind of context an agent needs to caveat results.

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 opening sentence is front-loaded and effective, but it then repeats the identical phrase 'about 68 countries worldwide (World Bank estimates) (country XX)' roughly 68 times — thousands of tokens that merely restate the country enum. That bloat buries the genuinely useful content about modelling assumptions and freshness.

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 an output schema exists, the description needn't explain return shapes, and it still covers coverage span, update cadence, currency/PPP handling, model caveats and null-field expectations. An agent has everything needed to call it and to caveat the answer 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 already 100%, so the baseline is 3; the description adds genuine value by enumerating the food_group categories in plain language and warning that 'The World Bank leaves some group figures blank', which the schema only notes in passing. It also reiterates the default-year behaviour. Still, most of the country-level detail is verbatim enum duplication rather than added semantics.

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?

States a specific resource and measure — the World Bank's modelled cost of a least-cost healthy diet per person per day — plus the sub-questions it answers (year-on-year change, food-group split). This is clearly distinguishable from pricepaid_grocery_prices or pricepaid_wholesale_fresh_food_prices, which cover actual food prices rather than a modelled diet cost.

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?

Opens with an explicit trigger ('Use this when a user asks how much it costs to eat healthily in a country') and closes with concrete exclusions: 'not for the price of a particular food or shop, restaurant meals, a family's real food bill, or for countries that are not listed.' Strong when-to-use and when-not coverage, but it never names the sibling tool an agent should switch to for those excluded cases.

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?

Annotations already declare readOnly/idempotent/non-destructive, yet the description still adds substantive behavior: the answer is an official average so range fields are null and there is no sample size, per-country publication lag and provisional flags, and the critical caveat that EIA gas is per Mcf and cannot be compared to electricity per kWh. These are exactly the operational caveats an agent needs.

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 trigger sentence is well front-loaded, but the body is an enormous block that duplicates the schema's country/taxes/band notes almost verbatim, including a repeated country entry ('the Netherlands, Norway... Norway') and two-paragraph freshness recital twice (household then business). Length is not paying for itself when the same detail already lives in structured fields.

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 15-parameter, multi-country tool with an output schema, nothing an agent needs is missing: entity coverage, defaults, unit peculiarities, tax-level semantics per country, business eligibility and freshness are all present. The risk here is over-provision, not omission.

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% and the schema already spells out per-country freshness, tax levels, bands and enum meanings in granular detail. The description largely restates that same content (repeating the half-yearly/quarterly/monthly cadence per country) rather than adding semantics the schema lacks, so this sits at the baseline for fully documented parameters.

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?

Opens with a specific verb-and-resource statement ('Use this when a user asks what households pay for electricity or natural gas per kWh') and enumerates the covered countries. It explicitly separates the tool from adjacent concepts ('a published average (price_type official_statistic), not a range built from sales') and from sibling tools in its closing exclusions.

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 an explicit trigger ('when a user asks... how that compares with another country, or how it changed'), plus concrete when-not rules: 'Do not use for one supplier's quote for a particular home or company, for wholesale exchange prices, for petrol and diesel, or for other countries.' The sector and supplier_offers switches are each scoped with conditions and eligibility limitations.

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?

Annotations already declare readOnly/idempotent/non-destructive, so the bar is low, yet the description adds substantial context: release lags by country with concrete examples (about six weeks for Statistics Canada, about four weeks for Defra), an instruction to always report the reference month, disclosure that range fields are null and there is no sample size, unit conventions per series, and that an official source and licence are returned. Nothing here contradicts the read-only, open-world annotations.

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?

It is front-loaded with the use case, which is good, but the body is a dense multi-clause run-on of 300-plus words, and the product list is duplicated almost verbatim in the product parameter description. The freshness sentences could be compressed to a single comparative statement without losing 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?

An output schema exists, yet the description still tells the agent what comes back (newest monthly price, reference month, month-on-month and year-on-year change, trailing 12 months, same product in other regions, source and licence), which is more than sufficient. Combined with the freshness caveats and the explicit scope exclusions, an agent has everything needed to call this correctly and to answer credibly.

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 schema already explains country enums, the province-required rule for Canada, the UK's national-only figure, and the product vocabulary. The description restates the product list and notes units (per tonne, per hundredweight, per dozen, per kilolitre), which adds only modestly 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 states a precise verb+resource+scope: monthly average prices farmers received, per product and region, for Canada and the UK, with the specific product list enumerated. It rules out neighbouring domains (supermarket, wholesale market, futures, EU) and clarifies it is an official_statistic rather than a sales-derived range. The one gap is that it never names the very similarly titled sibling pricepaid_farm_prices, so an agent must infer the split from the 'not a range built from sales' clause.

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 gives an explicit trigger ('use this when a user asks what farmers received, per month, for a crop or animal product... in a region of Canada or the United Kingdom') and an explicit exclusion list covering supermarket prices, wholesale market quotes, individual farms/fields/animals, farmland, fuel/energy, futures and EU member states. The freshness paragraph also tells the agent how to interpret timing, which is a real usage constraint.

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?

Well beyond the readOnly/openWorld annotations, it discloses that these are published official statistics rather than trade-derived ranges, that range fields are therefore null and there is no sample size, the update cadence per region (weekly, monthly for raw milk, ~two months for Finland), stale-quote flagging with reduced confidence, seasonality limits on fruit and vegetables, and per-country product gaps. That is exactly the operational context an agent needs before trusting the numbers.

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 use case and exclusions are correctly front-loaded, but the body runs to roughly 450 words and repeats material that the schema already carries verbatim — the full product list, unit conventions, and which series is shown versus stashed in extra.other_series. Freshness is explained at length twice (EU cadence, then Finland cadence again). It reads as thorough rather than economical.

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 a rich output schema, a two-parameter input and open-world data, nothing material is left out: period lag, stale-quote handling, missing-product behaviour, seasonal gaps, currency/unit normalisation and the exclusion list are all covered. An agent can call this correctly without consulting anything else.

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 baseline is 3; the description lifts it slightly by stating that aliases like 'pork', 'corn' and 'tomato' are understood, and by tying products to their quoting unit (per tonne for cereals, per 100 kg otherwise, per head for piglets, per litre for Finnish milk). Most of the long product taxonomy, however, duplicates what the schema's product description already contains, so the added value is modest.

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?

States a specific verb and resource: the official price farmers or wholesalers get for a named food commodity in EU member states or Finland, with units and supply-chain stage. The scope is tight and excludes the obvious wrong readings. It stops short of distinguishing itself from overlapping siblings such as pricepaid_farm_gate_prices, pricepaid_wholesale_fresh_food_prices or pricepaid_producer_prices, so an agent choosing between them still has to guess.

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 opening 'Use this when a user asks…' enumerates concrete user intents (current price, comparison with last week/month/year, position against the 12-month range) and the closing sentence carries a long list of when-not-to-use cases. What is missing is explicit routing to the alternative tools for those excluded cases — 'Do not use for supermarket prices' never names pricepaid_grocery_prices, and dairy/wholesale siblings go unmentioned.

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?

Annotations already cover read-only, idempotent and non-destructive behaviour, but the description adds material facts an agent cannot get elsewhere: a metered cost model (USD 0.02 per answered call after 10 free calls per day per caller), the x402/USDC payment mechanism with a 402 reply explaining it, and the guarantee that 'not enough records' and errors are not billed. Data provenance (daily snapshots of official data) is also disclosed, which matters for a tool that aggregates third-party statistics.

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?

Roughly ninety words across four sentences, front-loaded with the when-to-use condition and the exclusion before the cost note. Every sentence carries distinct information: purpose, negative scope, return shape, and billing behaviour. No repetition of schema or annotation 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?

For a ten-parameter tool spanning many countries with an output schema already present, the description supplies what the structured fields cannot: the routing decision against the 'now' tool and the billing/auth consequences of calling it. Nothing an agent needs in order to decide whether to call it and what it will cost is missing.

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 every one of the ten parameters, including per-country enum nuances for fuel, area, town and country, is already documented in the schema itself. The description adds only loose phrasing ('in a place', 'recent days or weeks') and does not explain parameter interactions such as days vs months or how area/town/postcode precedence resolves — that detail lives entirely in 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 opens with a specific verb+resource combination — how pump prices have changed over recent days or weeks in a place — and states the actual output: daily median, typical range, and change over the period from daily snapshots of official data. It also marks the boundary against a sibling by saying it is not for today's cheapest stations, so an agent can distinguish it from pricepaid_fuel_prices_now without opening either schema.

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 gives explicit trigger conditions (a user asks how prices have changed, or whether fuel is getting cheaper) plus an explicit exclusion (not for today's cheapest stations). The gap is that it never names the alternative tool, so the agent must infer that pricepaid_fuel_prices_now is the intended substitute for current-station lookups.

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?

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), and the description goes well beyond them by disclosing data lag per source, publication cadence, and what each answer reports (median, range, three cheapest stations, source and licence). Much of this restates freshness notes already present in the country enum descriptions, which blunts its marginal value, and it is delivered as an undifferentiated run-on.

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 several hundred words mixing purpose, a country list, and per-country freshness boilerplate, with repeated near-identical phrasing ('every answer states...' appears a dozen times). The purpose is front-loaded, but most of the bulk should have been pushed into the schema or summarized.

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 8 parameters, an output schema, and multi-source data with wildly varying lag, the description does supply the freshness and coverage context an agent needs to set user expectations. It is arguably over-complete on freshness and thin only in that it never summarizes the overall recency range in one line.

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%, with enums for fuel, country, tax and service and per-country notes on area/town/postcode, so the schema carries parameter meaning on its own. The description adds nothing about parameters that the schema doesn't already state, so 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 opening sentence names a specific verb+resource ('current price of petrol, diesel, E10... near a place') and adds the alternative question it answers ('or where fuel is cheapest there'). The 28-country enumeration is rambling and dilutes the core statement, but the purpose itself is unmistakable and distinguishable from pricepaid_fuel_price_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?

Explicit trigger ('when a user asks the current price'), explicit exclusion ('Do not use for other countries or for historical prices'), and the geographic coverage is spelled out so an agent can decide eligibility without guessing. It doesn't name the history sibling outright, which would have closed the loop.

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?

Annotations already declare readOnly/idempotent/non-destructive/openWorld, and the description goes well beyond them: it discloses the metered pricing model (10 free calls per caller per day, then USD 0.02 per answered call via x402 USDC, with a 402 reply explaining payment) and states that 'not enough records' and errors are not charged. It also sets expectations about coverage depth ('where a source has loaded long history, otherwise recent snapshots'), which an agent needs to interpret a thin result set.

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?

Four front-loaded sentences in a deliberate order: what it answers, what it returns, what it is not, what it costs. No sentence is padding, and the cost and exclusion caveats are stated compactly rather than repeated.

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 multi-country tool with an output schema already present, the description covers everything an agent needs before calling: the question shape it serves, the fallback behavior when history is shallow, the exclusion of live and retailer-specific prices, and the full billing/failure model. Return-value detail can safely live in the 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%, so the baseline is 3, but the description adds genuine meaning about how the time-window parameters behave: pass months up to 360 to get long monthly history where a source has it, otherwise the tool falls back to recent snapshots. It also frames what the period yields (the change over the period), which the schema alone does not express.

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?

States a specific verb and resource: how the shop price of an everyday grocery item has changed over time, returning official monthly average prices with the change over the period. It also draws a sharp line against siblings by excluding today's price and single-supermarket prices, so an agent can separate it from pricepaid_grocery_prices or pricepaid_wholesale_fresh_food_prices without opening a schema.

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?

Explicit when-to-use ('user asks how the shop price ... has changed over time, or whether it is getting cheaper or dearer') and when-not ('not for today's price or for a particular supermarket'). The only gap is that it never names the alternative tool an agent should call for a current price, leaving the redirect implicit.

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?

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so safety is covered; the description instead adds real behavioral context beyond them — that answers are official averages built from CPI shelf prices rather than receipts, per-country publication lag, that range fields can be null, that answers state source and licence, and that some countries answer 'no matches' or ignore a region. It stops short of a compact statement of that behavior because the same details are scattered and repeated per country.

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?

Far oversized: the WFP-country phrase 'countries WFP surveys (Africa, Asia, Middle East, Latin America) (country XX)' is repeated verbatim for roughly fifty codes, the freshness block repeats 'our copy is refreshed daily' many times, and the country list duplicates the enum. The genuine value (item definitions per country, lag times) is not front-loaded and is hard to retrieve.

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?

An output schema exists, so return-value explanation is optional, yet the description still covers source, licence, reference month and null behavior — nothing essential for correct invocation is missing. The gap is the opposite of incompleteness: it is padded with per-country repetition, so it is complete but inefficient.

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%, and the schema already documents item per country, region availability per country, and the country enum with provider descriptions. The description repeats rather than adds to that, and never explains the interaction between the three parameters beyond what the schema says. Baseline 3 applies when structured fields already carry the parameter 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 opening clause names a specific verb and resource ('what an everyday grocery item ... costs in the shops') and the closing sentence in the description scopes it as a 'published national (or regional) average, not a range of individual transactions.' However, the core statement is buried under an enormous country enumeration, and the closest sibling (pricepaid_grocery_price_history) is never named for the year-on-year case that overlaps with it.

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?

Explicit exclusions are given: 'Do not use for the price at a particular supermarket or online shop, loyalty-card or special-offer prices, restaurant meals, petrol or diesel, or for other countries.' That is strong when-not guidance, but there is no positive routing to the sibling tools that would serve those excluded cases (fresh produce at wholesale, price history, etc.).

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?

Beyond the read-only annotations, it explains that results are posted list tariffs rather than individual payments or quotes and clarifies the median and percentile aggregation. It also provides country-specific publication cadences, file dates, and the daily collection schedule, giving unusually useful freshness context.

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 content is logically ordered from use case to outputs, interpretation, freshness, and exclusions, with nearly all material serving a practical purpose. However, it is a dense single paragraph, and the detailed output enumeration and exact file dates make it somewhat heavy despite the output schema.

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 complex multi-country tool with 12 parameters, the description supplies the scope, statistical meaning, source character, freshness, and exclusions needed to select and interpret it correctly. Detailed invocation semantics are comprehensively covered by the input schema, while the output schema handles return-field specifics.

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 detailed schema already documents country-specific applicability, defaults, enums, and parameter interactions. The description reinforces the country scope and gives a region-and-deductible example, but adds little parameter meaning beyond that 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 identifies the resource and operation precisely: monthly health-insurance premiums aggregated from regulator-approved tariffs for CH, HK, and US. Its approved-tariff scope and exclusion of supplementary or private cover distinguish it from the broader insurance and supplementary-health siblings.

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 opens with an explicit use case, including an example involving an adult, region, and deductible. The closing sentence gives clear exclusions for personal quotes, supplementary or private cover, and unsupported countries.

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?

Adds real value beyond the readOnly/openWorld annotations: it discloses the return payload (median, 10th–90th percentile, sale counts, period, confidence label, source and licence) and warns that several countries return an index (2015 = 100) or transfer-tax declared values rather than verified sale prices. It does not discuss rate limits or cost, but the provenance and data-quality caveats are unusually rich.

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 opening sentence is well front-loaded, but the body repeats the identical 'Bulgaria, Croatia, Cyprus, Czechia ... and Spain (house price index only)' string roughly fifteen times, once per country code. That block is pure redundancy and makes the description many times longer than its information 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?

Complete enough to call: it explains coverage limits (partial US, Zürich-only CH, BC-only CA), that some sources return indexes not prices, and what the response contains. It is slightly short of 5 because it never explicitly positions itself against pricepaid_home_sales_history, the closest sibling.

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 per-country parameter semantics live in the schema, so the description only needs to point at the coverage. It does enumerate the supported countries and reiterates that country AT/AU/etc. are supported, which largely duplicates the enum. Baseline 3 applies when the schema carries the load.

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?

States a specific resource and measure: median sale prices actually paid, with typical range, sale counts, period, confidence and source. The exclusions ('Do not use for rents, asking prices, commercial property') separate it cleanly from pricepaid_rent_prices and pricepaid_commercial_property.

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?

Opens with an explicit trigger ('Use this when a user asks what homes actually sold for...') and closes with an explicit when-not list naming the adjacent domains (rents, asking prices, commercial property, other countries). Nothing is left to inference about tool selection.

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?

Annotations already cover read-only, idempotent and non-destructive behavior. The description adds substantial context beyond that: the cost model (10 free calls/day, then USD 0.02 via x402), the no-charge policy for insufficient records or errors, the data nature (aggregates of official sale records only), and the exact statistics returned (median and 10th–90th percentile with change over the period).

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 front-loaded with usage guidance and remains compact (four sentences) for a tool of this complexity. The pricing sentence is detailed but earns its place because agents must know about the 402 payment path. Slight redundancy between months/days explanation and the schema, but no wasted prose.

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 output schema exists and annotations cover the safety profile, the description supplies everything needed for selection and invocation: use context, exclusions, returned statistics, data provenance, cost, and the months/days fallback. Country-specific quirks are appropriately delegated to the 100%-covered schema rather than bloating the description.

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 14 parameters are already richly documented in the schema. The description adds only a high-level explanation of the months-vs-days choice, which largely restates the schema's own parameter descriptions. Baseline 3 is appropriate when the schema carries the detailed semantics.

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?

States a specific verb (how prices have changed over time / getting more or less expensive) and resource (home sale prices in a place), and explicitly distinguishes the tool from current-price, rent and asking-price queries. An agent can identify this as the historical home-sales series without opening any schema.

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 clear when-to-use (questions about price changes over time) and when-not-to-use (current price, rents, asking prices), plus guidance on selecting months vs days. It does not name a specific sibling alternative such as pricepaid_home_sales, leaving the agent to infer the replacement from the exclusion.

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?

Goes well beyond the readOnly/idempotent annotations: it discloses that values are declared installed costs at grant or claim (not receipts, quotes, or single-home payments), that price_type is official_statistic so range fields may be null and sample size appears only where the publisher states it, and that missing measures return status no_matches rather than an estimate. It also gives per-country freshness cadence (quarterly tables, May annual publication, irregular IE, LA table ending 2018/19).

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?

Front-loads the use case and exclusions well, but the body is one dense paragraph with stacked parentheticals and repeated enumerations ("heat pumps" and the GB/IE codes are restated several times in the opening sentence). The complexity justifies length, but the same facts could be conveyed with less repetition and shorter sentences.

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?

An output schema covers return values and annotations cover the safety profile, so the remaining burden is coverage and data-quality caveats—exactly what the description supplies (per-country measure availability, no_matches behavior, nullable ranges, publication lag, general-renovation-only countries). An agent has enough to decide and call 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 the schema already explains country, measure, area, size_kw, technology and dwelling_type, including defaults and enum meanings. The description reinforces the per-country measure support matrix (GB: solar_pv and heat_pump only; IE: renovation only) but adds little beyond what the parameter descriptions already state. 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?

States a specific verb and resource (what a home upgrade costs) with the exact measures and geographies covered. No sibling tool in the pricepaid_* family touches home retrofit costs, so the topic alone separates it cleanly.

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?

Opens with an explicit "Use this when a user asks..." trigger listing the geographies and measures, and closes with a concrete exclusion list: no quotes for a particular home, no installer prices or offers, no running costs or savings, no other countries. Both the when and the when-not are stated.

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?

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), but the description adds substantial context beyond them: the value is a published average over all hotels, not a range or a date-specific quote, so range fields are null and no sample size exists. It also discloses per-country publication lag and history depth (2008 back to five years, HK 2-3 months behind, SG annual), plus the refusal behaviour for HK/SG districts.

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?

It is front-loaded with the trigger, then the returned metric, then freshness, then exclusions - a sensible order for a complex tool. However, the freshness block is a run-on and repeats the clause "every answer states its month" verbatim for both the Ontario/Finland/Norway and Spain entries, which is wasted text.

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 an output schema existing, the description still tells the agent what to expect (average, null range fields, no sample size) and adds per-country freshness and coverage limits that no structured field conveys. For a three-parameter, six-country statistical tool, an agent has everything needed to decide and call 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% and the parameter descriptions are themselves extremely detailed (area examples per country, stars constraints, country enum meanings), so the schema does the heavy lifting and baseline 3 applies. The description reinforces the country set and implies area/stars behaviour but adds no syntax or format detail not already present in 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 opens with a specific verb and resource ("what a hotel room costs per night, on average"), enumerates the six covered countries, and defines the returned metric precisely (official average daily rate per occupied room, from the national statistics office). It is unambiguously distinguishable from siblings such as pricepaid_airfare_prices or pricepaid_rent_prices.

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 gives an explicit trigger ("Use this when a user asks what a hotel room costs per night... or how hotel prices changed on a year earlier") and an explicit exclusion list: "Do not use for the price of one named hotel, a booking for particular dates, holiday rentals or hostels, or for countries that are not listed." The country enumeration also acts as a hard boundary against out-of-scope queries.

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?

Goes well past the annotations (readOnly/openWorld/idempotent/non-destructive) by disclosing the privacy floor (aggregates only, never fewer than 5 policies), the output shape (median, 10th–90th percentile, policy count, period, confidence label, source and licence), the monthly refresh cadence with a checked-as-of date, and a substantive caveat that some premiums are administratively set rather than market quotes.

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?

Front-loaded with the usage trigger and the concrete example, then moves through output, caveats, freshness, and exclusions in a logical order. It is dense but every clause carries information; the only friction is the stacked parentheticals 'United States (federal flood insurance) (country US)' and the slightly buried freshness note.

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 two-parameter aggregate-lookup tool with an output schema, the description covers everything an agent needs: what it returns, the small-sample suppression rule, update cadence, the interpretation caveat about regulated premiums, and all the cases it should not be used for.

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 documents that 'area' accepts a 5-digit ZIP or a 2-letter state code and that country is US/NFIP. The description's mention of ZIP-or-state examples and the 5-policy minimum largely duplicates that text rather than adding new semantics, so the 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?

States a specific verb and resource — what insurance actually costs policyholders — and immediately narrows it to US federal flood insurance premiums per ZIP or state. The parenthetical '(federal flood insurance) (country US)' makes clear this is not generic insurance pricing, which is what distinguishes it from siblings like pricepaid_health_insurance_premiums.

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?

Opens with an explicit trigger ('Use this when a user asks what insurance actually costs the people who hold it') and closes with a clear exclusion list: no personal quotes, no uncovered insurance lines, no home value/replacement cost, no other countries. It stops short of naming which sibling to use for those excluded cases, leaving the agent to infer the routing.

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?

Annotations cover the safety profile (readOnly, idempotent, non-destructive), and the description adds genuinely behavioral context: the data are published averages (price_type official_statistic), so range fields are null and there is no sample size; publication lags about two years with country variance; answers state their reference year and flag stale figures. It also discloses that unknown region codes yield a clear no_matches and that each answer lists available regions.

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?

Front-loaded with the use case, then return contents, then caveats and exclusions — a sensible order. The reference-year warning is repeated in two consecutive sentences ('How fresh: annual... Always read the reference year in the answer'), which is redundant and could be tightened.

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 four parameters, an output schema, and full schema coverage, the description supplies everything an agent needs beyond structured fields: freshness/lag expectations, coverage gaps (DE, CY, GB absent; BE ends 2014, IT 2020; NO rents only), and the no_matches behavior for unsupported regions. Return values are left to the output schema as appropriate.

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, but the description still adds meaning: it explains the price vs rent distinction in terms of underlying Eurostat series and default land types ('price: arable; rent: arable and/or grassland'), and notes that not every country reports every land type. It stops short of adding anything new for country/region beyond what the schema already says.

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?

States a specific verb and resource — average agricultural land sale price or annual rent per hectare in EU member states and Norway, nationally or by NUTS region — and explicitly bounds scope by excluding field-level values, house/building land, commercial property, listings, and other countries. An agent can distinguish it from siblings like pricepaid_rent_prices, pricepaid_home_sales, and pricepaid_commercial_property without opening the schema.

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?

Opens with an explicit trigger ('Use this when a user asks what agricultural land sells for, or what it costs to rent') and closes with a clear negative list ('Do not use for the value of a particular field or farm, for house or building land or commercial property, for listings or asking prices, or for other countries'). Both when-to-use and when-not-to-use are spelled out.

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