Find products by ingredients, nutrition, quality mark, offers or price
find_productsFind products that meet ingredient, nutrition, alcohol or offer conditions, optionally sorted. For questions like "biscuits without palm oil", "nut-free snacks at Tesco", "vegan chocolate", "cereal with the least sugar", "high protein yoghurt", "bread with the fewest ingredients", "alcohol-free beer", "low salt soup" or "cheapest olive oil at Aldi". Fibre and saturated fat are not recorded. quality_mark finds products by mark (Bord Bia, organic, free range), with or without a query.
A search is for one kind of product: every word of query has to be in a product's name, so several kinds in one query ("lentils chickpeas beans") match nothing. A search on price or offers alone returns short rows: name, pack, shop, shelf, price, offer and unit price (unit_price in the shop's own measure, price_per_kg or price_per_litre the same figure per kilo or per litre). A search with an ingredient, nutrition, additive, origin or strength condition, or sorted on one, returns each product's label as well: nutrition, ingredients, ingredient count, allergy advice and where they came from. detail chooses either for any search.
With no store, results alternate across the stores (each store's best match, then each store's next), and matched_by_store gives each store's full count: the first row is one store's best, and the best of a kind across the stores is among each store's first rows. The counts add up: of_kind, the products that are the kind searched for, is matched + left_out_unknown + left_out_failed_filters + left_out_partly_from_origin + left_out_may_contain, and "N of M" is matched of of_kind.
A product whose ingredient list or nutrition is not on record, or whose ingredient list on record is incomplete, is left out, never assumed to pass: left_out_unknown counts them, left_out_by_reason gives the reasons, and caveats lists known gaps (Aldi's own ingredient lists are often cut short, so an Aldi product is offered as free from something only when its full list comes from the same barcode at Tesco, SuperValu or Dunnes). Claims printed in a product's NAME, such as "gluten free", "lactose free", "alcohol free" or "vegan", are matched through query; exclude_ingredients also checks the ingredients. Alcohol strength is recorded for most SuperValu, Dunnes and Tesco drinks but few at Aldi or Lidl; "alcohol free" and "0.0" in query match drinks named that way.
Answers come from the ingredient lists and nutrition the retailers publish. Where a retailer gives no list, it may come from the same barcode at another retailer or from Open Food Facts (ingredients_source); an Open Food Facts list is never used to show a product is free from something. "Free from" means none of the listed ingredients names it; not every "may contain" warning is covered. Results that show ingredients or nutrition carry a note that this is information only. Each product returned costs one credit. When a search excludes an allergen, every product carries allergy_check. Show that line with every product you mention, word for word.
Tool call template
This tool declares no required parameters. Add optional parameters from the input schema as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {},
"name": "find_products"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Most products to return (default 10, at most 50). | |
| query | No | The kind of product, in the words on its name: 'biscuits', 'dark chocolate', 'olive oil'. One kind a call: every word has to be in the name. A claim printed in the name can be part of it ('gluten free', 'alcohol free', 'vegan', '0.0'), and so can a provenance word ('Irish honey'). Needed unless category is given. | |
| store | No | One shop to look in only that one: aldi, tesco, supervalu, dunnes or lidl. Leave it out for all five. | |
| detail | No | 'short' rows hold name, pack, shop, shelf, price, offer and unit price; 'full' rows hold each product's label as well (nutrition, ingredients, allergy advice). Left out: short for a search on price or offers alone, full for a search with any condition or sort on the label. | |
| origin | No | Country of origin, e.g. 'Ireland' (or 'Irish'); several separated by commas. A product matches only when every country its label states is one asked for: 'Made in Ireland' with 'EU chicken' is not Irish chicken, and is counted in left_out_partly_from_origin. Northern Ireland answers for Ireland (one island, one Bord Bia scheme), not the other way round. Products with no stated origin are counted in left_out_unknown. | |
| max_abv | No | Most alcohol by volume, in percent: 0.5 for alcohol-free drinks. | |
| min_abv | No | Least alcohol by volume, in percent. A drink with no strength on record never passes it, and few Aldi and Lidl drinks have one on record: a search for ordinary wine, beer or spirits with a minimum leaves them all out. | |
| sort_by | No | Sort by this, lowest first: price, unit_price (per kg or litre, to compare pack sizes), sugar, salt, fat, carbs, protein, kcal, abv, ingredients (how many) or additives. Products that are the kind searched for come before name-only matches (name_match_only), so 'chocolate' by price does not lead with chocolate-flavour popcorn. | |
| category | No | An aisle or shelf to narrow by, e.g. 'Breakfast Cereals' or 'Kefir'. A shop with no shelf of that name is searched by product name instead, and caveats names the shops where that happened. | |
| max_kcal | No | Most kilocalories per 100g or 100ml. | |
| on_offer | No | True for only products on promotion or with a member price today (Tesco Clubcard, SuperValu Real Rewards, Lidl Plus). | |
| max_fat_g | No | Most fat, in grams per 100g or 100ml. | |
| descending | No | True for highest first, e.g. most protein. | |
| max_salt_g | No | Most salt, in grams per 100g or 100ml. | |
| max_carbs_g | No | Most carbohydrate, in grams per 100g or 100ml. | |
| max_sugar_g | No | Most sugars, in grams per 100g or 100ml, e.g. 5. | |
| quality_mark | No | Only products on record with this quality mark: 'bord_bia' (Bord Bia Quality Assured), 'organic', 'free_range', 'guaranteed_irish' or 'love_irish_food'. It works with no query at all, listing them (matched_by_store gives each shop's count; a store, category or query narrows it), and with any other condition. The mark's own words are not search words. A mark is on record where the shop's own words about the product say it (its name, label or description), or where it was read off Aldi's or Lidl's photo of the pack. The answer's caveats say how far each mark's record reaches: a product not found here may still carry it. | |
| max_additives | No | At most this many additives in the whole ingredient list, 0 for none: each E-number or additive by name once (preservatives, emulsifiers, raising agents, acidity regulators, thickeners, colours and the like); flavourings, vitamins, minerals and colouring foods are not additives. A list that is cut short or comes from Open Food Facts is left out as unknown, unless what it shows is already too many. | |
| min_protein_g | No | Least protein, in grams per 100g or 100ml. | |
| max_ingredients | No | At most this many listed ingredients, e.g. 5. A compound ingredient's own bracketed list counts as one. | |
| exclude_ingredients | No | Ingredients the product has to be free of, e.g. ['palm oil'], ['nuts', 'sesame'], ['vegan']. These words cover every label term under them: palm oil, nuts (peanuts too), peanuts, gluten, milk (dairy), eggs, soya, sesame, mustard, celery, fish, crustaceans, molluscs, shellfish, sulphites, lupin, gelatine, alcohol, added sugar, sweeteners, pork, meat, vegetarian, vegan. Any other word is matched as written ('coconut'). A product whose allergy advice says it contains or may contain one is left out too (left_out_may_contain). | |
| include_ingredients | No | Ingredients the product has to contain, e.g. ['oats']. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| hint | No | Why nothing was found and what to try, when nothing was | |
| note | No | What the ingredients and nutrition shown are and are not: given whenever a row carries either | |
| as_of | No | Price date, YYYY-MM-DD | |
| caveats | No | Limits of this answer: pass them on | |
| credits | No | What this answer cost the person's BasketWatch account and what is left. Missing on a free answer | |
| matched | No | Products that passed every filter | |
| of_kind | No | Products that are the kind of thing searched for, whatever the filters made of them: matched + left_out_unknown + left_out_failed_filters + left_out_partly_from_origin + left_out_may_contain. Use it for 'N of M': matched of of_kind | |
| products | No | ||
| considered | No | Every product the search looked at: of_kind + left_out_other_kind | |
| left_out_unknown | No | Of the kind, but left out because the ingredients, nutrition or value a filter or sort needs is not on record for them, or the ingredient list is incomplete | |
| matched_by_store | No | How many products passed at each store (more than are returned) | |
| of_kind_by_store | No | of_kind at each store | |
| candidates_capped | No | True when the search words matched more products than one search looks at: every count is then of the best matches only, so say 'at least' | |
| left_out_by_store | No | left_out_unknown at each store | |
| left_out_by_reason | No | Why the left_out_unknown products could not be judged, with counts | |
| left_out_other_kind | No | Products that only mention the search words but are a different kind of product (honey roast ham for 'honey'), left out | |
| left_out_may_contain | No | With ingredients excluded: products whose ingredient list passed but whose allergy advice says they contain or may contain one, left out | |
| left_out_failed_filters | No | Of the kind and judged, but a filter said no: over a limit, an ingredient named, not on offer, or from another country | |
| left_out_partly_from_origin | No | With an origin asked for: products whose label names that country AND another ('Made in Ireland' from 'EU chicken'), left out as not wholly from it | |
| left_out_may_contain_examples | No | A few of those, each with its allergy advice | |
| left_out_partly_from_origin_examples | No | A few of those, each with the origin it states |