Prezzinvista - Radar dei Volantini

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

Annotations already declare readOnly, idempotent, non-destructive and non-open-world, so safety is covered. The description adds real behavioral context beyond them: the return contract per document type, the citation URL, and the geographic coverage constraint ("Covers Italy only"), which is consistent with openWorldHint=false.

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 purpose sentence is front-loaded and the Italy-only constraint is useful, but the long per-document-type enumeration of returned fields largely restates what the existing output schema already specifies, so several clauses do not fully 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?

With an output schema present, return values need not be re-explained, yet the description still adds id provenance, scope limitation, and a citation-URL note. Nothing an agent needs to invoke it correctly is missing; the only flaw is mild redundancy with 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% and the single id parameter is documented in the schema, so the baseline is 3. The description adds a genuine provenance constraint — ids originate only from search — which meaningfully restricts how the parameter may be populated.

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 (read one document returned by search, given its id) and enumerates exactly what each document type yields. It is clearly distinguishable from siblings like search and get_price_trend, so an agent can select it 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?

"Use this to read one of the documents returned by search" plus "Ids come only from search" gives a clear precondition and effectively routes the agent from the search tool. It does not explicitly compare against get_price_trend, whose product-level trend data overlaps with what this tool returns, so there is a small gap in exclusions.

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

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

Annotations already declare readOnly, idempotent, non-destructive, and closed-world, so the safety profile is covered. The description adds valuable non-structured context: Italy-only coverage, a limited catalogue of ~200 Italian-named staples, and the MCP Apps card rendering. It does not mention rate limits or caching, but the annotation burden is largely met.

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 when-to-use triggers and examples, then covers scope, alternative, and output. It is somewhat long and the parenthetical product list is close to redundant with the schema examples, but every sentence carries 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 values need not be explained, yet the description still summarizes them (median/lowest, weekly and per-chain, link). Combined with the Italy-only and catalogue-size limits and the sibling routing, an agent has everything needed 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 single param is documented in the schema, so baseline is 3. The description goes beyond it by clarifying the expected vocabulary is a fixed set of ~200 staple products named in Italian (with examples like detersivo, pannolini), which meaningfully constrains how to fill the parameter.

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

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

States a specific resource (weekly price trend of a product) with verb-like intent and explicitly scopes it: median/lowest flyer prices per week and per chain. It also distinguishes itself from the sibling search_flyer_offers, which handles specific brands and models.

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 concrete trigger conditions ('how much does pasta cost this week', 'is coffee more expensive than last week') and names the alternative tool with the condition that selects it. Nothing is left to inference.

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 and destructiveHint=false, so the safety profile is covered; the description adds real value beyond that with the Italy-only boundary, the default 30 / nearest-first ordering behavior, and the MCP Apps card rendering in capable hosts. It does not discuss rate limits or failure modes, which keeps it from 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 usage trigger, then capabilities, then scope, then sibling routing; every sentence carries information. It is on the denser side and the output-fields sentence overlaps with the existing output schema, but there is no filler.

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

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

With an output schema present, enumerating return fields is optional; the description nonetheless frames the result shape and adds the geographic scope and host-dependent card behavior an agent needs to set user expectations. Nothing required to invoke it correctly is missing given the rich schema and annotations.

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 already documents its own format, defaults, limits and the 15 km radius rule, so the schema does the heavy lifting. The description only echoes the city/chain filtering at a high level ('optionally only for chains with a store near a city'), adding no syntax or format detail beyond the schema — baseline 3.

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 concrete verb+resource (lists store flyers valid right now) and scopes it to Italy, and explicitly distinguishes itself from the sibling search_flyer_offers by noting that flyer products are that tool's job. An agent can pick between the two 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?

Opens with explicit trigger conditions ('when the user asks which flyers are valid right now', 'whether a chain has a flyer this week', 'until when a flyer is valid') and names the alternative tool for the adjacent product-level question. When-to-use and when-to-use-something-else are both covered.

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, closed-world). The description adds real behavioral context beyond them: Italy-only coverage, the document-oriented return (offers, flyers, weekly price pages), and the relationship that full text comes from fetch. It does not discuss rate limits or result counts, so a 4 rather than 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?

Dense but well front-loaded: trigger first, then scope, then return format, then the sibling hand-off. Every sentence carries information, though the run-on structure of the first sentence makes it slightly harder to scan than it could be.

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

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

For a single-parameter search whose output schema documents the return shape, the description supplies everything else an agent needs: geographic scope, query language, example phrasings, and the fetch pairing. Nothing material 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 coverage is 100%, so baseline is 3; the description earns above that by supplying language requirement (Italian), the maxLength constraint (200), and concrete query shapes ('caffè Lavazza a Milano', 'volantino Lidl', 'prezzo pasta') that the terse schema description does not.

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 (free-text search over Italian store flyers) and immediately bounds it: no filters, no sorting, Italy only. It also explicitly contrasts with search_flyer_offers and fetch, so the agent can distinguish it from every relevant sibling.

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 you need citable sources for a free-text question ... no filters or sorting needed') and an explicit exclusion that routes the agent elsewhere ('Sorting by price, a price cap and a choice of chains belong to search_flyer_offers'). This is close to ideal routing guidance.

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

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

Annotations already declare readOnly, idempotent, non-destructive, closed-world, so safety is covered; the description goes further with non-obvious behavior: product names must be Italian, flyer prices are indicative and the in-store price prevails, and results render as cards in MCP Apps hosts. These are real operational caveats not derivable from structured fields.

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 when-to-use condition and otherwise dense, but the sentence enumerating return fields (price, previous price, pack size, price per kg, department, chain, expiry, link) duplicates the existing output schema and could be trimmed.

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 an 8-parameter zero-required search tool with annotations and an output schema, the description supplies everything an agent needs: trigger, geographic limitation, language constraint on query, data-quality caveat, and host-dependent rendering. No material gap remains.

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 is already documented (city radius, sort enum meanings, pagination, chain list, price cap). The description restates those filters and repeats the Italian-query requirement rather than adding format or syntax detail beyond the schema, 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+resource (search offers in flyers) with explicit scope: currently valid Italian supermarket/discount/electronics flyers, with filters and sorting. The 'covers Italy only, not online-shop prices' clause makes it easy to distinguish from siblings like search and list_current_flyers.

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 condition ('Use this when the user wants to know where a product is on offer ... and you need filters or sorting'), enumerates the concrete filter/sort scenarios, and states two exclusions (other countries, online-shop prices). Nothing about when to prefer or avoid it is left to inference.

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