Real Amazon (US, UK, DE, CA, AU) & Walmart shopping data for AI assistants: ranked product shortlists, current prices, live stock, real ratings, and price/BSR history from a 17M+ product warehouse. Free hosted endpoint, no signup — 30 queries a day.
Scored across 3 tools
The three tools cover distinct roles: shopping for curated discovery, search for filtered lists, and product for single-item history. Descriptions include explicit USE WHEN / DON'T USE guidance, but search vs shopping and product vs shopping(detail=true) have functional overlap that could still confuse an agent in edge cases.
All tool names are single lowercase words (product, search, shopping), which is a consistent style. However, they do not follow a verb_noun pattern, and product is an entity while search and shopping are action nouns, creating a minor inconsistency.
Three tools map cleanly to the core workflows: discovery, filtered search, and single-product detail/history. Each tool earns its place, and the count is well-suited to a read-only shopping intelligence API.
The surface covers discovery, search, product detail, history, seller feedback, and multiple marketplaces. Minor gaps exist, such as no dedicated seller, category-browse, or bulk-history tool, but agents can work around them by chaining existing calls or using detail flags.
Full dossier for ONE known product: its current snapshot plus its observed history. USE WHEN the user has a specific ASIN, Walmart item ID, product link, or a product_id returned by shopping or search, and asks about price history, historical prices, price changes, 30-day history, stock history, seller history, buy-box history, historical analysis, 'analyse this product', 'is this a good buy', 'has the price moved/dropped', 'who is selling this', 'is it in stock'. This is the ONLY tool that returns history: shopping and search return current values, so any historical question about a product they listed comes here. DON'T USE to discover products from a keyword (use shopping) or to pull a filtered list (use search). RETURNS current price, BSR, rating, review count, stock, buy-box seller and seller count, plus an observed_at freshness stamp, full price_history and stock_history back to first observation (keyed; the free lane carries the 30-day views), change events tagged with the buy-box seller at each change, the current all-seller offer table with 30-day buy-box days (each seller row carries fulfillment AMZ/FBA/FBM and delivery days), a fulfillment block (buy-box AMZ/FBA/FBM, offer counts, whether Amazon sells and holds the buy box, buy-box delivery days and dispatch latency), the bought-past-month badge (measured aggregate buyer behavior, not an estimate), brand stats, and since 2026-09-27: dimensions (item weight + package size as printed plus parsed metric weight_g / *_cm), deal_history (list price, savings and coupon/promotion text as segments of consecutive observations, with a current view), bought_past_month_history (the badge over time; null = page seen without a badge), rating_history (rating_count + rating per observed day with ratings_gained_30d/90d), and variation_coverage (the variation matrix as last seen with, per child, whether we track it and its latest 30-day price - current state, not history). With offer_history=true every per-seller point also carries that day's shipping cost, fba and prime. Amazon answers also carry the observed product-page content, the byline (authors[] with role_norm author/narrator/illustrator/editor/translator + author for books, audiobooks, music; 2026-09-29), the book/media format (format, format_norm, and formats[]: every format of the book, each its own ASIN with price and membership subscription_price, plus family_asin; 2026-09-30) block: description (with description_source), feature_bullets, images, breadcrumbs, variations with variation_count and parent_asin, stamped content_observed_at — content_observed_at:null with empty arrays means the content crawl has not captured this ASIN yet, never 'this product has no description/gallery'. For the ~17% of the catalog with no overall rank (media, books, niche items), bsr_leaf and bsr_leaf_category carry the best category rank instead. Every response carries a data_source field naming the marketplace the numbers were observed on (e.g. 'amazon US marketplace — observed listings') — attribute prices to that source when presenting them; they are marketplace listings, not manufacturer or site-wide prices. MARKETPLACES us, uk, de, ca, au, fr, it, es, jp, mx, br, walmart. Walmart takes a numeric item ID (or gtin= with the item's UPC) and returns the intelligence blocks plus its listing content: image_url, description, breadcrumbs, highlights (spec name/value pairs), warnings, upc, rating/review_count, was_price, in_stock, and shipping_cost per seller (no live scrape on Walmart). COST free lane 1 of 30 daily queries, cache only, and returns the snapshot + 30-day views (the full history streams, bsr_history, offer_history and live scrapes need an API key (plans from $19/mo) — the response's locked block lists exactly what a key unlocks). Keyed (2026-09-27): 0.5 credits from cache with everything included, 1 for a live scrape, +0.5 ONCE for history when bsr_history and/or offer_history come back (one charge for both). Misses and partial scrapes are never billed; a miss may return a hint (found on another marketplace, or retry with mode=live). SELLER FEEDBACK (2026-09-18): every response carries seller_ratings - one entry per seller the answer names (current offers, cheapest new/used, buy-box holder and, with offer_history, every historical seller) with seller_positive_pct, seller_feedback_count, seller_rating and observed_at from a nightly seller-feedback table; offer_history.sellers[] rows carry the same fields directly. Amazon's own offers have no feedback. Not billed.
| Name | Required | Description | Default |
|---|---|---|---|
| asin | Yes | 10-character Amazon ASIN, or a numeric Walmart item ID when country=walmart. Provide either asin or gtin. | |
| gtin | No | GTIN / UPC / EAN barcode (12, 13 or 14 digits; punctuation and leading zeros are tolerated), resolved to an ASIN in the requested marketplace. USE WHEN the user gives a barcode instead of an ASIN — scanned off a package, from a supplier sheet, or copied from a listing. A barcode can legitimately map to several ASINs; the best match is returned and the rest are listed in gtin_matches. Never billed when the barcode is unknown to us. | |
| mode | No | cache = stored observation only; live = force an on-demand scrape (Amazon only, takes a few seconds); auto = serve cache when fresher than max_age_days, otherwise scrape. The no-signup free lane is cache-only: mode=live returns an error asking for an API key (from $19/mo) (do not offer a live scrape to a keyless caller); with a key, live/auto scrape normally. | auto |
| country | No | Marketplace to look the product up in. 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. | us |
| bsr_history | No | Attach the full per-category BSR rank history (era-tagged daily points back to Oct 2023 for US; legacy top-100 segments are flagged censored). Amazon marketplaces only, API key required (free key works). History charge +0.5 once per call, shared with bsr_history. | |
| include_used | No | Include used, refurbished, open-box and collectible offers in current_sellers (default false keeps the new-condition list). Every seller row always carries condition (the marketplace's own label) and condition_class (new, used_like_new, used_very_good, used_good, used_acceptable, used, refurbished, open_box, collectible, unknown); current_sellers always carries used_offer_count, lowest_new (the cheapest new offer - the list is buy-box first, not price-sorted) and lowest_used (the cheapest second-hand offer) even without opting in. With offer_history it returns one series per seller+condition_class. Cached, live and historical data alike; not billed extra. | |
| max_age_days | No | How old a cached observation may be before mode=auto triggers a live scrape. | |
| offer_history | No | Attach the buy-box owner timeline and per-seller daily price series (US buy-box depth back to Dec 2024). Amazon marketplaces only, API key required (free key works). History charge +0.5 once per call, shared with offer_history. | |
| history_points | No | With offer_history: points per series, the most recent N observed days (default 500, max 20,000). The default 10 x 500 is inside the +0.5; beyond it 0.5 credit per started 1,000 points (offer_history.extra_credits). | |
| history_sellers | No | With offer_history: how many of the most-observed sellers carry a point series (default 10, max 50). Every observed seller is always listed as a summary row with points_total. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly/idempotent/non-destructive, but the description adds substantial non-obvious behavior: cache-vs-live mechanics, the free lane's cache-only 30-queries/day cap, billing units and shared history charge, the locked block, 'never billed' rules for misses, the null-content_crawl caveat, and seller-feedback provenance. This is far beyond what the annotations convey.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
It is front-loaded well with USE WHEN / DON'T USE / RETURNS / COST sections, which helps navigation. However it is enormously bloated with version-stamped parentheticals ('since 2026-09-27', '2026-09-29'), exhaustive field enumerations, and nested detail that a selection-time reader does not need. Structure is good but discipline is poor.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite no output schema, the description enumerates in depth what is returned (snapshot fields, price/stock history, offer table, fulfillment block, variation coverage, Walmart exceptions) plus cost and marketplace scope. For a tool of this complexity it is more than complete enough to call correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
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 asin, gtin, mode, country, bsr_history, offer_history, history_points and history_sellers in detail (including cost and key requirements). The description largely restates that behavior (free lane cache-only, key requirements, cost sharing), adding little the schema lacks. Baseline 3 is appropriate when the schema carries the load.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Opens with a precise verb+resource scope: 'Full dossier for ONE known product: its current snapshot plus its observed history.' It explicitly contrasts itself with siblings, noting it is 'the ONLY tool that returns history' while shopping and search return current values. An agent can distinguish it from search/shopping without opening any schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives explicit USE WHEN conditions (specific ASIN, Walmart item ID, product link, product_id, and named historical questions like 'has the price moved/dropped'), plus explicit DON'T USE routing ('to discover products from a keyword (use shopping)', 'to pull a filtered list (use search)'). Alternatives and conditions are fully spelled out.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Filtered query over the tracked-product warehouse (24M+ Amazon and Walmart products). USE WHEN the user wants a structured list matching explicit criteria: 'well-rated dehumidifiers under $150 with 1000+ reviews', 'everything by brand X sorted by BSR', 'FBA products in this category'. DON'T USE for 'best X' buying advice (use shopping, which ranks and groups), or for a single known product (use product). RETURNS a flat list of matching products with product_id (the ASIN on Amazon, the numeric item ID on Walmart), product_url, title, brand, price, rating, review count, BSR, seller count and marketplace, ordered by the sort field. Requires an anchor: pass q, brand, or category. Cite product_id when the user may want to act on a specific row, and pass it to the product tool for that item's full history. Every response row is observed marketplace data (the marketplace field names it). COVERAGE the continuously tracked BSR product universe, not the entire Amazon catalog. COST free lane 1 of 30 daily queries, capped at 25 rows. Keyed: 1 credit per 25 rows returned. Empty result sets are never billed. SELLER FEEDBACK (2026-09-18): the response also carries seller_ratings - a separate array with seller_positive_pct, seller_feedback_count, seller_rating and observed_at for every buy-box seller named in the rows (Amazon marketplaces; absent on Walmart). Row shapes are unchanged. Not billed.
| Name | Required | Description | Default |
|---|---|---|---|
| q | No | Keyword matched against the product title. Acts as the anchor when brand is not given. 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. | |
| fba | No | true = only Fulfilled by Amazon offers, false = only merchant-fulfilled. Omit to include both. | |
| fbm | No | Only merchant-fulfilled listings. The counterpart of fba, which was already exposed. | |
| sort | No | Field to order results by. bsr sorts ascending (best sellers first); the others sort descending. | bsr |
| brand | No | Exact brand name. Acts as the anchor when q is not given. | |
| limit | No | Maximum rows to return (up to 100). The free lane caps this at 25. | |
| seller | No | Restrict to products this seller has been observed offering. REFINEMENT ONLY - cannot be used on its own; pair it with an anchor (q, brand, or category). | |
| bsr_max | No | Maximum Best Sellers Rank. Use this to keep only strong sellers. | |
| bsr_min | No | Minimum Best Sellers Rank. Lower BSR means stronger sales, so this excludes the best sellers. | |
| category | No | A department or sub-category name (e.g. 'Home & Kitchen', 'Beading Storage'), matched in full and case-insensitively against the product's category chain — comma-separate several. Works BOTH ways: as an ANCHOR on its own to browse a category with no keyword ('everything in Home & Kitchen under $30, most reviews first'), or as a REFINEMENT alongside q or brand. A category-only browse returns the category's top products by in-category best-seller rank, then applies your filters and sort. | |
| price_max | No | Maximum current price, in the marketplace's local currency. | |
| price_min | No | Minimum current price, in the marketplace's local currency. | |
| rating_max | No | Maximum average star rating. USE WHEN looking for products whose reviews are weak — an incumbent rated 3.2 is an opening. | |
| rating_min | No | Minimum star rating, on a 0-5 scale. | |
| fulfillment | No | Buy-box fulfilment of the listing: amz = sold by Amazon itself, fba = a third party fulfilled by Amazon, fbm = merchant-fulfilled. Finer than fba/fbm because it separates Amazon Retail from FBA sellers. Amazon marketplaces only. | |
| marketplace | No | Which tracked marketplace to query. walmart = Walmart US (United States only). Pick the marketplace matching the user's country or locale when known; default amazon-us. | amazon-us |
| reviews_min | No | Minimum number of reviews. | |
| max_per_category | No | Cap how many results may come from any one category, to spread results across categories. | |
| seller_count_max | No | Maximum number of sellers competing on the listing. USE WHEN the user asks for products with little competition, few sellers, or an easy listing to win — this is the core sourcing filter. | |
| seller_count_min | No | Minimum number of sellers competing on the listing. USE WHEN the user wants proven demand rather than an untested listing. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, and the description adds substantial behavioral context: return fields (product_id, product_url, etc.), ordering semantics, coverage limits ('not the entire Amazon catalog'), cost structure ('free lane 1 of 30 daily queries', '1 credit per 25 rows'), and a dated seller-feedback note about an extra seller_ratings array. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but deliberately structured with labeled sections (COVERAGE, COST, SELLER FEEDBACK) and front-loaded purpose and usage. Every sentence adds value—even the seller-feedback note clarifies an evolving response shape. It is dense but appropriate for a tool with 20 parameters; a slightly shorter version might be possible, but nothing is fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 20-parameter tool with no output schema, the description is remarkably complete: it lists return fields, covers anchor semantics, marketplace selection, cost/limits, coverage scope, and even the optional seller_ratings array. An agent has everything needed to call it correctly, including the caution about empty result sets not being billed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3, but the description goes well beyond the schema: it explains that q is literal not semantic, category can act as anchor or refinement, seller_count_max is 'the core sourcing filter' for low competition, and rating_max is for weak-review incumbents. This adds decision-relevant meaning to parameters that the schema alone does not convey.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('query') and a specific resource ('tracked-product warehouse'), and explicitly differentiates from siblings: 'DON'T USE for "best X" buying advice (use shopping, which ranks and groups), or for a single known product (use product).' It also gives concrete example queries, making the tool's purpose unmistakable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides explicit USE WHEN and DON'T USE conditions, names the alternative tools (shopping and product), and specifies an anchor requirement ('Requires an anchor: pass q, brand, or category'). This leaves no ambiguity about when to invoke this tool versus its siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| 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. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare the safe read-only, idempotent, non-destructive profile, yet the description adds substantial undisclosed behavior: ~100ms latency, no affiliate/sponsored bias, zero-results semantics, the data_source attribution requirement, interpreted_as and match_quality caveats, and a detailed credit/free-lane cost model. Its only shortfall is not covering pagination or result-count edges beyond the limit parameter.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded correctly with purpose and routing first, then return shape, then query mechanics and cost. However it runs very long and duplicates the literal-keyword/query-style guidance that already appears in the q parameter description, so some sentences do not fully earn their place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There is no output schema, so the description carries the full burden of describing returns, and it does: product_id with per-marketplace meaning, product_url, title, price currency, rating, review count, stock, observed_at, brand facets, plus the match_quality/interpreted_as signals and grouping behavior. For a 13-param multi-marketplace tool this is complete enough to call blind.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3, but the description adds real meaning beyond the schema: the literal keyword-matching rule with the accessory trap explanation ('55 inch tv' returns TV stands), the storage-capacity exception, capitalization/language rules per marketplace, and the brand-token collision example. These are operational semantics the schema fields do not carry.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Opens with a specific verb+resource+scope ('Curated product discovery: a shopping keyword in, a ranked and grouped shortlist out') and immediately distinguishes itself from both siblings: product for ASIN-identified lookups, search for filtered datasets rather than recommendations. An agent can route correctly without opening any schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit USE WHEN / DON'T USE WHEN blocks naming the exact alternatives ('use product' for a known ASIN, 'use search' for a filtered dataset), plus trigger phrases ('best X', 'find me a Y under $Z'). Handoff rules are spelled out with concrete examples, including the detail=true vs product decision boundary.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
shopping2 fields changedInput schema / properties / collapseAdded value: +{
+ "default": true,
+ "description": "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.",
+ "type": "boolean"
+}Input schema / properties / formatAdded value: +{
+ "description": "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').",
+ "type": "string"
+}product2 fields changedInput schema / properties / bsr_history / descriptionPrevious value: -"Attach the full per-category BSR rank history (era-tagged daily points back to Oct 2023 for US; legacy top-100 segments are flagged censored). Amazon marketplaces only, API key required (free key works). +0.5 credits when data is returned."New value: +"Attach the full per-category BSR rank history (era-tagged daily points back to Oct 2023 for US; legacy top-100 segments are flagged censored). Amazon marketplaces only, API key required (free key works). History charge +0.5 once per call, shared with bsr_history."Input schema / properties / offer_history / descriptionPrevious value: -"Attach the buy-box owner timeline and per-seller daily price series (US buy-box depth back to Dec 2024). Amazon marketplaces only, API key required (free key works). +0.5 credits when data is returned."New value: +"Attach the buy-box owner timeline and per-seller daily price series (US buy-box depth back to Dec 2024). Amazon marketplaces only, API key required (free key works). History charge +0.5 once per call, shared with offer_history."shopping1 field changedInput schema / properties / include_unavailableAdded value: +{
+ "default": false,
+ "description": "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.",
+ "type": "boolean"
+}search1 field changedInput schema / properties / fulfillmentAdded value: +{
+ "description": "Buy-box fulfilment of the listing: amz = sold by Amazon itself, fba = a third party fulfilled by Amazon, fbm = merchant-fulfilled. Finer than fba/fbm because it separates Amazon Retail from FBA sellers. Amazon marketplaces only.",
+ "enum": [
+ "amz",
+ "fba",
+ "fbm"
+ ],
+ "type": "string"
+}product2 fields changedInput schema / properties / history_pointsAdded value: +{
+ "default": 500,
+ "description": "With offer_history: points per series, the most recent N observed days (default 500, max 20,000). The default 10 x 500 is inside the +0.5; beyond it 0.5 credit per started 1,000 points (offer_history.extra_credits).",
+ "maximum": 20000,
+ "minimum": 1,
+ "type": "integer"
+}Input schema / properties / history_sellersAdded value: +{
+ "default": 10,
+ "description": "With offer_history: how many of the most-observed sellers carry a point series (default 10, max 50). Every observed seller is always listed as a summary row with points_total.",
+ "maximum": 50,
+ "minimum": 1,
+ "type": "integer"
+}product1 field changedInput schema / properties / include_used / descriptionPrevious value: -"Include used, refurbished, open-box and collectible offers in current_sellers (default false keeps the new-condition list). Every seller row always carries condition (the marketplace's own label) and condition_class (new, used_like_new, used_very_good, used_good, used_acceptable, used, refurbished, open_box, collectible, unknown); current_sellers always carries used_offer_count and lowest_used (the cheapest second-hand offer) even without opting in. With offer_history it returns one series per seller+condition_class. Cached, live and historical data alike; not billed extra."New value: +"Include used, refurbished, open-box and collectible offers in current_sellers (default false keeps the new-condition list). Every seller row always carries condition (the marketplace's own label) and condition_class (new, used_like_new, used_very_good, used_good, used_acceptable, used, refurbished, open_box, collectible, unknown); current_sellers always carries used_offer_count, lowest_new (the cheapest new offer - the list is buy-box first, not price-sorted) and lowest_used (the cheapest second-hand offer) even without opting in. With offer_history it returns one series per seller+condition_class. Cached, live and historical data alike; not billed extra."product1 field changedInput schema / properties / include_usedAdded value: +{
+ "default": false,
+ "description": "Include used, refurbished, open-box and collectible offers in current_sellers (default false keeps the new-condition list). Every seller row always carries condition (the marketplace's own label) and condition_class (new, used_like_new, used_very_good, used_good, used_acceptable, used, refurbished, open_box, collectible, unknown); current_sellers always carries used_offer_count and lowest_used (the cheapest second-hand offer) even without opting in. With offer_history it returns one series per seller+condition_class. Cached, live and historical data alike; not billed extra.",
+ "type": "boolean"
+}product1 field changedInput schema / properties / mode / descriptionPrevious value: -"cache = stored observation only; live = force an on-demand scrape (Amazon only, takes a few seconds); auto = serve cache when fresher than max_age_days, otherwise scrape. The no-signup free lane is cache-only: mode=live returns an error asking for a free API key (do not offer a live scrape to a keyless caller); with a key, live/auto scrape normally."New value: +"cache = stored observation only; live = force an on-demand scrape (Amazon only, takes a few seconds); auto = serve cache when fresher than max_age_days, otherwise scrape. The no-signup free lane is cache-only: mode=live returns an error asking for an API key (from $19/mo) (do not offer a live scrape to a keyless caller); with a key, live/auto scrape normally."serpserpserpsearch3 fields changedInput schema / anyOfPrevious value: -[
- {
- "required": [
- "q"
- ]
- },
- {
- "required": [
- "brand"
- ]
- }
-]New value: +[
+ {
+ "required": [
+ "q"
+ ]
+ },
+ {
+ "required": [
+ "brand"
+ ]
+ },
+ {
+ "required": [
+ "category"
+ ]
+ }
+]Input schema / properties / category / descriptionPrevious value: -"Restrict to a single product category. REFINEMENT ONLY - cannot be used on its own; pair it with q or brand, which are the only anchors. To browse a category with no keyword, use the shopping tool instead."New value: +"A department or sub-category name (e.g. 'Home & Kitchen', 'Beading Storage'), matched in full and case-insensitively against the product's category chain — comma-separate several. Works BOTH ways: as an ANCHOR on its own to browse a category with no keyword ('everything in Home & Kitchen under $30, most reviews first'), or as a REFINEMENT alongside q or brand. A category-only browse returns the category's top products by in-category best-seller rank, then applies your filters and sort."Input schema / properties / seller / descriptionPrevious value: -"Restrict to products this seller has been observed offering. REFINEMENT ONLY - cannot be used on its own; pair it with q or brand, which are the only anchors."New value: +"Restrict to products this seller has been observed offering. REFINEMENT ONLY - cannot be used on its own; pair it with an anchor (q, brand, or category)."
Add one secure layer between your agents and this server.