Skip to main content
Glama

Search products by name

search_products
Read-onlyIdempotent

Search products by name across one or all Irish supermarkets: each shop's closest matches for the words, for a product that can be named ("kerrygold butter"). Matches on the name only: no ingredient, nutrition or offer filters, and no price sorting.

The answer has total (every match, with total_by_store when all five shops are searched) and as_of, the day the prices are from; when nothing matches, hint says which word no product has. unit_price is in the shop's own measure (unit_basis); price_per_kg or price_per_litre is the same figure per kilo or per litre. A row marked removed has left the shop's online range: its price is its last one, of the day in its scrape_date. Each product returned costs one credit.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "query": "<query>"
    },
    "name": "search_products"
  }
}

Input Schema

NameRequiredDescriptionDefault
limitNoHow many products to return in all; with no shop named they are shared out between the five (default 10, at most 200).
queryYesWords from the product's name, e.g. 'heinz baked beans' or 'kerrygold butter'. Every word has to be in the name, so search one kind of product at a time: 'lentils', not 'lentils chickpeas beans'.
storeNoOne shop to look in only that one: aldi, tesco, supervalu, dunnes or lidl. Leave it out for all five.

Output Schema

NameRequiredDescriptionDefault
hintNoWhy nothing was found and what to try, when nothing was
moreNoTrue when the page is full, so there may be more than limit allowed
as_ofNoThe day these prices were recorded, YYYY-MM-DD: the latest, where the shops differ
queryNo
storeNoThe shop asked for; missing for all five
totalNoHow many products match in all. products holds only the first of them
errorsNoA shop that could not be read, and why
offsetNoHow many rows this page skipped
creditsNoWhat this answer cost the person's BasketWatch account and what is left. Missing on a free answer
productsNo
next_offsetNoThe offset of the next page; missing on the last
total_by_storeNototal at each shop

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed46 schema fields changed
    • addedInput schema / properties / limit / description
      Added value: +"How many products to return in all; with no shop named they are shared out between the five (default 10, at most 200)."
    • addedInput schema / properties / limit / maximum
      Added value: +200
    • addedInput schema / properties / limit / minimum
      Added value: +1
    • removedInput schema / properties / limit / title
      Removed value: -"Limit"
    • addedInput schema / properties / query / description
      Added value: +"Words from the product's name, e.g. 'heinz baked beans' or 'kerrygold butter'. Every word has to be in the name, so search one kind of product at a time: 'lentils', not 'lentils chickpeas beans'."
    • removedInput schema / properties / query / title
      Removed value: -"Query"
    • 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: -"search_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 / Product / properties / available
      Added value: +{
      +  "anyOf": [
      +    {
      +      "type": "integer"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "default": null,
      +  "description": "0 when the shop shows it as out of stock; left out when it is in stock",
      +  "title": "Available"
      +}
    • addedOutput schema / $defs / Product / properties / clubcard_price
      Added value: +{
      +  "anyOf": [
      +    {
      +      "type": "number"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "default": null,
      +  "description": "Member price where one applies: Tesco Clubcard, SuperValu Real Rewards or Lidl Plus",
      +  "title": "Clubcard Price"
      +}
    • addedOutput schema / $defs / Product / properties / first_seen
      Added value: +{
      +  "anyOf": [
      +    {
      +      "type": "string"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "default": null,
      +  "description": "The first day the shop listed it: given for a newly listed product",
      +  "title": "First Seen"
      +}
    • changedOutput schema / $defs / Product / properties / id / description
      Previous value: -"Stable per-retailer product id, e.g. tesco:12345"New value: +"The shop's own product id, e.g. tesco:12345 (an Aldi id has no shop in front): the form a product_ids parameter takes"
    • addedOutput schema / $defs / Product / properties / last_price
      Added value: +{
      +  "anyOf": [
      +    {
      +      "type": "number"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "default": null,
      +  "description": "Its price on that last day",
      +  "title": "Last Price"
      +}
    • addedOutput schema / $defs / Product / properties / last_seen
      Added value: +{
      +  "anyOf": [
      +    {
      +      "type": "string"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "default": null,
      +  "description": "The last day the shop listed it: given for a product that has left its range",
      +  "title": "Last Seen"
      +}
    • changedOutput schema / $defs / Product / properties / name / description
      Previous value: -"Product name as the retailer lists it"New value: +"Product name as the shop lists it"
    • addedOutput schema / $defs / Product / properties / offer_text
      Added value: +{
      +  "anyOf": [
      +    {
      +      "type": "string"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "default": null,
      +  "description": "The offer as the shop words it",
      +  "title": "Offer Text"
      +}
    • addedOutput schema / $defs / Product / properties / pack_size
      Added value: +{
      +  "anyOf": [
      +    {
      +      "type": "string"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "default": null,
      +  "title": "Pack Size"
      +}
    • changedOutput schema / $defs / Product / properties / price / description
      Previous value: -"Shelf price in euro"New value: +"Shelf price in euro: what anyone pays"
    • addedOutput schema / $defs / Product / 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 / Product / 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"
      +}
    • addedOutput schema / $defs / Product / properties / removed
      Added value: +{
      +  "anyOf": [
      +    {
      +      "type": "integer"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "default": null,
      +  "description": "1 when it has left the shop's online range; left out when it is on sale",
      +  "title": "Removed"
      +}
    • changedOutput schema / $defs / Product / properties / scrape_date / description
      Previous value: -"Snapshot date, YYYY-MM-DD"New value: +"The day this row's price was recorded, YYYY-MM-DD: given when it is not the answer's as_of"
    • addedOutput schema / $defs / Product / properties / store
      Added value: +{
      +  "anyOf": [
      +    {
      +      "type": "string"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "default": null,
      +  "description": "aldi, tesco, supervalu, dunnes or lidl",
      +  "title": "Store"
      +}
    • changedOutput schema / $defs / Product / 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'"
    • changedOutput schema / $defs / Product / properties / unit_price / description
      Previous value: -"Price per kg or per litre"New 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 / $defs / Product / properties / url
      Added value: +{
      +  "anyOf": [
      +    {
      +      "type": "string"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "default": null,
      +  "title": "Url"
      +}
    • addedOutput schema / $defs / Product / properties / was_price
      Added value: +{
      +  "anyOf": [
      +    {
      +      "type": "number"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "default": null,
      +  "description": "The price the shop says it was before the offer",
      +  "title": "Was Price"
      +}
    • addedOutput schema / additionalProperties
      Added value: +true
    • addedOutput schema / properties / as_of
      Added value: +{
      +  "anyOf": [
      +    {
      +      "type": "string"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "default": null,
      +  "description": "The day these prices were recorded, YYYY-MM-DD: the latest, where the shops differ",
      +  "title": "As Of"
      +}
    • 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 / errors
      Added value: +{
      +  "additionalProperties": {
      +    "type": "string"
      +  },
      +  "description": "A shop that could not be read, and why",
      +  "title": "Errors",
      +  "type": "object"
      +}
    • 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"
      +}
    • addedOutput schema / properties / more
      Added value: +{
      +  "anyOf": [
      +    {
      +      "type": "boolean"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "default": null,
      +  "description": "True when the page is full, so there may be more than limit allowed",
      +  "title": "More"
      +}
    • addedOutput schema / properties / next_offset
      Added value: +{
      +  "anyOf": [
      +    {
      +      "type": "integer"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "default": null,
      +  "description": "The offset of the next page; missing on the last",
      +  "title": "Next Offset"
      +}
    • addedOutput schema / properties / offset
      Added value: +{
      +  "anyOf": [
      +    {
      +      "type": "integer"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "default": null,
      +  "description": "How many rows this page skipped",
      +  "title": "Offset"
      +}
    • addedOutput schema / properties / products
      Added value: +{
      +  "items": {
      +    "$ref": "#/$defs/Product"
      +  },
      +  "title": "Products",
      +  "type": "array"
      +}
    • addedOutput schema / properties / query
      Added value: +{
      +  "anyOf": [
      +    {
      +      "type": "string"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "default": null,
      +  "title": "Query"
      +}
    • removedOutput schema / properties / result
      Removed value: -{
      -  "items": {
      -    "$ref": "#/$defs/Product"
      -  },
      -  "title": "Result",
      -  "type": "array"
      -}
    • addedOutput schema / properties / store
      Added value: +{
      +  "anyOf": [
      +    {
      +      "type": "string"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "default": null,
      +  "description": "The shop asked for; missing for all five",
      +  "title": "Store"
      +}
    • addedOutput schema / properties / total
      Added value: +{
      +  "anyOf": [
      +    {
      +      "type": "integer"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "default": null,
      +  "description": "How many products match in all. products holds only the first of them",
      +  "title": "Total"
      +}
    • addedOutput schema / properties / total_by_store
      Added value: +{
      +  "additionalProperties": {
      +    "type": "integer"
      +  },
      +  "description": "total at each shop",
      +  "title": "Total By Store",
      +  "type": "object"
      +}
    • removedOutput schema / required
      Removed value: -[
      -  "result"
      -]
    • changedOutput schema / title
      Previous value: -"search_productsOutput"New value: +"ProductList"
  2. Changed1 schema field changed
    • addedOutput schema / $defs / Product / 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"
      +}
  3. First observed

TDQS

A4.6/5.0
Behavior5/5

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

Annotations already declare readOnly, idempotent, openWorld and non-destructive, and the description adds real behavior beyond them: each returned product costs one credit, removed rows carry last-seen prices with a scrape_date, and empty results produce a hint naming the unmatched word. That is substantive operational context an agent cannot get from the annotations.

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

Conciseness4/5

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

Front-loaded with purpose and scope, then a compact paragraph on results and cost; almost every sentence carries information. It is dense and slightly long, but the density is load-bearing rather than filler.

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?

For a three-parameter search tool with an output schema, the definition covers matching rules, credit cost, stale/removed price semantics, and the empty-result hint. Nothing material for correct invocation is missing, and return fields are described without needing to be.

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 baseline is 3; the description nonetheless adds meaning, explaining that limit is shared across the five shops when no store is named and that every query word must appear in the name. This clarifies interaction between the two parameters rather than restating types.

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

Purpose5/5

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

States a specific verb and resource ('Search products by name') and pins the scope: Irish supermarkets, each shop's closest matches, name-only matching. The explicit exclusions ('no ingredient, nutrition or offer filters, and no price sorting') make it distinguishable from filter- or deal-oriented siblings without naming them.

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?

Gives concrete when-to-use guidance ('for a product that can be named') and a usage constraint ('search one kind of product at a time: lentils, not lentils chickpeas beans'), plus when-not-to-use by ruling out ingredient, nutrition, offer filtering and price sorting. It stops short of naming which sibling to use for those excluded cases.

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