Pinch Grocery Prices (Australia)

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

With no annotations, the description fully discloses behavior: searches in parallel, returns raw unranked candidates, includes product_categories for disambiguation, explains the 'cheapest' hint semantics including its fallback logic, and warns about format ambiguity requiring user confirmation. This goes far beyond a generic tool description.

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 long but well-structured with clear sections (workflow, tips, ambiguity). Every sentence serves a purpose — from the upfront warning against misuse to detailed field semantics. No fluff; the length is justified by the tool's complexity.

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 having no output schema, the description fully covers the tool's behavior, parameters, return candidate characteristics, and edge cases like ambiguous formats. Combined with the input schema, an agent has enough context to use the tool correctly and handle subtle decision points.

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?

Although schema coverage is 100%, the description adds substantial meaning: explains how product_type narrows results and gives concrete examples per enum, notes category overrides product_type, and advises raising candidates_per_retailer for ambiguous queries. It enriches the schema's basic definitions.

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

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

The description opens with 'ADVANCED / manual selection' and clearly states it searches multiple items in parallel and returns raw candidate products with NO filtering or scoring. It explicitly distinguishes from build_basket and save_basket, making the tool's purpose unambiguous and differentiated.

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

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

Provides explicit when-to-use and when-not-to-use guidance: 'Do NOT use this to build a shopping list' and directs users to build_basket instead. Includes a step-by-step workflow and tips for refining queries, making appropriate usage highly actionable.

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

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

No annotations are provided, so the description carries the full burden. It discloses that the search uses keyword matching and may leak wrong products, describes the validation process, and outlines exact output formatting. This goes well beyond what annotations would provide and gives the agent a clear model of tool 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?

The description is long but every sentence serves a purpose given the tool's complexity. It is well-structured with clear sections (main instruction, validation, output format) and front-loaded with the critical usage rule. Slightly verbose but not rambling.

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

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

The description fully covers how to invoke the tool, how to validate results, what to do with missing items, and the exact output format (line 1, markdown table, share URL). Since there is no output schema, this level of detail is essential and complete.

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

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

Schema description coverage is 100% and already includes detailed examples and instructions (e.g., 'Include any size/quantity in the string'). The description repeats this guidance but adds no substantive new meaning beyond the schema. It does reinforce the retailer omission behavior, but that is also already 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 clearly states the tool is MANDATORY for shopping lists and explicitly says to call it once with the full list of 2+ grocery items. It distinguishes itself from siblings by saying 'Do NOT call decompose_product, search_products, or batch_search per item' and explains its built-in parallel search and query analysis.

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

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

Provides explicit when-to-use guidance: 'When the user gives you 2 or more grocery items, call this tool ONCE'. Also gives clear when-not-to-use guidance for sibling tools, and specific instructions for the retailers parameter ('If the user named the stores they shop at, pass them in retailers; otherwise omit it').

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

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

With no annotations, the description carries the transparency burden. It discloses the return format (all retailers sorted cheapest first) and adds a non-obvious limitation ('about 7,800 products have barcode matches'). This helps set expectations about potential empty results, but it does not mention edge cases like unavailable prices or data freshness.

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

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

The description is three sentences, front-loaded with the core purpose, followed by output behavior and a caveat. No wasted words; each sentence earns its place.

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

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

Given the tool's simplicity (one parameter, no output schema), the description is largely complete: it states the action, the input method, the output format, and a key limitation. It lacks explicit alternative guidance, but that is partially covered by purpose clarity. Overall, an agent has enough to select and invoke it correctly.

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

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

The schema already describes the single parameter (barcode) fully, so the baseline is 3. The description adds value by explaining the product coverage limitation ('about 7,800 products have barcode matches'), giving users context about expected match rates beyond the schema.

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

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

The description clearly states the tool's function: compare prices for the same product across retailers using a barcode. It also specifies the output (returns all retailers, sorted cheapest first), which distinguishes it from sibling tools like get_cheapest or get_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?

The description implies usage (when you need to compare prices across retailers for a specific product), but it does not explicitly mention when to use this tool versus alternatives like get_cheapest or get_product. No exclusions or alternative tool names are given, so guidance is only 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?

With no annotations provided, the description carries full responsibility for behavioral disclosure. It clearly states 'This does not call any API; it is a structured reasoning step', discloses the core rule about brand_preference being null unless a literal brand is given, and explains the cheapest-first strategy. This is comprehensive behavioral context for an AI agent.

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 the most critical usage warning ('ADVANCED / single item'), then proceeds to usage limits, no-API disclosure, output fields, and the core rule. Every sentence serves a functional purpose, and the line breaks make it easy to scan. It is appropriately sized for the tool's complexity.

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

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

