Title100/100
Search Products
The title clearly communicates the tool’s action and subject. Keep it concise.
Description98/100
Search Shoppable's product catalog by keyword, brand, or category. Returns a JSON payload with id, name, brand, category, price, salePrice, merchant, image, and a pre-built checkoutUrl for each result. Use the product ID with add_to_cart if you need to refresh the checkout URL later. SEARCH TIPS: the catalog is keyword-matched, so query with concise PRODUCT terms — the core product type plus distinguishing attributes (e.g. "oil-free sunscreen", not "a sunscreen that won't break me out"). Pass price limits via minPrice/maxPrice and a retailer via merchantId rather than putting them in the query text. Drop conversational filler; generic/non-product words (e.g. "good", "professional", "that won't") can surface irrelevant items like books or music whose titles happen to contain those words.
The description explains the capability, when to use it, and what to expect.
Inputs86/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
query
Search query — keywords, product name, brand, or category
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
merchantId
Filter results to a specific merchant MongoDB ID
Clarify units, where to obtain this value, or conventions not already expressed in the schema.
category
Filter by product category (e.g. "moisturizer", "sneakers")
Clear enough to supply this argument.
minPrice
Minimum sale price filter
Clear enough to supply this argument.
maxPrice
Maximum sale price filter
Clear enough to supply this argument.
limit
Number of results to return (max 50)
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
offset
Pagination offset
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
dedupe
Collapse size/style variants so each distinct product appears once (default true)
Clear enough to supply this argument.
sessionId
Shopping session id. OMIT on the first search; the response returns a sessionId — pass that SAME sessionId on every later search AND into add_to_cart / add_multiple_to_cart, so the shopper's searches and cart stay linked (this powers personalized recommendations on the checkout page).
Clear enough to supply this argument.
Annotations75/100
Declare idempotentHint based on the tool’s actual behavior.
{
"title": "Search Products",
"readOnlyHint": true,
"openWorldHint": true,
"destructiveHint": false
}Output schema87/100
The output schema explains the structured result.
View output schema
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"total",
"offset",
"count",
"results"
],
"properties": {
"count": {
"type": "number",
"description": "Number of products returned in this page"
},
"total": {
"type": "number",
"description": "Total products matching the query across all pages"
},
"offset": {
"type": "number",
"description": "Pagination offset of this page"
},
"results": {
"type": "array",
"items": {
"type": "object",
"required": [
"id"
],
"properties": {
"id": {
"type": "string",
"description": "Stable product id; pass to find_similar, or use a variation UPC with add_to_cart"
},
"name": {
"type": "string",
"description": "Product display name"
},
"size": {
"type": "string",
"description": "Size of this specific item, if applicable"
},
"brand": {
"type": "string",
"description": "Brand name"
},
"color": {
"type": "string",
"description": "Color of this specific item, if applicable"
},
"image": {
"type": "string",
"description": "Proxied product image URL"
},
"price": {
"type": "number",
"description": "List price"
},
"category": {
"type": "string",
"description": "Product category"
},
"merchant": {
"type": "string",
"description": "Selling merchant name"
},
"salePrice": {
"type": "number",
"description": "Current sale price, if discounted"
},
"variations": {
"type": "array",
"items": {
"type": "object",
"required": [
"upc"
],
"properties": {
"upc": {
"type": "string",
"description": "UPC to pass to add_to_cart for this variant"
},
"size": {
"type": "string"
},
"color": {
"type": "string"
},
"image": {
"type": "string"
}
},
"additionalProperties": false
},
"description": "Size/color variants of this product; each carries the UPC to add to cart"
},
"checkoutUrl": {
"type": "string",
"description": "Pre-built checkout URL for this product"
},
"description": {
"type": "string",
"description": "Short product description"
}
},
"additionalProperties": false
},
"description": "Matching products, best match first"
},
"sessionId": {
"type": "string",
"description": "Shopping session id — pass into later searches and add_to_cart to keep the shopper's activity linked"
},
"truncated": {
"type": "boolean",
"description": "True if results were trimmed to fit the tool-result size limit"
}
},
"additionalProperties": false
}