APIClaw

openapi_v2_markets_fulfillment_distributions

Function

Select up to 100 Amazon Listings with the highest monthly unit sales or monthly revenue in the market, then group them by fulfillment type. 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.

Use cases

Profile supply by fulfillment type and compare Listing counts, sales, revenue, prices and ratings to inform fulfillment choices and operational positioning.

Example

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

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.

Input Schema

Name	Required	Description	Default
`date`	No	Published 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.
`sampleType`	No	unitSalesTop100 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
`categoryIds`	Yes	Real category IDs; each ID selects an independent market.
`marketplace`	No	Marketplace code; currently US only.	US
`includeDescendantCategoryProducts`	No	true includes products from this category and its descendants; false counts only directly assigned products. Controls product statistics, not market-row selection.

Output Schema

Name	Required	Description
`data`	No	Response data payload
`meta`	Yes	Response metadata including pagination info
`error`	No	Error details if request failed
`success`	No	Whether the request was successful

Schema Changelog

Changes observed during successful MCP inspections.

AddedOct 21, 2026

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 behavioral burden and does so thoroughly: US-only scope, sample-of-100 methodology, null handling for missing metrics and means, distinct-denominator caveats, snapshot/date resolution rules, and a billing model (balance check does not deduct credits, empty data costs zero, billing per distinct returned market).

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?

The numbered sections (Function, Use cases, Example, Data range) front-load the purpose and the example JSON is immediately usable. The 'Data range' paragraph is a dense run-on mixing scope, nulls, billing and denominators, which slightly hurts scanability.

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?

An output schema exists, so return values need not be described, and the description still covers the remaining agent-facing gaps: scope, sample construction, date/snapshot behavior, and credit/billing implications. Nothing material for correct invocation is missing.

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 all five parameters are already documented in the schema, including date, sampleType, categoryIds and includeDescendantCategoryProducts semantics. The description largely restates these (date omission, sampleType ranking) rather than adding syntax the schema lacks, so the baseline of 3 is appropriate.

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 'Function' section states a precise verb and resource: select up to 100 Amazon Listings by monthly unit sales or revenue and group them by fulfillment type, then list the exact output metrics. This distinguishes it clearly from the many sibling distribution tools (price, rating, content, listing-age) which group by a different dimension.

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 by fulfillment type and compare counts, sales, revenue, prices and ratings to inform fulfillment choices. However, it never states when NOT to use this tool nor names an alternative among the numerous sibling *_distributions tools, so the agent must infer the routing itself.

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

All APIClaw tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources

Need Help?