The description covers when to use the tool, how it behaves (no API), and the key rule for brand_preference. It lists three output fields (canonical_query, disqualifiers, suggested_category) but does not fully enumerate the complete return object, which given the 9-parameter schema could be slightly more explicit. Overall, it is largely complete for invoking the tool 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 baseline is 3. The description adds an instructive semantic layer: 'Fill in every field based on what a typical Australian family would mean by this item', which helps interpret parameter values like qualifiers and disqualifiers. However, much of the core rule is already embedded in the schema's parameter descriptions, so the added value beyond the schema is moderate.

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

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

The description clearly states the tool's specific function: 'break ONE item into structured search attributes'. It distinguishes itself from the sibling build_basket by explicitly limiting usage to single items and overriding build_basket's pick. This is a specific verb+resource definition that leaves no ambiguity.

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

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

The description provides explicit when-to-use and when-not-to-use guidance: 'Do NOT use this to build a shopping list: for any list of 2 or more items, call build_basket' and 'Use decompose_product only to break ONE item... when you intend to override build_basket's pick'. It also clarifies that it is a reasoning step, not an API call, which helps decision-making.

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

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

No annotations are provided, so the description carries the burden. It discloses the search scope ('across all Australian grocery retailers') and result ordering ('sorted by price ascending'), which adds behavioral context beyond the schema. However, it does not mention whether the operation is read-only or any other edge-case behaviors, leaving some gaps.

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

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

The description is two concise sentences with no redundancy. It front-loads the core purpose and includes the most important detail (price sorting) efficiently.

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

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

For a simple search tool, the description adequately covers the essential behavior: search by name, national scope, and price sorting. It does not detail the return format, but given the simplicity and lack of output schema, this is a minor omission. The description is complete enough for an agent to select and invoke the tool 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%: both product_name and limit are clearly described in the schema. The description does not add additional parameter semantics beyond reinforcing that the search is by name, 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 clearly states the tool's specific function: finding the cheapest option for a product across Australian grocery retailers. It uses a specific verb ('Find') and resource ('cheapest option'), and explicitly mentions sorting by price ascending, which distinguishes it from generic search tools.

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

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

The description implies usage when the user needs the lowest price across all Australian retailers, but it does not explicitly contrast with sibling tools like compare_prices or search_products. There is no direct 'when not to use' guidance, but the purpose is clear enough to infer appropriate scenarios.

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

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

No annotations are present, so the description carries the transparency burden. It discloses the tier-dependent history depth (30-365 days) and the returned stats, which is meaningful beyond a bare 'get'. It does not mention rate limits or data freshness, but for a read-only tool this is adequate.

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

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

Three short, front-loaded sentences cover purpose, output stats, and a key limitation without redundancy. Every sentence earns its place.

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

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

Given the low complexity (2 params, no output schema), the description provides the essential return info (stats and history range). It omits pagination/error behavior, but for this tool the description is largely complete.

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

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

The schema already describes both parameters fully (100% coverage), including the default for 'days'. The description only adds the tier-dependent depth context, which is already reflected in the schema's 'days' description, so no significant extra semantic value is provided.

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

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

The description clearly states the action ('Get historical price data') and the target resource ('product'), and differentiates from siblings by emphasizing time-series stats (lowest, highest, average). It is specific and unambiguous.

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

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

The description implies use when price history or trend statistics are needed, but it does not explicitly mention alternatives or when not to use this tool. There is no exclusion or alternative naming, so guidance remains implied rather than explicit.

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

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

No annotations are provided, so the description carries the full burden. It only states that detailed information is returned, but does not disclose return format, error handling, or whether any side effects exist. This is minimal for a tool without structured safety hints.

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 only two sentences, front-loaded with the main action, and every sentence provides necessary context. No fluff or repetition.

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

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

For a simple get-by-id tool with one parameter and no output schema, the description is mostly adequate. However, it does not describe what 'detailed information' includes, nor does it explicitly relate to sibling tools (e.g., that search returns summaries while this returns full details). Given the lack of structured context, a bit more would help.

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% ('Product ID from search results'), and the description essentially repeats this fact ('by its ID', 'Product IDs are returned in search results'). No additional meaning is added beyond what the schema already provides.

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 verb ('Get'), resource ('grocery product'), and scope ('by its ID'), which clearly differentiates it from sibling tools like search_products or get_price_history. It also provides a hint about the ID source.

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

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

