Amazon MCP

[Pangolinfo MCP self-introspection] One call to get the full capability catalog, canonical workflows, and usage tips — no backend call, free. Use when: an AI client first connects to pangolinfo-mcp and needs to quickly grasp "what tools exist" / "how do they chain" / "which workflow for which scene"; user asks "what can you do" / "what capabilities are there"; capability audit before SOP planning. Don't use: for the full description of one specific tool (use tools/list — the 'summary' mode here gives one-liners only); for account balance or remaining credits (CONTRACT §9 forbids exposing account endpoints via MCP). Returns: { version, locale, liveTools[{name, domain, oneLiner, cost}], workflows[{title, steps[], note}], tips[] }. Pair with: ↓ AI decides which concrete tool to call next; does not consume downstream tools. Cost: 0 points (local data, no backend round-trip).

• detailstring'summary' returns tool catalog + canonical workflows (default, token-light); 'full' also expands the full description of every tool (~8KB — use on first integration or when context budget allows).

[Amazon SERP scrape] Run a real Amazon keyword search and return the first-page ASIN list. Use when: user says "search Amazon for X" / "who sells X" / "top results for keyword X" / "competitors for X"; or you need a list of ASINs for a keyword as upstream input to deeper analysis. Don't use: for a single ASIN detail (use get_amazon_product); for category bestseller ranks (use list_bestsellers); for Google/external demand on the term (use ai_search or keyword_trends). Returns (format='json', default): data.json[0].data.{ pageIndex, nextPage, keyword, results[{ asin, title, price, star, rating, sales, badge, rank, sponsored, image, delivery }] } — ~22 rows/page. **Pagination**: use the 'page' param (default 1, 1-based); response's 'nextPage' holds the next page number, 'nextPage=null' means last page reached. Pair with: ↓ feed results[].asin into get_amazon_product / get_amazon_reviews for single-product deep-dive; ↓ feed the same keyword into keyword_trends to compare in-site vs externa

• keywordstringrequiredSearch keyword. Examples: 'wireless earbuds' / 'stanley quencher' / 'iphone 16 case' / 'kitchen knife set'.
• sitestringAmazon marketplace. Defaults to 'amz_us' (US).
• zipcodestringZIP code that must match the site country (amz_us → US zip, amz_jp → JP zip, ...). Optional; backend picks a random one from the per-country pool when omitted. Cross-country zips (e.g. amz_us + JP zip) are rejected by the backend. Examples: 10001 (NY) / 90001 (LA) / 100-0001 (Tokyo).
• formatstringResponse format. Defaults to 'json' — structured search rows (asin, title, price, star, rating, sales, badge, rank, ...) ready for programmatic use. Use 'markdown' if you want the rendered SERP text instead.
• pageintegerPage number, 1-based. ~22 ASINs per page. Use response's pageIndex/nextPage to decide whether to continue: nextPage holds the next page number; nextPage=null (or absent) means last page reached. **Only paginate when the user explicitly asks for more / Top-N where N exceeds one page / all results** — otherwise the first page is enough.

[Amazon single-product detail] Scrape the full PDP for one ASIN. Use when: user supplies a specific ASIN ("look at B0XXXXXXXX" / "check this product's price/rating/seller" / "analyse this competitor"); or as a SOP step after candidate ASINs are picked. Don't use: for many products at once (use search_amazon or list_* series for lists); for reviews only (use get_amazon_reviews — cheaper and more focused). Returns (format='json', default): data.json[0].data.results[0] = { asin, title, price, star, rating, brand, seller{name,id}, parentAsin, ratingDistribution[], aiReviewsSummary, bestSellersRankItems, reviews[{date,star,content,helpful,...}], productOverview[], features[], productDescription[], images[], variantDetails[], attributes[], category_id, breadCrumbs, ... } — 30+ fields (variantDetails summary included). Pair with: ↑ asin typically comes from search_amazon / list_bestsellers / filter_niches; ↓ feed the same asin into get_amazon_reviews for more reviews (the PDP carries only ~5-

• asinstringrequiredAmazon ASIN, 10 letters/digits (case-insensitive — auto-uppercased). Examples: 'B09B8V1LZ3' (Echo Dot 5) / 'B0CRMZHDG8' (Stanley Quencher) / 'B0BDHWDR12' (AirPods Pro 2).
• sitestringAmazon marketplace. Defaults to 'amz_us' (US).
• zipcodestringZIP code that must match the site country (amz_us → US zip, amz_jp → JP zip, ...). Optional; backend picks a random one from the per-country pool when omitted. Cross-country zips (e.g. amz_us + JP zip) are rejected by the backend. Examples: 10001 (NY) / 90001 (LA) / 100-0001 (Tokyo).
• formatstringResponse format. Defaults to 'json' — a structured payload (title, price, rating, reviews, seller, etc.) ready for programmatic use. Use 'markdown' if you want the rendered PDP text instead.

