Amazon MCP

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

With no annotations, the description carries the full burden and does so: it discloses the credit cost per store ('one SerpAPI credit PER STORE (6 by default)'), the 5-minute server cache, that shipping is never folded into price_pln, that foreign prices are Amazon's own PLN conversion with Polish VAT, and that a failing store surfaces in `marketplaces` rather than as an error.

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?

Cost and defaults are front-loaded, which is right. But a large block is spent restating the full result shape and every product field — an output schema exists, so this is mostly redundant bulk that pushes the genuinely useful notes (asin_matches, error handling) toward the end.

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 17-parameter, 10-marketplace fan-out with no annotations, the description covers cost, caching, currency semantics, failure modes and ASIN grouping — everything an agent needs to call it correctly. Return values are covered by the output schema, and the extra shape dump, while verbose, leaves no ambiguity.

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 goes beyond it by explaining what shipping_location actually changes (delivery cost in `delivery`, no delivery guarantee under 'local', NBP conversion) and that min_price_pln is sent in local currency with 10% slack then enforced exactly. It doesn't similarly enrich sort vs order_by, which remain schema-only.

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?

States a specific verb and resource with scope: 'Run one query on several Amazon stores in parallel ... and merge the results in PLN'. The multi-store merge is precisely what separates it from amazon_search, and the default sort ('cheapest first') is named up front.

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?

Gives concrete usage advice — 'Use a precise query (brand + model) and min_price_pln to keep accessories out of a price-sorted list' — and explains the shipping_location 'PL' vs 'local' tradeoff as a decision. It never names amazon_search or amazon_product as the alternative for single-store or single-product lookups, so the when-not is left implicit.

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

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

With no annotations, the description carries the burden and does well: "static and free" discloses that no external calls or costs are involved, and it discloses extra domain behavior (EU membership means no customs to Poland) that an agent could not infer. It does not state return format or ordering, which keeps it off a 5.

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?

A single sentence, front-loaded with the action and count, followed by the returned field list and then the call-to-action. Every clause — field list, EU flag rationale, static/free — carries information an agent needs; nothing is padding.

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?

There is no output schema, so the description compensates by enumerating the returned fields and the count of records. For a zero-parameter static list tool, nothing further is required to call it 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 takes zero parameters, so the baseline is 4. The description reinforces this by framing it as a static table lookup with no filtering or selection inputs, so an agent will not go hunting for a marketplace argument.

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?

Names a specific verb and resource ("List the 22 Amazon stores") and immediately enumerates the returned fields — code, domain, country, currency, NBP table, languages, EU flag. The phrase "the other amazon_* tools support" cleanly separates this reference tool from the action-oriented siblings amazon_compare, amazon_product and amazon_search.

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?

"Call it to pick marketplaces without guessing" gives a clear call condition, and "static and free" signals it is a cheap lookup rather than a metered call. It stops short of explicitly stating it should be called before the search/product/compare tools, but the precursor role is strongly implied.

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

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

With no annotations provided, the description carries the burden well by disclosing cost and latency (one credit, ~10–25 s), marketplace override behavior, and a detailed result shape. It still omits some operational details such as authentication, error behavior, and the server-side cache behavior described in the schema.

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 purpose and cost are front-loaded, but the description is a very long single paragraph with an extensive result-shape listing. Since an output schema already exists, much of the return-field enumeration is redundant and reduces conciseness.

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 nine-parameter lookup tool with full schema coverage and an output schema, the description is largely complete: it explains the ASIN/URL input model, marketplace override, cost, latency, and output richness. Its main gap is explicit guidance on sibling-tool selection.

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 all nine parameters. The description adds some semantic context about ASIN URLs and cross-store ASIN lookup, but most parameter meaning is carried by the schema rather than the description.

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: retrieve full details of one Amazon product by ASIN or product URL. It clearly scopes the tool to a single product lookup, which distinguishes it from broader search, comparison, and marketplace-list sibling tools.

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 usage by explaining that it returns full details for one ASIN and that the same ASIN can be looked up on another store. However, it does not explicitly say when to use this instead of amazon_search, amazon_compare, or amazon_marketplaces, so routing remains mostly inferred.

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

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

With no annotations, the description carries the full burden and does so well: it discloses SerpAPI credit cost, 5-minute caching, post-filtering behavior, price_pln null semantics, sponsored defaults, and that empty searches return count 0 with a note rather than an error.

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 core purpose, cost, alternatives, and refinement behavior are front-loaded, but the description is very long and includes an extensive result-shape block even though an output schema exists. That return-shape detail is largely redundant and hurts conciseness.

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 complex 20-parameter search tool with no annotations, the description is complete enough for an agent to call it correctly. It covers costs, caching, filtering behavior, currency conversion, empty results, and sibling routing.

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 all 20 parameters thoroughly. The description restates many of the same refinements and adds only marginal extra meaning, so the baseline for high schema coverage 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 starts with a precise verb and resource: 'Search one Amazon store', and adds scope such as 22 countries and default amazon.pl. It clearly distinguishes this from sibling tools by pointing to amazon_compare and amazon_product for different tasks.

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?

It explicitly says when to use alternatives: amazon_compare for several stores at once and amazon_product for one ASIN's offers. The refinement guidance and note that no-result searches are successful outcomes further clarify intended usage.

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