The description implies usage after search results are obtained ('Product IDs are returned in search results'), but it does not explicitly mention when to use this tool versus alternatives. No exclusions are given, making the guidance implicit rather than explicit.

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?

Although annotations are absent, the description discloses important behavioral traits: weekly updates, exclusion of unconfirmed pre-changeover specials, the possibility of a near-empty list after changeover, and the fallback via get_product. This gives the agent a realistic picture of data freshness and edge cases beyond what the schema conveys.

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 the core purpose, then provides necessary caveats and an alternative in just a few sentences. Every sentence adds meaningful information, and the structure is logical and efficient.

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

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

The tool has no output schema and no annotations, but the description compensates with key context: what results include, data freshness, edge-case behavior, and the alternative tool for individual product prices. For a filtered list endpoint with three optional parameters, this is sufficiently complete.

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

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

The input schema covers 67% of parameter descriptions (limit and category), leaving only 'retailer' without a textual description but with an enum. The description's 'Filter by retailer or category' adds slight semantic context but largely repeats what the schema already states, so a baseline score of 3 is appropriate.

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

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

The description opens with 'Get current grocery specials and promotions', a specific verb+resource pairing that clearly distinguishes this tool from siblings like get_product or search_products. It also mentions filtering by retailer or category and that results include savings amounts, further scoping its purpose.

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

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

The description explicitly states when to use this tool (for current specials) and provides an alternative path for individual product prices, noting that after a catalogue changeover the list can be near-empty and to use get_product with special_may_have_ended: true. This clear context and alternative guidance satisfies the usage dimension.

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

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

With no annotations, the description carries the full burden. It discloses that this is a manual commit, computes totals, returns a shareable URL, and allows omitting retailers with no good match. It also warns against blindly passing product_ids, which adds meaningful operational context beyond what the schema conveys.

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 the critical warning, then the rule, then how-to guidance. Each sentence adds distinct value, and the structured paragraphs make it easy to scan despite its length. No redundancy or 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?

For a single-parameter tool with no output schema, the description thoroughly covers input shape, item-level requirements, alternatives, prerequisites, and return value. It falls just short of full completeness by not explicitly stating what 'commit' does in terms of persistence or any possible error behavior, but it is enough for an agent to invoke correctly.

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

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

Even though the schema documents selections/query/picks, the description enriches these parameters by explaining that product_ids should be the best match from batch_search, that not every retailer needs a pick, and that the query is the original shopping-list item. This goes well beyond the schema's generic property descriptions.

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

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

Description opens with 'ADVANCED / manual commit' and clearly states it commits a basket from product_ids the user has already chosen, computes totals, and returns a shareable URL. It explicitly distinguishes save_basket from build_basket, making its unique purpose 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?

Provides explicit when-to-use and when-not-to-use: 'Do NOT use this to build a basket from a shopping list: for any list of 2 or more items, call build_basket' and 'Use save_basket only to commit a basket from product_ids you have ALREADY chosen yourself.' Also adds a concrete example and prerequisite ('Only call this after you have reviewed batch_search results').

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

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

With no annotations, the description carries the burden. It discloses what is returned (product name, price, brand, category, unit price, on_special status) which is useful. However, it does not mention pagination behavior, data freshness, whether search is across all retailers at once, or any limitations. The description is accurate but not rich on process details.

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

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

The description is two sentences, concise, and front-loaded. It states the action and scope first, then the return fields. No filler or redundancy.

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

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

Given 6 parameters, no output schema, and no annotations, the description provides a solid overview: it names the retailers and return fields, which helps an agent understand the tool's output. The schema fills in parameter descriptions. Missing are usage notes about alternatives or edge cases, but overall it is sufficiently complete for a search 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 67% (4 of 6 params documented). The description adds meaning by indicating the search scope (across listed retailers) and listing return fields, which complements the schema. However, it does not clarify ambiguous params like sort or retailer beyond what the enum provides. Baseline 3 is appropriate since the schema does most of the heavy lifting.

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

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

The description clearly states the tool's function: 'Search Australian grocery products across Woolworths, Coles, Aldi, and Harris Farm.' It specifies the resource (grocery products) and the exact retailers, and lists return fields. This distinguishes it from siblings like get_product or get_cheapest.

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

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

No explicit guidance on when to use this tool versus alternatives. It does not mention batch_search for multiple queries, compare_prices for price comparison, or get_specials for specials only. The description only implies general search capability, leaving usage context to inference.

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