This server provides agent-native voice-of-customer (VOC) analysis for e-commerce products, supporting both Amazon ASINs and custom review files. It exposes six MCP-callable tools usable from Claude Code, Cursor, Cline, Continue, and others:
Fetch Amazon Reviews (fetch_reviews): Retrieve up to 1,000 raw reviews for any ASIN across 10 markets (US, CA, MX, GB, DE, FR, IT, ES, JP, AU) via the Shulex VOC API.
Analyze Existing Reviews (analyze_reviews): Run AI-powered VOC analysis on reviews you already have, producing sentiment breakdowns, pain points, selling points, listing tips, and bilingual summaries — without re-fetching from the API.
One-Shot VOC Report (voc_full): Fetch reviews and run full AI analysis in a single call — the default "give me a VOC report on this ASIN" tool.
Generate Listing Improvements (extract_listing_improvements): Produce copy-ready title, 5 bullet points, description, and missing keywords grounded in actual customer language (requires Anthropic API key).
Analyze CSV/Excel Reviews (analyze_csv): Import review data from non-Amazon sources (Helium 10, eBay, Shopify, AliExpress, etc.) with fuzzy column detection for English and Chinese column names.
Render HTML Dashboard (render_dashboard): Generate a standalone black-gold HTML dashboard featuring sentiment bars, pain-point/selling-point panels, executive summary, and an optional listing optimization card.
All outputs are available as markdown reports, structured JSON, and the interactive HTML dashboard. The server can also be run as a CLI tool or deployed to cloud platforms like Smithery or Vercel.
Fetches and analyzes Amazon product reviews via ASIN across 10 markets (US, CA, MX, GB, DE, FR, IT, ES, JP, AU) using the Shulex VOC OpenAPI data layer, providing sentiment analysis, pain points, and listing improvements.
Accepts eBay review CSV/Excel files for analysis, using fuzzy column detection to handle varying formats and generating the same VOC report and dashboard.
Accepts Helium 10 CSV/Excel exports for analysis, using fuzzy column detection to handle varying formats and generating the same VOC report and dashboard.
Accepts Shopify review CSV/Excel files for analysis, using fuzzy column detection to handle varying formats and generating the same VOC report and dashboard.
Two inputs, six tools, three outputs.
┌─────────────┐ ┌──────────────┐
│ ASIN │──┐ ┌─│ Markdown │
└─────────────┘ │ ┌─────────────────────────┐ │ │ report │
├──────▶ 6 agent-callable tools ├──────┤ ├──────────────┤
┌─────────────┐ │ └─────────────────────────┘ │ │ Structured │
│ CSV / XLSX │──┘ fetch_reviews analyze_csv │ │ JSON │
└─────────────┘ analyze_reviews voc_full │ ├──────────────┤
extract_listing_improvements └─│ Black-gold │
render_dashboard │ HTML deck │
└──────────────┘Inputs — Amazon ASIN (auto-fetched via Shulex VOC OpenAPI, 10 markets) or any review CSV / Excel (Helium 10 / eBay / Shopify / custom — fuzzy column detection)
Outputs — Markdown report · structured JSON · standalone HTML dashboard
Surface — MCP server (works in Claude Code / Cursor / Cline / Continue) and Skill (works in Claude Code)
Related MCP server: LaunchFast MCP
Requires uv.
Add this to your MCP client config (Claude Code, Claude Desktop, Cursor, Windsurf, VS Code Copilot, Cline, Continue.dev):
{
"mcpServers": {
"voc-amazon-reviews": {
"command": "uvx",
"args": ["voc-amazon-reviews-mcp"],
"env": {
"VOC_API_KEY": "your-shulex-key"
}
}
}
}Get a free Shulex API key (100 calls/month, no credit card): apps.voc.ai/openapi.
Optional: Add "ANTHROPIC_API_KEY": "sk-ant-..." to enable extract_listing_improvements (the only tool that calls Claude directly — others work without it). Must be an actual Anthropic key; other providers won't work.
First run resolves dependencies in ~5s; subsequent runs are instant.
Ask any MCP-compatible agent:
Run a VOC report on
B08N5WRWNW, render the dashboard, and write it to~/Desktop/voc.html.
The agent will call voc_full → render_dashboard and hand you the file.
bash voc.sh B08N5WRWNW --limit 100 --market US# Drop in any reviews CSV (Helium 10 export, eBay scrape, Shopify, custom)
python -c "from mcp_server.tools import analyze_csv, render_dashboard; \
r = analyze_csv('reviews.csv', product_name='My Product'); \
render_dashboard(r, output_path='dashboard.html')"Connect to the server remotely — no uvx, no Python, no local install. Bring
your own Shulex API key (Smithery prompts for it on first connection).
This repo ships a Dockerfile and smithery.yaml for one-click deploy.
To run your own hosted instance:
Fork or clone this repo to your GitHub.
Sign in at smithery.ai with GitHub.
Deploy a server → pick the repo. Smithery builds the container and exposes an HTTPS MCP endpoint.
Share the URL with users; they paste it into Claude / Cursor / Cline.
The same image runs anywhere that takes a Dockerfile — Fly.io, Railway, Cloudflare Workers (with adapter), Render, Cloud Run.
To run the HTTP transport locally (e.g. for testing):
MCP_TRANSPORT=streamable-http PORT=8080 python -m mcp_server.serverThis repo also ships vercel.json + app.py for one-click Vercel
deploys. Sign in at vercel.com with GitHub, import the
repo, and Vercel auto-detects the Python function.
Set these in Project Settings → Environment Variables before the first deploy:
Variable | Required | Notes |
| yes | Shulex VOC OpenAPI key |
| optional | Only for |
Timeout caveat: Vercel functions cap at 10s (Hobby default), 60s
(Hobby with maxDuration: 60 — already set in vercel.json), or 300s
(Pro). Long-running tools like voc_full (30-90s) and
extract_listing_improvements (20-60s) may exceed these limits. For
unbounded execution, prefer Option D (Docker/Render/Fly) or local install.
The MCP endpoint after deploy: https://your-project.vercel.app/mcp
# | Tool | Input | Use when |
1 |
| ASIN | You want raw reviews; you'll analyze them yourself |
2 |
| reviews JSON | You already have reviews and want the VOC report |
3 |
| ASIN | Default "give me a VOC report" — fetch + analyze in one call |
4 |
| ASIN | ★ Differentiator — copy-ready title / 5 bullets / description grounded in customer language |
5 |
| CSV / Excel path or URL | The product is NOT on Amazon, or you have your own scrape |
6 |
| VOC report | Generate a standalone black-gold HTML dashboard, no external deps |
All 6 tools speak MCP. All return JSON-serializable dicts. Full schemas in mcp_server/README.md.
Most "AI review tools" are a thin LLM wrapper over a brittle scraper. We invert that. The data layer is the moat:
Typical seller-tool data layer | review-analyzer | |
Source | Web scraper / undocumented scrape API | Paid Shulex VOC OpenAPI |
Reliability | Breaks when Amazon updates HTML | API-grade, no DOM dependencies |
Markets | US-only or 2-3 markets | 10: US, CA, MX, GB, DE, FR, IT, ES, JP, AU |
Volume | 10–50 reviews (free-tier cap) | Up to 1,000 reviews per ASIN |
Freshness | Daily snapshots, sometimes cached for days | Live pull |
Schema | Strings only | Full: verified-purchase, helpful votes, vine, variant, dates |
Non-English markets | Often broken / omitted | Native captures + AI translation |
Access | Locked behind a UI | curl + JSON, fully scriptable, MCP-ready |
For non-Amazon platforms, analyze_csv accepts any review file — fuzzy column matching detects 内容 / 评价 / body / review / content so you don't have to reformat. Bring data from anywhere, get the same VOC report.
review-analyzer | Helium 10 / Data Dive | review-analyzer-skill (Buluu) | Generic review scrapers | |
Input | ASIN or CSV | ASIN (manual UI) | CSV only | URL |
Markets | 10 | 1-3 | depends on user's data | 1 |
Output | JSON + Markdown + HTML dashboard | UI dashboard (locked) | CSV + MD + HTML dashboard | Raw CSV |
MCP-callable | ✅ | ❌ | ❌ Claude Code only | ❌ |
Listing copy gen | ✅ | Keyword research only | ❌ | ❌ |
Cost | Shulex API + Anthropic API ($0.05-0.20/listing) | $99-249/month subscription | Free (uses your Claude quota) | Free, brittle |
Open source | ✅ MIT | ❌ | ✅ MIT | varies |
Credit & inspiration: The 22-dimension tag system, fuzzy CSV column detection, and black-gold dashboard aesthetic were inspired by buluslan/review-analyzer-skill (MIT). We adapted them onto an MCP-native architecture with the Shulex VOC OpenAPI data layer.
mcp_server/
├── server.py # 6 @mcp.tool decorators
├── tools.py # implementations (subprocess wrappers + Anthropic SDK)
├── csv_loader.py # fuzzy column detection for CSV/Excel input
├── dashboard.py # HTML rendering
├── dashboard_template.html # black-gold template (placeholders)
├── tag_system.yaml # 22-dim tag schema (customizable per category)
├── schemas.py # pydantic structured-output models
└── tests/ # 36 unit tests (subprocess + Anthropic mocked)
fetch.sh / analyze.sh / voc.sh # shell pipeline behind tools 1-3fetch + analyze loop: shell scripts (proven, reproducible, easy to debug)
listing rewrites: Anthropic SDK direct (claude-opus-4-7 + adaptive thinking + prompt caching on the system rubric)
dashboard: pure stdlib HTML rendering, no node / no react
Channel | Status |
✅ Open | |
✅ Open | |
🟢 Auto-indexed via GitHub topics | |
🟢 Auto-pull | |
mcp.so / PulseMCP | 🟡 Pending (manual form submit) |
Smithery | 🟡 Container deploy ready ( |
Official MCP Registry | 🟡 Pending PyPI publish (W2) |
Drop in CSV / Excel (any platform, fuzzy column detect)
22-dimension tag system (YAML-configurable)
Black-gold HTML dashboard tool
6 MCP tools shipped
npx skills add mguozhen/review-analyzer one-line install
CLI subprocess engine option (use your Claude subscription, $0 API)
PyPI publish + official MCP Registry submission
Smithery deploy config (smithery.yaml + Dockerfile)
Vercel deploy config (vercel.json + app.py)
Smithery / mcp.so / PulseMCP form submissions
MIT. See LICENSE.
Acknowledgments: Tag schema, CSV column detection, and dashboard visual design inspired by buluslan/review-analyzer-skill. Data layer powered by Shulex VOC OpenAPI.
Analyze any review CSV / Excel — not just Amazon.
Drag in a Helium 10 export, an eBay / AliExpress scrape, or your own
Shopify export. The loader fuzzy-matches column names (内容 / 评价 /
body / review / content all detected automatically) so you don't
have to reformat the file.
Use this when:
The product is NOT on Amazon (eBay / AliExpress / D2C)
You already have a reviews file from another source
You want to bypass the Shulex VOC API entirely
Args: csv_path: Local path or HTTP(S) URL to a .csv / .xls / .xlsx file. product_name: Optional friendly name for the report header. market: Optional marketplace tag (US / GB / OTHER, etc.).
Returns: Same shape as analyze_reviews, with meta.columns_detected
showing which columns the loader matched.
| Name | Required | Description | Default |
|---|---|---|---|
| csv_path | Yes | ||
| product_name | No | ||
| market | No | OTHER |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Despite no annotations, the description thoroughly discloses behavioral traits: supported file formats (csv, xls, xlsx), fuzzy column matching with examples, and return structure including meta.columns_detected. 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 well-structured with clear sections and front-loaded purpose. It could be slightly more concise (e.g., reduce redundancy in examples), but every sentence adds value.
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 moderate complexity, the description covers all essential aspects: supported sources, fuzzy matching, parameter details, and return shape reference. No output schema needed as return behavior is fully described in terms of a sibling 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?
With 0% schema coverage, the description compensates fully by explaining each parameter in an 'Args' section: csv_path as local path or URL, product_name as optional header, market as optional tag with default. Adds meaning beyond schema titles.
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 explicitly states it analyzes any review CSV/Excel, not just Amazon, using a specific verb and resource. It distinguishes from siblings by mentioning bypassing the Shulex VOC API and supporting non-Amazon sources.
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 a clear 'Use this when:' section with three explicit conditions: product not on Amazon, have a reviews file from another source, want to bypass the API. This offers direct guidance on when to use and implies alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Run AI analysis on reviews you already have.
Useful when you fetched reviews via fetch_reviews (or your own scraper)
and want the VOC report — sentiment breakdown, pain points, selling
points, listing tips — without re-paying the Shulex API.
Args:
reviews_json: Either fetch.sh's {reviews, meta} envelope, or a
bare list of review objects.
asin: 10-character ASIN that the reviews belong to (for the report
header).
Returns: {asin, market, report_markdown, sentiment, pain_points, selling_points, tips, summary_zh, summary_en}
| Name | Required | Description | Default |
|---|---|---|---|
| reviews_json | Yes | ||
| asin | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavioral traits. It mentions that using this tool avoids re-paying the Shulex API, which is a cost-related behavior. However, it does not mention whether the tool is read-only, requires authentication, or any other side effects. Given it is an analysis tool, the description is moderately 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 concise and well-structured, with separate paragraphs for purpose, usage, arguments, and returns. It is front-loaded with the action. Could be slightly shorter, but no unnecessary filler.
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 complexity (custom input format) and lack of output schema, the description covers all return fields and provides usage context. It explains how reviews_json can be two different formats, which is crucial. It also mentions the relationship to fetch_reviews. Missing details on error handling or limitations, but overall adequate.
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 coverage is 0%, so the description must compensate. It does so by specifying that reviews_json accepts either a specific envelope format or a bare list, and explains asin as a 10-character identifier for the report header. This adds significant meaning beyond the 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 explicitly states the tool runs AI analysis on reviews to produce a VOC report with specific components (sentiment, pain points, etc.). It distinguishes from sibling tools like fetch_reviews (which fetches reviews) by focusing on analysis of already-obtained 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?
The description clearly indicates when this tool is useful: after fetching reviews via fetch_reviews or a custom scraper, to get analysis without extra API cost. It does not explicitly state when not to use, but the context is implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Differentiator tool — derive specific, copyable listing improvements from the VOC report, grounded in actual customer language.
Instead of raw search-volume tables (Data Dive style), Claude reads the full VOC report and produces a title, 5 bullets, a description paragraph, and missing keywords — each suggestion citing the pain point it preempts or selling point it amplifies.
Requires ANTHROPIC_API_KEY. Costs ~$0.05-0.20 per call (claude-opus-4-7).
| Name | Required | Description | Default |
|---|---|---|---|
| asin | Yes | ||
| market | No | US | |
| limit | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It discloses the AI model (claude-opus-4-7), cost range, required API key, and output structure (title, bullets, etc.), which is good transparency. However, it does not mention latency or potential failure modes.
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 relatively concise, with two paragraphs that front-load the core value. Minor redundancy exists (e.g., 'grounded in actual customer language' and 'citing the pain point').
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 (AI model, cost, API key), the description covers what it does, input (implicitly ASIN/market/limit), output format, and prerequisites. It lacks detail on how to obtain the VOC report and does not provide an output schema, but the output structure is described in text.
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 has three parameters (asin, market, limit) with no descriptions (0% coverage). The description does not explain these parameters at all, so the agent gains no additional meaning beyond the 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 clearly identifies the tool as a 'differentiator' that produces specific listing improvements from a VOC report, distinguishing it from raw data tools like 'analyze_reviews'. However, it does not explicitly contrast with each sibling tool, leaving some ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides context by contrasting with 'Data Dive style' and mentions API key and cost, implying usage when actionable suggestions are needed. But it lacks explicit 'when not to use' guidance or explicit alternatives among siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch raw Amazon reviews for an ASIN via the Shulex VOC API.
No analysis — returns the raw review array plus metadata. Use this when
you want to plug reviews into your own analysis pipeline, or when you
plan to call analyze_reviews later (avoids paying the Shulex API
twice).
Args: asin: 10-character Amazon product ID (e.g. "B08N5WRWNW"). market: Market code (US, GB, DE, FR, IT, ES, JP, AU, CA, MX) or amazon.* domain ("amazon.co.uk"). Default: US. limit: Number of reviews to fetch (1-1000). Default: 100.
Returns: { "reviews": [{rating, title, body, date, verified, ...}, ...], "meta": {asin, market, total_available, fetched} }
| Name | Required | Description | Default |
|---|---|---|---|
| asin | Yes | ||
| market | No | US | |
| limit | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations, but description fully discloses behavior: returns raw review array plus metadata, and implies read-only fetch. Could mention rate limits or auth, but overall 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?
Concise yet complete, with clear sections for overview, usage context, args, and returns. Every sentence adds value.
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 all necessary aspects given no annotations or output schema: purpose, parameters, return format, and relationship with sibling tools. No gaps.
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 0% description coverage, but the description provides detailed semantics for all 3 parameters, including format, examples, defaults, and valid values.
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 'Fetch raw Amazon reviews for an ASIN' with specific verb and resource, and distinguishes from siblings by emphasizing no analysis and returning raw data.
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 describes when to use (for raw data or prior to analyze_reviews) and when not to (if analysis is needed elsewhere), with alternatives named.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Render a VOC report as a standalone black-gold HTML dashboard.
The output is single-file HTML — no external dependencies, opens directly
in any browser. Includes sentiment bar, pain-point / selling-point
panels, executive summary, and (if improvements provided) a
copy-ready listing optimization card.
Args:
report: Output from analyze_reviews / voc_full / analyze_csv.
improvements: Optional output from extract_listing_improvements.
product_name: Friendly product name for the headline.
output_path: Optional file path to write the HTML to.
Returns: {html, bytes, output_path}
| Name | Required | Description | Default |
|---|---|---|---|
| report | Yes | ||
| improvements | No | ||
| product_name | No | ||
| output_path | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. Describes output format and optional features (improvements card). However, lacks details on error handling, side effects (file writing), and default behavior when output_path is omitted. Acceptable but not comprehensive.
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 concise (~150 words) with a clear front-loaded purpose statement and a structured Args section. Every sentence contributes valuable information 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?
Given no annotations, no output schema, and 1 required param, the description covers the tool's function, inputs, and outputs adequately. It mentions return type {html, bytes, output_path}. Minor gap: does not clarify behavior when output_path is absent (presumably returns HTML string only).
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 0%, but the description's Args section explains each parameter's purpose and source (e.g., report from `analyze_reviews`, improvements from `extract_listing_improvements`). Adds significant meaning beyond the bare schema types.
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 renders a VOC report as a standalone HTML dashboard. Specifies output format (single-file HTML) and lists included sections (sentiment bar, panels, executive summary, optimization card). Distinguishes from sibling analysis tools by being a rendering step.
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?
Implicitly indicates usage after obtaining a report from sibling tools like `analyze_reviews`. Does not explicitly state when not to use, but the context is clear. Could be improved by stating prerequisites (e.g., 'Use after analysis tools').
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
One-shot: fetch reviews AND run AI analysis.
The default tool for "give me a VOC report on this ASIN" style requests.
Internally equivalent to bash voc.sh ASIN — calls fetch.sh and
analyze.sh in sequence.
Args: asin: 10-character ASIN. market: Market code or amazon.* domain (default: US). limit: Number of reviews to fetch (default 100, max 1000).
Returns: Same shape as analyze_reviews.
| Name | Required | Description | Default |
|---|---|---|---|
| asin | Yes | ||
| market | No | US | |
| limit | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It explains the composite nature and returns shape, but does not disclose behavioral traits like read-only status, rate limits, error handling, or permissions. The limit constraint (max 1000) is mentioned, adding some transparency.
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 highly concise and well-structured: a single-sentence purpose, an explanatory note, and a clear args section. Every sentence adds value without redundancy, and the formatting is 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?
The description references the output shape of analyze_reviews, which assumes knowledge of that sibling tool. Without an output schema or further explanation of the AI analysis results, the description is somewhat incomplete. Additionally, no behavioral details (e.g., error handling, idempotency) are provided, leaving gaps for a composite 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 description coverage is 0%, so the description compensates effectively. It specifies that asin is a 10-character ASIN, market is a market code or amazon.* domain, and limit is the number of reviews with default 100 and max 1000. This adds valuable meaning beyond the schema's titles and defaults.
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 is a one-shot tool that fetches reviews and runs AI analysis, positioning it as the default for VOC report requests. It identifies the specific action (fetch + analyze) and resource (ASIN), differentiating from siblings like fetch_reviews and analyze_reviews by being a combined operation.
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 a clear usage context ('VOC report on this ASIN') and explains the internal composition, but does not explicitly state when not to use it or mention alternative sibling tools for separate fetch or analysis tasks. The guidance is adequate but lacks exclusions.
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.
v0.1.0analyze_csvanalyze_reviewsextract_listing_improvementsfetch_reviewsrender_dashboardvoc_fullScored across 6 tools
Most tools have distinct purposes, but `analyze_reviews` and `voc_full` can be confused since both produce a VOC report, differing only in fetching. `analyze_csv` overlaps conceptually with `analyze_reviews` but is differentiated by input type. Descriptions help clarify but some ambiguity remains.
Names mostly follow verb_noun pattern (analyze_csv, fetch_reviews, render_dashboard) but `extract_listing_improvements` is longer and `voc_full` breaks the pattern entirely. Inconsistent but still readable.
6 tools is well-scoped for the domain of Amazon review analysis. Each tool covers a distinct step (fetch, analyze, improve, render, external CSV analysis) without being too many or too few.
Core workflow (fetch, analyze, improve, visualize) is complete. Minor gaps: no tool for comparing multiple ASINs or batch processing, but this is acceptable for a focused toolkit.
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
Amazon brand, seller, niche & buy-box intelligence inside your own Claude or ChatGPT.
Connect Amazon Seller Central to Claude or ChatGPT via MCP. Orders, inventory, pricing, fees, FBA.
Real-time Amazon product, seller, and search data for AI agents across 21 marketplaces.
