Skip to main content
Glama

openapi_v2_markets_seller_country_distributions

  1. Function

Select up to 100 Amazon Listings with the highest monthly unit sales or monthly revenue in the market, then group them by seller country. Each group returns Listing count and share, monthly unit sales and share, monthly revenue and share, and per-Listing means for price, star rating, rating count, monthly unit sales and monthly revenue.

  1. Use cases

Profile supply origins by seller country; compare Listing counts, sales and revenue to understand geographic competition in the selected sample.

  1. Example

{"categoryIds":["679399011"],"sampleType":"unitSalesTop100"}

  1. Data range

US marketplace only. Each category is analyzed independently; product coverage can include or exclude descendants. Missing metrics remain null. Based on a leading sample of up to 100 Amazon Listings selected by monthly unit sales or revenue; results describe the sample. Omit the date for the latest available snapshot. An explicit date requires a published snapshot on that day; otherwise return no data. Use the resolvedDate returned by market search to query the same snapshot. Before querying, balance must cover the distinct requested market count at the endpoint unit price; this check does not deduct credits. Billing counts distinct returned markets (site and category ID); empty data costs zero. Price and rating means in this response exclude Listings whose corresponding metric is null; zero values participate. Different means can have different denominators; no valid values returns null.

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": {
      "categoryIds": "<categoryIds>"
    },
    "name": "openapi_v2_markets_seller_country_distributions"
  }
}

Input Schema

NameRequiredDescriptionDefault
dateNoPublished snapshot date (YYYY-MM-DD). Omit for the latest available common snapshot; an unpublished explicit date returns no data. Use the resolvedDate returned by market search to query the same snapshot.
sampleTypeNounitSalesTop100 selects up to 100 Amazon Listings by monthly unit sales; revenueTop100 selects up to 100 by monthly revenue. Concentration analysis uses the same metric to rank products, brands or sellers and calculate their sample shares.unitSalesTop100
categoryIdsYesReal category IDs; each ID selects an independent market.
marketplaceNoMarketplace code; currently US only.US
includeDescendantCategoryProductsNotrue includes products from this category and its descendants; false counts only directly assigned products. Controls product statistics, not market-row selection.

Output Schema

NameRequiredDescriptionDefault
dataNoResponse data payload
metaYesResponse metadata including pagination info
errorNoError details if request failed
successNoWhether the request was successful

Schema Changelog

Changes observed during successful MCP inspections.

  1. Added

TDQS

A4.4/5.0
Behavior5/5

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

With no annotations, the description carries the full burden and delivers: US-only scope, the 100-Listing sampled (not population) nature of results, null handling for missing metrics and per-metric denominators, snapshot/date semantics, and explicit billing rules (distinct returned markets, empty data costs zero, balance pre-check). This is unusually rich behavioral disclosure.

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?

Numbered sections (Function, Use cases, Example, Data range) front-load the purpose effectively, and the example is compact. The 'Data range' block is dense and repeats some date rules already in the schema, slightly hurting conciseness but the depth is defensible for an annotation-free tool.

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 complex, US-only, sampled distribution tool, the description covers scope, sampling limitations, cost, and empty-result behavior, while the output schema handles return structure. An agent has everything needed to decide and invoke correctly.

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

Parameters3/5

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

Schema description coverage is 100%, so parameters are already documented, and the description's example ({categoryIds, sampleType}) adds little semantic detail beyond the schema. It reinforces date/sample meaning but does not introduce formats or constraints the schema lacks, so the baseline 3 applies.

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?

States a precise verb and resource: select up to 100 Listings by monthly unit sales or revenue and group them by seller country, returning count/share/sales/revenue metrics. The grouping key (seller country) distinguishes it from sibling distribution tools such as price, rating, fulfillment, content, and listing-age distributions without needing to open the schema.

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

Usage Guidelines4/5

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

The 'Use cases' section gives clear context — profile supply origins by seller country and compare counts/sales/revenue for geographic competition — which tells an agent when this tool is relevant. It does not, however, name exclusions or which sibling to prefer when a different distribution dimension is wanted.

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.

Resources