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

Fetch current Amazon discounted products filtered by category, brand, price, discount, rating, and Prime program, with pagination and filter feedback.

Instructions

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 the fetch, scanning up to 3 upstream 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. First observedv0.1.0

TDQS

A4.6/5.0
Behavior5/5

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

Goes well beyond the readOnly/openWorld/idempotent annotations: discloses per-call pricing ($0.003), the post-fetch semantics of min_price/max_price/min_discount/max_discount (rows filtered after fetch, up to 3 upstream pages scanned, pages may hold fewer than 30 rows, total_count not reflecting them), the 30-row page and 500-row total_count cap, price expiry via deal_ends_at, and that available_filters/filters_applied/filters_ignored ride along in every answer.

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-loads the return shape, then filters, answer metadata, cost, id semantics, pagination and the post-fetch caveat. Every sentence carries real information, though the single-paragraph form is dense and the legacy-parameter sentence runs long.

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 14-parameter, open-world, paginated feed with an output schema, the description covers everything an agent needs: cost, pagination contract, filter-id mechanics, post-fetch filtering caveats, expiry and empty-result behaviour. Nothing material is left to inference.

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 genuine meaning on top: categories accepts an id or a localised name/fragment (with the free 400 listing valid names), brands accepts ids only, and it documents the legacy price_range/discount_range bucket and band encodings that do not appear in the schema at all.

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+resource ('Returns the current Amazon deals feed') and enumerates the exact row fields delivered (ASIN, title, deal price, list price, discount, badge, times, links). This is clearly distinguishable from siblings like best_sellers and search, which are separate feeds.

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?

Gives concrete routing guidance: brand-by-name must go through /search with brand=<name> and today_deals=true instead, categories must come from available_filters, and empty answers carry a hint explaining why. It does not spell out broader when-not conditions (e.g. vs best_sellers), so it stops short of a 5.

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