[Amazon review batch scrape] Page-fetch real buyer reviews for an ASIN. Filterable by star / sort / media type. Use when: user says "look at X's negative reviews" / "mine pain points" / "analyse competitor reviews" / "do VOC" / "find user complaints for Listing copy"; or pre-launch critical-review scan; or finding improvement points for listing optimization. Don't use: when the few reviews already in the PDP would suffice (get_amazon_product carries 5-10 reviews + aiReviewsSummary — enough for a quick read); for keyword search (use search_amazon). Returns: data.json[0].data.results[{ reviewId, date, country, star, title, content, author, authorId, authorLink, imgs[], videos, purchased, vineVoice, helpful, attributes }] — ~10 reviews per page. Pair with: ↑ asin typically from search_amazon / get_amazon_product / list_bestsellers; ↓ review text can be fed directly to an LLM for pain-point clustering and keyword extraction. Cost: **10 points per page** (expensive). Start with pageCount=1

• asinstringrequiredAmazon ASIN (10 letters/digits, case-insensitive — auto-uppercased). Examples: 'B09B8V1LZ3' / 'B0CRMZHDG8'.
• sitestringAmazon marketplace. Defaults to amz_us.
• pageCountintegerNumber of review pages to fetch (~10 reviews per page). **Costs 10 points per page** — control accordingly. Defaults to 1.
• filterByStarstringFilter by star rating. For VOC pain-point mining, pass 'critical' (1-3 star reviews) to surface defects; for positive-aspect extraction, pass 'positive'.
• sortBystringSort order: 'recent' (newest first — track current sentiment) or 'helpful' (most-upvoted first — highest impact reviews).
• mediaTypestringReview type: 'all_contents' for all, 'media_reviews_only' for reviews with photos/videos only (higher credibility).
• zipcodestringZIP code that must match the site country (amz_us → US zip, amz_jp → JP zip, ...). Optional; backend picks a random one from the per-country pool when omitted. Cross-country zips (e.g. amz_us + JP zip) are rejected by the backend. Examples: 10001 (NY) / 90001 (LA) / 100-0001 (Tokyo).

[Amazon Best Sellers] Top-50 ranking for a category with 24h rank deltas. Use when: user says "X category bestsellers" / "who's #1 in X" / "any new entrants climbing" / "benchmark top sellers"; setting baseline products during niche scouting; tracking category leadership in competitor radars. Don't use: for new arrivals (use list_new_releases); for full category listings beyond top 50 (use list_category_products); when you only have a keyword (use search_categories first). Returns: data.json[0].data.{ reftag, recsList } — recsList is a JSON-string array (parse twice); each row { id, metadataMap.{ render.zg.rank, currentSalesRank, percentageChange, twentyFourHourOldSalesRank } }. Pair with: ↑ categorySlug from user or scene inference (e.g. 'electronics' / 'home-garden' / 'beauty'); ↓ feed id (ASIN) into get_amazon_product for single-product deep-dive. Cost: ~1 point/call, ~5s. Tips: categorySlug is the hyphenated English slug in amazon.com/Best-Sellers URL paths.

• categorySlugstringrequiredAmazon Best Sellers category slug (lowercase, hyphenated). Examples: 'electronics', 'home-garden', 'beauty', 'toys-and-games'. Find these in the URL path on amazon.com/Best-Sellers.
• sitestringAmazon marketplace. Defaults to amz_us.
• zipcodestringZIP code that must match the site country (amz_us → US zip, amz_jp → JP zip, ...). Optional; backend picks a random one from the per-country pool when omitted. Cross-country zips (e.g. amz_us + JP zip) are rejected by the backend. Examples: 10001 (NY) / 90001 (LA) / 100-0001 (Tokyo).
• formatstringResponse format. Defaults to 'json' — structured Top-50 ranked ASIN list. Use 'markdown' for the rendered page text.

