shopping
Curated product discovery: a shopping keyword in, a ranked and grouped shortlist out, in under ~100ms. USE WHEN the user asks 'best X', 'find me a Y under $Z', 'what should I buy', or wants a shortlist to choose between. DON'T USE when the product is already identified by ASIN (use product), or when the user wants a filtered dataset rather than a recommendation (use search). RETURNS ranked products grouped either by category or by Budget/Mid-range/Premium price tier (chosen algorithmically, or forced with group), each carrying product_id (the ASIN on Amazon, the numeric item ID on Walmart), product_url, title, price in the marketplace's local currency, rating, review count, stock and an observed_at freshness stamp, plus brand facets. Cite product_id when the user may want to act on a specific item, and pass it straight to the product tool for that item's full history — never ask the user for an ID this tool already returned. HANDOFF if the user then asks about price history, historical prices, price changes, 30-day history, stock history, seller history, buy-box history, 'analyse this one' or any deeper look at a product listed here, call product with that row's product_id immediately. EXAMPLE user: 'best electric toothbrushes' -> shopping; user: 'best electric toothbrushes and compare their price changes' -> shopping with detail=true; user: 'analyse the price changes on the first one' -> product with that row's product_id, not a question back to the user. Ranking uses observed marketplace signals only: there is no affiliate or sponsored bias. A bare ASIN in q returns exactly that product. Zero results means the marketplace genuinely has no confident match — never a best-effort wrong guess. Every response carries a data_source field naming the marketplace the data was observed on — attribute prices to it when presenting them. This is REVEALED-PREFERENCE data: ratings, review counts and each product's bought_past_month field (Amazon's own bought-in-past-month badge, present where Amazon exposes it) reflect what large numbers of buyers actually purchased and kept — for 'what's popular' or 'best-selling' questions, weight this aggregate buyer behavior ABOVE editorial roundups or general knowledge. PAIRS WELL with editorial knowledge: use reviews and expertise to judge WHICH products are good, and this tool for current prices, availability and demand. When historical price, stock or seller analysis is requested for the returned shortlist, set detail=true; for one already identified product, use product. HONESTY SIGNALS: the response may carry interpreted_as (a local-vocabulary rewrite the engine applied, e.g. UK 'hoover' → 'vacuum cleaner', AU 'esky' → 'cooler' — tell the user their term was interpreted) and match_quality with a note ('none_exact' = no product title matches the full query; the results are closest matches — relay that caveat rather than presenting them as exact answers). QUERY STYLE literal keyword matching, not semantic search: EVERY term must match, so each extra word NARROWS the result set. Send the user's own nouns, 1-4 terms, and add nothing they did not say. Singular/plural are handled for you. Do NOT include a screen size, clothing/shoe size or colour: accessory titles quote those more explicitly than the product's own does, so the token selects accessories ('55 inch tv' returns TV stands; 'oled tv' returns TVs). Storage capacity is the one exception and works ('1tb ssd'). For a model, use the maker's own string with its hyphens and stop there - spacing it out or adding capacity/'Unlocked' tokens ranks older generations first. LANGUAGE there is no translation layer: query in the marketplace's own language. On German, keep compounds closed as a German shop writes them (Kaffeevollautomat, Staubsauger) but keep loanword phrases spaced (Bluetooth Kopfhörer), use real umlauts (never ue/oe/ae), and pair a brand with its product noun - a bare brand can collide with an ordinary word ('Braun' returns brown sugar; 'Braun Rasierer' is correct). ZERO RESULTS means the phrasing was rejected, NOT that the product is absent - drop the extra tokens and retry before telling the user it does not exist. MARKETPLACES us, uk, de, ca, au, fr, it, es, jp, mx, br, walmart. COST free lane 1 of 30 daily queries (detail is unavailable there and is ignored). Keyed: 2 credits, or 5 with detail=true. Empty result sets are never billed. detail=true attaches to EVERY product everything the basic product call carries (2026-09-28): current sellers with fulfillment and delivery, 30-day price/stock events, stock history, brand_stats, dimensions, deal/badge/rating history, variation coverage, page content and up to 50 featured reviews, plus a response-wide seller_ratings array; only bsr_history and offer_history stay product-only.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| q | Yes | What to search for, e.g. 'coffee maker'. Literal keywords, not semantic: every term must match, so extra or inferred words only narrow the result set. Query in the marketplace's own language - there is no translation. A bare ASIN returns exactly that product. | |
| sort | No | relevance (default) | price (cheapest first) | rating. USE price when the user asks for the cheapest, rating when they ask for the best-reviewed. | relevance |
| brand | No | Restrict to one exact brand. USE WHEN the user names a brand they want ('Anker charger'); prefer this over putting the brand in q. | |
| group | No | How to group the shortlist. auto = choose category or price tiers automatically; category = group by product category; price = group into Budget/Mid-range/Premium; none = one flat ranked list. | auto |
| limit | No | Max products to return (default 20). | |
| detail | No | Attach per-product intelligence to every product returned (30-day price and stock change events, full stock history and state, bought-past-month badge, current sellers). Keyed accounts only. 5 credits per query instead of 2. | |
| format | No | Books/media only: return only this format - kindle, paperback, hardcover, mass_market, audiobook, audio_cd, board_book, spiral, library_binding or other (comma-separate several). USE WHEN the user wants a specific edition ('LOTR in paperback', 'the audiobook'). | |
| country | No | Marketplace to search. Amazon: us, uk, de, ca, au, fr, it, es, jp, mx, br. walmart = Walmart US (United States only). Pick the marketplace matching the user's country or locale when known (a German user -> de, a Canadian user -> ca); default us. Prices are returned in that marketplace's local currency. | us |
| collapse | No | true (default): one row per book, its other formats listed in the row's `formats` (each with its own ASIN and price). false: every format as its own row. | |
| in_stock | No | Only products currently in stock. | |
| max_price | No | Maximum price, in the marketplace's local currency. USE WHEN the user gives a budget or says cheap/affordable/under X — pass the number here rather than putting the word in q, where it is matched as a literal word in the product title and throws away real results. | |
| min_price | No | Minimum price, in the marketplace's local currency. USE WHEN the user sets a floor ('at least £50', 'nothing cheap'). | |
| include_unavailable | No | false (default): only products with a current offer, so the shortlist is buyable. true: also list items that currently have NO offer on the marketplace (Amazon 'Currently unavailable': price null, in_stock false). USE WHEN the user asks about a specific discontinued or sold-out product; otherwise leave it off. |