Skip to main content
Glama

Find products by ingredients, nutrition, quality mark, offers or price

find_products
Read-onlyIdempotent

Find 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

NameRequiredDescriptionDefault
limitNoMost products to return (default 10, at most 50).
queryNoThe 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.
storeNoOne shop to look in only that one: aldi, tesco, supervalu, dunnes or lidl. Leave it out for all five.
detailNo'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.
originNoCountry 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_abvNoMost alcohol by volume, in percent: 0.5 for alcohol-free drinks.
min_abvNoLeast 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_byNoSort 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.
categoryNoAn 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_kcalNoMost kilocalories per 100g or 100ml.
on_offerNoTrue for only products on promotion or with a member price today (Tesco Clubcard, SuperValu Real Rewards, Lidl Plus).
max_fat_gNoMost fat, in grams per 100g or 100ml.
descendingNoTrue for highest first, e.g. most protein.
max_salt_gNoMost salt, in grams per 100g or 100ml.
max_carbs_gNoMost carbohydrate, in grams per 100g or 100ml.
max_sugar_gNoMost sugars, in grams per 100g or 100ml, e.g. 5.
quality_markNoOnly 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_additivesNoAt 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_gNoLeast protein, in grams per 100g or 100ml.
max_ingredientsNoAt most this many listed ingredients, e.g. 5. A compound ingredient's own bracketed list counts as one.
exclude_ingredientsNoIngredients 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_ingredientsNoIngredients the product has to contain, e.g. ['oats'].

Output Schema