[Amazon New Releases] Best-selling Top-50 ASINs that hit the market within the last 30 days for a category (backend cap; not 100). Use when: user says "new arrivals in X" / "any breakout new products" / "newly-launched that sell well" / "trending new directions" / "new entrants to monitor"; GTM scouting for new angles; competitor radar catching new entrants. Don't use: for evergreen winners (use list_bestsellers); for full category listings (use list_category_products); when you only have a keyword (use search_categories first). Returns: data.json[0].data.{ reftag='zg_bsnr_g_<slug>', recsList } — recsList is a JSON-string array (parse twice); each row { id, metadataMap.{ render.zg.rank, ... } }. Pair with: ↑ categorySlug as in list_bestsellers; ↓ feed id (ASIN) into get_amazon_product to see why it climbed (pitch, pricing, variant strategy). Cost: ~1 point/call, ~5s.

• categorySlugstringrequiredAmazon New Releases category slug (lowercase, hyphenated). Examples: 'electronics', 'home-garden'. Find these in the URL path on amazon.com/gp/new-releases.
• sitestringAmazon marketplace. Defaults to amz_us.
• zipcodestringZIP code that must match the site country (amz_us → US zip, amz_jp → JP zip, ...). Optional; backend picks a random one from the per-country pool when omitted. Cross-country zips (e.g. amz_us + JP zip) are rejected by the backend. Examples: 10001 (NY) / 90001 (LA) / 100-0001 (Tokyo).
• formatstringResponse format. Defaults to 'json' — structured ranking list. Use 'markdown' for the rendered page text.

[Amazon seller storefront] List all listings under a merchant ID, paginated (24 rows/page). Use when: user says "show me this seller's products" / "how many SKUs does store X carry" / "competitor storefront category breadth" / "what is this seller pushing" / "research a seller's catalog strategy". Don't use: without a merchant ID (find 'sold by' link on any product PDP first); for a single product (use get_amazon_product). Returns: data.json[0].data.{ pageIndex, maxPage, nextPage, results[{ asin, title, price, star, rating, rank, img }] } — 24 rows/page. **Every row carries rank** (its display order in the storefront, ≈ that seller's in-store popularity ranking) plus star/rating, so **this single call is enough to rank and tabulate the seller's listings — no need to re-fetch each PDP**. **Two pagination modes**: ① page locates a specific page (default 1); ② pageCount accumulates the first N pages in one call (N≤3, flat-merged into the same results). When pageCount>1, pageIndex/nextPage

• sellerIdstringrequiredAmazon merchant ID (14-char alphanumeric). Examples: 'ATVPDKIKX0DER' (Amazon.com first-party) / 'A2L77EE7U53NWQ' (Amazon Warehouse). Find it in a product page's 'sold by' link or amazon.com/sp?seller=... URL.
• sitestringAmazon marketplace. Defaults to amz_us.
• zipcodestringZIP code that must match the site country (amz_us → US zip, amz_jp → JP zip, ...). Optional; backend picks a random one from the per-country pool when omitted. Cross-country zips (e.g. amz_us + JP zip) are rejected by the backend. Examples: 10001 (NY) / 90001 (LA) / 100-0001 (Tokyo).
• formatstringResponse format. Defaults to 'json' — structured seller listings. Use 'markdown' for the rendered page text.
• pageintegerPage number, 1-based. 24 rows per page. Use response's pageIndex/maxPage/nextPage to decide whether to continue: nextPage holds the next page number; nextPage=null or page>=maxPage means last page reached. **Only paginate when the user explicitly asks for more / all SKUs** — otherwise the first page is enough. NOTE: when pageCount>1 (multi-page accumulate) is set, page is ignored (the backend always accumulates from page 1).
• pageCountintegerMulti-page accumulate: passing N crawls the first N pages in one call and returns them flat-merged (e.g. 3 = all products from pages 1+2+3). Default 1 (single page, uses the `page` flow); cap 3, larger values treated as 3. Difference vs `page`: `page` locates one specific page, `pageCount` pulls the first N pages merged. **Use only when you need the full multi-page SKU set in one shot.** Billed by pages actually crawled (a failed page is refunded).
• categoryIdstringCategory filter ID — filters the seller's products by category. A single leaf category ID (e.g. '7161074011'), or comma-separated multi-level categories (e.g. '172282,502394,7161073011'). Omit = all products of the seller. Extractable from the rh=n:<categoryId> part of an Amazon storefront URL.

[Amazon category listing] List concrete on-sale products under a Browse Node ID (paginated, 24 rows/page). Use when: user says "what's selling in category X" / "list products in node 12345" / "show me what's in this category"; after picking a categoryId during scouting, you want to see real listings; competitor-research on category density. Don't use: when only the top-50 winners matter (use list_bestsellers — cheaper and more signal); for category-level aggregate metrics (use filter_categories — sales/search volume/competitor density); for niche rather than full category (use filter_niches). Returns: data.json[0].data.{ pageIndex, maxPage, nextPage, categoryName, pagination, results[{ asin, title, price, star, rating, rank, img }] } — 24 rows/page. **Pagination**: use the 'page' param (default 1, 1-based); 'nextPage' holds the next page number, 'nextPage=null' or 'page>=maxPage' means last page reached. Pair with: ↑ nodeId from search_categories (keyword→category) or get_category_chil

