Skip to main content
Glama
apiguru-app

apiguru-amazon-data

by apiguru-app
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Hybrid

Current Amazon deals with filters

deals
Read-onlyIdempotent

Retrieve current Amazon promoted offers with ASIN, title, offer price, list price, discount, badge, and start/end times; filter by category, brand, rating, price, discount, or Prime program.

Instructions

Use for items currently promoted in Amazon's deals feed. Not for one product's price (product_details); for a brand by name use search with brand= and today_deals=true. Returns the current Amazon deals feed: ASIN, title, deal price, list price, discount, deal badge, start/end time and product links. Filter by department (categories), brand id (brands), rating cut-off, price bounds, minimum discount and Prime program. Every answer carries available_filters (the category and brand ids this marketplace accepts, with names), filters_applied / filters_ignored (what took effect) and next_offset (the next page, null when the feed ends). Price: $0.003 per call. Filters are by id: categories takes a department id or name, brands takes brand ids only; available_filters in every answer lists both with names, and filters_applied / filters_ignored report what Amazon honoured. A page is 30 rows; page with offset=next_offset (null when exhausted); total_count caps at 500. min_price, max_price, min_discount and max_discount are applied to the rows after retrieval, scanning up to 3 feed pages per call, so a page can hold fewer than 30 rows and total_count does not reflect them. An empty answer carries a hint saying why. Deal prices expire: check deal_ends_at. The older price_range and discount_range parameters are still accepted, as buckets (1-5 = under 25 / 25-50 / 50-100 / 100-200 / 200 and up; 1-4 = 10 / 25 / 50 / 70 percent off or more) or as bands such as 25-50 and 70+.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
geoNoMarketplace country code.US
limitNoHow many deals to return from this page (0 = all of them). A full page is 30 rows and roughly 35 KB with every field, which most clients spill to a file instead of showing inline. The answer carries _truncated with the true count when it trims.
brandsNoComma-separated brand ids, e.g. 46655 for Samsung on US. Take them from brand_id on any deals row or from available_filters.brands (the brands present in the current result). Names resolve only when this marketplace has already shown that brand; for a brand by name use /search with brand=<name> and today_deals=true instead.
fieldsNoComma-separated row fields to return instead of the light set, e.g. "asin,product_title,product_price". Rows list what they left out under _omitted_fields.
offsetNoRow to start at. A page is 30 rows; pass the previous answer's next_offset for the next page.
compactNoReturn light rows: identity, prices, discount, badge, end time, links, brand_id and department_ids, dropping the image arrays. false returns every field the REST API sends.
max_priceNoHighest deal price to return, in the marketplace currency.
min_priceNoLowest deal price to return, in the marketplace currency. Applied to the fetched rows; see notes.
categoriesNoDepartment to restrict to: its id from available_filters.categories, or its name as Amazon shows it for that marketplace (case-insensitive; a unique fragment such as "electronics" works). US departments: Amazon Devices & Accessories, Appliances, Arts Crafts & Sewing, Audible Books & Originals, Automotive, Baby Products, Beauty & Personal Care, Books, CDs & Vinyl, Cell Phones & Accessories, Clothing Shoes & Jewelry, Collectibles & Fine Art, Electronics, Everything Else, Grocery & Gourmet Food, Handmade Products, Health & Household, Home & Kitchen, Industrial & Scientific, Kindle Store, Movies & TV, Musical Instruments, Office Products, Patio Lawn & Garden, Pet Supplies, Software, Sports & Outdoors, Tools & Home Improvement, Toys & Games, Video Games. Other marketplaces use their own localised names -- read them from available_filters.categories of any deals answer for that geo. An unknown name is a free 400 listing the valid names.
max_discountNoLargest discount percentage to return.
min_discountNoSmallest discount percentage to return, e.g. 50 for half price or better.
prime_exclusiveNoOnly deals in Amazon's Prime Exclusive program.
prime_early_accessNoOnly Prime Early Access deals. A marketplace lists the programs it is running under available_filters.prime_programs; when Early Access is not running the answer is empty with a hint saying so.
min_product_star_ratingNoAmazon's deals feed offers one rating cut-off: 4 = four stars and up. ALL or omitted = no cut-off. Other values are rejected with a free 400.

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault
dealsNo
successNo
request_idNo
amazon_request_countNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv1.1.50
    • changedInput schema / properties / geo / enum
      Previous value: -[
-  "US",
-  "CA",
-  "DE",
-  "MX",
-  "UK",
-  "FR",
-  "IT",
-  "ES",
-  "AU",
-  "BR",
-  "IN",
-  "JP",
-  "NL",
-  "AE",
-  "PL",
-  "SA",
-  "SG",
-  "SE",
-  "TR",
-  "BE"
-]New value: +[
+  "US",
+  "CA",
+  "DE",
+  "MX",
+  "UK",
+  "FR",
+  "IT",
+  "ES",
+  "AU",
+  "BR",
+  "IN",
+  "JP",
+  "NL",
+  "AE",
+  "PL",
+  "SA",
+  "SG",
+  "SE",
+  "TR",
+  "BE",
+  "IE",
+  "ZA",
+  "EG"
+]
  2. First observedv0.1.0

TDQS

A4.6/5.0
Behavior4/5

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

Annotations cover the safety profile (readOnly, idempotent, non-destructive), and the description goes well beyond by disclosing per-call cost, the post-retrieval filtering quirk (min_price/max_discount applied after fetch across up to 3 pages, so pages can hold fewer than 30 rows and total_count ignores them), the 500 total_count cap, hint behavior on empty answers, and deal expiry via deal_ends_at. Slightly diluted by restating the available_filters/filters_applied behavior twice, but the disclosure load is high.

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 purpose then routing, then return shape, then filtering caveats. Efficient overall, but the middle section restates the available_filters / filters_applied / filters_ignored contract twice with near-identical wording, which is wasted space in an otherwise dense definition.

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 and annotations covering safety, the description only needs to cover gaps, and it does: pagination via next_offset, cost, truncation, the 500-row ceiling, empty-result hints, and the post-retrieval filter semantics that materially change what a caller sees. Nothing an agent needs to call this correctly is missing.

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: filters are by id, categories accepts id or case-insensitive name (with a free 400 on unknown names), brands accepts ids only, and inner- vs post-retrieval filtering is explained. It also documents the legacy price_range/discount_range bucket semantics that the schema does not carry.

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?

Opens with a specific verb and resource ('items currently promoted in Amazon's deals feed') and immediately distinguishes itself from two siblings by name, product_details and search. An agent can route correctly without opening 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 Guidelines5/5

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

Explicit exclusions with the alternative to use instead: 'Not for one product's price (product_details); for a brand by name use search with brand= and today_deals=true.' Also states the correct mechanism for brand-ID lookups and points to available_filters for valid ids.

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

Deploy Server

Other Tools