NameRequiredDescriptionDefault
hintNoWhy nothing was found and what to try, when nothing was
noteNoWhat the ingredients and nutrition shown are and are not: given whenever a row carries either
as_ofNoPrice date, YYYY-MM-DD
caveatsNoLimits of this answer: pass them on
creditsNoWhat this answer cost the person's BasketWatch account and what is left. Missing on a free answer
matchedNoProducts that passed every filter
of_kindNoProducts 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
productsNo
consideredNoEvery product the search looked at: of_kind + left_out_other_kind
left_out_unknownNoOf 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_storeNoHow many products passed at each store (more than are returned)
of_kind_by_storeNoof_kind at each store
candidates_cappedNoTrue 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_storeNoleft_out_unknown at each store
left_out_by_reasonNoWhy the left_out_unknown products could not be judged, with counts
left_out_other_kindNoProducts that only mention the search words but are a different kind of product (honey roast ham for 'honey'), left out
left_out_may_containNoWith ingredients excluded: products whose ingredient list passed but whose allergy advice says they contain or may contain one, left out
left_out_failed_filtersNoOf 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_originNoWith 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_examplesNoA few of those, each with its allergy advice
left_out_partly_from_origin_examplesNoA few of those, each with the origin it states

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed3 schema fields changed
    • changedInput schema / properties / quality_mark / anyOf
      Previous value: -[
      -  {
      -    "const": "bord_bia",
      -    "type": "string"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]New value: +[
      +  {
      +    "enum": [
      +      "bord_bia",
      +      "organic",
      +      "free_range",
      +      "guaranteed_irish",
      +      "love_irish_food"
      +    ],
      +    "type": "string"
      +  },
      +  {
      +    "type": "null"
      +  }
      +]
    • changedInput schema / properties / quality_mark / description
      Previous value: -"Only products that carry this quality mark on record: 'bord_bia' for Bord Bia Quality Assured. 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. The mark is on record where it was read off Aldi's or Lidl's photo of the pack, or where the label's origin statement names it (Tesco's labels, and the same barcode at another shop). Dunnes and SuperValu publish no such mark online, so few of their products are found: a product not found here may still carry it."New value: +"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."
    • changedOutput schema / $defs / FoundProduct / properties / quality_marks / description
      Previous value: -"Quality marks on record for the product, e.g. 'Bord Bia Quality Assured': read off the shop's photo of the pack, or named in the label's origin statement; missing where none is on record, which does not say the pack has none"New value: +"Quality marks on record for the product, e.g. 'Bord Bia Quality Assured' or 'Organic': read off the shop's photo of the pack, or said in the shop's own words about the product; missing where none is on record, which does not say the pack has none"
  2. Changed2 schema fields changed
    • addedInput schema / properties / quality_mark
      Added value: +{
      +  "anyOf": [
      +    {
      +      "const": "bord_bia",
      +      "type": "string"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "default": null,
      +  "description": "Only products that carry this quality mark on record: 'bord_bia' for Bord Bia Quality Assured. 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. The mark is on record where it was read off Aldi's or Lidl's photo of the pack, or where the label's origin statement names it (Tesco's labels, and the same barcode at another shop). Dunnes and SuperValu publish no such mark online, so few of their products are found: a product not found here may still carry it."
      +}
    • addedOutput schema / $defs / FoundProduct / properties / quality_marks
      Added value: +{
      +  "anyOf": [
      +    {
      +      "items": {
      +        "type": "string"
      +      },
      +      "type": "array"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "default": null,
      +  "description": "Quality marks on record for the product, e.g. 'Bord Bia Quality Assured': read off the shop's photo of the pack, or named in the label's origin statement; missing where none is on record, which does not say the pack has none",
      +  "title": "Quality Marks"
      +}
  3. Changed66 schema fields changed
    • addedInput schema / properties / category / description
      Added value: +"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."
    • removedInput schema / properties / category / title
      Removed value: -"Category"
    • addedInput schema / properties / descending / description
      Added value: +"True for highest first, e.g. most protein."
    • removedInput schema / properties / descending / title
      Removed value: -"Descending"
    • addedInput schema / properties / detail
      Added value: +{
      +  "anyOf": [
      +    {
      +      "enum": [
      +        "short",
      +        "full"
      +      ],
      +      "type": "string"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "default": null,
      +  "description": "'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."
      +}
    • addedInput schema / properties / exclude_ingredients / description
      Added value: +"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)."
    • removedInput schema / properties / exclude_ingredients / title
      Removed value: -"Exclude Ingredients"
    • addedInput schema / properties / include_ingredients / description
      Added value: +"Ingredients the product has to contain, e.g. ['oats']."
    • removedInput schema / properties / include_ingredients / title
      Removed value: -"Include Ingredients"
    • addedInput schema / properties / limit / description
      Added value: +"Most products to return (default 10, at most 50)."
    • addedInput schema / properties / limit / maximum
      Added value: +50
    • addedInput schema / properties / limit / minimum
      Added value: +1
    • removedInput schema / properties / limit / title
      Removed value: -"Limit"
    • addedInput schema / properties / max_abv / description
      Added value: +"Most alcohol by volume, in percent: 0.5 for alcohol-free drinks."
    • removedInput schema / properties / max_abv / title
      Removed value: -"Max Abv"
    • addedInput schema / properties / max_additives / description
      Added value: +"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."
    • removedInput schema / properties / max_additives / title
      Removed value: -"Max Additives"
    • addedInput schema / properties / max_carbs_g / description
      Added value: +"Most carbohydrate, in grams per 100g or 100ml."
    • removedInput schema / properties / max_carbs_g / title
      Removed value: -"Max Carbs G"
    • addedInput schema / properties / max_fat_g / description
      Added value: +"Most fat, in grams per 100g or 100ml."
    • removedInput schema / properties / max_fat_g / title
      Removed value: -"Max Fat G"
    • addedInput schema / properties / max_ingredients / description
      Added value: +"At most this many listed ingredients, e.g. 5. A compound ingredient's own bracketed list counts as one."
    • removedInput schema / properties / max_ingredients / title
      Removed value: -"Max Ingredients"
    • addedInput schema / properties / max_kcal / description
      Added value: +"Most kilocalories per 100g or 100ml."
    • removedInput schema / properties / max_kcal / title
      Removed value: -"Max Kcal"
    • addedInput schema / properties / max_salt_g / description
      Added value: +"Most salt, in grams per 100g or 100ml."
    • removedInput schema / properties / max_salt_g / title
      Removed value: -"Max Salt G"
    • addedInput schema / properties / max_sugar_g / description
      Added value: +"Most sugars, in grams per 100g or 100ml, e.g. 5."
    • removedInput schema / properties / max_sugar_g / title
      Removed value: -"Max Sugar G"
    • addedInput schema / properties / min_abv / description
      Added value: +"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."
    • removedInput schema / properties / min_abv / title
      Removed value: -"Min Abv"
    • addedInput schema / properties / min_protein_g / description
      Added value: +"Least protein, in grams per 100g or 100ml."
    • removedInput schema / properties / min_protein_g / title
      Removed value: -"Min Protein G"
    • addedInput schema / properties / on_offer / description
      Added value: +"True for only products on promotion or with a member price today (Tesco Clubcard, SuperValu Real Rewards, Lidl Plus)."
    • removedInput schema / properties / on_offer / title
      Removed value: -"On Offer"
    • addedInput schema / properties / origin / description
      Added value: +"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."
    • removedInput schema / properties / origin / title
      Removed value: -"Origin"
    • addedInput schema / properties / query / description
      Added value: +"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."
    • removedInput schema / properties / query / title
      Removed value: -"Query"
    • changedInput schema / properties / sort_by / anyOf
      Previous value: -[
      -  {
      -    "type": "string"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]New value: +[
      +  {
      +    "enum": [
      +      "price",
      +      "unit_price",
      +      "sugar",
      +      "salt",
      +      "fat",
      +      "carbs",
      +      "protein",
      +      "kcal",
      +      "abv",
      +      "ingredients",
      +      "additives"
      +    ],
      +    "type": "string"
      +  },
      +  {
      +    "type": "null"
      +  }
      +]
    • addedInput schema / properties / sort_by / description
      Added value: +"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."
    • removedInput schema / properties / sort_by / title
      Removed value: -"Sort By"
    • changedInput schema / properties / store / anyOf
      Previous value: -[
      -  {
      -    "type": "string"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]New value: +[
      +  {
      +    "enum": [
      +      "aldi",
      +      "tesco",
      +      "supervalu",
      +      "dunnes",
      +      "lidl"
      +    ],
      +    "type": "string"
      +  },
      +  {
      +    "type": "null"
      +  }
      +]
    • addedInput schema / properties / store / description
      Added value: +"One shop to look in only that one: aldi, tesco, supervalu, dunnes or lidl. Leave it out for all five."
    • removedInput schema / properties / store / title
      Removed value: -"Store"
    • removedInput schema / title
      Removed value: -"find_productsArguments"
    • addedOutput schema / $defs / Credits
      Added value: +{
      +  "additionalProperties": true,
      +  "properties": {
      +    "left": {
      +      "anyOf": [
      +        {
      +          "type": "integer"
      +        },
      +        {
      +          "type": "null"
      +        }
      +      ],
      +      "default": null,
      +      "description": "Credits left on the account after it",
      +      "title": "Left"
      +    },
      +    "note": {
      +      "anyOf": [
      +        {
      +          "type": "string"
      +        },
      +        {
      +          "type": "null"
      +        }
      +      ],
      +      "default": null,
      +      "description": "Said when the balance is low, or when it cut this answer short",
      +      "title": "Note"
      +    },
      +    "used": {
      +      "description": "Credits this answer cost: one for each record it returned",
      +      "title": "Used",
      +      "type": "integer"
      +    }
      +  },
      +  "required": [
      +    "used"
      +  ],
      +  "title": "Credits",
      +  "type": "object"
      +}
    • addedOutput schema / $defs / FoundProduct / properties / price_per_kg
      Added value: +{
      +  "anyOf": [
      +    {
      +      "type": "number"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "default": null,
      +  "description": "unit_price worked out per kilo, where the shop prices the product by weight: the figure to compare packs of different sizes on (per kilo drained, where unit_basis says drained weight)",
      +  "title": "Price Per Kg"
      +}
    • addedOutput schema / $defs / FoundProduct / properties / price_per_litre
      Added value: +{
      +  "anyOf": [
      +    {
      +      "type": "number"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "default": null,
      +  "description": "unit_price worked out per litre, where the shop prices the product by volume",
      +  "title": "Price Per Litre"
      +}
    • changedOutput schema / $defs / FoundProduct / properties / unit_basis / description
      Previous value: -"The unit unit_price is measured in"New value: +"The measure unit_price is in, as the shop states it: '1 KG', '100g', '75cl', 'each'"
    • addedOutput schema / $defs / FoundProduct / properties / unit_price / description
      Added value: +"The shop's own unit price, in the measure unit_basis names: per kg at one shop, per 100g or per 75cl at another, so as it stands it does not compare across rows"
    • addedOutput schema / properties / candidates_capped
      Added value: +{
      +  "anyOf": [
      +    {
      +      "type": "boolean"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "default": null,
      +  "description": "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'",
      +  "title": "Candidates Capped"
      +}
    • changedOutput schema / properties / considered / description
      Previous value: -"Products the search looked at"New value: +"Every product the search looked at: of_kind + left_out_other_kind"
    • addedOutput schema / properties / credits
      Added value: +{
      +  "anyOf": [
      +    {
      +      "$ref": "#/$defs/Credits"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "default": null,
      +  "description": "What this answer cost the person's BasketWatch account and what is left. Missing on a free answer"
      +}
    • addedOutput schema / properties / hint
      Added value: +{
      +  "anyOf": [
      +    {
      +      "type": "string"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "default": null,
      +  "description": "Why nothing was found and what to try, when nothing was",
      +  "title": "Hint"
      +}
    • changedOutput schema / properties / left_out_by_reason / description
      Previous value: -"Why products were left out, with counts"New value: +"Why the left_out_unknown products could not be judged, with counts"
    • addedOutput schema / properties / left_out_by_store / description
      Added value: +"left_out_unknown at each store"
    • addedOutput schema / properties / left_out_failed_filters
      Added value: +{
      +  "anyOf": [
      +    {
      +      "type": "integer"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "default": null,
      +  "description": "Of the kind and judged, but a filter said no: over a limit, an ingredient named, not on offer, or from another country",
      +  "title": "Left Out Failed Filters"
      +}
    • changedOutput schema / properties / left_out_unknown / description
      Previous value: -"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"New value: +"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"
    • addedOutput schema / properties / note / anyOf
      Added value: +[
      +  {
      +    "type": "string"
      +  },
      +  {
      +    "type": "null"
      +  }
      +]
    • addedOutput schema / properties / note / default
      Added value: +null
    • addedOutput schema / properties / note / description
      Added value: +"What the ingredients and nutrition shown are and are not: given whenever a row carries either"
    • removedOutput schema / properties / note / type
      Removed value: -"string"
    • addedOutput schema / properties / of_kind
      Added value: +{
      +  "anyOf": [
      +    {
      +      "type": "integer"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "default": null,
      +  "description": "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",
      +  "title": "Of Kind"
      +}
    • addedOutput schema / properties / of_kind_by_store
      Added value: +{
      +  "additionalProperties": {
      +    "type": "integer"
      +  },
      +  "description": "of_kind at each store",
      +  "title": "Of Kind By Store",
      +  "type": "object"
      +}
    • removedOutput schema / required
      Removed value: -[
      -  "note"
      -]
  4. Changed2 schema fields changed
    • addedInput schema / properties / max_additives
      Added value: +{
      +  "anyOf": [
      +    {
      +      "type": "integer"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "default": null,
      +  "title": "Max Additives"
      +}
    • addedOutput schema / $defs / FoundProduct / properties / additive_count
      Added value: +{
      +  "anyOf": [
      +    {
      +      "type": "integer"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "default": null,
      +  "description": "How many additives the whole ingredient list names (each E-number or additive by name once; flavourings, vitamins, minerals and colouring foods are not counted), given when the search sorted or filtered on additives",
      +  "title": "Additive Count"
      +}
  5. Changed1 schema field changed
    • addedOutput schema / $defs / FoundProduct / properties / offer_ends
      Added value: +{
      +  "anyOf": [
      +    {
      +      "type": "string"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "default": null,
      +  "description": "Last day the offer applies, YYYY-MM-DD, Irish time, where the retailer states it",
      +  "title": "Offer Ends"
      +}
  6. Changed1 schema field changed
    • addedOutput schema / $defs / FoundProduct / properties / ingredients_source
      Added value: +{
      +  "anyOf": [
      +    {
      +      "type": "string"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "default": null,
      +  "description": "Where the ingredient list came from: the retailer, the same product (same barcode) at another retailer, or Open Food Facts",
      +  "title": "Ingredients Source"
      +}
  7. Changed1 schema field changed
    • changedOutput schema / $defs / FoundProduct / properties / clubcard_price / description
      Previous value: -"Tesco Clubcard price, Tesco only"New value: +"Member price where one applies: Tesco Clubcard, SuperValu Real Rewards or Lidl Plus"
  8. Changed1 schema field changed
    • addedOutput schema / $defs / FoundProduct / properties / shelf_path
      Added value: +{
      +  "anyOf": [
      +    {
      +      "type": "string"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "default": null,
      +  "description": "Where the retailer shelves it, every level, e.g. 'Fresh Food > Yoghurts > Kefir > Kefir Drinks'",
      +  "title": "Shelf Path"
      +}
  9. Changed1 schema field changed
    • addedOutput schema / $defs / FoundProduct / properties / alcohol_abv_source
      Added value: +{
      +  "anyOf": [
      +    {
      +      "type": "string"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "default": null,
      +  "description": "Where the strength came from: the retailer's own listing, worked out from its alcohol units per bottle or can, or the same barcode at another store",
      +  "title": "Alcohol Abv Source"
      +}
  10. Changed4 schema fields changed
    • addedOutput schema / $defs / FoundProduct / properties / allergy_advice
      Added value: +{
      +  "anyOf": [
      +    {
      +      "type": "string"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "default": null,
      +  "description": "The retailer's allergy advice: what the product contains and may contain, e.g. 'May contain: Nuts.'",
      +  "title": "Allergy Advice"
      +}
    • changedOutput schema / $defs / FoundProduct / properties / origin / description
      Previous value: -"Country of origin as stated, e.g. 'Ireland'"New value: +"Every country the label states, e.g. 'Ireland' or 'Ireland, EU, non-EU'"
    • addedOutput schema / properties / left_out_may_contain
      Added value: +{
      +  "anyOf": [
      +    {
      +      "type": "integer"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "default": null,
      +  "description": "With ingredients excluded: products whose ingredient list passed but whose allergy advice says they contain or may contain one, left out",
      +  "title": "Left Out May Contain"
      +}
    • addedOutput schema / properties / left_out_may_contain_examples
      Added value: +{
      +  "description": "A few of those, each with its allergy advice",
      +  "items": {
      +    "type": "string"
      +  },
      +  "title": "Left Out May Contain Examples",
      +  "type": "array"
      +}
  11. Changed6 schema fields changed
    • addedInput schema / properties / origin
      Added value: +{
      +  "anyOf": [
      +    {
      +      "type": "string"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "default": null,
      +  "title": "Origin"
      +}
    • addedOutput schema / $defs / FoundProduct / properties / origin
      Added value: +{
      +  "anyOf": [
      +    {
      +      "type": "string"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "default": null,
      +  "description": "Country of origin as stated, e.g. 'Ireland'",
      +  "title": "Origin"
      +}
    • addedOutput schema / $defs / FoundProduct / properties / origin_source
      Added value: +{
      +  "anyOf": [
      +    {
      +      "type": "string"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "default": null,
      +  "description": "Where the origin came from",
      +  "title": "Origin Source"
      +}
    • addedOutput schema / properties / left_out_other_kind
      Added value: +{
      +  "anyOf": [
      +    {
      +      "type": "integer"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "default": null,
      +  "description": "Products that only mention the search words but are a different kind of product (honey roast ham for 'honey'), left out",
      +  "title": "Left Out Other Kind"
      +}
    • addedOutput schema / properties / left_out_partly_from_origin
      Added value: +{
      +  "anyOf": [
      +    {
      +      "type": "integer"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "default": null,
      +  "description": "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",
      +  "title": "Left Out Partly From Origin"
      +}
    • addedOutput schema / properties / left_out_partly_from_origin_examples
      Added value: +{
      +  "description": "A few of those, each with the origin it states",
      +  "items": {
      +    "type": "string"
      +  },
      +  "title": "Left Out Partly From Origin Examples",
      +  "type": "array"
      +}
  12. First observed

TDQS

A4.2/5.0
Behavior5/5

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

Beyond the annotations (read-only, open-world, idempotent, non-destructive), the description discloses a great deal: each product costs one credit, results with nutrition carry an information-only note, excluded-allergen searches add allergy_check, and unknown or incomplete ingredient data is left out and counted in left_out_unknown. It also explains data sourcing from Open Food Facts and cross-retailer barcode matching, which is rich 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.

Conciseness3/5

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

The description is front-loaded with a clear purpose sentence and useful examples, but quickly becomes a dense wall of text with long sentences covering many edge cases. Most sentences earn their place, yet the overall length and lack of structure make it harder to scan than necessary for a tool whose schema already documents parameters thoroughly.

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

Completeness5/5

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

Given a 22-parameter tool with an output schema and full annotation coverage, the description is complete: it explains data quality caveats, credit cost, allergy_check inclusion, free-from semantics, and the meaning of left_out counts. An agent has enough context to invoke it correctly and interpret its output limitations.

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

Parameters4/5

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

Schema coverage is 100%, so the schema already defines all 22 parameters. The description still adds meaning beyond it: store alternation behaviour when no store is given, the fact that a price-only search returns short rows and why, how descending interacts with sort_by, and quality_mark's reach limitations via caveats. Some parameter content duplicates the schema, keeping it from a 5.

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

Purpose4/5

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

The first sentence gives a specific verb and resource: 'Find products that meet ingredient, nutrition, alcohol or offer conditions, optionally sorted,' followed by concrete example queries. It does not explicitly distinguish itself from sibling tools like search_products, so it stops short of the top score.

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

Usage Guidelines4/5

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

The description gives extensive when-to-use context through examples ('biscuits without palm oil', 'cheapest olive oil at Aldi') and constraints ('A search is for one kind of product'). It explains that quality_mark works with no query and that detail chooses row shape, but it never names an alternative sibling tool or states when not to use this one.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources