The Amazon All-in-One Scrape MCP server provides 18 tools for AI assistants to perform comprehensive Amazon e-commerce research, IP data lookups, and market intelligence via natural language.
Amazon Product & Search
search_amazon: Keyword searches across 13 Amazon marketplaces (ASIN, price, ratings, sales, etc.)
get_amazon_product: Full product listing data for a single ASIN (title, bullets, reviews, variants, AI summary)
get_amazon_reviews: Batch-scrape buyer reviews with filters for star rating, sort order, and media type
scrape_url: Power-user escape hatch to scrape any Amazon URL with custom filters and pagination
Rankings & Seller Research
list_bestsellers: Top-50 Best Sellers for any category with 24-hour rank change data
list_new_releases: Top-50 newest products (listed within 30 days) for any category
list_seller_products: All products in a seller's storefront by merchant ID
list_category_products: All products under a specific Amazon Browse Node ID
Category Navigation & Niche Discovery
search_categories: Find Amazon category nodes by keyword
get_category_children: Drill down the Amazon category tree level by level
get_category_paths: Resolve category IDs into full breadcrumb paths
filter_categories: Screen categories by 30+ business metrics (sales, search volume, conversion rate, return rate, etc.)
filter_niches: Discover blue-ocean niches using 50+ filters (competition, growth rate, brand age, launch trends, etc.)
AI-Powered Search & Trends
ai_search: Google SERP results including AI Overview summaries, organic results, and related searches
keyword_trends: Compare up to 5 keywords via Google Trends — time series, regional interest, and breakout queries
search_amazon_alexa: Query Amazon's Rufus AI shopping assistant with natural language for structured product recommendations
IP & Trademark Clearance
wipo_search: Search WIPO global design/trademark databases for IP risk clearance; optionally join US patent litigation (PACER) data via enableLitigation=true
Local Business Research
search_local_maps: Find local businesses via Google Maps by location coordinates
Free Utility
pangolinfo_capabilities: Free local introspection tool returning the full tool catalog, recommended workflows, and usage tips at zero API cost
Provides tools for Amazon e-commerce data: keyword search, product details, reviews, bestsellers, new releases, category navigation, niche discovery, and seller catalog queries.
Provides tools for Google AI Search (overview answers) and Google Trends (interest over time data).
Provides a tool for Google Maps local business search.
Pangolinfo MCP server — 18 Amazon e-commerce & IP data tools for AI assistants via Model Context Protocol.
🔗 Official site: www.pangolinfo.com
Plug your favorite AI client (Claude Code, Cursor, Cline, Windsurf, Codex, Hermes, OpenClaw) into Pangolinfo's Amazon scrape APIs and let the AI run real-time ad tracking, Sponsored Products analysis, VOC sentiment analysis, keyword monitoring, and competitor product audit — plus keyword research, listing analysis, review mining, niche discovery, category navigation, AI search lookups, keyword-trend checks, and WIPO trademark clearance — all from natural-language instructions.
⚠️ BREAKING CHANGE in 0.7.0 —
pacer_searchretired, merged intowipo_searchThe standalone
pacer_searchtool was removed. US patent-litigation (PACER) lookups are now reached by passingenableLitigation=truetowipo_search— it finds the patent and joins the related US litigation cases in a single call. Prompts/scripts pinningpacer_searchwill getToolNotFound; switch towipo_searchwithenableLitigation.
Old name (≤ 0.2.x)
New name (0.3.0+)
google_ai_search
ai_search
google_trends
keyword_trendsTool names changed to remove third-party brand references from the public MCP interface. Tool parameters, return shape, and pricing are unchanged.
Version |
|
Tools | 18 business tools (+ a free local |
Transport | stdio (local) · streamable HTTP (hosted — see below) |
Runtime | Node.js 18+ |
License | MIT |
Get an API key | https://tool.pangolinfo.com/#/en/system/loading?sourceTag=github_amz |
The Pangolinfo Installer detects your AI client, writes the right config files, and you're done. Pass --scope=mcp to install only this MCP server (skip the Skills package).
macOS / Linux
curl -fsSL https://pangolinfo.dev/install.sh | sh -s -- \
--agent=<your-agent> \
--scope=mcp \
--api-key=pgl_xxxxxxxxxxxxWindows (PowerShell)
irm https://pangolinfo.dev/install.ps1 | iex; `
Install-Pangolinfo -Agent <your-agent> -Scope mcp -ApiKey pgl_xxxxxxxxxxxx<your-agent> is one of: claude-code, cursor, cline, windsurf, codex, hermes, openclaw.
After the installer finishes, restart your AI client so it picks up the new mcpServers entry.
The release artifact is a single self-contained server.mjs (~800 KB) — all dependencies are bundled in. No npm install needed.
# macOS / Linux
mkdir -p ~/.local/lib/pangolinfo-mcp
curl -fsSL https://github.com/pangolinfo/pangolinfo-mcp/releases/latest/download/server.mjs \
-o ~/.local/lib/pangolinfo-mcp/server.mjs
chmod +x ~/.local/lib/pangolinfo-mcp/server.mjs# Windows (PowerShell)
$dir = "$env:LOCALAPPDATA\pangolinfo-mcp"
New-Item -ItemType Directory -Force -Path $dir | Out-Null
irm https://github.com/pangolinfo/pangolinfo-mcp/releases/latest/download/server.mjs `
-OutFile "$dir\server.mjs"Then wire it into your AI client — see the per-client snippets below. Point args at the file you just downloaded.
Developers: to build from source,
git clonethis repo and runnpm install && npm run build. The produceddist/server.mjsis identical to the release asset.
Related MCP server: logimu-shopping-mcp
Sign up at https://tool.pangolinfo.com/#/en/system/loading?sourceTag=github_amz
Copy your pgl_xxxxxxxx key from the dashboard
Top up credits if needed (each Amazon scrape call costs 0.75 credits; pangolinfo_capabilities is free)
Replace /abs/path/to/pangolinfo-mcp/dist/server.mjs with your real path, and pgl_xxxxxxxx with your key.
~/.claude/settings.json){
"mcpServers": {
"pangolinfo": {
"command": "node",
"args": ["/abs/path/to/pangolinfo-mcp/dist/server.mjs"],
"env": { "PANGOLINFO_API_KEY": "pgl_xxxxxxxx" }
}
}
}Prefer
claude mcp add --scope user pangolinfo node /abs/path/to/dist/server.mjs— it writes the same entry without hand-editing JSON.
~/.cursor/mcp.json){
"mcpServers": {
"pangolinfo": {
"command": "node",
"args": ["/abs/path/to/pangolinfo-mcp/dist/server.mjs"],
"env": { "PANGOLINFO_API_KEY": "pgl_xxxxxxxx" }
}
}
}Open Cline → MCP Servers → Edit settings JSON, then add:
{
"mcpServers": {
"pangolinfo": {
"command": "node",
"args": ["/abs/path/to/pangolinfo-mcp/dist/server.mjs"],
"env": { "PANGOLINFO_API_KEY": "pgl_xxxxxxxx" }
}
}
}The settings file lives at <vscode-user>/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json.
If you're on the standalone Cline CLI, use ~/.cline/data/settings/cline_mcp_settings.json instead.
~/.codeium/windsurf/mcp_config.json){
"mcpServers": {
"pangolinfo": {
"command": "node",
"args": ["/abs/path/to/pangolinfo-mcp/dist/server.mjs"],
"env": { "PANGOLINFO_API_KEY": "pgl_xxxxxxxx" }
}
}
}~/.codex/config.toml)[mcp_servers.pangolinfo]
command = "node"
args = ["/abs/path/to/pangolinfo-mcp/dist/server.mjs"]
[mcp_servers.pangolinfo.env]
PANGOLINFO_API_KEY = "pgl_xxxxxxxx"~/.hermes/config.yaml)mcp_servers:
pangolinfo:
command: node
args: ["/abs/path/to/pangolinfo-mcp/dist/server.mjs"]
env:
PANGOLINFO_API_KEY: pgl_xxxxxxxx~/.openclaw/openclaw.json){
"mcpServers": {
"pangolinfo": {
"command": "node",
"args": ["/abs/path/to/pangolinfo-mcp/dist/server.mjs"],
"env": { "PANGOLINFO_API_KEY": "pgl_xxxxxxxx" }
}
}
}Don't want to install anything? Point your AI client at the hosted endpoint
instead of a local server.mjs. This is the streamable HTTP transport
(MCP spec), multi-tenant — you bring your own key on every request.
Endpoint |
|
Transport | Streamable HTTP (POST + SSE) |
Auth | Your |
1. Authorization header (recommended)
Authorization: Bearer pgl_xxxxxxxxThis is the preferred method: the key stays out of URLs, logs, and browser
history. The Bearer scheme is matched case-insensitively (bearer,
BEARER, Bearer all work) and extra whitespace is tolerated.
2. ?api_key= URL query (fallback)
https://mcp.pangolinfo.com/mcp?api_key=pgl_xxxxxxxxEasiest for clients that only let you paste a URL. If your key contains URL-special characters, URL-encode it. The header (method 1) takes precedence if both are supplied.
"url"-style remote MCP){
"mcpServers": {
"pangolinfo": {
"url": "https://mcp.pangolinfo.com/mcp",
"headers": { "Authorization": "Bearer pgl_xxxxxxxx" }
}
}
}If your client can't set headers, fall back to the URL form:
"url": "https://mcp.pangolinfo.com/mcp?api_key=pgl_xxxxxxxx".
If you're calling the endpoint directly (not through a standard MCP client):
POST your JSON-RPC body to /mcp.
The MCP streamable transport normally requires the request to advertise
both application/json and text/event-stream in its Accept header.
This server backfills the missing media type for you, so a plain
Accept: application/json, Accept: */*, or even a missing Accept
header all work — you don't need to hand-craft it.
A 401 means the key was not found in either the header or the
query string — check that your client actually sent it (some libraries
drop the Authorization header on cross-origin redirects).
See MCP-TOOLS-MAP.md for the full coordination graph (which tools chain into which).
# | Tool | Purpose | Cost (credits) |
1 |
| Amazon keyword search → structured product list | 0.75 |
2 |
| Single-ASIN listing detail (title / bullets / features / aiReviewsSummary) | 0.75 |
3 |
| Batch reviews for an ASIN (VOC mining) | 0.75 |
4 |
| Amazon Bestsellers by category | 0.75 |
5 |
| Amazon New Releases by category | 0.75 |
6 |
| Catalog of products under one seller | 0.75 |
7 |
| All products in a category leaf | 0.75 |
8 |
| Search Amazon category tree by keyword | 0.75 |
9 |
| Drill down one level in the category tree | 0.75 |
10 |
| Filter category nodes by criteria | 0.75 |
11 |
| Niche discovery (size × competition × growth) | 0.75 |
12 |
| Resolve full ancestor paths for a category node | 0.75 |
13 |
| Google Maps local business search | 0.75 |
14 |
| WIPO global design / trademark search (IP clearance). Set | 2 (+12 when |
15 |
| AI Search via Google SERP (AI Overview + organic, with compliance disclaimer) | 2 |
16 |
| Keyword Trends via Google Trends (with compliance disclaimer) | 1.5 |
17 |
| Power-user escape hatch: scrape a raw Amazon URL + parserName (non-standard pages) | 0.75 |
18 |
| Amazon Rufus AI conversational product picks (scene-based, no keyword) | 6 |
Plus a free local call:
pangolinfo_capabilitiesreturns the full tool catalog, canonical workflows, and usage tips with no backend round-trip (0 credits). It is a self-introspection helper, not one of the 18 data tools.
Default marketplace is Amazon US (marketplaceId=ATVPDKIKX0DER, zip=90001). Override per call via tool arguments.
Two tools legitimately run long because they wait on live AI generation:
Tool | Typical latency | Worst case |
| 60–90s per prompt | >200s for multiple prompts |
| ~30s | ~60s |
Most MCP clients enforce a per-tool-call timeout — often 60 seconds of silence — and abort the call if nothing comes back in time. When that happens the client reports a transport-level timeout/disconnect, and the agent mistakes it for "the tool is unavailable/broken." This is the usual reason search_amazon_alexa gets flagged as unavailable — it reliably crosses the silent 60s line.
Two things keep this from happening:
The server emits progress heartbeats. While a tool runs, the server sends a notifications/progress every 15s if your client included a progressToken in the call. Spec-compliant clients reset their idle timeout on each heartbeat, so the whole 60–90s render stays under the wire. Most modern MCP clients send a progressToken automatically — no action needed.
Raise the client timeout for clients that don't honor progress. If your client has no progressToken support or a hard cap, bump its MCP tool-call timeout to ≥120s before using search_amazon_alexa. Where to set it depends on the client (examples):
Claude Code / config-based clients: raise the MCP request/tool timeout in the client config.
Custom SDK clients: pass a larger timeout (and, ideally, a progressToken) in the callTool request options.
Also prefer exactly one prompt per search_amazon_alexa call — multiple prompts stack latency linearly and make the timeout far more likely.
The server resolves the API key with this priority:
CLI args: --api-key=pgl_xxx --api-base=... --scrape-base=...
Env vars: PANGOLINFO_API_KEY, PANGOLINFO_API_BASE, PANGOLINFO_SCRAPE_BASE
Config file at ~/.pangolinfo/config.json:
{
"api_key": "pgl_xxxxxxxxxxxx",
"api_base": "https://extapi.pangolinfo.com",
"scrape_base": "https://scrapeapi.pangolinfo.com"
}Missing key → startup failure with an actionable error.
CLI args win over env vars — convenient when you want per-server keys without polluting the global environment.
Tool descriptions and error hints are available in English and Chinese. The
language is resolved in this order: --lang=zh|en → PANGOLINFO_LANG=zh|en → OS locale
($LANG starting with zh* → Chinese, otherwise English) → English when there is no
locale signal at all. So a Chinese-locale machine gets Chinese automatically; everyone
else gets English. Force a language explicitly:
"env": {
"PANGOLINFO_API_KEY": "pgl_xxxxxxxx",
"PANGOLINFO_LANG": "zh"
}Startup logs are always English (operator-facing); tool descriptions and error hint fields follow the resolved locale.
After restarting your AI client, ask it:
List all available
pangolinfoMCP tools.
You should see 18 tools. Then try:
Use
pangolinfo_capabilitieswith mode "summary".
This is a free local call — if it returns the tool catalog, your install is wired correctly. Next, run something paid like:
Search Amazon for "wireless mouse" and return the top 5 results.
Expected: ~0.75 credits deducted, ~300 KB of structured product data returned.
npm install
npm run dev # tsx src/server.ts — hot-reload
npm run build # esbuild → dist/server.mjs
npm run typecheck # tsc --noEmit
npm start # node dist/server.mjssrc/
├── server.ts MCP stdio entry + tool registration
├── auth.ts API key resolution (CLI > env > config file)
├── client.ts HTTP client (Authorization, User-Agent)
├── errors.ts PangolinfoError + status-code mapping
├── config.ts Default endpoints / constants
├── i18n.ts zh/en translation lookup
└── tools/
├── _types.ts Tool / ToolContext type definitions
├── index.ts Tool registry (18 tools + capabilities)
└── <verb_noun>.ts One file per toolCreate src/tools/<verb_noun>.ts exporting a Tool object — mirror search_amazon.ts.
Import it in src/tools/index.ts and append to the tools array.
Schema is zod; .describe() every field — the AI reads those.
Never call fetch directly — use ctx.client.post(...). Auth is already injected.
Throw PangolinfoError on failure; the HTTP client already throws this for non-2xx responses.
We take operator and user safety seriously. By design, this MCP server:
Brings your own key. Authentication is via your personal PANGOLINFO_API_KEY (issued at https://tool.pangolinfo.com/#/en/system/loading?sourceTag=github_amz). The key is read locally from your AI client's config or environment — it is never transmitted anywhere except to https://scrapeapi.pangolinfo.com (or https://mcp.pangolinfo.com for the hosted variant) over TLS 1.2+.
No telemetry. This server does not phone home, does not collect usage analytics, and does not log your prompts. The only outbound traffic is the actual Amazon / Google / WIPO scrape API calls you explicitly invoke through tools.
No PII collection. No user account info, no email, no IP geolocation, and no prompt content is persisted by this server. Tool calls forward only the parameters you (or the AI agent) supplied.
Read-only. Every tool is a strictly read-only data lookup. None of them can write to Amazon, place orders, post reviews, modify listings, or take any side-effecting action on third-party platforms.
HTTPS-only transport. Both the stdio variant (local) and the hosted variant (https://mcp.pangolinfo.com/mcp) require HTTPS; HTTP requests are refused.
Open source. The full source is in this repository under MIT license — anyone can audit what the server sends and where.
Responsible use. Pangolinfo APIs aggregate public e-commerce data. You are responsible for using the returned data in compliance with the terms of service of the underlying platforms (Amazon, Google, etc.) and with applicable laws in your jurisdiction.
Report security issues privately to security@pangolinfo.com — please do not file public GitHub issues for vulnerabilities.
API docs: https://docs.pangolinfo.com
Email: support@pangolinfo.com
MIT © Pangolinfo
[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. 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,text}] }, { type:'related_searches', items:[...] } ], screenshot, taskId }. Pair with: ↑ query inferred from user; in 'ai_mode' pass followups[1..5] for multi-turn; ↓ ai_overview.references[].url for authoritative external sources, organic items for content-competition analysis. Cost: ~2 points/call, ~30s (slow — Google AI render time). Tips: prefer overview for single queries (cheaper); use ai_mode only when you need decomposed multi-turn investigation. Followups > 5 visibly slow down responses.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | Search 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). | |
| mode | No | Search 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. | overview |
| followups | No | Follow-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.** | |
| screenshot | No | Whether to return a screenshot URL of the rendered search page. Defaults to false. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses cost (~2 points), slowness (~30s), return format structure, behavioral differences between modes, followups limit, and legal compliance. No annotations exist, so description carries full burden and meets it comprehensively.
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?
Description is moderately long but well-structured with sections. Every sentence adds value, though a minor reduction could improve conciseness without losing information.
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?
Given 4 parameters and no output schema, the description covers input semantics, behavioral traits, return format, cost, usage guidance, and integration hints. No gaps identified.
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%, but description adds significant value: query examples, mode behavior explanation, followups degradation warning, screenshot purpose. This goes beyond the schema's basic descriptions.
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?
Description clearly states the tool scrapes Google search results with two modes. It distinguishes from siblings by mentioning on-Amazon vs external search and trend-curve tools.
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 cases are listed (e.g., 'Google for me', 'consumer voice' step) and explicit non-use cases (on-Amazon, trend curve) with alternative tools named. Also provides pairing guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
[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, avgAdSpendPerClick, unitSoldTrendDirection, unitSoldChangeRateBucket, ... trend + quantile-bucket fields }] + data.items.pagination.{ total, page, size, hasNext }. Pagination: use the 'page' param (default 1, 1-based, size capped at 10); 'pagination.hasNext=true' means more pages exist, 'hasNext=false' means last page. Pair with: ↑ required timeRange ('l7d' common) + sampleScope ('all_asin') + marketplaceId (defaults US); categoryId from search_categories / get_category_children; ↓ feed high-potential categories into list_category_products / list_bestsellers for real listings. Cost: ~1 point/page, ~5s. Tips: size capped at 10 (backend hard limit); only paginate when the user explicitly asks for more candidate categories — single-detail or quick-filter calls are fine on page 1; long-tail filter fields (unitSoldTrendDirections / metricChangeRateBuckets / dozens more) pass through via extraFilters.
| Name | Required | Description | Default |
|---|---|---|---|
| marketplaceId | No | Amazon marketplace id. Common: US, UK, DE, JP, FR, IT, ES, CA. Defaults to US. | US |
| timeRange | Yes | Aggregation time range (required). Examples: 'l7d' (last 7 days — verified working). The exact enum is backend-defined; 'l7d' is the safest known value. | |
| sampleScope | Yes | Sample scope (required). Examples: 'all_asin' (all ASINs — verified working). | |
| categoryId | No | When 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'. | |
| page | No | Page number, 1-based. | |
| size | No | Page size, max 10 (backend hard limit). | |
| sortField | No | Sort field; any response field name is accepted (e.g. 'unitSoldSum', 'netShippedGmsSum'). | |
| sortOrder | No | Sort order: 'asc' or 'desc'. | |
| unitSoldSumMin | No | Min total units sold. | |
| unitSoldSumMax | No | Max total units sold. | |
| netShippedGmsSumMin | No | Min total GMS (gross merchandise sales). | |
| netShippedGmsSumMax | No | Max total GMS. | |
| searchVolumeSumMin | No | Min total search volume. | |
| searchVolumeSumMax | No | Max total search volume. | |
| buyBoxPriceAvgMin | No | Min average buy-box price (marketplace currency). | |
| buyBoxPriceAvgMax | No | Max average buy-box price. | |
| buyBoxPriceTiers | No | Price-tier filter. Allowed: budget, mainstream, premium, luxury. | |
| returnRatioLevels | No | Return-rate quality buckets. Allowed: excellent, average, risk. | |
| searchToPurchaseRatioLevels | No | Search-to-purchase conversion buckets. Allowed: to_improve, average, excellent. | |
| extraFilters | No | Pass-through for any other upstream filter (e.g. unitSoldTrendDirections, newAsinCountLevels, metricChangeRateBuckets). Keys must match the upstream doc verbatim. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses cost (~1 point/page, ~5s), pagination limits, and extraFilters pass-through. No annotations, so description covers behavior adequately, though could explicitly state read-only nature.
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?
Well-structured with purpose upfront, then usage, don't-use, returns, pairing, cost, and tips. Slightly long but every sentence adds value; could be more concise.
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 tool with 20 parameters and no output schema, the description covers return structure, pagination, cost, and limitations. Additional info like example field names and pairing with other tools enhances completeness.
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?
All parameters have schema descriptions (100% coverage). Description adds context: categoryId dual role, timeRange examples, pagination limits, and extraFilters usage. Adds value beyond schema.
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?
Clearly states it filters categories by metrics or acts as a detail endpoint. Distinguishes from siblings like filter_niches and list_category_products.
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?
Explicitly lists when to use (e.g., 'find categories worth entering') and when not to use, with specific alternative tools. Provides pairing and pagination tips.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
[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, primeProductsPercentage, top5ProductsClickShare, top20BrandsClickShare, brandCount, sellingPartnerCount, avgBrandAge, avgBestSellerRank, avgProductPrice, avgReviewCount, avgReviewRating, avgDetailPageQuality, newProductsLaunchedT180/T360, successfulLaunchesT90/T180/T360, returnRateT360, fee fields T365 … 100+ fields }] + data.items.pagination.{ total, page, size, hasNext }. Pagination: use the 'page' param (default 1, 1-based, size capped at 10 (default 3)); 'pagination.hasNext=true' means more pages exist, 'hasNext=false' means last page. Pair with: ↑ marketplaceId required (defaults US); nicheTitle for keyword filter, nicheId for single-niche detail; ↓ feed referenceAsin into get_amazon_product to see the representative product; niche doesn't carry a categoryId directly — derive separately if needed. Cost: ~1 point/call, ~5s. Tips: size capped at 10 (default 3); pass long-tail filters (50+ fields) via extraFilters; classic blue-ocean combo = high searchVolumeT90Min + low top5ProductsClickShareT360Max + moderate productCountMax + positive searchVolumeGrowthT90Min + returnRateT360Max ≤ 0.10 (low-return). For return-rate filtering use returnRateT360Max (upper bound, 0-1 decimal); the response includes returnRateT360 with the actual return rate.
| Name | Required | Description | Default |
|---|---|---|---|
| marketplaceId | No | Amazon marketplace id (required). Common: US, UK, DE, JP, FR, IT, ES, CA. Defaults to US. | US |
| nicheId | No | When 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). | |
| nicheTitle | No | Keyword match against niche titles. Examples: 'iphone 16 wallet case' / 'wireless earbuds for sports'. | |
| page | No | Page number, 1-based. | |
| size | No | Page 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). | |
| sortField | No | Sort field; any response field name is accepted (e.g. 'searchVolumeT90', 'avgProductPrice'). | |
| sortOrder | No | Sort order: 'asc' or 'desc'. | |
| searchVolumeT90Min | No | Min search volume over last 90 days. | |
| searchVolumeT90Max | No | Max search volume over last 90 days. | |
| searchVolumeT360Min | No | Min search volume over last 360 days. | |
| searchVolumeT360Max | No | Max search volume over last 360 days. | |
| searchVolumeGrowthT90Min | No | Min 90-day search-volume growth rate (decimal, 0.1 = +10%). | |
| searchVolumeGrowthT90Max | No | Max 90-day search-volume growth rate. | |
| minimumPriceMin | No | Lower bound on the niche's minimum product price. | |
| maximumPriceMax | No | Upper bound on the niche's maximum product price. | |
| productCountMin | No | Min product count in the niche. | |
| productCountMax | No | Max product count in the niche. | |
| avgReviewCountMin | No | Min average review count. | |
| avgReviewCountMax | No | Max average review count — lower means less competition. | |
| avgReviewRatingMin | No | Min average review rating (0-5). | |
| top5ProductsClickShareT360Max | No | Max top-5-products click share over 360 days (0-1). Lower = more fragmented niche, more opportunity. | |
| returnRateT360Max | No | Max return rate over 360 days (0-1). | |
| extraFilters | No | Pass-through for any other upstream filter (e.g. sponsoredProductsPercentageT360Min, successfulLaunchesT360Max, avgBestSellerRankMax). Keys must match the upstream doc verbatim. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully discloses pagination behavior (page 1-based, size capped at 10, default 3, hasNext flag), cost (~1 point, ~5s), and filter range semantics (e.g., return rate as decimal 0-1).
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?
Well-structured with clear sections (use, don't use, returns, pair with, cost, tips), front-loaded with purpose, and every sentence adds value without redundancy.
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 tool with 23 parameters, no output schema, and no annotations, the description is comprehensive: covers pagination, cost, return fields, filter examples, and pairings, making it fully actionable.
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%, but the description adds critical context: size default rationale (AI context limits), extraFilters pass-through, sortField accepting any response field, and a classic blue-ocean filter combo.
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 clearly states it filters Amazon niches by 50+ commercial metrics, serves as a niche detail endpoint, and explicitly distinguishes from sibling tools like filter_categories and search_amazon.
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?
Provides explicit when-to-use examples (blue ocean, high search/low competition, niche detail) and when-not-to (full categories, products, plain keyword search) with alternative tool names.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
[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-10). Cost: ~1 point/call, ~5s.
| Name | Required | Description | Default |
|---|---|---|---|
| asin | Yes | Amazon ASIN, 10 chars uppercase. Examples: 'B09B8V1LZ3' (Echo Dot 5) / 'B0CRMZHDG8' (Stanley Quencher) / 'B0BDHWDR12' (AirPods Pro 2). | |
| site | No | Amazon marketplace. Defaults to 'amz_us' (US). | amz_us |
| zipcode | No | ZIP 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). | |
| format | No | Response 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. | json |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description carries full burden. It discloses cost (~1 point/call, ~5s), that PDP carries only ~5-10 reviews, and details the return structure. This is highly transparent.
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?
Every sentence is purposeful, structured with clear sections (use/don't use/returns/pair/cost). There is zero waste, and it is front-loaded with the core purpose.
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 fully enumerates the return fields. It covers cost, timing, pairing, and limitations. The description is complete for an agent to invoke 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 coverage is 100%, but the description adds value with examples (ASIN examples), usage context for zipcode (cross-country rejection), and format explanations (json vs markdown). It also outlines the entire return object.
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 starts with 'Scrape the full PDP for one ASIN', which is a specific verb+resource. It clearly distinguishes from siblings like search_amazon and get_amazon_reviews.
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 when-to-use (specific ASIN, SOP step), when-not-to-use (many products, reviews only), and alternatives (search_amazon, list_*, get_amazon_reviews) are all provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
[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 to confirm data, scale to 3-5 only when needed. Prefer filterByStar='critical' — highest signal density. Tips: filterByStar = all_stars / five_star ... one_star / positive / critical; sortBy = recent (default) | helpful; mediaType = all_contents (default) | media_reviews_only (with photos/videos, higher credibility).
| Name | Required | Description | Default |
|---|---|---|---|
| asin | Yes | Amazon ASIN (10-char uppercase alphanumeric). Examples: 'B09B8V1LZ3' / 'B0CRMZHDG8'. | |
| site | No | Amazon marketplace. Defaults to amz_us. | amz_us |
| pageCount | No | Number of review pages to fetch (~10 reviews per page). **Costs 10 points per page** — control accordingly. Defaults to 1. | |
| filterByStar | No | Filter by star rating. For VOC pain-point mining, pass 'critical' (1-3 star reviews) to surface defects; for positive-aspect extraction, pass 'positive'. | all_stars |
| sortBy | No | Sort order: 'recent' (newest first — track current sentiment) or 'helpful' (most-upvoted first — highest impact reviews). | recent |
| mediaType | No | Review type: 'all_contents' for all, 'media_reviews_only' for reviews with photos/videos only (higher credibility). | all_contents |
| zipcode | No | ZIP 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). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, but description fully discloses expensive cost (10 points per page), recommends starting with pageCount=1, and provides strategic tips on filters. Also explains return structure and pairing with other tools for downstream tasks.
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?
Well-structured with sections (use when, don't use, returns, cost, tips) and front-loaded with purpose. Though lengthy, each sentence adds value; slight reduction possible without losing clarity.
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?
No output schema, but description provides detailed return structure (fields like reviewId, date, star, content) and explains pairing with other tools. Covers all aspects for a complex 7-param tool with enums and strategic advice.
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%, baseline 3. Description adds significant value by explaining the purpose of each filter (e.g., 'critical' for pain-point mining), giving usage examples, and providing cost/strategy tips beyond schema details.
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?
Clearly states batch scraping of real buyer reviews for an ASIN with filtering options. Uses specific verb 'page-fetch' and resource 'reviews', distinguishing from get_amazon_product which carries only 5-10 reviews.
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?
Explicitly lists use cases (e.g., 'look at X's negative reviews', 'mine pain points') and when not to use (when PDP reviews suffice or for keyword search), with alternative tools named (get_amazon_product, search_amazon).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
[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 either omitted (roots) or from search_categories; ↓ feed each result's browseNodeIdPath back in to drill another level, or into list_category_products / filter_categories. Cost: ~1 point/page, ~3s. Only paginate when a node has unusually many children (>size) and the user explicitly wants all subcategories.
| Name | Required | Description | Default |
|---|---|---|---|
| parentBrowseNodeIdPath | No | Parent 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. | |
| page | No | Page number, 1-based. | |
| size | No | Page size. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It discloses response structure (fields like browseNodeId, hasChild), pagination details (page, size, hasNext), cost (~1 point/page, ~3s), and a usage caveat (only paginate when necessary).
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?
Description is detailed but well-structured: purpose first, then usage guidelines, return details, pairing, cost. Every sentence adds value. Could be slightly more concise, but front-loading ensures agent gets key info quickly.
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?
Given no annotations and no output schema, description covers all essential aspects: purpose, when to use vs avoid, parameter details, return structure, pagination, cost, and pairing with siblings. No gaps for an agent to invoke 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 has 100% coverage, but description adds value by explaining parameter usage beyond schema: examples of parentBrowseNodeIdPath values (e.g., '2619526011'), how omitting it fetches roots, and pagination parameter behavior (defaults, max size). Adds context without redundancy.
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 clearly states the tool lists direct children of a category node in Amazon's category tree, using specific verbs ('List direct children') and resources ('from any node or start at roots'). It distinguishes from siblings like search_categories (keyword jump) and list_category_products (products vs subcategories).
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?
Explicitly provides when to use (e.g., 'show me Amazon's category tree', 'subcategories under X', 'list top-level departments') and when not to use (keyword jumps, product listing). Also mentions pairing with sibling tools like search_categories and list_category_products.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
[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).
| Name | Required | Description | Default |
|---|---|---|---|
| categoryIds | Yes | Category IDs to resolve full path for. Examples: ['2619526011'] (Appliances) / ['172282', '11965861'] (Electronics + Musical Instruments). | |
| site | No | Amazon marketplace. Defaults to 'amz_us' (US). | amz_us |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It discloses cost (~1 point/call), speed (~2s), and that it's cheaper than N single resolutions. Also notes downstream rarely depends on it (presentation-only). No contradictions.
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?
Description is well-organized into sections with bullet points for returns and pairing. Slightly verbose but each sentence adds value. Could be slightly more concise but no waste.
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?
No output schema, but description explains return structure in detail (data.items with fields). Parameter meanings are clear from schema and description. For a simple 2-param tool, this is fully complete.
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% with both parameters having descriptions. The description adds context beyond schema: provides example paths, explains batch behavior, and details return format. Baseline 3, increased due to added value.
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?
Description clearly states it batch-resolves category IDs to full paths with an example ('Electronics > Headphones'). Explicitly distinguishes from sibling tool get_category_children (tree structure) and notes other tools already return browseNodeNamePath for single IDs.
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?
Explicitly states when to use (need readable category context, multiple IDs) and when not to use (single ID, tree structure). Also mentions pairing with prior steps like filter_niches/filter_categories output.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
[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 user or core terms found via search_amazon; ↓ feed Breakout/rising terms back into search_amazon to explore new opportunities, or filter_niches to see if they've crystallized into a niche. Cost: ~1.5 points/call, ~5s. Tips: timeRange = today 12-m (default) | today 3-m | today 5-y | all ; region = ISO country code or 'WORLD'; language affects related-query language.
| Name | Required | Description | Default |
|---|---|---|---|
| keywords | Yes | Keywords to compare (1-5). Examples: ['wireless earbuds', 'bluetooth earbuds'] (synonyms) / ['stanley quencher', 'yeti rambler', 'hydro flask'] (competing brands) / ['halloween costume'] (single keyword for seasonality). | |
| timeRange | No | Time 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). | today 12-m |
| region | No | Region code (ISO country, or 'WORLD' for global). Common: 'US' / 'GB' / 'DE' / 'JP' / 'CN'. | US |
| language | No | Interface language (BCP-47), affects related-query language. Defaults to 'en-US'. Use 'zh-CN' for Chinese. | en-US |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses cost (~1.5 points/call, ~5s), data source (Google Trends), limitations (relative scale 0-100, not absolute), and tips for timeRange, region, language. Since no annotations exist, the description fully covers behavioral traits.
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?
Well-structured with bolded sections, bullet points, and clear separation of sections. Slightly verbose but every sentence adds value. Could be tightened, but remains effective.
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?
Returns are described in detail (data.json structure with keywordsGeoData, timelineData, etc.) despite no output schema. Cost and tips are included. The description covers all critical aspects for agent invocation.
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 has 100% description coverage. The description adds meaningful context beyond defaults: examples for keywords (synonyms, competing brands, seasonality), highlights common timeRanges, and explains language influences related-query language.
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 opens with 'Keyword Trends via Google Trends' and clearly explains it provides popularity time series, per-region heatmap, and rising related queries. It also explicitly distinguishes from siblings by stating it is not for absolute search volume or products/links, and requires at least 2 keywords for meaningful comparison.
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?
Provides explicit 'Use when' and 'Don't use' sections with many concrete scenarios e.g., 'how hot is keyword X', 'A vs B popularity', 'find breakout terms'. Also gives pairing instructions with sibling tools like search_amazon and filter_niches.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
[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.
| Name | Required | Description | Default |
|---|---|---|---|
| categorySlug | Yes | Amazon 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. | |
| site | No | Amazon marketplace. Defaults to amz_us. | amz_us |
| zipcode | No | ZIP 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). | |
| format | No | Response format. Defaults to 'json' — structured Top-50 ranked ASIN list. Use 'markdown' for the rendered page text. | json |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses the cost (~1 point, ~5s), response structure details (including nested JSON), and behavior of the zipcode parameter (optional, random when omitted). It could mention rate limits or authentication, but the provided information is sufficient for safe invocation.
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 exceptionally well-structured: a bold summary, then clear 'Use when', 'Don't use', 'Returns', 'Pair with', and 'Cost/Tips' sections. Every sentence adds value without redundancy. It is packed with information while remaining easy to scan.
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 having no output schema, the description thoroughly explains the return value structure, including the need to parse recsList twice and the fields within each row. It also covers cost, tips, and parameter behavior. For a tool with 4 parameters, this is complete.
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 the baseline is 3. The description adds value by explaining how to find the categorySlug (via URL), the meaning of the zipcode parameter with examples, and the purpose of the format parameter. This extra context elevates the score above the baseline.
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 opens with a clear statement: 'Top-50 ranking for a category with 24h rank deltas.' It specifies the resource (Amazon Best Sellers), the verb (list), and key features (rank, deltas). It also distinguishes from siblings like list_new_releases and list_category_products, making the 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?
The description provides explicit 'Use when' scenarios (e.g., 'user says X category bestsellers'), explicit 'Don't use' cases with alternatives (e.g., 'for new arrivals use list_new_releases'), and pairing suggestions with other tools. Tips for obtaining the categorySlug and cost/time estimates further guide appropriate use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
[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_children (tree drilldown); ↓ asin into get_amazon_product; same categoryId can also feed filter_categories for aggregate metrics. Cost: ~1 point/page, ~5s. Only paginate when the user explicitly asks for more / all results — otherwise the first page is enough.
| Name | Required | Description | Default |
|---|---|---|---|
| nodeId | Yes | Amazon category Browse Node ID (numeric). Examples: '172282' (Electronics) / '2619526011' (Appliances) / '11965861' (Musical Instruments). Obtain via search_categories or get_category_children. | |
| site | No | Amazon marketplace. Defaults to amz_us. | amz_us |
| zipcode | No | ZIP 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). | |
| format | No | Response format. Defaults to 'json' — structured category listings. Use 'markdown' for the rendered page text. | json |
| page | No | Page 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. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses pagination logic (page param, nextPage, maxPage), cost (~1 point/page, ~5s), and explicit instruction to only paginate when user asks. No annotations exist, but description fully covers behavioral traits.
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?
Long but well-structured: core purpose first, then guidelines, return format, pagination, pairing, cost. Every sentence earns its place, but slightly verbose with repetition of pagination info in both description and param section.
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?
With no output schema, description details return structure and pagination behavior. Covers pairing, cost, and when to paginate. Complete for a complex tool with five parameters.
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%, but description adds context: nodeId sources, zipcode cross-country rejection, format 'markdown' usage, and pagination details for page param. Each parameter is enriched with usage examples.
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 clearly states it lists on-sale products under a Browse Node ID, paginated with 24 rows per page. It distinguishes from siblings like list_bestsellers and filter_categories, making the purpose unambiguous.
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?
Explicitly states when to use (category listing after picking nodeId) and when not to use (top 50 winners, aggregate metrics, niche). Also specifies pairing with other tools, providing comprehensive guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
[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_', 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.
| Name | Required | Description | Default |
|---|---|---|---|
| categorySlug | Yes | Amazon New Releases category slug (lowercase, hyphenated). Examples: 'electronics', 'home-garden'. Find these in the URL path on amazon.com/gp/new-releases. | |
| site | No | Amazon marketplace. Defaults to amz_us. | amz_us |
| zipcode | No | ZIP 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). | |
| format | No | Response format. Defaults to 'json' — structured ranking list. Use 'markdown' for the rendered page text. | json |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
In the absence of annotations, the description fully discloses behavior: backend cap, cost (~1 point/call, ~5s), and detailed return structure including parsing instructions for recsList. No contradictions.
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?
Despite length, description is well-structured with clear sections (what, use when, don't use, returns, pair with, cost). Each sentence adds value; no redundancy.
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?
Given 4 parameters and no output schema, the description provides complete guidance: param details, return format with parsing, pairing suggestions, and cost. All necessary information for correct invocation is present.
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%, but the description adds extra context (e.g., where to find categorySlug, cross-country zip rejection, format usage). This goes beyond the schema descriptions, justifying a score above baseline 3.
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 clearly states it returns the top-50 best-selling new releases (within 30 days) for a category, with explicit mention of 'Amazon New Releases' and backend cap. It distinguishes from siblings by specificity to new releases.
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?
Explicitly lists when to use (e.g., 'new arrivals', 'breakout new products') and when not to use (e.g., 'for evergreen winners use list_bestsellers'). Provides clear alternatives and context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
[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. 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 are blanked (pages already merged). Category filter: categoryId filters the seller's products by category. Pair with: ↑ sellerId usually from get_amazon_product's seller.id field, or from amazon.com/sp?seller=... URL; categoryId extractable from the storefront URL's rh=n:; ↓ feed asin into get_amazon_product to deep-dive hero products. Cost: ~1 point/page, ~5s; pageCount=N billed by pages actually crawled (failed pages refunded). Tips: use pageCount to grab the full multi-page SKU set in one shot (max 3 pages); use page to view one specific page; the first page is enough to glance at what the store sells. Amazon first-party sellerId = 'ATVPDKIKX0DER'.
| Name | Required | Description | Default |
|---|---|---|---|
| sellerId | Yes | Amazon 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. | |
| site | No | Amazon marketplace. Defaults to amz_us. | amz_us |
| zipcode | No | ZIP 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). | |
| format | No | Response format. Defaults to 'json' — structured seller listings. Use 'markdown' for the rendered page text. | json |
| page | No | Page 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). | |
| pageCount | No | Multi-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). | |
| categoryId | No | Category 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. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully bears the burden of behavioral disclosure. It details two pagination modes (page vs pageCount), how pageCount merges pages, what happens to response fields when multi-page accumulate is used (pageIndex/nextPage blanked), billing (1 point/page), timing (~5s), and error handling (failed pages refunded).
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 well-structured with paragraphs, bullet points, and clear headings. It front-loads the core purpose and usage guidance. While it is lengthy, every sentence adds value – the tool is complex and requires this level of detail. A slight improvement could be further condensing the 'Tips' section into the parameter descriptions.
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 having no output schema, the description explicitly documents the response structure (data.json[0].data.{ pageIndex, maxPage, nextPage, results[...] }) and explains how to iterate with nextPage. It covers all parameters, two pagination modes, category filtering, marketplace defaults, and integration with sibling tools. For a 7-parameter tool with multiple modes, this is very complete.
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?
The input schema already has 100% coverage, but the description adds substantial context: how to find sellerId (from product page 'sold by' link or amazon.com/sp URL), zipcode cross-country rejection, the difference between page and pageCount (one locates a specific page, the other accumulates), and how to extract categoryId from storefront URL. This goes far beyond what the schema alone provides.
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 opens with a specific verb and resource: 'List all listings under a merchant ID, paginated (24 rows/page).' It immediately communicates the tool's scope (entire catalog of a seller) and distinguishes it from single-product tools like get_amazon_product.
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?
The description provides extensive usage guidance: explicit use cases ('show me this seller's products', 'competitor storefront category breadth'), a clear 'Don't use' section (requires merchant ID, not for single product), and pairs with sibling tools (get_amazon_product for deep-dives). It even explains how to extract the required sellerId.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
[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).
| Name | Required | Description | Default |
|---|---|---|---|
| detail | No | '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). | summary |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description fully bears the burden. Discloses that it's local with no backend call, cost 0 points, and returns a specific structure. No contradictions; all behavioral traits are clearly stated.
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 well-structured with clear sections (purpose, use cases, don't use, returns, pairing, cost). However, it is slightly verbose; could streamline some phrasing without losing meaning. Still very effective.
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?
Given no output schema, the description provides a detailed return structure (version, locale, tools, workflows, tips). Parameter semantics fully covered. Context about cost and usage pairs is complete. Siblings are many but tool's unique role is clear.
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% with one parameter 'detail'. Description adds value by explaining the enum values ('summary' vs 'full') and their effects, including token size estimates. This goes beyond the schema's description.
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 clearly defines the tool as a self-introspection call that returns the full capability catalog, canonical workflows, and usage tips. It uses specific verbs ('get') and resources ('capability catalog') and distinguishes from siblings by being local and free, contrasting with tools/list for detailed descriptions.
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?
Explicitly states when to use (first connection, user asks 'what can you do', capability audit before SOP planning) and when not to use (for full tool descriptions, for account balance). Also mentions pairing with deciding which tool to call next, providing clear guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
[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_amazon, single ASIN → get_amazon_product, seller → list_seller_products, category ranks → list_bestsellers/list_new_releases. Returns (format='json'): data.json[0].data.{ ... results[] ... }, shape depends on parserName. ⚠️ If content/url doesn't match parserName, the backend returns data.{ status_code, rawHtml, url } (unparsed). Pair with: ↓ feed asin into get_amazon_product / get_amazon_reviews. Cost: ~1 point/call, ~5s. ⚠️ Pass exactly one of content / url (both or neither errors); filtering/pagination requires url mode; parserName must match the page type.
| Name | Required | Description | Default |
|---|---|---|---|
| parserName | Yes | Parser 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. | |
| content | No | Bare 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. | |
| url | No | Full 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. | |
| site | No | Amazon 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). | amz_us |
| format | No | Response format. Defaults to 'json' (structured results). Use 'markdown' for the rendered page text. | json |
| zipcode | No | ZIP code matching the site's country. Optional; backend picks one if omitted. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Despite no annotations, the description discloses behavioral traits: input modes, that content mode carries no filter/sort/pagination, that exactly one of content/url must be provided, that parserName must match the page type, the return shape, error behavior when mismatch, cost (~1 point, ~5s), and pairing advice. This is thorough disclosure.
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 well-structured with sections (①②), bullet points, and clear warnings. Every sentence adds value; it is efficient and not verbose. The structure makes it easy to parse quickly.
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?
Given the tool's complexity (6 parameters, 9 parserName options, two modes), the description covers all necessary aspects: input modes, limitations, prerequisites (parserName match), return shape, cost, pairing with other tools, and error behavior. No gaps are apparent.
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%, but the description adds significant meaning beyond the schema: it explains the two input modes with examples, when to use each, filter syntax examples for url, parserName mappings, optionality of site and zipcode, and default values. This far exceeds the schema's descriptions.
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 clearly states that this is a generic Amazon scrape for pages not covered by 5 purpose-built tools, and explicitly names those sibling tools. It distinguishes itself as a 'power-user escape hatch' with two input modes, making the purpose very specific and unambiguous.
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?
The description provides explicit guidance on when to use each mode (content vs url), including filter/sort/pagination requirements, and explicitly states when not to use it (when a purpose-built tool fits), listing exact alternatives like search_amazon, get_amazon_product, etc. This is comprehensive.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
[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 external demand. Cost: ~1 point/page, ~5s. Only paginate when the user explicitly asks for more / Top-N (N>22) / all results — otherwise the first page is enough.
| Name | Required | Description | Default |
|---|---|---|---|
| keyword | Yes | Search keyword. Examples: 'wireless earbuds' / 'stanley quencher' / 'iphone 16 case' / 'kitchen knife set'. | |
| site | No | Amazon marketplace. Defaults to 'amz_us' (US). | amz_us |
| zipcode | No | ZIP 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). | |
| format | No | Response 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. | json |
| page | No | Page 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. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully covers behavioral traits: pagination details (nextPage, page param), response structure, cost (~1 point/page, ~5s), and when to paginate (only on explicit user request). No contradictions.
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 dense and well-structured, front-loading purpose and usage. While every sentence is informative, it is slightly verbose due to extensive usage guidelines and pairing info. Could be more concise but still effective.
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?
Given no output schema, the description covers return structure, pagination, cost, and pairing with siblings. All parameter details are thorough, and the context of sibling tools is addressed. Complete for a search tool.
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?
All 5 parameters have schema descriptions (100% coverage). The description adds value by explaining format choices, zipcode cross-country rejection, and pagination guidance beyond schema.
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 begins with a clear verb and resource: 'Run a real Amazon keyword search and return the first-page ASIN list.' It also distinguishes from siblings by explicitly listing tools for single ASIN detail, bestseller ranks, and external demand.
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?
Provides explicit when-to-use triggers (e.g., 'user says "search Amazon for X"') and when-not-to-use alternatives (e.g., 'Don't use: for a single ASIN detail (use get_amazon_product)'). Also includes pairing instructions for deeper analysis.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
[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 for deep-dive; follow_up_questions can seed the next round's prompts for multi-turn exploration. Cost: 6 points PER PROMPT (billed by prompts count, NOT a flat 6 per call; N prompts = N×6 points). ⚠️ Slow tool: strongly prefer sending exactly 1 prompt per call. A single prompt typically takes 60–90s (Rufus generates the conversation live — far slower than a normal scrape); multiple prompts add up linearly and can exceed 200s, costing both time and points. Treat this as a long-running call: set a generous timeout, and do NOT retry or fire concurrent duplicate calls just because it didn't return instantly. For several needs, make several single-prompt calls rather than batching them.
| Name | Required | Description | Default |
|---|---|---|---|
| prompts | Yes | Conversation 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']. | |
| screenshot | No | Return the Rufus conversation screenshot URL. Defaults to false. Setting true adds backend load; only enable when you need an image proof for end users. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. Details: 6 points per prompt (not per call), slow (60-90s per prompt), linear scaling, do not retry, output structure including snake_case follow_up_questions.
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?
Description is well-structured with clear sections but somewhat verbose. Front-loaded purpose and usage, but could be trimmed without losing essential info.
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?
Given complexity (cost, slowness, output structure) and no output schema, description is thorough: explains return format, cost billing, pairing, and warnings.
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% with detailed descriptions. Description adds value by emphasizing cost, slowness, and usage recommendations beyond schema.
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?
Description clearly states it uses Amazon Rufus AI for conversational product recommendations. Explicitly distinguishes from siblings: lists when not to use and alternatives (search_amazon, list_bestsellers, get_amazon_product, ai_search).
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?
Provides explicit 'Use when' and 'Don't use' sections. Also gives strong guidance on preferring 1 prompt per call due to cost and slowness.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
[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; ↓ feed into get_category_paths for breadcrumbs. Cost: ~1 point/call, ~3s.
| Name | Required | Description | Default |
|---|---|---|---|
| keyword | Yes | Category name keyword (Chinese or English). Examples: 'headphones' / 'kitchen knives' / '无线耳机' / 'wireless earbuds'. | |
| site | No | Marketplace to search categories in. Defaults to 'amz_us'. | amz_us |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Although no annotations are provided, the description fully discloses behavioral traits: it is a search (read-only implied), returns a detailed structure with fields, costs ~1 point and ~3 seconds, and pairs with downstream tools. No contradictions exist.
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 well-structured with clear sections: summary, use when, don't use, returns, pair with, and cost. Every sentence adds value, and the key information is front-loaded. It is concise yet comprehensive for the tool's complexity.
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?
Given the tool has only 2 parameters and no output schema, the description provides a complete picture: it explains the output format in detail, lists return fields, gives usage guidance, and mentions cost. It covers all necessary context for an AI agent to use the tool 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?
The schema covers both parameters (keyword and site) with descriptions and examples. The description adds value by explaining the purpose of keyword (Chinese or English) and providing concrete examples, which goes beyond the schema's basic description. Baseline is 3, extra context raises to 4.
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 clearly states the tool matches Amazon's category tree by keyword and returns candidate nodes. It uses specific verbs ('Match') and resources ('Amazon's category tree'), and distinguishes from siblings by listing use cases and alternatives like get_category_paths and get_category_children.
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?
The description explicitly provides 'Use when' and 'Don't use' conditions, including specific alternative tools (e.g., get_category_paths, get_category_children). It gives clear context for when to use—when user provides a keyword instead of a category ID—and when not to, making it highly actionable for an AI agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
[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 you a whole neighborhood; zoom 17+ narrows to one street.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | Local search query. Examples: 'coffee shop' / 'wholesale electronics' / '电子产品批发' / 'pet store'. | |
| latitude | Yes | Latitude of search center. Examples: 37.7822 (San Francisco) / 40.7128 (New York) / 34.0522 (Los Angeles). | |
| longitude | Yes | Longitude of search center. Examples: -122.4642 (San Francisco) / -74.0060 (New York) / -118.2437 (Los Angeles). | |
| zoom | No | Map zoom level, 1=world, 13=city, 21=building. Default 13. | |
| language | No | BCP-47 language code, e.g. 'en', 'zh-CN'. | en |
| limit | No | Max results to return (1-100). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses data source (Google Maps), cost (~1.5 points), latency (~5s), and zoom behavior tips. No annotations provided, so description carries burden; lacks details on authentication or rate limits.
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?
Well-structured with clear sections, front-loaded purpose. Slightly verbose but every sentence adds value; appropriate for tool complexity.
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?
Covers purpose, usage, return structure, cost, tips. No output schema, so return description is helpful but could elaborate on field semantics. Overall adequate for a search tool.
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%, baseline 3. Description adds value with zoom level usage examples ('13 gives neighborhood, 17+ narrows to street') and pairing hints. Slightly above baseline.
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?
Clearly states 'Local-business search' at a lat/lng, lists returned fields, and distinguishes from sibling tools like ai_search and keyword_trends with explicit 'Don't use' instructions.
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?
Provides explicit 'Use when' and 'Don't use' sections with concrete examples and alternatives (e.g., 'use keyword_trends' for global trends), plus pairing advice.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
[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 }] }. With enableLitigation=true each matched patent additionally carries litigationStatus(success/skipped/failed) + caseTotal + cases[{ caseId, docketNumber, caseName, court, status, dateFiled, parties[], patentNumbers[], entries[] }] (backed by US PACER litigation data — one call returns patents + lawsuits). Pair with: ↑ source required; hol=holder name / prod=product name / irn=international registration / lcs=design classification; enableLitigation=true chains US litigation lookup (IP-risk loop, no separate tool needed); ↓ DETAIL_URL lets the user jump to WIPO's official page to verify. Cost: ~2 points/call, ~5s; with enableLitigation=true add +12 points only when a patent is found (free if none). ⚠️ Perf contract: CNID + hol/prod MUST be paired with id/idSearch/rd/status/lcs (otherwise the backend rejects to avoid a 17M-row full scan); JPID has no HOL/PROD; USID has no STATUS; ed (expiration date) is silently ignored on all sources — filter dates via rd instead. With enableLitigation on, each page re-triggers the litigation query and billing.
| Name | Required | Description | Default |
|---|---|---|---|
| source | Yes | Data 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. | |
| ds | No | Designated country code (e.g. 'US', 'CN'). Optional — usually implied by `source`. | |
| hol | No | Holder 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). | |
| prod | No | Product 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. | |
| irn | No | International Registration Number exact match. Examples: 'DM/000298' (HAGUE) / 'D1107730' (USID). | |
| id | No | Full ID exact match, e.g. 'CNID.2023.123456'. Routes CNID queries to a single partition (avoids full scan). | |
| idSearch | No | ID variant fuzzy match. | |
| rd | No | Registration date (YYYY or YYYY-MM-DD). One of the recommended narrowing fields for CNID — routes to a year partition. | |
| status | No | Legal status: 'ACT' (active), 'EXP' (expired), etc. USID has no STATUS column (will be ignored). | |
| lcs | No | Design classification (Locarno Classification code), e.g. '23-01' = fluid distribution equipment. | |
| from | No | Pagination offset, 0-based. | |
| num | No | Page size (default 10, max 100). | |
| enableLitigation | No | Enable 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). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description carries full burden. It discloses critical behavioral details: CNID+hol/prod pairing requirements, source-specific limitations (JPID no HOL/PROD, USID no STATUS, ed ignored), enableLitigation auto-chaining behavior, cost/performance (~2 points, 5s, +12 points only when patents found), and return structure. This is exceptionally transparent.
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 comprehensive but somewhat lengthy. However, it is well-organized with sections (description, use/don't use, returns, pair with, cost, perf contract) and front-loaded with a clear summary. Every sentence adds value, though conciseness could be slightly improved by condensing repeated 'CNID' warnings.
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?
Given the tool's complexity (13 parameters, no output schema, no annotations), the description is remarkably complete. It explains return data structure, pagination, litigation chaining, cost implications, and source-specific constraints. It also mentions pairing with other tools (e.g., DETAIL_URL for verification). This exceeds expectations for completeness.
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% with parameter descriptions, but the description adds significant meaning beyond schema: pairing constraints (CNID + hol MUST be paired with id/idSearch/rd/status/lcs), source-specific behaviors (JPID no HOL/PROD, USID no STATUS), and usage notes for each parameter (e.g., 'Examples: 'Apple'' for hol). This enriches the agent's understanding.
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 clearly states the tool's purpose: querying WIPO design database across 12 sources with TRO risk control. It is specific ('Design Patent TRO risk control · WIPO global design / IP search') and distinguishes from sibling tools like search_amazon by explicitly stating it is an IP database, not a commerce database.
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?
The description provides explicit 'Use when' and 'Don't use' sections, listing example user queries (e.g., 'check trademark', 'design patent search') and explicitly excluding commerce-related searches. It also mentions pairing with source and other parameters, giving clear guidance on when to use this tool versus alternatives.
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. Dates show when Glama detected each change.
v0.7.3ai_search4 fields changedInput schema / properties / followups / descriptionPrevious value: -"多轮追问列表（仅 mode='ai_mode' 时生效）。每条是基于前一轮答案的追问。**超过 5 条响应效率显著下降**。"New value: +"Follow-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.**"Input schema / properties / mode / descriptionPrevious value: -"搜索模式：'overview'（默认）= 标准 Google SERP + 顶部 AI Overview 摘要，适合一次性查询；'ai_mode' = Google AI Mode 沉浸式搜索（udm=50），适合复杂问题拆解和多轮追问。"New value: +"Search 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."Input schema / properties / query / descriptionPrevious value: -"搜索关键词或问题。Examples: 'wireless earbuds reviews' (单点查询) / 'how does noise cancellation work' (问句) / 'what do people complain about Stanley Quencher' (用户痛点)。"New value: +"Search 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)."Input schema / properties / screenshot / descriptionPrevious value: -"是否返回搜索页截图 URL。默认 false。"New value: +"Whether to return a screenshot URL of the rendered search page. Defaults to false."filter_categories20 fields changedInput schema / properties / buyBoxPriceAvgMax / descriptionPrevious value: -"平均黄金购物车价格上限。"New value: +"Max average buy-box price."Input schema / properties / buyBoxPriceAvgMin / descriptionPrevious value: -"平均黄金购物车价格下限（按站点本币）。"New value: +"Min average buy-box price (marketplace currency)."Input schema / properties / buyBoxPriceTiers / descriptionPrevious value: -"价格档位筛选。可选：budget、mainstream、premium、luxury。"New value: +"Price-tier filter. Allowed: budget, mainstream, premium, luxury."Input schema / properties / categoryId / descriptionPrevious value: -"传入单个类目 ID 时返回该类目的全维度详情（替代“详情接口”）；不传则按筛选条件返回多个类目。Example: '979832011'。"New value: +"When 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'."Input schema / properties / extraFilters / descriptionPrevious value: -"透传任意上游字段（如 unitSoldTrendDirections、newAsinCountLevels、metricChangeRateBuckets 等）。键名按 Pangolinfo 文档原样填写。"New value: +"Pass-through for any other upstream filter (e.g. unitSoldTrendDirections, newAsinCountLevels, metricChangeRateBuckets). Keys must match the upstream doc verbatim."Input schema / properties / marketplaceId / descriptionPrevious value: -"Amazon 站点 ID。常见值：US、UK、DE、JP、FR、IT、ES、CA。默认 US。"New value: +"Amazon marketplace id. Common: US, UK, DE, JP, FR, IT, ES, CA. Defaults to US."Input schema / properties / netShippedGmsSumMax / descriptionPrevious value: -"GMS 上限。"New value: +"Max total GMS."Input schema / properties / netShippedGmsSumMin / descriptionPrevious value: -"商品销售总额 (GMS) 下限。"New value: +"Min total GMS (gross merchandise sales)."Input schema / properties / page / descriptionPrevious value: -"页码，从 1 开始。"New value: +"Page number, 1-based."Input schema / properties / returnRatioLevels / descriptionPrevious value: -"退货率质量等级。可选：excellent、average、risk。"New value: +"Return-rate quality buckets. Allowed: excellent, average, risk."Input schema / properties / sampleScope / descriptionPrevious value: -"数据样本范围（必填）。Examples: 'all_asin'（全部 ASIN，已验证有效）。"New value: +"Sample scope (required). Examples: 'all_asin' (all ASINs — verified working)."Input schema / properties / searchToPurchaseRatioLevels / descriptionPrevious value: -"搜索到购买转化率等级。可选：to_improve、average、excellent。"New value: +"Search-to-purchase conversion buckets. Allowed: to_improve, average, excellent."Input schema / properties / searchVolumeSumMax / descriptionPrevious value: -"总搜索量上限。"New value: +"Max total search volume."Input schema / properties / searchVolumeSumMin / descriptionPrevious value: -"总搜索量下限。"New value: +"Min total search volume."Input schema / properties / size / descriptionPrevious value: -"每页条数，上限 10（服务端硬限制）。"New value: +"Page size, max 10 (backend hard limit)."Input schema / properties / sortField / descriptionPrevious value: -"排序字段，支持任意响应字段名（如 'unitSoldSum'、'netShippedGmsSum'）。"New value: +"Sort field; any response field name is accepted (e.g. 'unitSoldSum', 'netShippedGmsSum')."Input schema / properties / sortOrder / descriptionPrevious value: -"排序顺序：'asc' 升序，'desc' 降序。"New value: +"Sort order: 'asc' or 'desc'."Input schema / properties / timeRange / descriptionPrevious value: -"数据聚合时间范围（必填）。Examples: 'l7d'（近 7 天，已验证有效）。具体可选值由后端决定，l7d 是已知能跑通的取值。"New value: +"Aggregation time range (required). Examples: 'l7d' (last 7 days — verified working). The exact enum is backend-defined; 'l7d' is the safest known value."Input schema / properties / unitSoldSumMax / descriptionPrevious value: -"总销量上限。"New value: +"Max total units sold."Input schema / properties / unitSoldSumMin / descriptionPrevious value: -"总销量下限。"New value: +"Min total units sold."filter_niches23 fields changedInput schema / properties / avgReviewCountMax / descriptionPrevious value: -"平均评论数上限——评论数越低意味着竞争越弱。"New value: +"Max average review count — lower means less competition."Input schema / properties / avgReviewCountMin / descriptionPrevious value: -"平均评论数下限。"New value: +"Min average review count."Input schema / properties / avgReviewRatingMin / descriptionPrevious value: -"平均评分下限（0-5）。"New value: +"Min average review rating (0-5)."Input schema / properties / extraFilters / descriptionPrevious value: -"透传任意上游字段（如 sponsoredProductsPercentageT360Min、successfulLaunchesT360Max、avgBestSellerRankMax 等）。键名按 Pangolinfo 文档原样填写。"New value: +"Pass-through for any other upstream filter (e.g. sponsoredProductsPercentageT360Min, successfulLaunchesT360Max, avgBestSellerRankMax). Keys must match the upstream doc verbatim."Input schema / properties / marketplaceId / descriptionPrevious value: -"Amazon 站点 ID（必填）。常见值：US、UK、DE、JP、FR、IT、ES、CA。默认 US。"New value: +"Amazon marketplace id (required). Common: US, UK, DE, JP, FR, IT, ES, CA. Defaults to US."Input schema / properties / maximumPriceMax / descriptionPrevious value: -"利基内最高商品价格的上限。"New value: +"Upper bound on the niche's maximum product price."Input schema / properties / minimumPriceMin / descriptionPrevious value: -"利基内最低商品价格的下限。"New value: +"Lower bound on the niche's minimum product price."Input schema / properties / nicheId / descriptionPrevious value: -"传入单个利基 ID 时返回该利基的全维度深度报告（替代“详情接口”）；不传则按筛选条件返回多个利基。Example: '8140a265-768d-4679-8bc2-994cb1c96f0b'（UUID 格式）。"New value: +"When 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)."Input schema / properties / nicheTitle / descriptionPrevious value: -"按关键词匹配利基标题。Examples: 'iphone 16 wallet case' / 'wireless earbuds for sports'。"New value: +"Keyword match against niche titles. Examples: 'iphone 16 wallet case' / 'wireless earbuds for sports'."Input schema / properties / page / descriptionPrevious value: -"页码，从 1 开始。"New value: +"Page number, 1-based."Input schema / properties / productCountMax / descriptionPrevious value: -"利基内商品数上限。"New value: +"Max product count in the niche."Input schema / properties / productCountMin / descriptionPrevious value: -"利基内商品数下限。"New value: +"Min product count in the niche."Input schema / properties / returnRateT360Max / descriptionPrevious value: -"近 360 天退货率上限（0-1）。"New value: +"Max return rate over 360 days (0-1)."Input schema / properties / searchVolumeGrowthT90Max / descriptionPrevious value: -"近 90 天搜索量增长率上限。"New value: +"Max 90-day search-volume growth rate."Input schema / properties / searchVolumeGrowthT90Min / descriptionPrevious value: -"近 90 天搜索量增长率下限（小数，0.1 = +10%）。"New value: +"Min 90-day search-volume growth rate (decimal, 0.1 = +10%)."Input schema / properties / searchVolumeT360Max / descriptionPrevious value: -"近 360 天搜索量上限。"New value: +"Max search volume over last 360 days."Input schema / properties / searchVolumeT360Min / descriptionPrevious value: -"近 360 天搜索量下限。"New value: +"Min search volume over last 360 days."Input schema / properties / searchVolumeT90Max / descriptionPrevious value: -"近 90 天搜索量上限。"New value: +"Max search volume over last 90 days."Input schema / properties / searchVolumeT90Min / descriptionPrevious value: -"近 90 天搜索量下限。"New value: +"Min search volume over last 90 days."Input schema / properties / size / descriptionPrevious value: -"每页条数,上限 10(服务端硬限制),默认 3(小默认值避免 AI 上下文超限 — 需要更宽扫描时显式传 size=10)。"New value: +"Page 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)."Input schema / properties / sortField / descriptionPrevious value: -"排序字段，支持任意响应字段名（如 'searchVolumeT90'、'avgProductPrice'）。"New value: +"Sort field; any response field name is accepted (e.g. 'searchVolumeT90', 'avgProductPrice')."Input schema / properties / sortOrder / descriptionPrevious value: -"排序顺序：'asc' 升序，'desc' 降序。"New value: +"Sort order: 'asc' or 'desc'."Input schema / properties / top5ProductsClickShareT360Max / descriptionPrevious value: -"近 360 天前 5 商品点击份额上限（0-1）。值越低代表利基越分散、机会越大。"New value: +"Max top-5-products click share over 360 days (0-1). Lower = more fragmented niche, more opportunity."get_amazon_product4 fields changedInput schema / properties / asin / descriptionPrevious value: -"Amazon ASIN，10 位大写字母+数字。Examples: 'B09B8V1LZ3' (Echo Dot 5) / 'B0CRMZHDG8' (Stanley Quencher) / 'B0BDHWDR12' (AirPods Pro 2)。"New value: +"Amazon ASIN, 10 chars uppercase. Examples: 'B09B8V1LZ3' (Echo Dot 5) / 'B0CRMZHDG8' (Stanley Quencher) / 'B0BDHWDR12' (AirPods Pro 2)."Input schema / properties / format / descriptionPrevious value: -"返回格式。默认 'json'——结构化字段（title/price/rating/reviews/seller 等），适合程序处理。需要原始页面阅读时切 'markdown'。"New value: +"Response 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."Input schema / properties / site / descriptionPrevious value: -"Amazon 站点。默认 amz_us（美国站）。"New value: +"Amazon marketplace. Defaults to 'amz_us' (US)."Input schema / properties / zipcode / descriptionPrevious value: -"邮编，必须匹配 site 站点所在国家（amz_us → 美国邮编，amz_jp → 日本邮编 …）。可选；不传时后端会从对应国家邮编池随机挑一个。跨国邮编（如 amz_us + 日本邮编）会被后端拒绝。Examples: 10001 (NY) / 90001 (LA) / 100-0001 (Tokyo)."New value: +"ZIP 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)."get_amazon_reviews7 fields changedInput schema / properties / asin / descriptionPrevious value: -"Amazon ASIN（10 位大写字母+数字）。Examples: 'B09B8V1LZ3' / 'B0CRMZHDG8'。"New value: +"Amazon ASIN (10-char uppercase alphanumeric). Examples: 'B09B8V1LZ3' / 'B0CRMZHDG8'."Input schema / properties / filterByStar / descriptionPrevious value: -"按星级筛选。VOC 痛点挖掘建议传 'critical'（1-3 星差评），找改进点；正面卖点提取传 'positive'。"New value: +"Filter by star rating. For VOC pain-point mining, pass 'critical' (1-3 star reviews) to surface defects; for positive-aspect extraction, pass 'positive'."Input schema / properties / mediaType / descriptionPrevious value: -"评论类型：'all_contents' 全部评论，'media_reviews_only' 仅含图片/视频的评论（更真实可信）。"New value: +"Review type: 'all_contents' for all, 'media_reviews_only' for reviews with photos/videos only (higher credibility)."Input schema / properties / pageCount / descriptionPrevious value: -"拉取的评论页数（1 页约 10 条评论）。**每页扣 10 积点**，请按需控制。默认 1 页。"New value: +"Number of review pages to fetch (~10 reviews per page). **Costs 10 points per page** — control accordingly. Defaults to 1."Input schema / properties / site / descriptionPrevious value: -"Amazon 站点。默认 amz_us。"New value: +"Amazon marketplace. Defaults to amz_us."Input schema / properties / sortBy / descriptionPrevious value: -"排序：'recent' 按时间倒序（看最新口碑），'helpful' 按帮助票数（看影响力大的评论）。"New value: +"Sort order: 'recent' (newest first — track current sentiment) or 'helpful' (most-upvoted first — highest impact reviews)."Input schema / properties / zipcode / descriptionPrevious value: -"邮编，必须匹配 site 站点所在国家（amz_us → 美国邮编，amz_jp → 日本邮编 …）。可选；不传时后端会从对应国家邮编池随机挑一个。跨国邮编（如 amz_us + 日本邮编）会被后端拒绝。Examples: 10001 (NY) / 90001 (LA) / 100-0001 (Tokyo)."New value: +"ZIP 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)."get_category_children3 fields changedInput schema / properties / page / descriptionPrevious value: -"页码，从 1 开始。"New value: +"Page number, 1-based."Input schema / properties / parentBrowseNodeIdPath / descriptionPrevious value: -"父节点路径。可填单个 browseNodeId 或斜杠分隔的完整路径。Examples: '2619526011' (Appliances, 顶级下钻) / '2619526011/18116197011' (Appliances > Ranges/Ovens/Cooktops, 三级下钻)。留空则返回顶级根节点。"New value: +"Parent 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."Input schema / properties / size / descriptionPrevious value: -"每页条数。"New value: +"Page size."get_category_paths2 fields changedInput schema / properties / categoryIds / descriptionPrevious value: -"要解析完整路径的类目 ID 列表。Examples: ['2619526011'] (Appliances) / ['172282', '11965861'] (Electronics + Musical Instruments)。"New value: +"Category IDs to resolve full path for. Examples: ['2619526011'] (Appliances) / ['172282', '11965861'] (Electronics + Musical Instruments)."Input schema / properties / site / descriptionPrevious value: -"Amazon 站点。默认 amz_us（美国站）。"New value: +"Amazon marketplace. Defaults to 'amz_us' (US)."keyword_trends4 fields changedInput schema / properties / keywords / descriptionPrevious value: -"对比的关键词列表（1-5 个）。Examples: ['wireless earbuds', 'bluetooth earbuds'] (同义词对比) / ['stanley quencher', 'yeti rambler', 'hydro flask'] (竞品品牌对比) / ['halloween costume'] (单词看季节性)。"New value: +"Keywords to compare (1-5). Examples: ['wireless earbuds', 'bluetooth earbuds'] (synonyms) / ['stanley quencher', 'yeti rambler', 'hydro flask'] (competing brands) / ['halloween costume'] (single keyword for seasonality)."Input schema / properties / language / descriptionPrevious value: -"界面语言 BCP-47 代码，影响相关查询的语言。默认 'en-US'。中文用 'zh-CN'。"New value: +"Interface language (BCP-47), affects related-query language. Defaults to 'en-US'. Use 'zh-CN' for Chinese."Input schema / properties / region / descriptionPrevious value: -"地区代码（ISO 国家或 'WORLD' 全球）。常用：'US' / 'GB' / 'DE' / 'JP' / 'CN'。"New value: +"Region code (ISO country, or 'WORLD' for global). Common: 'US' / 'GB' / 'DE' / 'JP' / 'CN'."Input schema / properties / timeRange / descriptionPrevious value: -"时间窗口。常用：'today 12-m'（近 12 月，默认，平衡近况和趋势）、'today 3-m'（近 90 天）、'today 5-y'（5 年长期）、'all'（自 2004 起全部）。"New value: +"Time 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)."list_bestsellers4 fields changedInput schema / properties / categorySlug / descriptionPrevious value: -"Amazon Best Sellers 类目 slug（小写英文短横线），如 'electronics'、'home-garden'、'beauty'、'toys-and-games'。可以从 amazon.com/Best-Sellers 顶部导航的 URL 路径里读到。"New value: +"Amazon 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."Input schema / properties / format / descriptionPrevious value: -"返回格式。默认 'json'——结构化 Top-50 ASIN 排名列表。需要原始页面阅读时切 'markdown'。"New value: +"Response format. Defaults to 'json' — structured Top-50 ranked ASIN list. Use 'markdown' for the rendered page text."Input schema / properties / site / descriptionPrevious value: -"Amazon 站点。默认 amz_us。"New value: +"Amazon marketplace. Defaults to amz_us."Input schema / properties / zipcode / descriptionPrevious value: -"邮编，必须匹配 site 站点所在国家（amz_us → 美国邮编，amz_jp → 日本邮编 …）。可选；不传时后端会从对应国家邮编池随机挑一个。跨国邮编（如 amz_us + 日本邮编）会被后端拒绝。Examples: 10001 (NY) / 90001 (LA) / 100-0001 (Tokyo)."New value: +"ZIP 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)."list_category_products5 fields changedInput schema / properties / format / descriptionPrevious value: -"返回格式。默认 'json'——结构化类目商品列表。需要原始页面阅读时切 'markdown'。"New value: +"Response format. Defaults to 'json' — structured category listings. Use 'markdown' for the rendered page text."Input schema / properties / nodeId / descriptionPrevious value: -"Amazon 类目 Browse Node ID（纯数字）。Examples: '172282' (Electronics) / '2619526011' (Appliances) / '11965861' (Musical Instruments)。可通过 search_categories / get_category_children 获得。"New value: +"Amazon category Browse Node ID (numeric). Examples: '172282' (Electronics) / '2619526011' (Appliances) / '11965861' (Musical Instruments). Obtain via search_categories or get_category_children."Input schema / properties / page / descriptionPrevious value: -"页码，从 1 开始。每页 24 条。结合响应里的 pageIndex/maxPage/nextPage 决定是否继续：nextPage 为下一页页码，nextPage=null 或 page>=maxPage 表示到底。**只在用户明确要更多/全部时才翻**，否则首页够用。"New value: +"Page 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."Input schema / properties / site / descriptionPrevious value: -"Amazon 站点。默认 amz_us。"New value: +"Amazon marketplace. Defaults to amz_us."Input schema / properties / zipcode / descriptionPrevious value: -"邮编，必须匹配 site 站点所在国家（amz_us → 美国邮编，amz_jp → 日本邮编 …）。可选；不传时后端会从对应国家邮编池随机挑一个。跨国邮编（如 amz_us + 日本邮编）会被后端拒绝。Examples: 10001 (NY) / 90001 (LA) / 100-0001 (Tokyo)."New value: +"ZIP 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)."list_new_releases4 fields changedInput schema / properties / categorySlug / descriptionPrevious value: -"Amazon New Releases 类目 slug（小写英文短横线），如 'electronics'、'home-garden'。可以从 amazon.com/gp/new-releases 顶部导航的 URL 路径里读到。"New value: +"Amazon New Releases category slug (lowercase, hyphenated). Examples: 'electronics', 'home-garden'. Find these in the URL path on amazon.com/gp/new-releases."Input schema / properties / format / descriptionPrevious value: -"返回格式。默认 'json'——结构化新品榜单。需要原始页面阅读时切 'markdown'。"New value: +"Response format. Defaults to 'json' — structured ranking list. Use 'markdown' for the rendered page text."Input schema / properties / site / descriptionPrevious value: -"Amazon 站点。默认 amz_us。"New value: +"Amazon marketplace. Defaults to amz_us."Input schema / properties / zipcode / descriptionPrevious value: -"邮编，必须匹配 site 站点所在国家（amz_us → 美国邮编，amz_jp → 日本邮编 …）。可选；不传时后端会从对应国家邮编池随机挑一个。跨国邮编（如 amz_us + 日本邮编）会被后端拒绝。Examples: 10001 (NY) / 90001 (LA) / 100-0001 (Tokyo)."New value: +"ZIP 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)."list_seller_products7 fields changedInput schema / properties / categoryId / descriptionPrevious value: -"类目筛选 ID，按该类目过滤店铺商品。单个最小类目 ID（如 '7161074011'），或逗号分隔的多级类目（如 '172282,502394,7161073011'）。不填 = 返回店铺全部商品。可从 Amazon 店铺页 URL 的 rh=n:<类目ID> 中提取。"New value: +"Category 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."Input schema / properties / format / descriptionPrevious value: -"返回格式。默认 'json'——结构化卖家商品列表。需要原始页面阅读时切 'markdown'。"New value: +"Response format. Defaults to 'json' — structured seller listings. Use 'markdown' for the rendered page text."Input schema / properties / page / descriptionPrevious value: -"页码，从 1 开始。每页 24 条。结合响应里的 pageIndex/maxPage/nextPage 决定是否继续：nextPage 为下一页页码，nextPage=null 或 page>=maxPage 表示到底。**只在用户明确要更多/全部 SKU 时才翻**，否则首页够用。注意：传了 pageCount>1（多页累计）时，page 被忽略（后端固定从第 1 页开始累计）。"New value: +"Page 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)."Input schema / properties / pageCount / descriptionPrevious value: -"多页累计爬取：传 N 则一次连续爬取前 N 页并扁平合并返回（如 3 = 第 1+2+3 页全部商品）。默认 1（单页，走 page 逻辑）；上限 3，超过按 3 处理。与 page 的区别：page 是定位看某一页，pageCount 是一次拉前 N 页合并。**只在需要一次性拿多页全量 SKU 时用**；按实际成功页数计费（某页失败退该页费用）。"New value: +"Multi-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)."Input schema / properties / sellerId / descriptionPrevious value: -"Amazon 卖家 ID（merchant ID，14 位字母数字）。Examples: 'ATVPDKIKX0DER'（Amazon 自营）/ 'A2L77EE7U53NWQ'（Amazon Warehouse）。从商品页 'sold by' 链接或 amazon.com/sp?seller=... URL 里读取。"New value: +"Amazon 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."Input schema / properties / site / descriptionPrevious value: -"Amazon 站点。默认 amz_us。"New value: +"Amazon marketplace. Defaults to amz_us."Input schema / properties / zipcode / descriptionPrevious value: -"邮编，必须匹配 site 站点所在国家（amz_us → 美国邮编，amz_jp → 日本邮编 …）。可选；不传时后端会从对应国家邮编池随机挑一个。跨国邮编（如 amz_us + 日本邮编）会被后端拒绝。Examples: 10001 (NY) / 90001 (LA) / 100-0001 (Tokyo)."New value: +"ZIP 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)."pangolinfo_capabilities1 field changedInput schema / properties / detail / descriptionPrevious value: -"'summary' 返回工具清单 + 典型链路（默认，省 token）；'full' 把 17 个 tool 的完整 description 也一并展开（约 8KB，第一次接入或上下文不紧时用）。"New value: +"'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)."scrape_url6 fields changedInput schema / properties / content / descriptionPrevious value: -"裸零件(后端按 parserName 自动拼 URL)。传这个**或** url 二选一。Examples: 'wireless earbuds'(amzKeyword)/ '172282'(amzProductOfCategory 的 nodeId)/ 'ATVPDKIKX0DER'(amzProductOfSeller 的 sellerId)/ 'B09B8V1LZ3'(amzProductDetail 的 ASIN)。用户/AI 通常只有零件,优先用这个。"New value: +"Bare 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."Input schema / properties / format / descriptionPrevious value: -"返回格式。默认 'json'(结构化 results);需要原始页面阅读时切 'markdown'。"New value: +"Response format. Defaults to 'json' (structured results). Use 'markdown' for the rendered page text."Input schema / properties / parserName / descriptionPrevious value: -"解析器名,决定后端怎么解析页面 + 怎么从 content 拼 URL。必须和页面类型匹配:amzKeyword=关键词搜索(content=关键词)/ amzProductOfCategory=类目商品(content=nodeId)/ amzProductOfSeller=卖家店铺(content=sellerId)/ amzProductDetail=单品(content=ASIN)/ amzBestSellers / amzNewReleases / amzReviewV2=评论 / amzFollowSeller=跟卖 / amzVariantAsin=变体。"New value: +"Parser 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."Input schema / properties / site / descriptionPrevious value: -"Amazon 站点(content 模式下后端据此选域名拼 URL)。默认 amz_us。url 模式下可省略(url 已含域名)。"New value: +"Amazon 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)."Input schema / properties / url / descriptionPrevious value: -"完整 Amazon URL(https://)。传这个**或** content 二选一。用于你已经有一个现成链接(如浏览器复制的带筛选/排序的搜索结果页)。Example: 'https://www.amazon.com/s?k=earbuds&rh=p_36%3A2500-5000&s=review-rank'。必须和 parserName 匹配。"New value: +"Full 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."Input schema / properties / zipcode / descriptionPrevious value: -"邮编,必须匹配 site 所在国家。可选;不传时后端随机挑一个。"New value: +"ZIP code matching the site's country. Optional; backend picks one if omitted."search_amazon5 fields changedInput schema / properties / format / descriptionPrevious value: -"返回格式。默认 'json'——结构化搜索结果（每条含 asin/title/price/star/rating/sales/badge/rank 等），适合程序处理。需要原始页面阅读时切 'markdown'。"New value: +"Response 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."Input schema / properties / keyword / descriptionPrevious value: -"搜索关键词。Examples: '蓝牙耳机' / 'wireless earbuds' / 'stanley quencher' / 'iphone 16 case'。"New value: +"Search keyword. Examples: 'wireless earbuds' / 'stanley quencher' / 'iphone 16 case' / 'kitchen knife set'."Input schema / properties / page / descriptionPrevious value: -"页码，从 1 开始。每页约 22 条 ASIN。结合响应里的 pageIndex/nextPage 决定是否继续翻：nextPage 为下一页页码，nextPage=null（或缺失）表示已到最后一页。**只在用户明确要更多/Top-N（N>单页量）/全部时才翻**，否则首页够用。"New value: +"Page 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."Input schema / properties / site / descriptionPrevious value: -"Amazon 站点。默认 amz_us（美国站）。"New value: +"Amazon marketplace. Defaults to 'amz_us' (US)."Input schema / properties / zipcode / descriptionPrevious value: -"邮编，必须匹配 site 站点所在国家（amz_us → 美国邮编，amz_jp → 日本邮编 …）。可选；不传时后端会从对应国家邮编池随机挑一个。跨国邮编（如 amz_us + 日本邮编）会被后端拒绝。Examples: 10001 (NY) / 90001 (LA) / 100-0001 (Tokyo)."New value: +"ZIP 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)."search_amazon_alexa2 fields changedInput schema / properties / prompts / descriptionPrevious value: -"对话提示词数组(中英文均可)。每条独立向 Rufus 发问,返回独立分组结果。**整次调用固定 6 积点**(与条数无关),但建议 ≤3 条:>3 条响应耗时显著不稳定。Examples: ['gifts for a 5-year-old who loves dinosaurs'] / ['camping gear under $50','best tent for 2 people']。"New value: +"Conversation 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']."Input schema / properties / screenshot / descriptionPrevious value: -"是否返回 Rufus 对话页面截图 URL。默认 false。true 会增加后端负担,仅当需要给最终用户附图证据时打开。"New value: +"Return the Rufus conversation screenshot URL. Defaults to false. Setting true adds backend load; only enable when you need an image proof for end users."search_categories2 fields changedInput schema / properties / keyword / descriptionPrevious value: -"类目名称关键词（中英文均可）。Examples: 'headphones' / 'kitchen knives' / '无线耳机' / 'wireless earbuds'。"New value: +"Category name keyword (Chinese or English). Examples: 'headphones' / 'kitchen knives' / '无线耳机' / 'wireless earbuds'."Input schema / properties / site / descriptionPrevious value: -"搜索的 Amazon 站点。默认 amz_us（美国站）。"New value: +"Marketplace to search categories in. Defaults to 'amz_us'."search_local_maps6 fields changedInput schema / properties / language / descriptionPrevious value: -"BCP-47 语言码，例如 'en'、'zh-CN'。"New value: +"BCP-47 language code, e.g. 'en', 'zh-CN'."Input schema / properties / latitude / descriptionPrevious value: -"搜索中心点的纬度。Examples: 37.7822 (旧金山) / 40.7128 (纽约) / 34.0522 (洛杉矶)。"New value: +"Latitude of search center. Examples: 37.7822 (San Francisco) / 40.7128 (New York) / 34.0522 (Los Angeles)."Input schema / properties / limit / descriptionPrevious value: -"返回的最大结果数（1-100）。"New value: +"Max results to return (1-100)."Input schema / properties / longitude / descriptionPrevious value: -"搜索中心点的经度。Examples: -122.4642 (旧金山) / -74.0060 (纽约) / -118.2437 (洛杉矶)。"New value: +"Longitude of search center. Examples: -122.4642 (San Francisco) / -74.0060 (New York) / -118.2437 (Los Angeles)."Input schema / properties / query / descriptionPrevious value: -"本地搜索关键词。Examples: 'coffee shop' / 'wholesale electronics' / '电子产品批发' / 'pet store'。"New value: +"Local search query. Examples: 'coffee shop' / 'wholesale electronics' / '电子产品批发' / 'pet store'."Input schema / properties / zoom / descriptionPrevious value: -"地图缩放级别，1=全球，13=城市，21=单栋建筑。默认 13。"New value: +"Map zoom level, 1=world, 13=city, 21=building. Default 13."wipo_search13 fields changedInput schema / properties / ds / descriptionPrevious value: -"指定国家代码（如 'US'、'CN'）。可选——传 source 时通常已隐含国家。"New value: +"Designated country code (e.g. 'US', 'CN'). Optional — usually implied by `source`."Input schema / properties / enableLitigation / descriptionPrevious value: -"是否开启智能联动风控模式：命中专利后自动用专利号查关联的美国诉讼案件（底层 PACER），案件 join 进每条专利的 cases 字段。默认 false。开启后每条命中专利会多 litigationStatus / caseTotal / cases 字段；仅当查到专利才额外计费 +12 积点（没查到专利不收）。"New value: +"Enable 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)."Input schema / properties / from / descriptionPrevious value: -"分页起始位置，从 0 开始。"New value: +"Pagination offset, 0-based."Input schema / properties / hol / descriptionPrevious value: -"权利人（公司或个人）名称模糊匹配。Examples: 'Apple' / 'Samsung' / 'Nike'。注意：CNID + hol 必须配合 id/idSearch/rd/status/lcs 至少一项；JPID 无 HOL 字段（会被忽略）。"New value: +"Holder 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)."Input schema / properties / id / descriptionPrevious value: -"完整 ID 精确匹配，如 'CNID.2023.123456'。用于 CNID 路由到单分区，避免全表扫描。"New value: +"Full ID exact match, e.g. 'CNID.2023.123456'. Routes CNID queries to a single partition (avoids full scan)."Input schema / properties / idSearch / descriptionPrevious value: -"ID 变体模糊匹配。"New value: +"ID variant fuzzy match."Input schema / properties / irn / descriptionPrevious value: -"国际注册号精确匹配。Examples: 'DM/000298'（HAGUE）/ 'D1107730'（USID）。"New value: +"International Registration Number exact match. Examples: 'DM/000298' (HAGUE) / 'D1107730' (USID)."Input schema / properties / lcs / descriptionPrevious value: -"外观设计分类（洛迦诺分类号 LCS），如 '23-01' = 流体分配设备。"New value: +"Design classification (Locarno Classification code), e.g. '23-01' = fluid distribution equipment."Input schema / properties / num / descriptionPrevious value: -"每页条数（默认 10，上限 100）。"New value: +"Page size (default 10, max 100)."Input schema / properties / prod / descriptionPrevious value: -"产品名称模糊匹配。CNID 搜中文，其他 source 搜英文。Examples: '椅子' (CNID) / 'wireless headphones' (USID) / 'iphone case' (USID)。CNID + prod 必须配合 id/idSearch/rd/status/lcs；JPID 无 PROD 字段。"New value: +"Product 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."Input schema / properties / rd / descriptionPrevious value: -"注册日期（YYYY 或 YYYY-MM-DD）。CNID 必备的窄化字段之一，能把查询路由到年份分区。"New value: +"Registration date (YYYY or YYYY-MM-DD). One of the recommended narrowing fields for CNID — routes to a year partition."Input schema / properties / source / descriptionPrevious value: -"数据来源（必填）。WIPO 数据按 source 分区存储，跨 source 不可查。常用：USID（美国外观）、CNID（中国外观，17M+ 条）、HAGUE（海牙体系国际注册）、DEID、JPID。"New value: +"Data 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."Input schema / properties / status / descriptionPrevious value: -"法律状态：'ACT'（生效）、'EXP'（过期）等。USID 无 STATUS 字段（会被忽略）。"New value: +"Legal status: 'ACT' (active), 'EXP' (expired), etc. USID has no STATUS column (will be ignored)."v0.7.2ai_searchfilter_niches2 fields changedInput schema / properties / size / defaultPrevious value: -10New value: +3Input schema / properties / size / descriptionPrevious value: -"每页条数，上限 10（服务端硬限制）。"New value: +"每页条数,上限 10(服务端硬限制),默认 3(小默认值避免 AI 上下文超限 — 需要更宽扫描时显式传 size=10)。"google_ai_searchgoogle_trendskeyword_trendslist_bestsellers1 field changedInput schema / properties / format / descriptionPrevious value: -"返回格式。默认 'json'——结构化 Top-100 ASIN 排名列表。需要原始页面阅读时切 'markdown'。"New value: +"返回格式。默认 'json'——结构化 Top-50 ASIN 排名列表。需要原始页面阅读时切 'markdown'。"list_seller_products3 fields changedInput schema / properties / categoryIdAdded value: +{
+ "description": "类目筛选 ID，按该类目过滤店铺商品。单个最小类目 ID（如 '7161074011'），或逗号分隔的多级类目（如 '172282,502394,7161073011'）。不填 = 返回店铺全部商品。可从 Amazon 店铺页 URL 的 rh=n:<类目ID> 中提取。",
+ "type": "string"
+}Input schema / properties / page / descriptionPrevious value: -"页码，从 1 开始。每页 24 条。结合响应里的 pageIndex/maxPage/nextPage 决定是否继续：nextPage 为下一页页码，nextPage=null 或 page>=maxPage 表示到底。**只在用户明确要更多/全部 SKU 时才翻**，否则首页够用。"New value: +"页码，从 1 开始。每页 24 条。结合响应里的 pageIndex/maxPage/nextPage 决定是否继续：nextPage 为下一页页码，nextPage=null 或 page>=maxPage 表示到底。**只在用户明确要更多/全部 SKU 时才翻**，否则首页够用。注意：传了 pageCount>1（多页累计）时，page 被忽略（后端固定从第 1 页开始累计）。"Input schema / properties / pageCountAdded value: +{
+ "default": 1,
+ "description": "多页累计爬取：传 N 则一次连续爬取前 N 页并扁平合并返回（如 3 = 第 1+2+3 页全部商品）。默认 1（单页，走 page 逻辑）；上限 3，超过按 3 处理。与 page 的区别：page 是定位看某一页，pageCount 是一次拉前 N 页合并。**只在需要一次性拿多页全量 SKU 时用**；按实际成功页数计费（某页失败退该页费用）。",
+ "maximum": 3,
+ "minimum": 1,
+ "type": "integer"
+}scrape_urlwipo_search2 fields changedInput schema / properties / enableLitigationAdded value: +{
+ "default": false,
+ "description": "是否开启智能联动风控模式：命中专利后自动用专利号查关联的美国诉讼案件（底层 PACER），案件 join 进每条专利的 cases 字段。默认 false。开启后每条命中专利会多 litigationStatus / caseTotal / cases 字段；仅当查到专利才额外计费 +12 积点（没查到专利不收）。",
+ "type": "boolean"
+}Input schema / properties / lcs / descriptionPrevious value: -"洛迦诺分类号（外观设计国际分类），如 '23-01' = 流体分配设备。"New value: +"外观设计分类（洛迦诺分类号 LCS），如 '23-01' = 流体分配设备。"v0.2.1filter_categoriesfilter_nichesget_amazon_productget_amazon_reviewsget_category_childrenget_category_pathsgoogle_ai_searchgoogle_trendslist_bestsellerslist_category_productslist_new_releaseslist_seller_productspangolinfo_capabilitiessearch_amazonsearch_amazon_alexasearch_categoriessearch_local_mapswipo_searchEach tool targets a distinct resource or action: category-level vs niche-level filtering, product details vs reviews, different list types (bestsellers, new releases, category products), and separate external data sources (Google search, trends, Maps, WIPO). The detailed descriptions provide clear use cases and don't use guidance, minimizing ambiguity.
Tool names follow a mostly consistent verb_noun snake_case pattern (e.g., filter_categories, get_amazon_product, list_bestsellers). However, there are minor deviations: 'google_ai_search' and 'google_trends' use different structures, and 'pangolinfo_capabilities' lacks a verb. Still, the majority are predictable and readable.
With 18 tools, the server covers a wide range of Amazon research needs plus external data (Google, Maps, WIPO). While the count might seem high, each tool serves a specific purpose aligned with the server's broad scope. A few tools like search_local_maps could be considered peripheral, but overall the number is reasonable and not excessive.
The tool set covers the full lifecycle of Amazon product research: category and niche discovery, product listing, detail and review analysis, rankings, seller info, Amazon search, external trend validation (Google), and intellectual property checks (WIPO). There are no obvious gaps for the advertised purpose of ad tracking and review intelligence.
Real-time Amazon product, seller, and search data for AI agents across 21 marketplaces.
Marketing intelligence API for AI agents. Real campaign data, not LLM guesses.
Amazon brand, seller, niche & buy-box intelligence inside your own Claude or ChatGPT.
AMZScout Skill + MCP gives AI agents live access to real Amazon marketplace data across 14 Amazon marketplaces. Analyze any ASIN, validate product ideas, research niches, compare competitors, discover profitable keywords, and build data-driven PPC strategies using trusted Amazon insights instead of AI assumptions. Works with Claude, ChatGPT, Cursor, and any other MCP-compatible AI client. To connect, you'll need an AMZScout API plan and authorize your account. Get access and view pricing here: https://learn.amzscout.net/amazon-product-api-for-ai-agents
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/pangolinfo/pangolinfo-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
