Skip to main content
Glama

Nova Amazon MCP Server

query_bsr

Read-only

Best Seller Rank (BSR) for the seller's products — the CORRECT dedicated source that keeps the per-marketplace (category, rank) pair intact (a plain average would sever it). Use THIS for any BSR question; query_metrics does NOT serve BSR. granularity='latest' (default) returns the last observed rank in the window plus period-average main/sub category ranks (with an optional change vs a baseline window); a time grain (day/week/month/quarter/year) returns a rank time series. Lower rank = better. Products: pass the list matching groupBy (skus / childAsins / parentAsins) — ALL of them in ONE call, rows come back per product; never loop one call per ASIN. Without that list the tool reports the best sellers of the catalogue (limit, default 50, by sales of the last 90 days) and says so in scope; parentAsins with groupBy childAsin reports those parents' children. An empty result never means 'no BSR data': it is a filter that matches nothing, and the error says which.

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": {
      "groupBy": "<groupBy>",
      "from": "<from>",
      "to": "<to>"
    },
    "name": "query_bsr"
  }
}

Input Schema

NameRequiredDescriptionDefault
toYesDate in ISO format (YYYY-MM-DD).
fromYesDate in ISO format (YYYY-MM-DD).
skusNo
tagsNo"Your Filters" tag IDS from list_tags (manual custom tags or predefined segmentations, Brand included) — a tag NAME is rejected.
limitNoWithout a product list only: how many best sellers to report (1–200, default 50). A product list is reported in full.
offsetNoWithout a product list only: best sellers to skip (pagination, default 0).
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.
groupByYesWhat to report BSR for.
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.
baselineToNoBaseline window end.
childAsinsNo
granularityNo'latest' (default) = last observed rank + period averages; a time grain = a rank series.
parentAsinsNo
baselineFromNoBaseline window start (latest mode) — enables the rank change vs baseline.
marketplacesNoMarketplace IDs.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observed

TDQS

A4.7/5.0
Behavior5/5

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

Annotations already establish read-only, closed-world, non-destructive behavior, so the description is free to add genuine operational context it does cover: rows come back per product, the default limit of 50 is ranked by 90-day sales, a `scope` field discloses which mode ran, and an empty result is a filter mismatch rather than missing BSR data, with the error identifying the culprit. These are the failure modes an agent would otherwise misread.

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?

Front-loaded with the resource and the routing decision, then ordered from mode selection to edge cases. Dense but nearly every clause carries distinct information; the capitalized emphasis ('CORRECT', 'THIS') and a few parentheticals add noise without adding meaning.

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

Completeness4/5

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

For a 15-parameter tool with no output schema, the description covers mode selection, product-list behavior, the best-sellers fallback, pagination scope, and empty-result semantics — enough to call it correctly. It leaves marketplace defaults, tag-ID requirements, and the reason field to the schema, which is acceptable given 80% schema coverage.

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 80%, so the baseline is 3; the description earns above that by explaining cross-parameter relationships the schema cannot express — that skus/childAsins/parentAsins must match groupBy, that limit/offset only apply when no product list is given, and that parentAsins with groupBy childAsin expands to children. It does not clarify tags, marketplaces, or the baseline window pairing, which remain schema-only.

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?

Names a specific metric (Best Seller Rank) for a specific resource (the seller's products) and explicitly contrasts itself with the sibling query_metrics, which it says does not serve BSR. Also states the key structural property it preserves — the per-marketplace (category, rank) pair — which no sibling implies.

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?

Gives explicit routing ('Use THIS for any BSR question; query_metrics does NOT serve BSR'), mode selection ('latest' vs a time grain), the list-matches-groupBy rule, the no-list best-sellers fallback, the parentAsins+groupBy childAsin case, and a prohibitive anti-pattern ('never loop one call per ASIN'). Both when-to-use and when-not-to-use are covered.

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.