Skip to main content
Glama

Nova Amazon MCP Server

query_reviews

Read-only

Amazon REVIEWS and RATINGS of the seller's products, per ASIN and marketplace (Amazon Data Kiosk): the reviews received over a period, the critical ones (3 stars or less), the star rating and the ratings count Amazon displays, and a review rate. The same route as the app's Reviews columns and modal, on the Seller Central (3P) accounts of the call. Metric keys are their OWN universe, not list_metrics keys: reviews, critical_reviews, critical_review_share, review_units, review_rate, rating, ratings, rating_week_end, rating_marketplace (describe_metric defines each). ⚠️ READ BEFORE ANSWERING. (1) The COUNTS (reviews, critical_reviews, critical_review_share, review_units, review_rate) exist only on the marketplaces where Amazon serves them: US, CA, MX, BR. Everywhere else, Europe included, they are null (n/a), never 0. (2) A review belongs to the ASIN: every new rating from ANY buyer of the ASIN, written or not (the product page lists the written ones only), not only this seller's buyers. So there is no SKU grain (a SKU or tag filter reads its ASIN's reviews), and two seller accounts carrying one ASIN carry the same reviews: never add up the rows of groupBy sellerAccount yourself, summary.total counts each ASIN once. (3) Amazon serves a day of reviews about 3 days late, and its last served day is still filling: the answer's reviews_served_from and reviews_served_to are the first and last days served, reviews_complete_to the last complete one. Compare periods, or compute a pace or a rate, over complete days only. In a series a bucket without a review reads null: no review on a served day, not known on the others. (4) rating and ratings are the state the product page displays (ratings is Amazon's count for the ASIN worldwide since its launch, not the period's), read at the period end, never a period total. A row covering several marketplaces reads its top-selling one (rating_marketplace), never a blend; never add ratings up across rows. Amazon keeps no rating history: Nova's is its own reads, which started on 2026-10-01 (per week, the first document closes on 2026-09-26); a bucket before the first read is empty, never 0. (5) review_rate = the ASIN's reviews (all buyers) per 100 units sold by THIS account (review_units): meaningful only where the seller is the ASIN's only seller (its own brand), meaningless on a reseller's shared ASINs (it can exceed 100). (6) NO comparison mode: call once per period. (7) groupBy is EITHER an entity grain (parentAsin, marketplaceParentAsin, childAsin, marketplace, sellerAccount) OR a time grain (day, week, month), never both: for one product's series, filter on it and group by the grain. Per day, week or month: the flows (reviews, critical_reviews, critical_review_share). Per day (as read each day) or week (Amazon's week documents), never month, and in a call of their own: rating, ratings, rating_week_end. Never per time bucket: review_units, review_rate, rating_marketplace. A series comes whole and in date order, one row per bucket: no sortBy, limit or offset, and 1000 buckets at most (over a long period, group by week or month). 🔒 HISTORY: every plan reads the whole history, except a read of review_units or review_rate by an organization on its free trial (no subscription yet, an abandoned checkout included, or no active subscription while its 14-day trial still runs): nothing before its floor is served then, its reviews included, and the answer carries dataFloor, that ISO day, when Nova can state the floor that applied. A paying plan, and a plan cancelled after its trial ended, read the whole history. Vendor Central (1P) accounts have no reviews here: Amazon serves vendors no rating and no review count.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "metrics": "<metrics>",
      "period": "<period>"
    },
    "name": "query_reviews"
  }
}

Input Schema

NameRequiredDescriptionDefault
limitNoRows per page of an entity grouping, 1 to 1000 (default 50). Not with a time grain: a series comes whole.
offsetNoRow offset for paging an entity grouping (default 0). Not with a time grain.
periodYesREQUIRED. The flows are summed over it; rating and ratings are the state at its end. No comparison period: call once per period.
reasonNoOne sentence, ALWAYS IN ENGLISH (regardless of the conversation language), on WHY you are making this call — the user question or your analytical goal. Recorded so the seller can see how their data is used.
sortByNoA metric of `metrics` to rank the rows of an entity grouping by (e.g. "reviews"); rating_week_end and rating_marketplace sort alphabetically. Not with a time grain: a series comes in date order.
filtersNoRestrict the read. Omit for every product of the accounts.
groupByNoEITHER an entity grain: parentAsin (a variation family, in every marketplace where it exists), marketplaceParentAsin (a family on ONE marketplace, keyed '<marketplaceId>:<parentAsin>': the app's parent rows), childAsin, marketplace or sellerAccount; OR a time grain: day, week or month (one row per bucket, the whole series). Omit, or null, for one total row.
metricsYesReviews metric keys: reviews, critical_reviews, critical_review_share, review_units, review_rate, rating, ratings, rating_week_end, rating_marketplace. Their own universe: NOT list_metrics, ads or SQP keys. A natural name that means exactly one of them (e.g. "review rate") is resolved and echoed under `metricAliases`.
accountsNoRestrict to a subset of your own seller account IDs (from list_accounts). Omit to include all your accounts. A brand/account name is accepted and resolved to its id when it matches one of your accounts unambiguously; a label that carries the id ("Brand (A1B2C3D4E5F6G)") resolves to that id.
sortOrderNodesc (default) = biggest first, asc = smallest first. Not with a time grain.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observed

TDQS

A4.8/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations only establish readOnly/non-destructive, and the description adds substantial context beyond them: reviews are served roughly 3 days late with the last day still filling (reviews_served_from/to, reviews_complete_to), null means not-served rather than zero, a bucket without a review reads null, rating history starts 2026-10-01, and free-trial organizations get a truncated history surfaced as dataFloor. It also warns that summary.total dedupes ASINs so seller-account rows must not be summed.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Purpose is front-loaded in the first sentence before the warning block, and the numbered points are individually load-bearing given the metric quirks. It is nonetheless very dense and repeats rules already carried by the schema (groupBy exclusivity, limit not with a time grain), so it is well-organized but not maximally economical.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 10-parameter tool with nested filters, no output schema, and highly non-obvious metric semantics, the description covers grain constraints, null-vs-zero semantics, deduplication across seller accounts, latency, history floors, and vendor-account exclusion. An agent has everything needed to call it correctly and interpret the rows without further documentation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3, and the description goes beyond it by explaining that limit/offset/sortBy do not apply to time grains, that groupBy is an exclusive either/or with null meaning one total row, and by enumerating the exact reviews metric keys and their alias resolution. Some of this restates the schema's own parameter descriptions (e.g. the groupBy and limit wording), which keeps it from a 5.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The first sentence names a specific verb-less but unambiguous resource: Amazon reviews and ratings of the seller's products, per ASIN and marketplace, sourced from Amazon Data Kiosk. It explicitly separates the tool from the metric-family siblings by stating that the metric keys are "their OWN universe, not list_metrics keys" and by pointing to describe_metric for definitions.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The numbered block gives explicit when-to-use and when-not-to-use rules: no comparison mode (call once per period), groupBy must be either an entity grain or a time grain, rating/ratings only per day or week and never month, review_units/review_rate/rating_marketplace never per time bucket, and 1000-bucket cap with the workaround of grouping by week or month. It also states the free-trial history floor and that Vendor Central accounts have no reviews here.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.