batch_search
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).
Input Schema
| 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. |