Live Amazon product, review, search, deal, offer/stock and seller data across 20 marketplaces.
Returns the current Amazon best-seller list for a category, with optional subcategory drill-down and pagination. Price: $0.01 per call. No required parameters - calling it bare returns US appliances page 1.
| Name | Required | Description | Default |
|---|---|---|---|
| geo | No | Marketplace country code. | US |
| page | No | Result page, 1-based. | |
| limit | No | How many ranked products to return from this page (0 = all of them). A full page is up to 48 rows and about 54 KB, which most clients spill to a file instead of showing inline. The answer carries _truncated with the true count when it trims. | |
| fields | No | Comma-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. | |
| compact | No | Return light rows: identity, price, rating, badges and one delivery_date, dropping the long delivery prose that repeats itself across three fields. false returns every field the REST API sends (roughly 3x the size). | |
| category | No | Category slug, lowercased by the server. Defaults to 'appliances'. | appliances |
| subcategory_code | No | Optional subcategory node id to drill into. |
| Name | Required | Description |
|---|---|---|
| data | No | |
| success | No | |
| request_id | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare read-only, idempotent, non-destructive behavior. The description adds valuable behavioral details beyond those annotations, including the $0.01 per-call cost, the existence of pagination and subcategory drill-down, and the exact default bare-call result. This is useful context that annotations alone do not convey.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three concise sentences with no filler: purpose, cost, and default behavior. It is front-loaded with the core action and resource, and every sentence adds distinct information that helps the agent decide and invoke correctly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the rich input schema (100% parameter coverage), existing output schema, and comprehensive annotations, the description is complete enough for an agent to understand what the tool does, what a default call returns, and how pagination/subcategory drill-down work. No critical operational context is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the input schema already documents all seven parameters in detail. The description adds only a high-level summary of the default call rather than deeper parameter semantics, which is acceptable given the schema's completeness. The baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Returns'), a clear resource ('current Amazon best-seller list for a category'), and key scope modifiers ('optional subcategory drill-down and pagination'). This clearly distinguishes it from sibling tools like search, deals, and product_details, which serve different purposes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives practical usage context by noting 'No required parameters - calling it bare returns US appliances page 1,' which tells an agent exactly what a minimal call will do. It does not explicitly name alternatives or when-not-to-use conditions, but the intended use case is clear from the description and title.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Returns active Amazon deals, filterable by category, brand, minimum star rating, price band, discount band, and Prime early access. Price: $0.01 per call. The bucket parameters are ordinal buckets, not literal prices or percentages. min_product_star_rating rejects 5.
| Name | Required | Description | Default |
|---|---|---|---|
| geo | No | Marketplace country code. | US |
| limit | No | How many deals to return from this page (0 = all of them). A full page is up to 48 rows and about 54 KB, which most clients spill to a file instead of showing inline. The answer carries _truncated with the true count when it trims. | |
| brands | No | Brand filter. | |
| fields | No | Comma-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. | |
| offset | No | Pagination offset, non-negative. | |
| compact | No | Return light rows: identity, price, rating, badges and one delivery_date, dropping the long delivery prose that repeats itself across three fields. false returns every field the REST API sends (roughly 3x the size). | |
| categories | No | Category filter. | |
| price_range | No | Price band bucket 1-5, or ALL. | |
| discount_range | No | Discount band bucket 1-4, or ALL. | |
| prime_early_access | No | Restrict to Prime early access deals. | |
| min_product_star_rating | No | Minimum star rating. Only 1, 2, 3, 4 or ALL are accepted - 5 is rejected with 400. |
| Name | Required | Description |
|---|---|---|
| deals | No | |
| success | No | |
| request_id | No | |
| amazon_request_count | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover read-only, idempotent, open-world, and non-destructive behavior. The description adds useful facts beyond that: the $0.01 per-call price, bucket parameters being ordinal rather than literal, and min_product_star_rating rejecting 5. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short sentences with the main purpose front-loaded and no filler. Each sentence carries a distinct, useful fact: what the tool does, the cost, and key behavioral caveats.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the comprehensive input schema, output schema, and rich annotations, the description covers the essential cross-cutting facts an agent needs (pricing, bucket semantics, rejection). Nothing necessary for correct invocation is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and each parameter already has a clear description. The description adds a cross-cutting semantic clarification that bucket parameters are ordinal buckets, not literal prices or percentages, which applies to price_range, discount_range, and min_product_star_rating. This adds value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description states a specific verb and resource: 'Returns active Amazon deals' and enumerates the available filters. This clearly identifies the tool's domain and distinguishes it from product, search, and seller siblings by focusing on deals.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives like best_sellers or search. It does not state conditions, exclusions, or mention sibling tools at all. The only implicit context is that it returns deals, which is purpose, not usage guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List every Apiguru endpoint with its price, required parameters and supported marketplaces, plus your current access mode, cache and session budget. Free: answers locally with no network request and no charge. Call this before paid tools if you need to plan.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark the tool as read-only, idempotent, and non-destructive. The description adds meaningful behavioral context by stating it is free, answers locally with no network request, and avoids any charge, which goes beyond what the annotations convey.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact, front-loaded with the core purpose, and every sentence adds value. It efficiently conveys what the tool lists, that it is free and local, and when to call it.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With an output schema present, no return-format explanation is needed, and the zero-parameter schema leaves no input ambiguity. The description covers purpose, cost behavior, local execution, and usage timing, making it fully sufficient for an agent to invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the description carries no parameter burden; the baseline of 4 applies. The description does not need to explain input semantics since there are none.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists every Apiguru endpoint with price, required parameters, and supported marketplaces, making its purpose unmistakable. It also distinguishes itself from the sibling tools by being a free, meta-level capability listing rather than a data retrieval tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly advises calling this tool before paid tools when planning is needed, giving clear usage context. It does not enumerate when-not-to-use cases or name alternative tools, but the guidance is sufficiently clear for an agent to choose it appropriately.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Returns the current offer list per ASIN (seller, price, condition, buy-box winner) and, optionally, the actual purchasable stock quantity. Price: $0.015 per item (max 10). Billed per upstream Amazon request, which is more than one per ASIN when check_inventory is true. /scrape is a legacy alias for the same handler.
| 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. Any of ALL, NEW, USED_LIKE_NEW, USED_VERY_GOOD, USED_GOOD, USED_ACCEPTABLE. Unrecognised values silently fall back to ALL. | |
| offers_count | No | 'all' for every offer, 'winner' for the buy-box offer only, or a specific alphanumeric Offer ID. | all |
| check_inventory | No | Resolve the true purchasable stock quantity. Slower and bills more upstream requests, so leave off unless you need the number. |
| Name | Required | Description |
|---|---|---|
| results | No | |
| request_id | No | |
| country_code | No | |
| response_time | No | |
| amazon_request_count | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark it read-only and idempotent, and the description adds valuable behavioral context: per-item pricing, upstream request billing, extra upstream requests when check_inventory is true, and the /scrape legacy alias. This goes beyond what annotations or schema provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three dense sentences with no fluff, opening with the core return value and then covering cost, billing behavior, and the legacy alias. Every sentence adds actionable information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the read-only annotations, full schema coverage, and an output schema, the description supplies the missing operational context: pricing, upstream requests, and the optional inventory mode. An agent has enough to invoke and interpret the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
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 meaning by explaining the cost and latency implication of check_inventory and reinforcing the maximum of 10 ASINs. It also clarifies the optional, purchasable-stock intent beyond the schema's field label.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb and resource: 'Returns the current offer list per ASIN' with seller, price, condition, and buy-box winner, plus optional inventory. It is clearly distinct from siblings like product_details or search, and the title reinforces the 'up to 10 ASINs' scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The purpose statement makes it clear when offers/inventory data is needed, and the check_inventory guidance says to leave it off unless the stock number is required. However, it does not explicitly name alternative tools or state when not to use this tool versus siblings such as product_details_batch.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetches the complete product record for one ASIN on one marketplace: title, price, star rating, rating count, images, description, feature bullets, variations and category. Price: $0.01 per call. 404 means the ASIN is absent from that marketplace and IS billed. 503 means our fetch failed and is NOT billed - retry. Bullet points and specs are what Amazon shows for the listing; on multi-variant listings they can describe the product family rather than the exact variant. A null field means Amazon did not show it.
| Name | Required | Description | Default |
|---|---|---|---|
| geo | No | Marketplace country code. | US |
| asin | Yes | Single Amazon ASIN, 10 uppercase alphanumeric characters. Exactly one - comma-separated lists are rejected; use product_details_batch for many. | |
| fields | No | Comma-separated top-level fields to return instead of the compact set, e.g. "tech_specs,product_information". Any response lists what it left out under _omitted_fields. | |
| compact | No | Return the compact record (about 4 KB: identity, price, rating, availability, bullets, category, offer, buy box). false returns the full record (about 75 KB, includes from_manufacturer, tech_specs, product_information, product_reviews). |
| Name | Required | Description |
|---|---|---|
| data | No | |
| success | No | |
| request_id | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the read-only, idempotent, open-world annotations, the description discloses per-call pricing, billing consequences of 404s, retry behavior for 503s, the multi-variant caveat about bullets/specs, and the meaning of null fields. This is exactly the behavioral context an agent needs to set expectations and handle failures.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Each sentence earns its place: scope and data list, cost, billing/error semantics, data-acuracy caveat, and null-field meaning. The most important information is front-loaded, and the prose is dense without being verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With an output schema available, annotations covering safety and idempotence, and parameters fully documented in the schema, the description supplies the missing operational pieces: cost, billing on 404, retry on 503, multi-variant semantics, and null meaning. Nothing essential for using the tool correctly is left out.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already covers all four parameters fully: asin has a pattern and format, geo has an enum, fields has an example, and compact describes sizes and outputs. The description does not add new parameter-level meaning beyond confirming the single-ASIN scope, so the schema-heavy baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool fetches the complete product record for one ASIN on one marketplace, and it enumerates the data returned: title, price, rating, images, bullets, variations, category. The 'one ASIN' scoping distinguishes it from batch and search tools, and the title reinforces the purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear operational guidance: it works on a single ASIN per marketplace, and it explains when to retry (503, not billed) versus when not to (404, billed). It does not explicitly name alternatives such as product_details_batch for multiple ASINs, but the single-ASIN framing and error-handling instructions make the intended use clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Batch variant of product_details. Accepts a comma-separated ASIN list, deduplicates it, and fetches all of them concurrently. Far cheaper and faster than N single calls. Price: $0.008 per item (max 20). Billed per ASIN processed, including ones that come back not-found. More than 20 ASINs returns 413. Bullet points and specs are what Amazon shows for the listing; on multi-variant listings they can describe the product family rather than the exact variant. A null field means Amazon did not show it.
| Name | Required | Description | Default |
|---|---|---|---|
| geo | No | Marketplace country code. | US |
| asins | Yes | Comma-separated ASIN list, maximum 20 after de-duplication. Each must be 10 uppercase alphanumeric characters. | |
| fields | No | Comma-separated top-level fields to return instead of the compact set, e.g. "tech_specs,product_information". Any response lists what it left out under _omitted_fields. | |
| compact | No | Return the compact record (about 4 KB: identity, price, rating, availability, bullets, category, offer, buy box). false returns the full record (about 75 KB, includes from_manufacturer, tech_specs, product_information, product_reviews). |
| Name | Required | Description |
|---|---|---|
| results | No | |
| request_id | No | |
| country_code | No | |
| response_time | No | |
| amazon_request_count | No | |
| billable_requests_count | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the read-only/idempotent annotations, the description discloses deduplication, concurrent fetching, per-ASIN billing including not-found results, the 413 limit beyond 20 ASINs, the multi-variant listing caveat for bullets/specs, and the meaning of null fields. This is far more behavioral transparency than annotations alone provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Every sentence carries distinct operational value: batch identity, concurrency, cost, billing edge case, limit behavior, data caveat, and null-field interpretation. The description is compact relative to the amount of behavior it discloses and front-loads the most important facts.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description, combined with the detailed schema and annotations, covers what the tool does, when to use it, its limits, its costs, edge-case behaviors, and returned-field semantics. With an output schema present, return-value details are already handled, so no meaningful operational gap remains.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3; the description adds meaningful semantics by explaining deduplication and the 20-ASIN maximum, the not-found billing consequence, and the semantic caveat that bullets/specs may describe the product family rather than the exact variant. This enriches the parameter meaning without contradicting the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: 'Batch variant of product_details', 'Accepts a comma-separated ASIN list... fetches all of them concurrently.' It clearly differentiates itself from product_details and other siblings by focusing on the batch ASIN capability rather than reviews, sellers, or offers.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context: use this batch variant when you need multiple ASINs, and it is 'far cheaper and faster than N single calls.' It names product_details as the base variant, implying single-ASIN use is routed there, though it does not explicitly state when-not or list alternative tools for overlapping needs.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Returns the review block for one ASIN: overall star rating, total rating count, Amazon's 'customers say' AI summary, and the individual review list. Price: $0.01 per call. Same 404-billed / 503-not-billed semantics as product_details.
| Name | Required | Description | Default |
|---|---|---|---|
| geo | No | Marketplace country code. | US |
| asin | Yes | Single Amazon ASIN, 10 uppercase alphanumeric characters. | |
| max_reviews | No | Cap on individual reviews returned (0 = all). The rating summary and customers_say are always returned; _reviews_total says how many exist. |
| Name | Required | Description |
|---|---|---|
| data | No | |
| success | No | |
| request_id | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent, openWorld, and destructiveHint false. The description adds value beyond annotations by disclosing per-call cost and the 404-billed / 503-not-billed semantics, which an agent needs to reason about cost and retry behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no filler: first sentence lists the core returned data, second covers pricing and billing semantics. All sentences earn their place and key information is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple three-parameter read-only tool with a full output schema, the description covers purpose, return contents, and cost/billing behavior. An agent has enough information to call it correctly without additional context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and the input schema already documents asin format, geo marketplace, and max_reviews cap. The tool description does not need to repeat those details, so baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Returns the review block for one ASIN,' then enumerates the exact contents (star rating, rating count, customers say summary, review list). This clearly separates it from siblings like product_details and seller_reviews, which cover different data.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the intended use case: fetching reviews for a single product ASIN. It does not explicitly name alternatives or say when not to use it, but the single-ASIN scope and review-specific contents provide clear context without exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Keyword search with pagination, sorting, and filtering by category, price range, condition, brand or seller. Price: $0.01 per call. Blank values and the literal string 'null' are treated as unset. page must be a positive integer or the call 400s. Ten filters narrow a search besides query: page, sort_by, geo, brand, seller_id, category_id, min_price, max_price, product_condition and today_deals. product_num_ratings and offers_count are integers; product_star_rating, product_price and product_original_price are decimal strings; a null field means Amazon did not show it for that result. is_prime is true when the result carries a Prime badge or its delivery line offers Prime delivery. metadata.total_pages says how far page can go. TWO THINGS TO READ CAREFULLY: product_num_ratings is the count for the whole listing family, not for this ASIN - Amazon pools reviews across variants, so every colour of one shoe reports the same number. And a variant's product_title can be the parent's title while the ASIN is the variant's; the URL slug usually shows which variant it really is, and /v2/product-details on that ASIN is authoritative. badges is the source of truth for Amazon's Choice / Best Seller / Overall Pick; is_amazon_choice and is_best_seller are derived from it. delivery splits the delivery line: free_delivery_date is the date a non-member gets for free, prime_delivery the slot Prime would give, fastest_delivery_date the paid faster option; raw is always the whole line. Dates are the strings Amazon printed, and on non-English marketplaces only raw may be filled. A full page is up to 48 results and about 54 KB of JSON; over MCP the tool returns the first 10 as light rows by default and tells you how to ask for more (limit, compact, fields).
| Name | Required | Description | Default |
|---|---|---|---|
| geo | No | Marketplace country code. | US |
| page | No | Result page, 1-based. | |
| brand | No | Brand name filter. | |
| limit | No | How many search results to return from this page (0 = all of them). A full page is up to 48 rows and about 54 KB, which most clients spill to a file instead of showing inline. The answer carries _truncated with the true count when it trims. | |
| query | Yes | Search keywords. Required and must be non-empty. | |
| fields | No | Comma-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. | |
| compact | No | Return light rows: identity, price, rating, badges and one delivery_date, dropping the long delivery prose that repeats itself across three fields. false returns every field the REST API sends (roughly 3x the size). | |
| sort_by | No | Result ordering. | RELEVANCE |
| max_price | No | Maximum price filter, marketplace currency. | |
| min_price | No | Minimum price filter, marketplace currency. | |
| seller_id | No | Restrict results to one seller. | |
| category_id | No | Restrict to an Amazon category id. | |
| today_deals | No | Restrict to items in today's deals. | |
| product_condition | No | Condition filter, e.g. NEW or USED. |
| Name | Required | Description |
|---|---|---|
| success | No | |
| metadata | No | |
| products | No | |
| request_id | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, openWorldHint, and idempotentHint, but the description adds substantial behavior beyond that: cost per call, null/blank handling, 400 on invalid page, output field type semantics, Prime badge derivation, variant review pooling, delivery field roles, and marketplace-specific date behavior. This is exemplary 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.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long, but it is information-dense and front-loaded with the core operation, then grouped caveats and MCP behavior. Some redundancy exists, such as repeating the 48-row/54 KB sizing that already appears in the limit schema description, and calling page and sort_by 'filters' is slightly imprecise. Overall, every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 14 parameters, an output schema, and subtle response-field quirks, the description is remarkably complete. It covers input constraints, output semantics, edge cases, pricing, pagination limits, and MCP-specific truncation. An agent has enough to invoke correctly and interpret results safely.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so baseline is 3, but the description adds significant non-obvious meaning: literal 'null' strings are unset, invalid page causes a 400, product_num_ratings pools across variants, product_title can belong to the parent ASIN, badges are authoritative, and delivery fields have precise semantics. This greatly exceeds the schema's bare parameter descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the action: keyword search over Amazon products with pagination, sorting, and multiple filters. It is specific and not tautological. However, it does not explicitly contrast against siblings like best_sellers or deals, so it stops short of full sibling differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives strong operational guidance: query is required, page must be a positive integer, pagination limits are explained, and MCP truncation behavior is documented. It does not explicitly say when to prefer this tool over alternatives such as best_sellers, offers_stock, or product_details, so the guidance is clear context without exclusionary routing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Returns the paginated catalogue of products offered by a given seller storefront. Price: $0.01 per call. Unlike seller_profile_batch, seller_id format is not pattern-validated here.
| Name | Required | Description | Default |
|---|---|---|---|
| geo | No | Marketplace country code. | US |
| page | No | Result page, 1-based. | |
| limit | No | How many the seller's products to return from this page (0 = all of them). A full page is up to 48 rows and about 54 KB, which most clients spill to a file instead of showing inline. The answer carries _truncated with the true count when it trims. | |
| fields | No | Comma-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. | |
| compact | No | Return light rows: identity, price, rating, badges and one delivery_date, dropping the long delivery prose that repeats itself across three fields. false returns every field the REST API sends (roughly 3x the size). | |
| seller_id | Yes | Amazon seller ID. Required. |
| Name | Required | Description |
|---|---|---|
| data | No | |
| success | No | |
| request_id | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover safety with readOnlyHint, idempotentHint, and destructiveHint=false. The description adds meaningful behavioral context beyond those: a $0.01 per-call cost, paginated results, and the fact that seller_id is not pattern-validated unlike seller_profile_batch. This is useful extra transparency without contradicting the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences with no filler. It front-loads the core purpose, then adds the cost and a single high-value caveat about seller_id validation. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has six parameters, a rich input schema, an output schema, and strong safety annotations. The description adds price, pagination, and a validation caveat, covering the main behavioral facts an agent needs. It is missing explicit routing to sibling tools like offers_stock, but the title and purpose statement are sufficient in combination with the structured metadata.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and the parameter descriptions are already rich: limit explains 0=all and truncation behavior, compact explains the size tradeoff, and fields describes _omitted_fields. The tool description adds no parameter-specific semantics, so the baseline of 3 applies because the schema carries the burden.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Returns the paginated catalogue of products offered by a given seller storefront.' This clearly identifies what the tool does and who the data belongs to. It also distinguishes itself from seller_profile_batch by noting the seller_id validation difference, which supports sibling differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not state when to choose this tool over alternatives such as offers_stock, product_details, or search. The only comparison is a validation caveat about seller_profile_batch, which is a behavior nuance rather than usage guidance. No explicit 'use this when' or 'use that instead' guidance is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Returns the storefront profile for each seller id: business name, rating, feedback counts, address and marketplace presence. Price: $0.012 per item (max 10). Seller ID validation is all-or-nothing: one malformed id rejects the entire request with 400.
| Name | Required | Description | Default |
|---|---|---|---|
| geo | No | Marketplace country code. | US |
| seller_ids | Yes | Comma-separated seller IDs, maximum 10. Each must be 13-15 alphanumeric characters or the whole call 400s. |
| Name | Required | Description |
|---|---|---|
| results | No | |
| request_id | No | |
| country_code | No | |
| response_time | No | |
| amazon_request_count | No | |
| billable_requests_count | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare read-only, non-destructive, idempotent behavior; the description adds valuable edge-case behavior (all-or-nothing validation with a 400 for any malformed ID) and the per-item price. This goes beyond what annotations capture.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no filler: the first states output and content, the second states cost and the critical failure mode. Key information is front-loaded and every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With a rich input schema, an output schema, and safety annotations, the description covers the important operational details: output fields, batch cap, cost, and failure mode. It is complete enough for correct invocation, though a note comparing it to seller_products/seller_reviews would round it out.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents seller_ids, the 13-15 character rule, the max of 10, and the geo enum/default. The description mostly restates these facts without adding new parameter-level meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific verb and resource ('Returns the storefront profile for each seller id') and enumerates the exact payload fields (business name, rating, feedback counts, address, marketplace presence). This clearly distinguishes it from sibling tools like seller_products or seller_reviews.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies batch storefront-profile use and notes the 10-ID maximum and cost, but it provides no explicit when-to-use guidance or comparisons with alternatives such as seller_products or product_details_batch. Usage context is inferable, not stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Returns paginated seller feedback, optionally filtered to a star-rating window. Price: $0.01 per call. from_rating and to_rating are optional; omit both for unfiltered feedback.
| Name | Required | Description | Default |
|---|---|---|---|
| geo | No | Marketplace country code. | US |
| page | No | Result page, 1-based. | |
| limit | No | How many seller reviews to return from this page (0 = all of them). A full page is up to 48 rows and about 54 KB, which most clients spill to a file instead of showing inline. The answer carries _truncated with the true count when it trims. | |
| fields | No | Comma-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. | |
| compact | No | Return light rows: identity, price, rating, badges and one delivery_date, dropping the long delivery prose that repeats itself across three fields. false returns every field the REST API sends (roughly 3x the size). | |
| seller_id | Yes | Amazon seller ID. Required. | |
| to_rating | No | Upper bound of the star-rating filter. | |
| from_rating | No | Lower bound of the star-rating filter. |
| Name | Required | Description |
|---|---|---|
| data | No | |
| success | No | |
| request_id | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds meaningful context beyond that: the per-call price ($0.01), pagination behavior, and the optional rating-window filtering. Pricing is a cost signal annotations cannot express, so this exceeds the baseline.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three terse sentences, front-loaded with the core purpose, then the price, then filter usage. Every sentence earns its place and there is no repetition of schema content. The description is appropriately sized for a tool whose parameter details live in a strong schema."
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the 100% schema coverage, a rich output schema, and annotations covering the safety and idempotency profile, the description is complete enough for an agent to decide to invoke and understand the call shape. The only minor gap is the lack of explicit sibling routing, which the distinctive 'seller feedback' resource largely mitigates.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3 and the schema already documents all 8 parameters thoroughly. The description adds only a minor clarification about the from_rating/to_rating interaction (omitting both yields unfiltered feedback) which is not explicitly stated in the individual parameter docs but does not substantially exceed schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The first clause, 'Returns paginated seller feedback, optionally filtered to a star-rating window,' states a specific verb, resource, and scope. The phrase 'seller feedback' clearly distinguishes it from the sibling product_reviews, so an agent can tell them apart 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.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives filter guidance ('from_rating and to_rating are optional; omit both for unfiltered feedback') and discloses pricing, but provides no explicit when-to-use versus alternatives. Routing is implied by the resource name rather than stated, and no exclusions are given relative to sibling tools like product_reviews or seller_products.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Report a bug, ask for a field, or say what would make this API more useful. Free: never billed, no API key needed.
Prefer GitHub if you have an account -- an issue at
https://github.com/apiguru-app/agent-kit/issues gets a reply on the
thread, this wall does not. Use this tool when you have no GitHub
account or nothing to attach one to.
message: what happened or what you want. Be specific: the tool, the
parameters, the field, what you expected, what you got.
category: bug | wish | praise | question | other
endpoint: which tool or path it is about, e.g. "search".
agent: what you are, e.g. "acme-pricing-bot/2.1". Optional.
contact: a GitHub handle or email if you want a reply. Shown
publicly on the wall. Optional.
| Name | Required | Description | Default |
|---|---|---|---|
| agent | No | ||
| contact | No | ||
| message | Yes | ||
| category | No | other | |
| endpoint | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations carry the base safety profile (not read-only, not idempotent, not destructive, open-ended), and the description adds meaningful context beyond them: 'Free: never billed, no API key needed' discloses cost and auth behavior, while 'this wall does not [get a reply]' and 'Shown publicly on the wall' disclose visibility and response expectations. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured: purpose statement, cost/auth note, routing guidance, then a cleanly formatted parameter block. Every sentence earns its place, and the most decision-relevant facts (what it does, that it's free, when to use it) are front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 5 parameters, an output schema, and clear sibling differentiation, the description covers everything an agent needs to invoke it correctly: purpose, cost, auth, alternatives, all parameter semantics, and privacy implications of contact. The only minor gap is the mechanics of what happens after submission, but the output schema covers return values and the wall behavior is referenced.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description fully compensates by documenting all five parameters with concrete guidance. It explains message specificity ('the tool, the parameters, the field, what you expected, what you got'), enumerates category values (bug | wish | praise | question | other), and gives examples for endpoint and agent.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The opening line 'Report a bug, ask for a field, or say what would make this API more useful' states a concrete action and resource (submitting feedback about the API). It is unmistakably distinct from the commerce/product sibling tools like best_sellers and product_reviews, so an agent cannot confuse it with them.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit routing guidance is provided: 'Prefer GitHub if you have an account' with a named alternative URL, plus the exact condition for using this tool instead: 'Use this tool when you have no GitHub account or nothing to attach one to.' This is textbook when/when-not usage guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.
best_sellersdealslist_capabilitiesoffers_stockproduct_detailsproduct_details_batchproduct_reviewssearchseller_productsseller_profile_batchseller_reviewssend_feedbackClaiming proves that you control a remote MCP connector. It does not move, proxy, or interrupt the server.
Open the connector listing, choose Claim ownership, and sign in to Glama.
Complete one verification method:
GitHub identity — fastest for official registry listings. For a namespace such as io.github.alice/server, link the matching GitHub user or an account that owns the GitHub organization, then choose Claim with GitHub.
HTTP challenge — works when you can deploy a public file. Generate a token, publish the exact JSON Glama shows at /.well-known/glama.json on the same origin as the connector, then choose Check HTTP challenge.
DNS challenge — works when you control DNS but cannot change the server. Generate a token, create the exact TXT record Glama shows, wait for it to propagate, then choose Check DNS challenge.
After verification, Glama sends a confirmation email and gives you access to listing details, thumbnails, health checks, and analytics. Keep the HTTP file or DNS record in place: Glama periodically checks it and ownership remains verified while the token is discoverable.
The HTTP ownership file has this structure:
{
"$schema": "https://glama.ai/mcp/schemas/connector.json",
"claim": "glama_claim_..."
}Claim tokens are opaque, stable, and bound to the signed-in Glama account. They contain no email address or other personal information. If Glama can no longer discover a verified HTTP or DNS token, it starts a seven-day grace period before removing claim-based access. Restore the same token during that period to keep ownership verified. Never publish an email address, Glama session token, GitHub token, or connector credential as ownership proof.
If verification fails, confirm that you copied the current token exactly. The HTTP file must be public, return valid JSON with a successful HTTP response, and stay on the connector's origin. DNS changes may need more time to propagate. A claim cannot transfer to a different origin or hostname: if the connector target changes, Glama starts the grace period and the new target must be claimed separately after the previous claim is released.
For a connector linked to the official MCP Registry, registry updates continue to replace its name, description, and URL by default. After claiming, open Manage connector and enable Use Glama listing details as the source of truth if edits made on Glama should be preserved. Categories and thumbnails are always managed on Glama; registry linkage and technical connection settings continue to sync.
Control your server's listing on Glama, including description and metadata
Access analytics and receive server usage reports
Get monitoring and health status updates for your server
Feature your server to boost visibility and reach more users
To improve your MCP server's ranking:
Claim ownership of the server listing
Complete the server profile with an accurate description and thumbnail
Provide a test profile so Glama can connect to and evaluate the server
Keep tool definitions clear and complete to earn a high Tool Definition Quality Score (TDQS)
Route real usage through the Glama Gateway; more recorded successful server uses also improve the ranking
For users:
Full audit trail – every tool call is logged with inputs and outputs for compliance and debugging
Granular tool control – enable or disable individual tools per connector to limit what your AI agents can do
Centralized credential management – store and rotate API keys and OAuth tokens in one place
Change alerts – get notified when a connector changes its schema, adds or removes tools, or updates tool definitions, so nothing breaks silently
For server owners:
Proven adoption – public usage metrics on your listing show real-world traction and build trust with prospective users
Tool-level analytics – see which tools are being used most, helping you prioritize development and documentation
Direct user feedback – users can report issues and suggest improvements through the listing, giving you a channel you would not have otherwise
The connector status is unhealthy when Glama is unable to successfully connect to the server. This can happen for several reasons:
The server is experiencing an outage
The URL of the server is wrong
Credentials required to access the server are missing or invalid
If you are the owner of this MCP connector and would like to make modifications to the listing, including providing test credentials for accessing the server, please contact support@glama.ai.
No comments yet. Be the first to start the discussion!
Amazon marketplace data for products, offers, reviews, sellers, search, categories, and deals.
Amazon keyword volume, reverse-ASIN, and SERP data across 11 marketplaces.
Amazon product API & MCP server: search, prices, reviews, sellers, deals, and ASIN lookup by Canopy.
Hundreds of scraping & data APIs through one key. USD pay-per-request, normalized schemas, failover.
Add one secure layer between your agents and this server.
Most tools target clearly distinct resources—product details, reviews, offers, sellers, deals—and the batch/meta tools are obvious. A couple of adjacent tools could be confused (product_details vs offers_stock, or search by seller vs seller_products), but the descriptions are detailed enough to prevent serious misselection.
Names are all snake_case and use readable resource prefixes (product_*, seller_*), but the verb/noun pattern is inconsistent: bare plural nouns (best_sellers, deals), single verbs (search), and compound nouns (offers_stock, product_details_batch) are mixed. It is readable but not a uniform convention.
Twelve tools is a well-scoped size for an Amazon data API. Each tool serves a distinct data-access or meta purpose with no obvious redundancy or bloat.
The toolkit covers the core Amazon data surface: product lookup (single/batch), discovery (search, best sellers, deals), offers/stock, reviews, and seller information. Minor gaps exist—no category-tree endpoint and review pagination is not explicit—but primary agent workflows are covered.