• nodeIdstringrequiredAmazon category Browse Node ID (numeric). Examples: '172282' (Electronics) / '2619526011' (Appliances) / '11965861' (Musical Instruments). Obtain via search_categories or get_category_children.
• sitestringAmazon marketplace. Defaults to amz_us.
• zipcodestringZIP code that must match the site country (amz_us → US zip, amz_jp → JP zip, ...). Optional; backend picks a random one from the per-country pool when omitted. Cross-country zips (e.g. amz_us + JP zip) are rejected by the backend. Examples: 10001 (NY) / 90001 (LA) / 100-0001 (Tokyo).
• formatstringResponse format. Defaults to 'json' — structured category listings. Use 'markdown' for the rendered page text.
• pageintegerPage number, 1-based. 24 rows per page. Use response's pageIndex/maxPage/nextPage to decide whether to continue: nextPage holds the next page number; nextPage=null or page>=maxPage means last page reached. **Only paginate when the user explicitly asks for more / all results** — otherwise the first page is enough.

[Amazon category search] Match Amazon's category tree by keyword (Chinese or English) and return candidate nodes. Use when: user gave a keyword/concept rather than a category id, and a downstream tool needs categoryId / browseNodeId (e.g. filter_niches / filter_categories / list_category_products / inferring list_bestsellers slug); when you need to know where a product concept lives in Amazon's taxonomy. Don't use: when you already have categoryId/nodeId (use get_category_paths for breadcrumbs or a downstream filter directly); when you want to drill the subtree (use get_category_children). Returns: data.items.data[{ browseNodeId, browseNodeIdPath, browseNodeName, browseNodeNameCn, browseNodeNamePath, browseNodeNamePathCn, parentBrowseNodeIdPath, productType, sellable, hasChild }] + pagination. Pair with: ↓ feed browseNodeId into list_category_products / list_bestsellers (derive slug from path) / filter_niches / filter_categories; ↓ feed into get_category_children to drill further; ↓ fe

• keywordstringrequiredCategory name keyword (Chinese or English). Examples: 'headphones' / 'kitchen knives' / '无线耳机' / 'wireless earbuds'.
• sitestringMarketplace to search categories in. Defaults to 'amz_us'.

[Amazon category tree drilldown] List direct children from any node (or omit parent to start at the roots). Use when: user says "show me Amazon's category tree" / "subcategories under X" / "list top-level departments" / "drill to level 3"; building a category map; deciding which level is right after search_categories returned candidates. Don't use: when a keyword jump is faster (use search_categories); when you want products in the category, not its subcategories (use list_category_products). Returns: data.items.data[{ browseNodeId, browseNodeIdPath, browseNodeName, browseNodeNameCn, parentBrowseNodeIdPath, productType, sellable, hasChild }] + data.items.pagination.{ total, page, size, hasNext }; omit parentBrowseNodeIdPath to fetch top-level roots; hasChild=1 means the node has further children. **Pagination**: use the 'page' param (default 1, size default 10 / max 50); 'pagination.hasNext=true' means the node has more children not yet listed. Pair with: ↑ parentBrowseNodeIdPath eithe

• parentBrowseNodeIdPathstringParent node path. Either a single browseNodeId or a slash-joined path. Examples: '2619526011' (Appliances, drill from top) / '2619526011/18116197011' (Appliances > Ranges/Ovens/Cooktops, level-3 drill). Omit to fetch top-level roots.
• pageintegerPage number, 1-based.
• sizeintegerPage size.

[Amazon category commercial-metrics filter] Filter categories by dozens of metrics (sales, GMS, search volume, conversion, return rate, price tier, competitor density, …) — or use as a "category detail" endpoint by passing a single categoryId. Use when: user says "find categories worth entering" / "high-sales categories" / "low return-rate categories" / "high search-volume but low competition categories" / "show me all metrics for category X"; category-level blue-ocean hunt; getting the 30+ metric snapshot of one category. Don't use: for niche-level (use filter_niches — finer granularity); for actual products in a category (use list_category_products); for just the readable name (use get_category_paths). Returns: data.items.data[{ id, categoryId, marketplaceId, timeRange, sampleScope, snapshotDate, unitSoldSum, glanceViewsSum, searchVolumeSum, netShippedGmsSum, buyBoxPriceAvg, buyBoxPriceTier, searchToPurchaseRatio, returnRatio, asinCount, offersPerAsin, newAsinCount, newBrandCount, av

