BestPrice

Search BestPrice products

search_products

Read-onlyIdempotent

Find physical products sold in Greece by name, model, category, or barcode, and return up to eight grouped matches with catalog prices and BestPrice links.

Instructions

Searches physical products sold in Greece by product name, model, category, or barcode and returns up to eight grouped products with canonical product IDs, catalog prices, relevance warnings, and BestPrice links. Price bounds apply before shipping; feature hints are not independently verified. A valid GTIN with one unambiguous catalog match is supported. Broadened-category results are related products rather than exact matches. Categories containing only ungrouped listings return an empty product list and a category handoff. Catalog minimum prices are indicative, may include filtered offers, and are not buyable quotes. Prohibited, age-restricted, digital, service, and unverified catalog branches are excluded. No checkout or direct merchant links are provided.

Input Schema

Name	Required	Description	Default
`sort`	No	Result order: catalog relevance (default), lowest catalog price first, or highest catalog price first.	relevance
`limit`	No	Maximum number of grouped products to return, from 1 to 8.
`query`	Yes	Product name, model, barcode (GTIN/EAN), or category in Greek or English. A pasted merchant listing title is accepted; the search reduces it to the model it names. Catalog search does not verify requirements based on needs, household size, or suitability.
`locale`	No	Response locale. The current service supports el-GR.	el-GR
`country`	No	Shopping market. The current service supports Greece (GR).	GR
`price_max`	No	Optional maximum product price in EUR, before shipping.
`price_min`	No	Optional minimum product price in EUR, before shipping.
`required_features`	No	Optional relevance hints such as OLED, Wi-Fi, or noise cancellation. They are not independently verified for every result.

Output Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

Changed8 schema fields changedv2.9.0Nov 2, 2026
- removedInput schema / $schema
```
Removed value: -"https://json-schema.org/draft/2020-12/schema"
```
- removedInput schema / properties / country / const
```
Removed value: -"GR"
```
- removedInput schema / properties / locale / const
```
Removed value: -"el-GR"
```
- removedInput schema / properties / price_max / exclusiveMinimum
```
Removed value: -0
```
- addedOutput schema / $defs / __schema10 / properties / model / anyOf
```
Added value: +[
+  {
+    "maxLength": 220,
+    "minLength": 1,
+    "type": "string"
+  },
+  {
+    "type": "null"
+  }
+]
```
- removedOutput schema / $defs / __schema10 / properties / model / maxLength
```
Removed value: -220
```
- removedOutput schema / $defs / __schema10 / properties / model / minLength
```
Removed value: -1
```
- removedOutput schema / $defs / __schema10 / properties / model / type
```
Removed value: -"string"
```

Changed10 schema fields changedv2.8.1Oct 29, 2026

changedInput schema / properties / query / description

Previous value: -"Product name, model, barcode (GTIN/EAN), or category in Greek or English. A pasted merchant listing title is accepted; the search reduces it to the model it names. Use get_shopping_decision with the original request for recommendations based on needs, household size, or suitability; catalog search does not verify those requirements."New value: +"Product name, model, barcode (GTIN/EAN), or category in Greek or English. A pasted merchant listing title is accepted; the search reduces it to the model it names. Catalog search does not verify requirements based on needs, household size, or suitability."

changedInput schema / properties / required_features / description

Previous value: -"Optional relevance hints such as OLED, Wi-Fi, or noise cancellation. They are not independently verified for every result; confirm them on the product page."New value: +"Optional relevance hints such as OLED, Wi-Fi, or noise cancellation. They are not independently verified for every result."

changedInput schema / properties / sort / description

Previous value: -"Result order. Use relevance unless the user explicitly asks for cheapest or most expensive first."New value: +"Result order: catalog relevance (default), lowest catalog price first, or highest catalog price first."

changedOutput schema / $defs / __schema1 / pattern

Previous value: -"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"New value: +"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"

addedOutput schema / $defs / __schema10 / properties / match_relationship

Added value: +{
+  "description": "Deterministic relationship to a requested named model. exact_product covers requested identity tokens and variant qualifiers; it does not certify features. Unknown codes carry no identity assurance. Known values: exact_product, variant, accessory, related_product. New values are added without a tools/list change.",
+  "maxLength": 100,
+  "pattern": "^[a-z][a-z0-9_]*$",
+  "type": "string"
+}

addedOutput schema / $defs / __schema10 / properties / offer_count / anyOf

Added value: +[
+  {
+    "maximum": 9007199254740991,
+    "minimum": 0,
+    "type": "integer"
+  },
+  {
+    "type": "null"
+  }
+]

removedOutput schema / $defs / __schema10 / properties / offer_count / maximum
```
Removed value: -9007199254740991
```
removedOutput schema / $defs / __schema10 / properties / offer_count / minimum
```
Removed value: -0
```
removedOutput schema / $defs / __schema10 / properties / offer_count / type
```
Removed value: -"integer"
```

changedOutput schema / $defs / __schema10 / properties / price_from / description

Previous value: -"Catalog lowest listed item price in EUR before shipping. Same identity as compare_offers.catalog_price_from. Not a buyable quote; it may be a promoted, out-of-stock, or filtered offer that compare_offers omits. Never subtract this from another product compare_offers item_price."New value: +"Catalog lowest listed item price in EUR before shipping. Indicative catalog minimum rather than a buyable quote; it may originate from a promoted, out-of-stock, or filtered offer. It has a different basis from returned offer quotes."

Changed13 schema fields changedv2.8.0Sep 26, 2026

changedInput schema / properties / query / description

