Get the best grocery and supermarket prices, price history, and price tracking. Build the best value baskets for what you want.
ADVANCED / manual selection. Do NOT use this to build a shopping list: for any list of 2 or more items, call build_basket (one call, server-side, cheapest pick per item). Use batch_search only when you need the RAW candidate products for items you intend to select MANUALLY (for example, to override build_basket's pick on one item). It searches multiple items in parallel and returns raw candidate products per query (up to candidates_per_retailer per retailer) with NO filtering or scoring applied.
WORKFLOW:
Call batch_search with your shopping list items
Review the candidates for each item. For each query, pick the single best product_id per retailer that actually matches what the user wants (correct product type, reasonable size, not a different product). If none of the candidates are a good match for a query, call batch_search again with a refined query (e.g., more specific terms, different wording)
Once you have confirmed product_id selections for all items, call save_basket with your picks
TIPS:
Set product_type to help narrow results to the right category (e.g., fresh_produce for herbs and vegetables)
Each candidate includes a product_categories field (JSON array of retailer category labels like 'Yoghurt', 'Herbs & Spices', 'Sausages'). Use this to distinguish the actual product type when names are ambiguous (e.g., 'oregano' the herb vs 'oregano sausages')
Prefer products where the name clearly matches the query intent
For staples (milk, eggs, bread), the cheapest option is usually the store brand
If results look wrong (e.g., searching 'rosemary' returns snacks instead of herbs), retry with a more specific query like 'fresh rosemary'
Each item includes a 'cheapest' hint with one entry per retailer. This is the cheapest candidate whose product_categories match the inferred subcategory for the query, NOT necessarily the lowest unit_price overall: a clearly off-category cheaper item (e.g., a snack bar under 'peanut butter') is deliberately excluded. When no category signal is available it falls back to the raw lowest unit_price. Treat the hint as advisory and confirm against the full candidate list and the user's intended format.
AMBIGUITY: When candidates for a query span clearly different product formats (e.g., microwave rice pouches vs dry rice bags, single-serve vs family/bulk sizes, flavoured vs plain variants, fresh vs frozen), ASK the user which format they prefer before selecting a product. Compare the size field across candidates to detect this: a spread from 125g to 5kg signals format ambiguity. Do not silently pick the cheapest option when it may be the wrong format (e.g., a 250g microwave pouch when the user likely wants a 1kg bag).
| Name | Required | Description | Default |
|---|---|---|---|
| items | Yes | List of grocery items to search (1-20 items). | |
| retailers | No | Filter to these retailers only. If omitted, all 4 are searched. | |
| candidates_per_retailer | No | Number of candidate products to return per retailer per item (1-30, default 10). Use more candidates if you expect ambiguous results. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Even without annotations, the description fully discloses behavioral traits: parallel search, no filtering/scoring, per-retailer candidate limits, the 'cheapest' hint logic (advisory, may exclude off-category cheaper items), and the product_categories field to distinguish ambiguous names. This transparency goes well beyond what annotations might have provided.
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 highly structured (ADVANCED/use cases, WORKFLOW, TIPS, AMBIGUITY). Every sentence provides actionable guidance; there is no repeated or filler content. The length is justified by the tool's complexity and the need to guide manual product selection.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema or annotations, the description is remarkably complete: it explains what the tool returns (raw candidates, cheapest hint), how to handle ambiguous results, when to retry, and how to proceed with save_basket. It covers all essential aspects 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?
Despite 100% schema coverage, the description adds rich parameter semantics: candidates_per_retailer should be increased for ambiguous results, product_type narrows results, category overrides product_type, and the 'cheapest' hint's behavior is clarified. This guidance is not 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 clearly states the tool's purpose: it searches multiple items in parallel and returns raw candidate products with no filtering or scoring applied. It explicitly distinguishes itself from build_basket, positioning batch_search as the manual selection tool for cases where the user wants to override automatic picks.
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... call build_basket". It also explains the exact workflow (batch_search → review candidates → call save_basket) and gives tips for refining queries when results look wrong.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
MANDATORY for shopping lists. When the user gives you 2 or more grocery items, call this tool ONCE with the full list. Do NOT call decompose_product, search_products, or batch_search per item: this tool searches every item in parallel with built-in query analysis (category routing, brand aliases, subcategory boost) and returns a basket with per-item cheapest pick, per-retailer options, basket total, retailer totals, and a shareable share_url. If the user named the stores they shop at, pass them in 'retailers'; otherwise omit it to search all four.
VALIDATION (mandatory before rendering): The search engine uses keyword matching, so wrong products leak through. Items flagged with a 'review' field on their cheapest pick are LIKELY WRONG and need your attention first. Then scan ALL picks (flagged or not) and check: (1) Is the product actually what was asked for? (e.g. 'frozen chips' is NOT 'frozen blueberries', 'sweet potato' is NOT 'potato', 'chicken fingers crumbed' is NOT 'chicken breast') (2) Is the size/form correct? (e.g. 400g pack is not a valid match for '2kg') (3) Is the selected option the cheapest CORRECT product, not just the cheapest product? If a pick is wrong: pick the correct product from by_retailer options for that item, or mark as '(check in store)'. Recalculate basket_total from your corrected picks.
OUTPUT FORMAT: Line 1: 'Cheapest basket: $X.XX' (use corrected basket_total). Then ONE markdown table with columns: Item | Product | Store | Price | Size. Then one line: 'View and share this basket: '. Use '(check in store)' in the Product cell for items in items_missing or where no correct product exists. No preamble, no per-item narration, no follow-up offers.
| Name | Required | Description | Default |
|---|---|---|---|
| items | Yes | Shopping list items exactly as the user wrote them, e.g. ['4 bananas', 'whole chicken', '12 free range eggs', 'full cream milk 2L', 'spaghetti', 'sliced white bread']. Include any size/quantity in the string ('2L', '1kg', '12 pack') so the cheapest CORRECT size is chosen. | |
| retailers | No | Only return results from these stores. Omit to search all four. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It discloses parallel search, built-in query analysis, keyword-matching limitation, the 'review' field warning, and detailed validation steps to catch wrong products. This goes well beyond what the schema provides.
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-organized into mandatory usage, validation, and output format sections. Every sentence serves a purpose, though it could be trimmed slightly without losing critical information. It is comprehensive and front-loaded with the 'MANDATORY' call-out.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists, so the description thoroughly explains return values (per-item cheapest pick, retailer options, totals, share_url) and dictates the exact output format including validation and handling of missing items. This gives the agent all necessary context for correct invocation and response.
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 both parameters already have rich descriptions. The tool description adds extra context for 'retailers' (pass only if user named stores), but most parameter semantics are already present in the schema. The added guidance is helpful yet not essential, so above baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states it builds a shopping basket by searching all items in parallel and returning cheapest picks, totals, and share URL. It explicitly distinguishes from siblings by instructing 'Do NOT call decompose_product, search_products, or batch_search per item'.
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 tool is marked 'MANDATORY for shopping lists' and explicitly says when to use it (2+ grocery items) and when not to use alternatives. It also explains when to pass 'retailers' versus omit it, providing clear decision context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Compare prices for the same product across retailers using its barcode. Returns all retailers stocking the product, sorted cheapest first. About 7,800 products have barcode matches.
| Name | Required | Description | Default |
|---|---|---|---|
| barcode | Yes | EAN-13 barcode (e.g., '9300675016902') |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden of behavioral disclosure. It states the output behavior (all retailers, sorted cheapest first) and provides a critical limitation ('About 7,800 products have barcode matches'), warning the agent about potential empty results. It does not mention pagination or errors, but for a simple lookup 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?
Two sentences, front-loaded with the core purpose immediately, and zero redundant words. It informs the agent about the action, result, and a key constraint 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?
The tool is simple (one input, no output schema), and the description covers the purpose, output behavior, and a coverage limitation. It could be more explicit about the exact structure of returned retailers (e.g., names/prices), but given the lack of output schema, it is reasonably 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 description covers 100% of the parameter (barcode) including format and example. The tool description only references 'barcode' without adding new semantics, so it meets the baseline but does not exceed it.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Compare') and resource ('prices for the same product across retailers') along with the input method ('using its barcode'). It clearly distinguishes from siblings like get_cheapest (single result) and search_products (text search) by focusing on cross-retailer comparison.
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 clearly indicates when to use it: when you have a barcode and need price comparison across retailers. It also implies the scope ('all retailers stocked, sorted cheapest first'), but does not explicitly mention alternatives or when not to use it, leaving some room for interpretation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
ADVANCED / single item. Do NOT use this to build a shopping list: for any list of 2 or more items, call build_basket (one call, server-side). Use decompose_product only to break ONE item into structured search attributes when you intend to override build_basket's pick for that single item. This does not call any API; it is a structured reasoning step.
OUTPUT: canonical_query, disqualifiers, and suggested_category for that single item.
Fill in every field based on what a typical Australian family would mean by this item. CORE RULE: Unless the user literally specifies a brand, brand_preference MUST be null and the strategy is cheapest-first (unit_price_asc, no retailer filter).
| Name | Required | Description | Default |
|---|---|---|---|
| quantity | Yes | Target size. Use to filter results after search. Family intent means prefer larger sizes for better unit price. | |
| raw_input | Yes | The item exactly as the user wrote it | |
| qualifiers | Yes | Soft preferences that improve a match but don't disqualify if absent. e.g. ['skinless', 'boneless'] for chicken breast, ['Australian'] for sultanas | |
| category_path | Yes | Ontological path from general to specific, e.g. ['meat', 'poultry', 'chicken', 'breast'] or ['pantry', 'cereal', 'wheat biscuits'] | |
| disqualifiers | Yes | Terms that indicate a WRONG product. Results containing these MUST be excluded. e.g. for 'chicken breast': ['thigh', 'drumstick', 'wing', 'nugget', 'schnitzel', 'crumbed', 'marinated']. For 'Vegemite': ['twist', 'scroll', 'shapes', 'cheesy bite']. For 'strawberries': ['yoghurt', 'jam', 'ice cream', 'flavoured']. For 'milk': ['flavoured', 'chocolate', 'coffee', 'almond', 'oat', 'soy', 'coconut']. | |
| canonical_query | Yes | The cleaned search term to use with search_products. Strip sizes and brands (unless brand IS the product, like 'Vegemite'). 'chicken breast bulk pack' becomes 'chicken breast fillets'. 'Sanitarium Weet-Bix' becomes 'Weet-Bix'. 'full cream milk 2L' becomes 'full cream milk'. | |
| barcode_eligible | Yes | true for branded packaged goods (Weet-Bix, Vegemite, cheese slices, chips). false for fresh produce, meat, and store-brand generics. When true AND a result has a barcode, call compare_prices to check if another retailer has it cheaper. | |
| brand_preference | No | ONLY set this if the user LITERALLY named a brand (e.g. 'Weet-Bix', 'Vegemite'). If the user wrote a generic item like 'milk', 'chicken breast', 'eggs', 'bread', this MUST be null. When null, Pinch finds the cheapest option regardless of brand. | |
| suggested_category | No | The grocery store category to filter search results. Use this to prevent wrong-category contamination. e.g. 'Pantry' for rice crackers (prevents dairy lunch packs), 'Fruit & Vegetables' for fresh produce, 'Meat & Seafood' for meat, 'Dairy, Eggs & Fridge' for dairy, 'Frozen' for frozen items. Only set when the item clearly belongs to one category and cross-category results would be noise. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden and excels: 'This does not call any API; it is a structured reasoning step' clearly discloses no external side effects. It also states the output fields and core rule about brand_preference, which gives the agent a clear model of 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?
Well-structured and front-loaded: opens with 'ADVANCED / single item', then exclusion, purpose, non-API clarification, output summary, and core rule. Every sentence earns its place, and the length is appropriate for a complex reasoning 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?
No output schema exists, but the description explicitly names the expected output fields (canonical_query, disqualifiers, suggested_category). Combined with the usage guidance and behavioral transparency, it gives the agent everything needed to 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%, so baseline is 3. The description adds some context (e.g., 'typical Australian family' and the brand rule) but these largely reinforce what's already in the schema. No significant new semantic meaning 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 purpose: 'break ONE item into structured search attributes' and 'structured reasoning step'. It also distinguishes from sibling build_basket by specifying it's for a single item only.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly provides 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'. This is textbook usage clarity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find the cheapest option for a product across all Australian grocery retailers. Searches by name and returns results sorted by price ascending.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Number of results (1-50, default 10) | |
| product_name | Yes | Product to search for (e.g., 'full cream milk 2L') |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure. It states that it 'searches by name' and 'returns results sorted by price ascending,' which conveys read-only search behavior and result order. However, it does not mention edge cases like no results, handling of limits, or any other side effects, leaving some ambiguity.
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, front-loaded with the main purpose, and contains no redundant or filler content. Every word adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-parameter search tool with no output schema, the description covers the core purpose, search method, scope, and output sorting. It is sufficiently complete for an agent to invoke correctly, though it could optionally state what fields appear in the results.
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 both 'product_name' and 'limit' well-documented. The description adds context by saying 'by name' and 'price ascending,' but it does not provide additional meaning beyond the schema. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Find' with a clear resource: 'cheapest option for a product across all Australian grocery retailers.' It also distinguishes the tool from siblings like compare_prices or search_products by explicitly stating the 'cheapest' across all retailers and sorting by price ascending.
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 clearly implies when to use this tool: when you need the cheapest option for a product by name across Australian grocery retailers. It does not explicitly mention alternatives or exclusions, but the context is unambiguous enough for an agent to decide.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get historical price data for a product. Shows price changes over time with stats (lowest, highest, average). History depth depends on your tier (30-365 days).
| Name | Required | Description | Default |
|---|---|---|---|
| days | No | Number of days of history (default: max for your tier) | |
| product_id | Yes | Product ID from search results |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the behavioral disclosure burden. It discloses the tier-dependent history depth (30-365 days) and the nature of the output, and 'Get' implies a read-only operation. However, it does not explicitly state side-effect-free behavior, permissions, or rate limits, leaving some room for ambiguity.
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 long, front-loaded with the primary purpose, and every sentence adds meaningful information—the stats and the tier constraint. There is no redundant or fluff 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 simple read-only tool with two parameters and no output schema, the description covers the purpose, output contents, and an important operational constraint (tier). It does not mention pagination or response format, but those are not essential given the simplicity of the 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?
The input schema provides descriptions for both product_id and days, giving 100% coverage. The description enhances this by adding the specific range '30-365 days' for history depth, which clarifies the schema's 'default: max for your tier' and provides extra semantic value for the days 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?
The description clearly states the verb 'Get' and the resource 'historical price data for a product', distinguishing it from siblings like get_product (current data) and get_cheapest (single best price). It also specifies the output: price changes over time with stats (lowest, highest, average).
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 for historical price trend analysis, but it does not explicitly state when to use this tool versus alternatives such as get_specials or compare_prices. There are no exclusion criteria or alternative tool references, leaving usage guidance mostly implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get detailed information about a specific grocery product by its ID. Product IDs are returned in search results.
| Name | Required | Description | Default |
|---|---|---|---|
| product_id | Yes | Product ID from search results |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
There are no annotations, so the description carries the burden. It clearly implies a read-only operation ('Get') with no side effects, but does not disclose behavior on invalid IDs, required permissions, or return format. For a simple retrieval tool, this is adequate but lacks richness.
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, front-loaded with the primary action, and every phrase is necessary. It avoids redundancy with the schema aside from the note about product IDs, which is concise and helpful as usage guidance.
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, no annotations), the description adequately covers what it does and where the input comes from. It could mention what fields 'detailed information' includes, but the essential context is present for an agent to select and invoke the 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?
The input schema provides 100% coverage with a description for product_id ('Product ID from search results'). The tool description repeats this same information ('Product IDs are returned in search results') without adding new meaning, so it does not elevate beyond the baseline for full schema coverage.
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: 'Get detailed information about a specific grocery product by its ID.' This uses a specific verb ('Get') and resource ('grocery product'), and distinguishes it from sibling tools like search_products by emphasizing retrieval of a single product by ID.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear usage context by noting that 'Product IDs are returned in search results,' implying the tool should be used after a search to fetch details. While it doesn't explicitly name alternatives or exclusions, the guidance is sufficient for an agent to sequence search_products then get_product.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get current grocery specials and promotions. Filter by retailer or category. Results include savings amounts. Updated weekly. Specials captured before the most recent Wednesday catalogue changeover (Coles/Woolworths) are excluded as unconfirmed; after a changeover the list can be near-empty until the next collection. Individual products still expose such prices via get_product with special_may_have_ended: true.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Number of results (1-50, default 20) | |
| category | No | Filter by category | |
| retailer | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does an excellent job. It discloses the weekly update cycle, the exclusion of unconfirmed specials before the Wednesday changeover, and the possibility of an empty list afterward. This goes beyond a simple 'retrieve specials' statement and provides meaningful behavioral 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 description is three sentences, front-loaded with purpose, and every sentence contributes—purpose/filters, update frequency/savings, and a critical exclusion rule with an alternative. There is no waste or redundant repetition of schema details.
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 list tool with optional parameters and no output schema, the description covers essential aspects: what it returns (specials with savings), filtering options, update cadence, and an important edge case. It could be more detailed about the exact result structure, but for this simple tool it 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?
Schema coverage is 67%, with limit and category already described in the schema. The description adds context that 'Filter by retailer or category' and that 'Results include savings amounts', which clarifies the meaning of the retailer and category filters. It also connects the retailer filter to the catalogue changeover behavior, enhancing semantic understanding without repeating schema details.
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 'Get current grocery specials and promotions' with a specific verb and resource, and it distinguishes itself from sibling tools like get_product by focusing on specials/promotions rather than individual product data. This makes the tool's purpose immediately obvious.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains when to use this tool for current specials and provides an explicit alternative: 'Individual products still expose such prices via get_product with special_may_have_ended: true'. It also warns about the near-empty list after a catalogue changeover, which is a valuable usage caveat.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
ADVANCED / manual commit. Do NOT use this to build a basket from a shopping list: for any list of 2 or more items, call build_basket (it searches, picks the cheapest, totals, and returns a share_url in one call). Use save_basket only to commit a basket from product_ids you have ALREADY chosen yourself (for example, after overriding build_basket's pick on an item). It computes totals and returns a shareable basket URL.
For each item, provide the query string and one product_id per retailer (the best match you found in batch_search results). You do NOT need a pick for every retailer; omit a retailer if no good match was found.
IMPORTANT: Only call this after you have reviewed batch_search results and confirmed your picks. Do not pass product_ids blindly from search results.
| Name | Required | Description | Default |
|---|---|---|---|
| selections | Yes | List of confirmed product selections, one entry per shopping list item. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations available, the description fully carries the behavioral transparency burden. It discloses that this is an 'ADVANCED/manual commit', explains it computes totals and returns a shareable URL, warns against blindly passing product_ids, and clarifies that not every retailer needs a pick.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-organized into three short paragraphs, each serving a distinct purpose: usage distinction, parameter guidance, and safety warning. Every sentence adds value without 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?
Despite lacking an output schema, the description mentions the return value ('shareable basket URL'), provides prerequisites, explains parameter filling, and warns against misuse. It fully addresses the complexity of a manual commit tool and its relationship to siblings.
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 structure, but the description adds meaningful semantics: 'provide the query string and one product_id per retailer (the best match you found in batch_search results)' and 'omit a retailer if no good match was found.' This goes beyond the schema's structural descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: to commit a basket from pre-chosen product_ids, compute totals, and return a shareable URL. It explicitly distinguishes itself from build_basket, noting that save_basket is for manual commits, not building baskets from lists.
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 basket from a shopping list' and directs users to build_basket for lists of 2+ items. It also states the exact scenario for using save_basket: after choosing product_ids manually, e.g., after overriding a build_basket pick.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search Australian grocery products across Woolworths, Coles, Aldi, and Harris Farm. Returns product name, price, brand, category, unit price, and whether it's on special.
| Name | Required | Description | Default |
|---|---|---|---|
| sort | No | relevance | |
| limit | No | Number of results (1-50, default 20) | |
| query | Yes | Search query (e.g., 'full cream milk', 'chicken breast') | |
| category | No | Filter by category | |
| retailer | No | ||
| on_special | No | If true, only return products on special |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral disclosure burden. It explicitly states the return fields (name, price, brand, category, unit price, special status) and lists the four covered retailers. It does not mention pagination or rate limits, but for a read-only search 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?
The description is two short sentences with no filler. It front-loads the action and directly communicates the returned data, making every word 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?
Given 6 parameters and no output schema, the description covers the core purpose, scope, and return fields. It omits edge cases like pagination or default sort behavior, but those are derivable from the schema or not critical 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%, so the description should partially compensate. It adds context about retailers and specials, aligning with the retailer and on_special params, but does not explain sort or limit 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 'Search Australian grocery products across Woolworths, Coles, Aldi, and Harris Farm' with a clear verb and resource scope. It also lists return fields, distinguishing it from sibling tools like get_product or get_specials.
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 for general product searches across multiple retailers but does not explicitly mention when to use this vs batch_search, compare_prices, or get_cheapest. No alternatives are named.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.
batch_searchbuild_basketcompare_pricesdecompose_productget_cheapestget_price_historyget_productget_specialssave_basketsearch_productsClaiming proves that you control a remote MCP connector. It does not move, proxy, or interrupt the server.
Open the connector listing, choose Claim ownership, and sign in to Glama.
Complete one verification method:
GitHub identity — fastest for official registry listings. For a namespace such as io.github.alice/server, link the matching GitHub user, then choose Claim with GitHub. An organization namespace such as io.github.acme/server also needs that organization to have installed the Glama AI GitHub App and approved its permissions, because GitHub discloses organization membership only to apps it has installed. Use HTTP or DNS when it has not.
HTTP challenge — works when you can deploy a public file. Generate a token, publish the exact JSON Glama shows at /.well-known/glama.json on the same origin as the connector, then choose Check HTTP challenge.
DNS challenge — works when you control DNS but cannot change the server. Generate a token, create the exact TXT record Glama shows, wait for it to propagate, then choose Check DNS challenge.
After verification, Glama sends a confirmation email and gives you access to listing details, thumbnails, health checks, and analytics. Keep the HTTP file or DNS record in place: Glama periodically checks it and ownership remains verified while the token is discoverable.
The HTTP ownership file has this structure:
{
"$schema": "https://glama.ai/mcp/schemas/connector.json",
"claim": "glama_claim_..."
}Claim tokens are opaque, stable, and bound to the signed-in Glama account. They contain no email address or other personal information. If Glama can no longer discover a verified HTTP or DNS token, it starts a seven-day grace period before removing claim-based access. Restore the same token during that period to keep ownership verified. Never publish an email address, Glama session token, GitHub token, or connector credential as ownership proof.
If verification fails, confirm that you copied the current token exactly. The HTTP file must be public, return valid JSON with a successful HTTP response, and stay on the connector's origin. DNS changes may need more time to propagate. A claim cannot transfer to a different origin or hostname: if the connector target changes, Glama starts the grace period and the new target must be claimed separately after the previous claim is released.
For a connector linked to the official MCP Registry, registry updates continue to replace its name, description, and URL by default. After claiming, open Manage connector and enable Use Glama listing details as the source of truth if edits made on Glama should be preserved. Categories and thumbnails are always managed on Glama; registry linkage and technical connection settings continue to sync.
Control your server's listing on Glama, including description and metadata
Access analytics and receive server usage reports
Get monitoring and health status updates for your server
Feature your server to boost visibility and reach more users
To improve your MCP server's ranking:
Claim ownership of the server listing
Complete the server profile with an accurate description and thumbnail
Provide a test profile so Glama can connect to and evaluate the server
Keep tool definitions clear and complete to earn a high Tool Definition Quality Score (TDQS)
Route real usage through the Glama Gateway; more recorded successful server uses also improve the ranking
For users:
Full audit trail – every tool call is logged with inputs and outputs for compliance and debugging
Granular tool control – enable or disable individual tools per connector to limit what your AI agents can do
Centralized credential management – store and rotate API keys and OAuth tokens in one place
Change alerts – get notified when a connector changes its schema, adds or removes tools, or updates tool definitions, so nothing breaks silently
For server owners:
Proven adoption – public usage metrics on your listing show real-world traction and build trust with prospective users
Tool-level analytics – see which tools are being used most, helping you prioritize development and documentation
Direct user feedback – users can report issues and suggest improvements through the listing, giving you a channel you would not have otherwise
The connector status is unhealthy when Glama is unable to successfully connect to the server. This can happen for several reasons:
The server is experiencing an outage
The URL of the server is wrong
Credentials required to access the server are missing or invalid
If you are the owner of this MCP connector and would like to make modifications to the listing, including providing test credentials for accessing the server, please contact support@glama.ai.
No comments yet. Be the first to start the discussion!
Add one secure layer between your agents and this server.
batch_search, search_products, and get_cheapest all provide product search with overlapping output, and build_basket/save_basket both handle basket creation. However, detailed usage notes (mandatory vs. advanced) help clarify, though an agent could still misselect among the search tools.
All tools follow a consistent verb_noun pattern in lowercase_snake_case (e.g., batch_search, compare_prices, get_product), making the API predictable and easy to learn.
10 tools is well within the ideal 3-15 range and appropriately scoped for a grocery price-comparison and basket-building service, covering search, comparison, history, specials, and basket workflows without redundancy.
The tool set covers the full grocery shopping lifecycle: searching products, comparing prices by barcode, viewing price history, checking specials, building baskets, and saving manually curated selections. No obvious gaps for typical user requests.