• marketplaceIdstringAmazon marketplace id. ⚠️ Backend currently supports US only; other marketplaces will fail or fall back. Use US (the default).
• timeRangestringrequiredAggregation time range (required). Examples: 'l7d' (last 7 days — verified working). The exact enum is backend-defined; 'l7d' is the safest known value.
• sampleScopestringrequiredSample scope (required). Examples: 'all_asin' (all ASINs — verified working).
• categoryIdstringWhen set, returns the full metric row for that single category (this endpoint doubles as the 'detail' endpoint). Omit to list multiple categories matching the filters. Example: '979832011'.
• pageintegerPage number, 1-based.
• sizeintegerPage size, max 10 (backend hard limit).
• sortFieldstringSort field; any response field name is accepted (e.g. 'unitSoldSum', 'netShippedGmsSum').
• sortOrderstringSort order: 'asc' or 'desc'.
• unitSoldSumMinintegerMin total units sold.
• unitSoldSumMaxintegerMax total units sold.
• netShippedGmsSumMinintegerMin total GMS (gross merchandise sales).
• netShippedGmsSumMaxintegerMax total GMS.
• searchVolumeSumMinintegerMin total search volume.
• searchVolumeSumMaxintegerMax total search volume.
• buyBoxPriceAvgMinnumberMin average buy-box price (marketplace currency).
• buyBoxPriceAvgMaxnumberMax average buy-box price.
• buyBoxPriceTiersarrayPrice-tier filter. Allowed: budget, mainstream, premium, luxury.
• returnRatioLevelsarrayReturn-rate quality buckets. Allowed: excellent, average, risk.
• searchToPurchaseRatioLevelsarraySearch-to-purchase conversion buckets. Allowed: to_improve, average, excellent.
• extraFiltersobjectPass-through for any other upstream filter (e.g. unitSoldTrendDirections, newAsinCountLevels, metricChangeRateBuckets). Keys must match the upstream doc verbatim.

[Amazon niche filter] Filter Amazon Niches (a finer-grained "demand cluster" than categories) by 50+ commercial metrics, or use as a "niche detail" endpoint for one niche. Use when: user says "find blue ocean" / "high search volume + low competition niches" / "fast-growing small markets" / "niche scouting" / "give me the deep report on this niche" / "low return-rate niches" / "niches with return rate under 10%"; the core filter step of GTM scouting SOPs; getting fee structure / brand age / new-launch trends for one niche. Don't use: for full categories (use filter_categories); for actual products in a niche (the niche record only carries 1 referenceAsin; combine with categoryId + list_category_products); for plain keyword search (use search_amazon). Returns: data.items.data[{ nicheId, nicheTitle, referenceAsinImageUrl, currency, searchVolumeT90, searchVolumeT360, searchVolumeGrowthT90, minimumPrice, maximumPrice, avgPrice, productCount, sponsoredProductsPercentage, primeProductsPercent

• marketplaceIdstringAmazon marketplace id (required). ⚠️ Backend currently supports US only; other marketplaces will fail or fall back. Use US (the default).
• nicheIdstringWhen set, returns the full deep report for that single niche (this endpoint doubles as the niche-detail endpoint). Omit to list multiple niches matching the filters. Example: '8140a265-768d-4679-8bc2-994cb1c96f0b' (UUID).
• nicheTitlestringKeyword match against niche titles. Examples: 'iphone 16 wallet case' / 'wireless earbuds for sports'.
• pageintegerPage number, 1-based.
• sizeintegerPage size, max 10 (backend hard limit), default 3 (small default to keep responses under AI context limits — pass size=10 explicitly when you need a wider sweep).
• sortFieldstringSort field; any response field name is accepted (e.g. 'searchVolumeT90', 'avgProductPrice').
• sortOrderstringSort order: 'asc' or 'desc'.
• searchVolumeT90MinintegerMin search volume over last 90 days.
• searchVolumeT90MaxintegerMax search volume over last 90 days.
• searchVolumeT360MinintegerMin search volume over last 360 days.
• searchVolumeT360MaxintegerMax search volume over last 360 days.
• searchVolumeGrowthT90MinnumberMin 90-day search-volume growth rate (decimal, 0.1 = +10%).
• searchVolumeGrowthT90MaxnumberMax 90-day search-volume growth rate.
• minimumPriceMinnumberLower bound on the niche's minimum product price.
• maximumPriceMaxnumberUpper bound on the niche's maximum product price.
• productCountMinintegerMin product count in the niche.
• productCountMaxintegerMax product count in the niche.
• avgReviewCountMinintegerMin average review count.
• avgReviewCountMaxintegerMax average review count — lower means less competition.
• avgReviewRatingMinnumberMin average review rating (0-5).
• top5ProductsClickShareT360MaxnumberMax top-5-products click share over 360 days (0-1). Lower = more fragmented niche, more opportunity.
• returnRateT360MaxnumberMax return rate over 360 days (0-1).
• extraFiltersobjectPass-through for any other upstream filter (e.g. sponsoredProductsPercentageT360Min, successfulLaunchesT360Max, avgBestSellerRankMax). Keys must match the upstream doc verbatim.

