apiguru-amazon-data

Live offers and inventory for up to 10 ASINs

offers_stock

Read-onlyIdempotent

Fetch current Amazon offers per ASIN, including seller, price, condition, and buy-box winner, with optional true stock quantity for inventory checks.

Instructions

Returns the current offer list per ASIN (seller, price, condition, buy-box winner) and, optionally, the actual purchasable stock quantity. Price: $0.0045 per item (max 10). Billed per upstream Amazon request, which is more than one per ASIN when check_inventory is true. offers_count=winner returns only the offer flagged is_buybox_winner (offers_total keeps the full count); it used to scope only the inventory check and return every offer. /scrape is a legacy alias for the same handler.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`geo`	No	Marketplace country code.	US
`asins`	Yes	Comma-separated ASIN list, maximum 10. Each must be 10 uppercase alphanumeric characters; malformed entries are rejected with 400.
`condition`	No	Comma-separated condition filter: ALL, NEW, USED_LIKE_NEW, USED_VERY_GOOD, USED_GOOD, USED_ACCEPTABLE (case-insensitive). Omit for every offer. An unknown value is a free 400 listing the allowed ones; it used to be silently treated as ALL.
`offers_count`	No	'all' for every offer (default), 'winner' for the buy-box offer only, or a specific alphanumeric Offer ID. Every offer carries is_buybox_winner; with 'winner' the per-ASIN data holds that one offer and offers_total says how many exist. An ASIN with no featured offer answers an empty list with an explanatory error. The response echoes filters_applied.	all
`check_inventory`	No	Resolve the true purchasable stock quantity. Slower and bills more upstream requests, so leave off unless you need the number.

Output Schema

TableJSON Schema

Name	Required	Description	Default
`results`	No
`request_id`	No
`country_code`	No
`response_time`	No
`filters_applied`	No
`amazon_request_count`	No

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.1.0Sep 27, 2026

TDQS

A4.5/5.0

Behavior5/5

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

Adds substantial context beyond the readOnly/idempotent annotations: per-item pricing ($0.0045, max 10), billing granularity tied to upstream requests, the empty-list-with-error case for ASINs lacking a featured offer, the filters_applied echo, and the /scrape legacy alias. This is exactly the operational detail an agent needs before calling.

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

Conciseness3/5

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

Front-loads the core purpose well, but the parenthetical historical notes ('it used to scope only the inventory check', 'it used to be silently treated as ALL') add length without helping selection or invocation. The dense run-on sentences make the cost and behavior points harder to parse than necessary.

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?

With an output schema present, return format need not be described, and the description still covers pricing, billing, filtering semantics, defaults, and edge cases. An agent has everything required to invoke it correctly.

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, but the description adds real meaning: offers_count=winner returns only the flagged offer while offers_total preserves the full count, and it notes the historical behavior change. This clarifies semantics the enum value alone would not convey.

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 ('Returns the current offer list per ASIN') and enumerates the returned fields (seller, price, condition, buy-box winner) plus the optional inventory quantity. This clearly separates it from siblings like product_details, deals, and best_sellers.

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?

Explains the cost/billing tradeoff of enabling check_inventory ('billed per upstream Amazon request, which is more than one per ASIN') and the effect of offers_count=winner, which tells the agent when the extra spend is justified. It stops short of naming sibling tools or explicit when-not-to-use conditions.

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

Deploy Server