Previous value: -"Product name, model, barcode (GTIN/EAN), or category in Greek or English. Use get_shopping_decision with the original request for recommendations based on needs, household size, or suitability; catalog search does not verify those requirements."New value: +"Product name, model, barcode (GTIN/EAN), or category in Greek or English. A pasted merchant listing title is accepted; the search reduces it to the model it names. Use get_shopping_decision with the original request for recommendations based on needs, household size, or suitability; catalog search does not verify those requirements."

changedInput schema / properties / query / maxLength
```
Previous value: -200New value: +400
```
removedOutput schema / $defs / __schema0 / const
```
Removed value: -"2.0"
```

addedOutput schema / $defs / __schema0 / description

Added value: +"Result schema version. Currently 2.0; a later <major>.<minor> is returned without a tools/list change."

addedOutput schema / $defs / __schema0 / pattern
```
Added value: +"^[1-9][0-9]*\\.[0-9]+$"
```
removedOutput schema / $defs / __schema10 / additionalProperties
```
Removed value: -false
```
removedOutput schema / $defs / __schema10 / properties / match_basis / const
```
Removed value: -"catalog_relevance_token_coverage_v1"
```

addedOutput schema / $defs / __schema10 / properties / match_basis / description

Added value: +"Relevance method behind match_confidence. Currently catalog_relevance_token_coverage_v1; a revised method is returned as a new <name>_v<N> id without a tools/list change."

addedOutput schema / $defs / __schema10 / properties / match_basis / maxLength
```
Added value: +100
```
addedOutput schema / $defs / __schema10 / properties / match_basis / pattern
```
Added value: +"^[a-z][a-z0-9_]*_v[1-9][0-9]*$"
```
removedOutput schema / $defs / __schema11 / additionalProperties
```
Removed value: -false
```
removedOutput schema / $defs / __schema12 / additionalProperties
```
Removed value: -false
```

changedOutput schema / anyOf

Previous value: -[
-  {
-    "additionalProperties": false,
-    "properties": {
-      "applied_filters": {
-        "additionalProperties": false,
-        "properties": {
-          "feature_hints": {
-            "items": {
-              "$ref": "#/$defs/__schema8"
-            },
-            "maxItems": 10,
-            "type": "array"
-          },
-          "feature_hints_verified": {
-            "const": false,
-            "type": "boolean"
-          },
-          "price_max": {
-            "$ref": "#/$defs/__schema6"
-          },
-          "price_min": {
-            "$ref": "#/$defs/__schema6"
-          },
-          "sort": {
-            "enum": [
-              "relevance",
-              "price_asc",
-              "price_desc"
-            ],
-            "type": "string"
-          }
-        },
-        "required": [
-          "price_min",
-          "price_max",
-          "sort",
-          "feature_hints",
-          "feature_hints_verified"
-        ],
-        "type": "object"
-      },
-      "as_of": {
-        "$ref": "#/$defs/__schema1"
-      },
-      "category_handoff": {
-        "$ref": "#/$defs/__schema12",
-        "description": "Present only when products is empty because the matched category holds merchant offers but no grouped BestPrice product yet. url is the plain public category page, not a product landing link. These offers are not comparable products: they have no product_id for compare_offers or get_price_history."
-      },
-      "currency": {
-        "$ref": "#/$defs/__schema2"
-      },
-      "interpreted_query": {
-        "maxLength": 400,
-        "minLength": 1,
-        "type": "string"
-      },
-      "locale": {
-        "$ref": "#/$defs/__schema3"
-      },
-      "products": {
-        "description": "Grouped BestPrice products. For a barcode (GTIN) query the text search cannot find, at most the one grouped product that carries exactly that barcode, with a warning saying so; a barcode shared by several products returns none.",
-        "items": {
-          "$ref": "#/$defs/__schema10"
-        },
-        "maxItems": 8,
-        "type": "array"
-      },
-      "requested_query": {
-        "maxLength": 400,
-        "minLength": 1,
-        "type": "string"
-      },
-      "schema_version": {
-        "$ref": "#/$defs/__schema0"
-      },
-      "search_mode": {
-        "enum": [
-          "catalog_ranked",
-          "broadened_category"
-        ],
-        "type": "string"
-      },
-      "suggested_queries": {
-        "items": {
-          "$ref": "#/$defs/__schema9"
-        },
-        "maxItems": 5,
-        "type": "array"
-      },
-      "total_matches": {
-        "description": "Number of products returned after public scope, price, and result limits; not full catalog cardinality.",
-        "maximum": 9007199254740991,
-        "minimum": 0,
-        "type": "integer"
-      },
-      "warnings": {
-        "$ref": "#/$defs/__schema4"
-      }
-    },
-    "required": [
-      "schema_version",
-      "as_of",
-      "currency",
-      "locale",
-      "warnings",
-      "interpreted_query",
-      "total_matches",
-      "products"
-    ],
-    "type": "object"
-  },
-  {
-    "additionalProperties": false,
-    "properties": {
-      "as_of": {
-        "$ref": "#/$defs/__schema1"
-      },
-      "currency": {
-        "$ref": "#/$defs/__schema2"
-      },
-      "error": {
-        "additionalProperties": false,
-        "properties": {
-          "code": {
-            "pattern": "^[A-Z][A-Z0-9_]{2,63}$",
-            "type": "string"
-          },
-          "message": {
-            "maxLength": 240,
-            "minLength": 1,
-            "type": "string"
-          },
-          "retryable": {
-            "type": "boolean"
-          }
-        },
-        "required": [
-          "code",
-          "message",
-          "retryable"
-        ],
-        "type": "object"
-      },
-      "locale": {
-        "$ref": "#/$defs/__schema3"
-      },
-      "schema_version": {
-        "$ref": "#/$defs/__schema0"
-      },
-      "warnings": {
-        "$ref": "#/$defs/__schema4"
-      }
-    },
-    "required": [
-      "schema_version",
-      "as_of",
-      "currency",
-      "locale",
-      "warnings",
-      "error"
-    ],
-    "type": "object"
-  }
-]New value: +[
+  {
+    "properties": {
+      "applied_filters": {
+        "properties": {
+          "feature_hints": {
+            "items": {
+              "$ref": "#/$defs/__schema8"
+            },
+            "maxItems": 10,
+            "type": "array"
+          },
+          "feature_hints_verified": {
+            "const": false,
+            "type": "boolean"
+          },
+          "price_max": {
+            "$ref": "#/$defs/__schema6"
+          },
+          "price_min": {
+            "$ref": "#/$defs/__schema6"
+          },
+          "sort": {
+            "enum": [
+              "relevance",
+              "price_asc",
+              "price_desc"
+            ],
+            "type": "string"
+          }
+        },
+        "required": [
+          "price_min",
+          "price_max",
+          "sort",
+          "feature_hints",
+          "feature_hints_verified"
+        ],
+        "type": "object"
+      },
+      "as_of": {
+        "$ref": "#/$defs/__schema1"
+      },
+      "category_handoff": {
+        "$ref": "#/$defs/__schema12",
+        "description": "Present only when products is empty because the matched category holds merchant offers but no grouped BestPrice product yet. url is the plain public category page, not a product landing link. These offers are not comparable products: they have no product_id for compare_offers or get_price_history."
+      },
+      "currency": {
+        "$ref": "#/$defs/__schema2"
+      },
+      "interpreted_query": {
+        "maxLength": 400,
+        "minLength": 1,
+        "type": "string"
+      },
+      "locale": {
+        "$ref": "#/$defs/__schema3"
+      },
+      "products": {
+        "description": "Grouped BestPrice products. For a barcode (GTIN) query the text search cannot find, at most the one grouped product that carries exactly that barcode, with a warning saying so; a barcode shared by several products returns none.",
+        "items": {
+          "$ref": "#/$defs/__schema10"
+        },
+        "maxItems": 8,
+        "type": "array"
+      },
+      "requested_query": {
+        "maxLength": 400,
+        "minLength": 1,
+        "type": "string"
+      },
+      "schema_version": {
+        "$ref": "#/$defs/__schema0"
+      },
+      "search_mode": {
+        "description": "How the returned catalog page was retrieved. Known values: catalog_ranked, broadened_category. New values are added without a tools/list change.",
+        "maxLength": 100,
+        "pattern": "^[a-z][a-z0-9_]*$",
+        "type": "string"
+      },
+      "suggested_queries": {
+        "items": {
+          "$ref": "#/$defs/__schema9"
+        },
+        "maxItems": 5,
+        "type": "array"
+      },
+      "total_matches": {
+        "description": "Number of products returned after public scope, price, and result limits; not full catalog cardinality.",
+        "maximum": 9007199254740991,
+        "minimum": 0,
+        "type": "integer"
+      },
+      "warnings": {
+        "$ref": "#/$defs/__schema4"
+      }
+    },
+    "required": [
+      "schema_version",
+      "as_of",
+      "currency",
+      "locale",
+      "warnings",
+      "interpreted_query",
+      "total_matches",
+      "products"
+    ],
+    "type": "object"
+  },
+  {
+    "properties": {
+      "as_of": {
+        "$ref": "#/$defs/__schema1"
+      },
+      "currency": {
+        "$ref": "#/$defs/__schema2"
+      },
+      "error": {
+        "properties": {
+          "code": {
+            "pattern": "^[A-Z][A-Z0-9_]{2,63}$",
+            "type": "string"
+          },
+          "message": {
+            "maxLength": 240,
+            "minLength": 1,
+            "type": "string"
+          },
+          "retryable": {
+            "type": "boolean"
+          }
+        },
+        "required": [
+          "code",
+          "message",
+          "retryable"
+        ],
+        "type": "object"
+      },
+      "locale": {
+        "$ref": "#/$defs/__schema3"
+      },
+      "schema_version": {
+        "$ref": "#/$defs/__schema0"
+      },
+      "warnings": {
+        "$ref": "#/$defs/__schema4"
+      }
+    },
+    "required": [
+      "schema_version",
+      "as_of",
+      "currency",
+      "locale",
+      "warnings",
+      "error"
+    ],
+    "type": "object"
+  }
+]

Changed3 schema fields changedv1.2.7Sep 24, 2026

changedInput schema / properties / query / description

Previous value: -"Product name, model, or category in Greek or English. Use get_shopping_decision with the original request for recommendations based on needs, household size, or suitability; catalog search does not verify those requirements."New value: +"Product name, model, barcode (GTIN/EAN), or category in Greek or English. Use get_shopping_decision with the original request for recommendations based on needs, household size, or suitability; catalog search does not verify those requirements."

addedOutput schema / $defs / __schema12

Added value: +{
+  "additionalProperties": false,
+  "properties": {
+    "category_id": {
+      "exclusiveMinimum": 0,
+      "maximum": 9007199254740991,
+      "type": "integer"
+    },
+    "listing_count": {
+      "description": "Ungrouped merchant offers BestPrice showed in this category for the search, within any price bounds.",
+      "exclusiveMinimum": 0,
+      "maximum": 9007199254740991,
+      "type": "integer"
+    },
+    "title": {
+      "maxLength": 100,
+      "minLength": 1,
+      "type": "string"
+    },
+    "url": {
+      "format": "uri",
+      "type": "string"
+    }
+  },
+  "required": [
+    "category_id",
+    "title",
+    "url",
+    "listing_count"
+  ],
+  "type": "object"
+}

changedOutput schema / anyOf

Previous value: -[
-  {
-    "additionalProperties": false,
-    "properties": {
-      "applied_filters": {
-        "additionalProperties": false,
-        "properties": {
-          "feature_hints": {
-            "items": {
-              "$ref": "#/$defs/__schema8"
-            },
-            "maxItems": 10,
-            "type": "array"
-          },
-          "feature_hints_verified": {
-            "const": false,
-            "type": "boolean"
-          },
-          "price_max": {
-            "$ref": "#/$defs/__schema6"
-          },
-          "price_min": {
-            "$ref": "#/$defs/__schema6"
-          },
-          "sort": {
-            "enum": [
-              "relevance",
-              "price_asc",
-              "price_desc"
-            ],
-            "type": "string"
-          }
-        },
-        "required": [
-          "price_min",
-          "price_max",
-          "sort",
-          "feature_hints",
-          "feature_hints_verified"
-        ],
-        "type": "object"
-      },
-      "as_of": {
-        "$ref": "#/$defs/__schema1"
-      },
-      "currency": {
-        "$ref": "#/$defs/__schema2"
-      },
-      "interpreted_query": {
-        "maxLength": 400,
-        "minLength": 1,
-        "type": "string"
-      },
-      "locale": {
-        "$ref": "#/$defs/__schema3"
-      },
-      "products": {
-        "items": {
-          "$ref": "#/$defs/__schema10"
-        },
-        "maxItems": 8,
-        "type": "array"
-      },
-      "requested_query": {
-        "maxLength": 400,
-        "minLength": 1,
-        "type": "string"
-      },
-      "schema_version": {
-        "$ref": "#/$defs/__schema0"
-      },
-      "search_mode": {
-        "enum": [
-          "catalog_ranked",
-          "broadened_category"
-        ],
-        "type": "string"
-      },
-      "suggested_queries": {
-        "items": {
-          "$ref": "#/$defs/__schema9"
-        },
-        "maxItems": 5,
-        "type": "array"
-      },
-      "total_matches": {
-        "description": "Number of products returned after public scope, price, and result limits; not full catalog cardinality.",
-        "maximum": 9007199254740991,
-        "minimum": 0,
-        "type": "integer"
-      },
-      "warnings": {
-        "$ref": "#/$defs/__schema4"
-      }
-    },
-    "required": [
-      "schema_version",
-      "as_of",
-      "currency",
-      "locale",
-      "warnings",
-      "interpreted_query",
-      "total_matches",
-      "products"
-    ],
-    "type": "object"
-  },
-  {
-    "additionalProperties": false,
-    "properties": {
-      "as_of": {
-        "$ref": "#/$defs/__schema1"
-      },
-      "currency": {
-        "$ref": "#/$defs/__schema2"
-      },
-      "error": {
-        "additionalProperties": false,
-        "properties": {
-          "code": {
-            "pattern": "^[A-Z][A-Z0-9_]{2,63}$",
-            "type": "string"
-          },
-          "message": {
-            "maxLength": 240,
-            "minLength": 1,
-            "type": "string"
-          },
-          "retryable": {
-            "type": "boolean"
-          }
-        },
-        "required": [
-          "code",
-          "message",
-          "retryable"
-        ],
-        "type": "object"
-      },
-      "locale": {
-        "$ref": "#/$defs/__schema3"
-      },
-      "schema_version": {
-        "$ref": "#/$defs/__schema0"
-      },
-      "warnings": {
-        "$ref": "#/$defs/__schema4"
-      }
-    },
-    "required": [
-      "schema_version",
-      "as_of",
-      "currency",
-      "locale",
-      "warnings",
-      "error"
-    ],
-    "type": "object"
-  }
-]New value: +[
+  {
+    "additionalProperties": false,
+    "properties": {
+      "applied_filters": {
+        "additionalProperties": false,
+        "properties": {
+          "feature_hints": {
+            "items": {
+              "$ref": "#/$defs/__schema8"
+            },
+            "maxItems": 10,
+            "type": "array"
+          },
+          "feature_hints_verified": {
+            "const": false,
+            "type": "boolean"
+          },
+          "price_max": {
+            "$ref": "#/$defs/__schema6"
+          },
+          "price_min": {
+            "$ref": "#/$defs/__schema6"
+          },
+          "sort": {
+            "enum": [
+              "relevance",
+              "price_asc",
+              "price_desc"
+            ],
+            "type": "string"
+          }
+        },
+        "required": [
+          "price_min",
+          "price_max",
+          "sort",
+          "feature_hints",
+          "feature_hints_verified"
+        ],
+        "type": "object"
+      },
+      "as_of": {
+        "$ref": "#/$defs/__schema1"
+      },
+      "category_handoff": {
+        "$ref": "#/$defs/__schema12",
+        "description": "Present only when products is empty because the matched category holds merchant offers but no grouped BestPrice product yet. url is the plain public category page, not a product landing link. These offers are not comparable products: they have no product_id for compare_offers or get_price_history."
+      },
+      "currency": {
+        "$ref": "#/$defs/__schema2"
+      },
+      "interpreted_query": {
+        "maxLength": 400,
+        "minLength": 1,
+        "type": "string"
+      },
+      "locale": {
+        "$ref": "#/$defs/__schema3"
+      },
+      "products": {
+        "description": "Grouped BestPrice products. For a barcode (GTIN) query the text search cannot find, at most the one grouped product that carries exactly that barcode, with a warning saying so; a barcode shared by several products returns none.",
+        "items": {
+          "$ref": "#/$defs/__schema10"
+        },
+        "maxItems": 8,
+        "type": "array"
+      },
+      "requested_query": {
+        "maxLength": 400,
+        "minLength": 1,
+        "type": "string"
+      },
+      "schema_version": {
+        "$ref": "#/$defs/__schema0"
+      },
+      "search_mode": {
+        "enum": [
+          "catalog_ranked",
+          "broadened_category"
+        ],
+        "type": "string"
+      },
+      "suggested_queries": {
+        "items": {
+          "$ref": "#/$defs/__schema9"
+        },
+        "maxItems": 5,
+        "type": "array"
+      },
+      "total_matches": {
+        "description": "Number of products returned after public scope, price, and result limits; not full catalog cardinality.",
+        "maximum": 9007199254740991,
+        "minimum": 0,
+        "type": "integer"
+      },
+      "warnings": {
+        "$ref": "#/$defs/__schema4"
+      }
+    },
+    "required": [
+      "schema_version",
+      "as_of",
+      "currency",
+      "locale",
+      "warnings",
+      "interpreted_query",
+      "total_matches",
+      "products"
+    ],
+    "type": "object"
+  },
+  {
+    "additionalProperties": false,
+    "properties": {
+      "as_of": {
+        "$ref": "#/$defs/__schema1"
+      },
+      "currency": {
+        "$ref": "#/$defs/__schema2"
+      },
+      "error": {
+        "additionalProperties": false,
+        "properties": {
+          "code": {
+            "pattern": "^[A-Z][A-Z0-9_]{2,63}$",
+            "type": "string"
+          },
+          "message": {
+            "maxLength": 240,
+            "minLength": 1,
+            "type": "string"
+          },
+          "retryable": {
+            "type": "boolean"
+          }
+        },
+        "required": [
+          "code",
+          "message",
+          "retryable"
+        ],
+        "type": "object"
+      },
+      "locale": {
+        "$ref": "#/$defs/__schema3"
+      },
+      "schema_version": {
+        "$ref": "#/$defs/__schema0"
+      },
+      "warnings": {
+        "$ref": "#/$defs/__schema4"
+      }
+    },
+    "required": [
+      "schema_version",
+      "as_of",
+      "currency",
+      "locale",
+      "warnings",
+      "error"
+    ],
+    "type": "object"
+  }
+]

Changed3 schema fields changedv1.2.2Sep 22, 2026

changedInput schema / properties / query / description

Previous value: -"Product name, model, category, or natural-language shopping need. Greek and English are accepted."New value: +"Product name, model, or category in Greek or English. Use get_shopping_decision with the original request for recommendations based on needs, household size, or suitability; catalog search does not verify those requirements."

addedOutput schema / $defs

Added value: +{
+  "__schema0": {
+    "const": "2.0",
+    "type": "string"
+  },
+  "__schema1": {
+    "format": "date-time",
+    "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$",
+    "type": "string"
+  },
+  "__schema10": {
+    "additionalProperties": false,
+    "properties": {
+      "availability": {
+        "enum": [
+          "available",
+          "unavailable",
+          "unknown"
+        ],
+        "type": "string"
+      },
+      "bestprice_url": {
+        "format": "uri",
+        "type": "string"
+      },
+      "brand": {
+        "anyOf": [
+          {
+            "maxLength": 80,
+            "minLength": 1,
+            "type": "string"
+          },
+          {
+            "type": "null"
+          }
+        ]
+      },
+      "category_id": {
+        "anyOf": [
+          {
+            "exclusiveMinimum": 0,
+            "maximum": 9007199254740991,
+            "type": "integer"
+          },
+          {
+            "type": "null"
+          }
+        ]
+      },
+      "category_title": {
+        "anyOf": [
+          {
+            "maxLength": 100,
+            "minLength": 1,
+            "type": "string"
+          },
+          {
+            "type": "null"
+          }
+        ]
+      },
+      "data_timestamp": {
+        "$ref": "#/$defs/__schema1"
+      },
+      "decision_id": {
+        "description": "Signed, anonymous id joining this recommendation to its BestPrice landing and outbound-click telemetry.",
+        "pattern": "^d1\\.[a-f0-9]{32}\\.[A-Za-z0-9_-]{43}$",
+        "type": "string"
+      },
+      "image_url": {
+        "anyOf": [
+          {
+            "format": "uri",
+            "type": "string"
+          },
+          {
+            "type": "null"
+          }
+        ]
+      },
+      "match_basis": {
+        "const": "catalog_relevance_token_coverage_v1",
+        "type": "string"
+      },
+      "match_confidence": {
+        "description": "Deterministic relative relevance hint based on token coverage and rank; not a probability or feature verification.",
+        "maximum": 1,
+        "minimum": 0,
+        "type": "number"
+      },
+      "model": {
+        "maxLength": 220,
+        "minLength": 1,
+        "type": "string"
+      },
+      "offer_count": {
+        "maximum": 9007199254740991,
+        "minimum": 0,
+        "type": "integer"
+      },
+      "price_from": {
+        "$ref": "#/$defs/__schema6",
+        "description": "Catalog lowest listed item price in EUR before shipping. Same identity as compare_offers.catalog_price_from. Not a buyable quote; it may be a promoted, out-of-stock, or filtered offer that compare_offers omits. Never subtract this from another product compare_offers item_price."
+      },
+      "product_id": {
+        "pattern": "^bp_[0-9]{10}$",
+        "type": "string"
+      },
+      "rating": {
+        "anyOf": [
+          {
+            "$ref": "#/$defs/__schema11"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "description": "BestPrice shopper rating for this product: average of count first-party ratings. Null when the product has none."
+      },
+      "title": {
+        "maxLength": 220,
+        "minLength": 1,
+        "type": "string"
+      },
+      "variant": {
+        "anyOf": [
+          {
+            "maxLength": 160,
+            "minLength": 1,
+            "type": "string"
+          },
+          {
+            "type": "null"
+          }
+        ]
+      }
+    },
+    "required": [
+      "product_id",
+      "title",
+      "brand",
+      "model",
+      "variant",
+      "category_id",
+      "category_title",
+      "price_from",
+      "offer_count",
+      "availability",
+      "match_confidence",
+      "match_basis",
+      "rating",
+      "data_timestamp",
+      "decision_id",
+      "bestprice_url",
+      "image_url"
+    ],
+    "type": "object"
+  },
+  "__schema11": {
+    "additionalProperties": false,
+    "properties": {
+      "average": {
+        "maximum": 5,
+        "minimum": 0,
+        "type": "number"
+      },
+      "count": {
+        "exclusiveMinimum": 0,
+        "maximum": 9007199254740991,
+        "type": "integer"
+      }
+    },
+    "required": [
+      "average",
+      "count"
+    ],
+    "type": "object"
+  },
+  "__schema2": {
+    "const": "EUR",
+    "type": "string"
+  },
+  "__schema3": {
+    "const": "el-GR",
+    "type": "string"
+  },
+  "__schema4": {
+    "items": {
+      "$ref": "#/$defs/__schema5"
+    },
+    "maxItems": 20,
+    "type": "array"
+  },
+  "__schema5": {
+    "maxLength": 240,
+    "minLength": 1,
+    "type": "string"
+  },
+  "__schema6": {
+    "anyOf": [
+      {
+        "$ref": "#/$defs/__schema7"
+      },
+      {
+        "type": "null"
+      }
+    ]
+  },
+  "__schema7": {
+    "maximum": 10000000,
+    "minimum": 0,
+    "type": "number"
+  },
+  "__schema8": {
+    "maxLength": 50,
+    "minLength": 1,
+    "type": "string"
+  },
+  "__schema9": {
+    "maxLength": 400,
+    "minLength": 1,
+    "type": "string"
+  }
+}

changedOutput schema / anyOf

Previous value: -[
-  {
-    "additionalProperties": false,
-    "properties": {
-      "applied_filters": {
-        "additionalProperties": false,
-        "properties": {
-          "feature_hints": {
-            "items": {
-              "maxLength": 50,
-              "minLength": 1,
-              "type": "string"
-            },
-            "maxItems": 10,
-            "type": "array"
-          },
-          "feature_hints_verified": {
-            "const": false,
-            "type": "boolean"
-          },
-          "price_max": {
-            "anyOf": [
-              {
-                "maximum": 10000000,
-                "minimum": 0,
-                "type": "number"
-              },
-              {
-                "type": "null"
-              }
-            ]
-          },
-          "price_min": {
-            "anyOf": [
-              {
-                "maximum": 10000000,
-                "minimum": 0,
-                "type": "number"
-              },
-              {
-                "type": "null"
-              }
-            ]
-          },
-          "sort": {
-            "enum": [
-              "relevance",
-              "price_asc",
-              "price_desc"
-            ],
-            "type": "string"
-          }
-        },
-        "required": [
-          "price_min",
-          "price_max",
-          "sort",
-          "feature_hints",
-          "feature_hints_verified"
-        ],
-        "type": "object"
-      },
-      "as_of": {
-        "format": "date-time",
-        "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$",
-        "type": "string"
-      },
-      "currency": {
-        "const": "EUR",
-        "type": "string"
-      },
-      "interpreted_query": {
-        "maxLength": 400,
-        "minLength": 1,
-        "type": "string"
-      },
-      "locale": {
-        "const": "el-GR",
-        "type": "string"
-      },
-      "products": {
-        "items": {
-          "additionalProperties": false,
-          "properties": {
-            "availability": {
-              "enum": [
-                "available",
-                "unavailable",
-                "unknown"
-              ],
-              "type": "string"
-            },
-            "bestprice_url": {
-              "format": "uri",
-              "type": "string"
-            },
-            "brand": {
-              "anyOf": [
-                {
-                  "maxLength": 80,
-                  "minLength": 1,
-                  "type": "string"
-                },
-                {
-                  "type": "null"
-                }
-              ]
-            },
-            "category_id": {
-              "anyOf": [
-                {
-                  "exclusiveMinimum": 0,
-                  "maximum": 9007199254740991,
-                  "type": "integer"
-                },
-                {
-                  "type": "null"
-                }
-              ]
-            },
-            "category_title": {
-              "anyOf": [
-                {
-                  "maxLength": 100,
-                  "minLength": 1,
-                  "type": "string"
-                },
-                {
-                  "type": "null"
-                }
-              ]
-            },
-            "data_timestamp": {
-              "format": "date-time",
-              "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$",
-              "type": "string"
-            },
-            "decision_id": {
-              "description": "Signed, anonymous id joining this recommendation to its BestPrice landing and outbound-click telemetry.",
-              "pattern": "^d1\\.[a-f0-9]{32}\\.[A-Za-z0-9_-]{43}$",
-              "type": "string"
-            },
-            "image_url": {
-              "anyOf": [
-                {
-                  "format": "uri",
-                  "type": "string"
-                },
-                {
-                  "type": "null"
-                }
-              ]
-            },
-            "match_basis": {
-              "const": "catalog_relevance_token_coverage_v1",
-              "type": "string"
-            },
-            "match_confidence": {
-              "description": "Deterministic relative relevance hint based on token coverage and rank; not a probability or feature verification.",
-              "maximum": 1,
-              "minimum": 0,
-              "type": "number"
-            },
-            "model": {
-              "maxLength": 220,
-              "minLength": 1,
-              "type": "string"
-            },
-            "offer_count": {
-              "maximum": 9007199254740991,
-              "minimum": 0,
-              "type": "integer"
-            },
-            "price_from": {
-              "anyOf": [
-                {
-                  "maximum": 10000000,
-                  "minimum": 0,
-                  "type": "number"
-                },
-                {
-                  "type": "null"
-                }
-              ],
-              "description": "Catalog lowest listed item price in EUR before shipping. Same identity as compare_offers.catalog_price_from. Not a buyable quote; it may be a promoted, out-of-stock, or filtered offer that compare_offers omits. Never subtract this from another product compare_offers item_price."
-            },
-            "product_id": {
-              "pattern": "^bp_[0-9]{10}$",
-              "type": "string"
-            },
-            "rating": {
-              "anyOf": [
-                {
-                  "additionalProperties": false,
-                  "properties": {
-                    "average": {
-                      "maximum": 5,
-                      "minimum": 0,
-                      "type": "number"
-                    },
-                    "count": {
-                      "exclusiveMinimum": 0,
-                      "maximum": 9007199254740991,
-                      "type": "integer"
-                    }
-                  },
-                  "required": [
-                    "average",
-                    "count"
-                  ],
-                  "type": "object"
-                },
-                {
-                  "type": "null"
-                }
-              ],
-              "description": "BestPrice shopper rating for this product: average of count first-party ratings. Null when the product has none."
-            },
-            "title": {
-              "maxLength": 220,
-              "minLength": 1,
-              "type": "string"
-            },
-            "variant": {
-              "anyOf": [
-                {
-                  "maxLength": 160,
-                  "minLength": 1,
-                  "type": "string"
-                },
-                {
-                  "type": "null"
-                }
-              ]
-            }
-          },
-          "required": [
-            "product_id",
-            "title",
-            "brand",
-            "model",
-            "variant",
-            "category_id",
-            "category_title",
-            "price_from",
-            "offer_count",
-            "availability",
-            "match_confidence",
-            "match_basis",
-            "rating",
-            "data_timestamp",
-            "decision_id",
-            "bestprice_url",
-            "image_url"
-          ],
-          "type": "object"
-        },
-        "maxItems": 8,
-        "type": "array"
-      },
-      "requested_query": {
-        "maxLength": 400,
-        "minLength": 1,
-        "type": "string"
-      },
-      "schema_version": {
-        "const": "2.0",
-        "type": "string"
-      },
-      "search_mode": {
-        "enum": [
-          "catalog_ranked",
-          "broadened_category"
-        ],
-        "type": "string"
-      },
-      "suggested_queries": {
-        "items": {
-          "maxLength": 400,
-          "minLength": 1,
-          "type": "string"
-        },
-        "maxItems": 5,
-        "type": "array"
-      },
-      "total_matches": {
-        "description": "Number of products returned after public scope, price, and result limits; not full catalog cardinality.",
-        "maximum": 9007199254740991,
-        "minimum": 0,
-        "type": "integer"
-      },
-      "warnings": {
-        "items": {
-          "maxLength": 240,
-          "minLength": 1,
-          "type": "string"
-        },
-        "maxItems": 20,
-        "type": "array"
-      }
-    },
-    "required": [
-      "schema_version",
-      "as_of",
-      "currency",
-      "locale",
-      "warnings",
-      "interpreted_query",
-      "total_matches",
-      "products"
-    ],
-    "type": "object"
-  },
-  {
-    "additionalProperties": false,
-    "properties": {
-      "as_of": {
-        "format": "date-time",
-        "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$",
-        "type": "string"
-      },
-      "currency": {
-        "const": "EUR",
-        "type": "string"
-      },
-      "error": {
-        "additionalProperties": false,
-        "properties": {
-          "code": {
-            "pattern": "^[A-Z][A-Z0-9_]{2,63}$",
-            "type": "string"
-          },
-          "message": {
-            "maxLength": 240,
-            "minLength": 1,
-            "type": "string"
-          },
-          "retryable": {
-            "type": "boolean"
-          }
-        },
-        "required": [
-          "code",
-          "message",
-          "retryable"
-        ],
-        "type": "object"
-      },
-      "locale": {
-        "const": "el-GR",
-        "type": "string"
-      },
-      "schema_version": {
-        "const": "2.0",
-        "type": "string"
-      },
-      "warnings": {
-        "items": {
-          "maxLength": 240,
-          "minLength": 1,
-          "type": "string"
-        },
-        "maxItems": 20,
-        "type": "array"
-      }
-    },
-    "required": [
-      "schema_version",
-      "as_of",
-      "currency",
-      "locale",
-      "warnings",
-      "error"
-    ],
-    "type": "object"
-  }
-]New value: +[
+  {
+    "additionalProperties": false,
+    "properties": {
+      "applied_filters": {
+        "additionalProperties": false,
+        "properties": {
+          "feature_hints": {
+            "items": {
+              "$ref": "#/$defs/__schema8"
+            },
+            "maxItems": 10,
+            "type": "array"
+          },
+          "feature_hints_verified": {
+            "const": false,
+            "type": "boolean"
+          },
+          "price_max": {
+            "$ref": "#/$defs/__schema6"
+          },
+          "price_min": {
+            "$ref": "#/$defs/__schema6"
+          },
+          "sort": {
+            "enum": [
+              "relevance",
+              "price_asc",
+              "price_desc"
+            ],
+            "type": "string"
+          }
+        },
+        "required": [
+          "price_min",
+          "price_max",
+          "sort",
+          "feature_hints",
+          "feature_hints_verified"
+        ],
+        "type": "object"
+      },
+      "as_of": {
+        "$ref": "#/$defs/__schema1"
+      },
+      "currency": {
+        "$ref": "#/$defs/__schema2"
+      },
+      "interpreted_query": {
+        "maxLength": 400,
+        "minLength": 1,
+        "type": "string"
+      },
+      "locale": {
+        "$ref": "#/$defs/__schema3"
+      },
+      "products": {
+        "items": {
+          "$ref": "#/$defs/__schema10"
+        },
+        "maxItems": 8,
+        "type": "array"
+      },
+      "requested_query": {
+        "maxLength": 400,
+        "minLength": 1,
+        "type": "string"
+      },
+      "schema_version": {
+        "$ref": "#/$defs/__schema0"
+      },
+      "search_mode": {
+        "enum": [
+          "catalog_ranked",
+          "broadened_category"
+        ],
+        "type": "string"
+      },
+      "suggested_queries": {
+        "items": {
+          "$ref": "#/$defs/__schema9"
+        },
+        "maxItems": 5,
+        "type": "array"
+      },
+      "total_matches": {
+        "description": "Number of products returned after public scope, price, and result limits; not full catalog cardinality.",
+        "maximum": 9007199254740991,
+        "minimum": 0,
+        "type": "integer"
+      },
+      "warnings": {
+        "$ref": "#/$defs/__schema4"
+      }
+    },
+    "required": [
+      "schema_version",
+      "as_of",
+      "currency",
+      "locale",
+      "warnings",
+      "interpreted_query",
+      "total_matches",
+      "products"
+    ],
+    "type": "object"
+  },
+  {
+    "additionalProperties": false,
+    "properties": {
+      "as_of": {
+        "$ref": "#/$defs/__schema1"
+      },
+      "currency": {
+        "$ref": "#/$defs/__schema2"
+      },
+      "error": {
+        "additionalProperties": false,
+        "properties": {
+          "code": {
+            "pattern": "^[A-Z][A-Z0-9_]{2,63}$",
+            "type": "string"
+          },
+          "message": {
+            "maxLength": 240,
+            "minLength": 1,
+            "type": "string"
+          },
+          "retryable": {
+            "type": "boolean"
+          }
+        },
+        "required": [
+          "code",
+          "message",
+          "retryable"
+        ],
+        "type": "object"
+      },
+      "locale": {
+        "$ref": "#/$defs/__schema3"
+      },
+      "schema_version": {
+        "$ref": "#/$defs/__schema0"
+      },
+      "warnings": {
+        "$ref": "#/$defs/__schema4"
+      }
+    },
+    "required": [
+      "schema_version",
+      "as_of",
+      "currency",
+      "locale",
+      "warnings",
+      "error"
+    ],
+    "type": "object"
+  }
+]

First observedv1.8.0Sep 3, 2026

TDQS

A4/5.0

Behavior5/5

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

Annotations already declare readOnly, idempotent, openWorld, non-destructive, but the description adds substantial context beyond them: price bounds apply before shipping, feature hints are unverified, catalog minimums are indicative and not buyable quotes, prohibited/digital/service branches are excluded, and no checkout links are returned. This is exactly the extra behavioral texture the annotations cannot convey.

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?

The core capability is front-loaded in the first sentence, and the caveats all carry real meaning about result quality and coverage. Still, it is a dense run-on paragraph of caveats that would scan better as structured clauses; a few sentences are near-duplicates of schema text.

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?

With an output schema covering returns, full annotations, and 100% schema coverage, the description supplies the remaining edge cases an agent needs—GTIN handling, broadened categories as related not exact, empty-list handoff behavior, and price caveats. Nothing material is missing for correct invocation.

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

Parameters3/5

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

Schema description coverage is 100%, so the schema already documents sort, limit, price bounds, locale, country, and required_features. The description mostly restates these (price before shipping, feature hints unverified) and adds the GTIN single-match case, so it sits at the baseline where the schema does the heavy lifting.

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 states a specific verb and resource: searches physical products sold in Greece by name, model, category, or barcode, returning up to eight grouped products. Scope is precise. Sibling differentiation is implicit rather than explicit—it never names compare_offers or get_price_history—so it falls short of a 5.

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

Usage Guidelines3/5

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

It conveys supported query forms (name, model, barcode, pasted listing title) and some behavioral conditions, such as broadened categories returning related products and ungrouped-only categories returning an empty list with a handoff. However, it never states when to prefer this tool over compare_offers or get_shopping_decision, leaving the agent to infer routing from sibling names.

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

Deploy Server

Search BestPrice products

Instructions

Input Schema

Output Schema

Schema Changelog

TDQS

Other Tools