[Amazon category breadcrumb resolver] Batch-resolve categoryId list to full paths (e.g. 'Electronics > Headphones > Over-Ear Headphones'). Use when: a report needs readable category context (not bare IDs); user has a list of numeric IDs and wants the names; multiple categories need labels for comparison. Don't use: for a single ID — most other tools already return browseNodeNamePath in their responses; for tree structure (use get_category_children). Returns: data.items[{ categoryId, categoryName, categoryNameCn, browseNodeNamePaths[], browseNodeNamePathCns[] }] — one row per input ID. Pair with: ↑ categoryIds from any prior step (filter_niches/filter_categories output, user-pasted ID list); ↓ usually presentation-only, downstream rarely depends on it. Cost: ~1 point/call, ~2s (cheaper than N single resolutions).

• categoryIdsarrayrequiredCategory IDs to resolve full path for. Examples: ['2619526011'] (Appliances) / ['172282', '11965861'] (Electronics + Musical Instruments).
• sitestringAmazon marketplace. Defaults to 'amz_us' (US).

[Local Maps via Google Maps] Local-business search (data source: Google Maps; use must comply with Google Terms of Service). Search local businesses at a given lat/lng — returns name, address, rating, review count, etc. Use when: user says "Y businesses in city X" / "local retail research" / "offline channel distribution" / "coffee shops/supermarkets/wholesalers in area" / "physical-store coverage density"; offline competitor/channel research; gauging physical-supply density of a category in a region. Don't use: for e-commerce listings (Amazon series); for global trends (use keyword_trends); for Google search results (use ai_search). Returns: data.organicResults[{ place_id, name, about, rating, number_of_reviews, borough, street_addr, city, postal_code, ... }]. Pair with: ↑ query (business keyword) + latitude/longitude/zoom (zoom 1=world, 13=city, 21=single building); ↓ presentation-focused, downstream rarely consumes. Cost: ~1.5 points/call, ~5s. Tips: zoom 13 (city, default) gives yo

• querystringrequiredLocal search query. Examples: 'coffee shop' / 'wholesale electronics' / '电子产品批发' / 'pet store'.
• latitudenumberrequiredLatitude of search center. Examples: 37.7822 (San Francisco) / 40.7128 (New York) / 34.0522 (Los Angeles).
• longitudenumberrequiredLongitude of search center. Examples: -122.4642 (San Francisco) / -74.0060 (New York) / -118.2437 (Los Angeles).
• zoomintegerMap zoom level, 1=world, 13=city, 21=building. Default 13.
• languagestringBCP-47 language code, e.g. 'en', 'zh-CN'.
• limitintegerMax results to return (1-100).

[Design Patent TRO risk control · WIPO global design / IP search] Query the WIPO design database across 12 sources (USPTO US designs, CNID China, HAGUE international registrations, …), with one-click chaining to US design-patent TRO (temporary restraining order) / litigation risk control. Use when: user says "check trademark" / "design patent search" / "any IP risk for new product" / "X company's patent portfolio" / "WIPO search" / "USPTO query" / "what is registration DM/XXX"; pre-launch IP clearance during scouting/GTM SOPs; competitor IP-portfolio research. Don't use: for keyword ranks / product reviews / product detail (this is an IP database, not a commerce database); for US text-trademark search (this DB focuses on design patents — text trademark coverage is limited). Returns: data.data.{ total, hits[{ IRN, HOL[], DETAIL_DATA.structured.{indication_of_products, statement_of_novelty, ...}, IMG[], IMG_DATA[{filename,url}], DC, RD, STATUS, LCS[], DS[], PROD[], SOURCE, DETAIL_URL }]

• sourcestringrequiredData source (required). WIPO data is partitioned by source — cross-source queries not supported. Common: USID (US design), CNID (China design, 17M+ rows), HAGUE (Hague international), DEID, JPID.
• dsstringDesignated country code (e.g. 'US', 'CN'). Optional — usually implied by `source`.
• holstringHolder name fuzzy match. Examples: 'Apple' / 'Samsung' / 'Nike'. NOTE: CNID + hol MUST be paired with id/idSearch/rd/status/lcs; JPID has no HOL column (will be ignored).
• prodstringProduct name fuzzy match. CNID searches Chinese, other sources search English. Examples: '椅子' (CNID) / 'wireless headphones' (USID) / 'iphone case' (USID). CNID + prod MUST be paired with id/idSearch/rd/status/lcs; JPID has no PROD column.
• irnstringInternational Registration Number exact match. Examples: 'DM/000298' (HAGUE) / 'D1107730' (USID).
• idstringFull ID exact match, e.g. 'CNID.2023.123456'. Routes CNID queries to a single partition (avoids full scan).
• idSearchstringID variant fuzzy match.
• rdstringRegistration date (YYYY or YYYY-MM-DD). One of the recommended narrowing fields for CNID — routes to a year partition.
• statusstringLegal status: 'ACT' (active), 'EXP' (expired), etc. USID has no STATUS column (will be ignored).
• lcsstringDesign classification (Locarno Classification code), e.g. '23-01' = fluid distribution equipment.
• fromintegerPagination offset, 0-based.
• numintegerPage size (default 10, max 100).
• enableLitigationbooleanEnable Smart Risk Control Mode: after patents match, auto-query related US litigation (PACER backend) by patent number; cases are joined into each patent's `cases` field. Default false. When on, each matched patent gains litigationStatus / caseTotal / cases; +12 points charged only when a patent is found (free if none).

[AI Search via Google SERP] Scrape publicly-available Google search results (data source: Google; use must comply with Google Terms of Service) with top AI Overview, organic results, and related searches. Two modes: overview (standard SERP) / ai_mode (immersive multi-turn conversational search). Use when: user says "Google for me" / "external demand" / "what do people say about X" / "Reddit/Quora pain points" / "will my content be cited in AI search" / "find user complaints for keyword X"; "consumer voice" step in scouting SOPs; verifying whether a new product concept has off-Amazon demand; **see which Google Shopping ads competitors run / their ad landing pages** (the sponsered block). Don't use: for on-Amazon search (use search_amazon); when only the trend curve matters (use keyword_trends — cheaper and tighter). Returns: data.{ results_num, ai_overview, json.items[ { type:'ai_overview', items:[{content:[...], references:[{title,url,domain}]}] }, { type:'organic', items:[{title,url,t

• querystringrequiredSearch keyword or question. Examples: 'wireless earbuds reviews' (single keyword) / 'how does noise cancellation work' (question) / 'what do people complain about Stanley Quencher' (user pain point).
• modestringSearch mode: 'overview' (default) = standard Google SERP with AI Overview at the top, best for one-shot queries; 'ai_mode' = Google AI Mode immersive search (udm=50), best for complex multi-step questions with follow-ups.
• followupsarrayFollow-up question list (only honored when mode='ai_mode'). Each item is a follow-up question on the previous answer. **More than 5 entries significantly degrades response time.**
• screenshotbooleanWhether to return a screenshot URL of the rendered search page. Defaults to false.

[Keyword Trends via Google Trends] Keyword popularity (data source: Google Trends; use must comply with Google Terms of Service). Time series + per-region heatmap + rising related queries (with 'Breakout' tags). Compare up to 5 keywords on one chart. Use when: user says "how hot is keyword X" / "A vs B popularity" / "any seasonality" / "which states love X" / "find breakout terms" / "new-product direction" / "trend comparison" / "is X past its peak yet". Don't use: for absolute search volume (Trends is 0-100 relative); for products/links (use search_amazon / ai_search); for a single keyword's snapshot (need ≥ 2 for meaningful comparison). Returns: data.json.{ keywordsGeoData[{ keyword, geoMapData[{ geoCode, geoName, value[], formattedValue[], hasData[] }] }], keywordsRankData[{ keyword, rankList[{ rankedKeyword[{ query, value, formattedValue, link, hasData }] }] }], timelineData[{ time, formattedTime, value[], formattedValue[] }], geoMapData[] }, taskId, url. Pair with: ↑ keywords from

• keywordsarrayrequiredKeywords to compare (1-5). Examples: ['wireless earbuds', 'bluetooth earbuds'] (synonyms) / ['stanley quencher', 'yeti rambler', 'hydro flask'] (competing brands) / ['halloween costume'] (single keyword for seasonality).
• timeRangestringTime window. Common: 'today 12-m' (last 12 months, default), 'today 3-m' (last 90 days), 'today 5-y' (5-year long-term), 'all' (since 2004).
• regionstringRegion code (ISO country, or 'WORLD' for global). Common: 'US' / 'GB' / 'DE' / 'JP' / 'CN'.
• languagestringInterface language (BCP-47), affects related-query language. Defaults to 'en-US'. Use 'zh-CN' for Chinese.

[Generic Amazon scrape — power-user escape hatch] Scrape pages the 5 purpose-built tools don't cover. Two input modes (pick one): ① content=bare fragment (keyword / nodeId / sellerId / ASIN) + site — backend builds a basic URL per parserName. **content mode carries NO filter/sort/pagination** — it's just the bare fragment. Best for simple pages when you only have the fragment. ② url=full Amazon link — **put ANY filter/sort/pagination into this url** (the only way, since content mode can't). Filter syntax examples: price $25-50 → '/s?k=earbuds&low-price=25&high-price=50'; sort by reviews → '&s=review-rank'; paginate → '&page=2'; category+price → '/s?i=aps&rh=n%3A172282&fs=true&low-price=25'. Use when: a standard tool can't build the target URL — "search X but only $25-50" / "results sorted by reviews" / "category filtered by price"; or the user already has a specific Amazon link. For any filtering, use url mode. Don't use: when a purpose-built tool fits — plain keyword search → search_a

• parserNamestringrequiredParser deciding how the backend extracts the page AND builds the URL from content. Must match the page type: amzKeyword=keyword search (content=keyword) / amzProductOfCategory=category (content=nodeId) / amzProductOfSeller=seller storefront (content=sellerId) / amzProductDetail=single product (content=ASIN) / amzBestSellers / amzNewReleases / amzReviewV2=reviews / amzFollowSeller=follow-seller / amzVariantAsin=variant.
• contentstringBare fragment (backend builds the URL per parserName). Pass this OR url. Examples: 'wireless earbuds' (amzKeyword) / '172282' (nodeId for amzProductOfCategory) / 'ATVPDKIKX0DER' (sellerId for amzProductOfSeller) / 'B09B8V1LZ3' (ASIN for amzProductDetail). Users/AI usually only have the fragment — prefer this.
• urlstringFull Amazon URL (https://). Pass this OR content. Use when you already have a ready link (e.g. a filtered/sorted SERP copied from the browser). Example: 'https://www.amazon.com/s?k=earbuds&rh=p_36%3A2500-5000&s=review-rank'. Must match parserName.
• sitestringAmazon site (in content mode the backend picks the domain from this). Defaults to amz_us. Optional in url mode (the URL already has the domain).
• formatstringResponse format. Defaults to 'json' (structured results). Use 'markdown' for the rendered page text.
• zipcodestringZIP code matching the site's country. Optional; backend picks one if omitted.

[Amazon Rufus AI conversational recommendations] Ask Amazon's AI shopping assistant Rufus in natural language, get grouped structured product recommendations + Rufus text reply + follow-up questions. Use when: user says "ask Amazon AI X" / "Rufus recommendations" / "find products conversationally" / "products for a scene (gifting / camping / moving)" / "open-ended sourcing" / "I have no keyword, just a scenario". Don't use: when you already have a clear keyword and want SERP (use search_amazon); category bestseller ranks (use list_bestsellers); single-ASIN detail (use get_amazon_product); Google-side AI search (use ai_search). Returns: data.json[{ prompt, content, products[{ title, items[{ asin,url,title,cover,score,ratingsCount,price,originalPrice,describe }] }], follow_up_questions[], screenshot }] + top-level taskId / url / screenshot. Note: follow_up_questions is snake_case (passed through from backend verbatim). Pair with: ↓ feed asin into get_amazon_product / get_amazon_reviews f

• promptsarrayrequiredConversation prompts (zh or en). Each item is sent to Rufus independently and returns its own grouped results. **Billed per prompt: 6 points each** (N prompts = N×6 points, NOT a flat 6 per call). **Strongly prefer exactly 1 prompt per call**: this is a slow tool — 60–90s for one, and multiple add up linearly and can exceed 200s. Max 5, but multiple is both slow and costly; for several needs make several single-prompt calls. Examples: ['gifts for a 5-year-old who loves dinosaurs'] / ['camping gear under $50'].
• screenshotbooleanReturn the Rufus conversation screenshot URL. Defaults to false. Setting true adds backend load; only enable when you need an image proof for end users.