Read-only Amazon shopping intelligence: Top-100 BSR, product profiles, price history, comparisons.
Scored across 10 tools
Most tools are clearly distinct by resource+action (price vs price_change vs top100 vs category_brief), but `request` heavily overlaps with `get_product` (fields=profile) and `get_price` (fields=price), and `request` with live=true duplicates `scrap_page`. The descriptions hint at the difference, yet an agent can reasonably reach for either tool for the same data, creating real misselection risk.
The set is solidly snake_case with predictable verb_noun shapes (get_price, list_categories, search_products, compare_products). The outlier is `request`, a bare vague noun that doesn't follow the verb_object pattern, plus `scrap_page` reads as a typo of scrape.
Ten tools is a well-scoped size for a product-research service, with each entry covering a recognizable capability. The count is slightly inflated by `request`, whose field-enum design could absorb `scrap_page` and parts of `get_product`/`get_price`.
The lifecycle is well covered: discovery (search_products, list_categories, get_top100), detail (get_product, get_price, get_price_change), comparison (compare_products), context (get_category_brief), and live freshness (scrap_page). Minor gaps: no review/rating-listing tool, no seller or related-products lookup, and competitor discovery must be improvised via the generic `request`.
Compare two to five products side-by-side across dimensions. asins: a list of 2-5 valid ASINs (10-char alphanumeric, e.g. "B08N5WRWNW"). Fewer than 2 or more than 5 items returns an error.
| Name | Required | Description | Default |
|---|---|---|---|
| asins | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare read-only and idempotent behavior. The description adds useful behavioral detail beyond those annotations by specifying the allowed ASIN range and that out-of-range input returns 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 description is short, front-loaded, and contains no filler. Each sentence adds either purpose, parameter constraints, or error behavior.
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 one-parameter comparison tool with annotations covering safety behavior, the description is almost complete for correct invocation. It does not explain what comparison dimensions or return structure to expect, but the tool has no output schema and the missing information is relatively minor.
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 carries the full burden for the single asins parameter. It specifies that the value is a list of 2-5 ASINs, gives the 10-character alphanumeric format, provides an example, and states the error condition.
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: compare products side-by-side. It also constrains the operation to two to five products, which distinguishes it from single-product siblings like get_product.
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 comparison use case is implied by 'side-by-side' and the ASIN count constraint. However, the description does not explicitly say when to use this instead of get_product or search_products, nor does it name any alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a structured brief for a category: market overview, considering factors, gotchas, common questions, needs, and keywords.
| Name | Required | Description | Default |
|---|---|---|---|
| category_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnlyHint=true and idempotentHint=true, so the safety profile is covered. The description adds useful context by enumerating the sections of the structured brief. However, it does not explain behavior when the category is missing, whether the brief is cached, or how complete or current the returned data is.
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 definition is a single efficient sentence with the main action front-loaded and the return contents enumerated compactly. There is no wasted phrasing, though the itemized list could be slightly easier to scan if formatted.
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 read-only retrieval tool, the description is adequate about what the brief contains and annotations cover safety. However, with no output schema and 0% parameter-description coverage, it should do more to explain the required category_id and any error conditions. It is usable but incomplete for reliable invocation.
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?
There is one required parameter, category_id, and schema description coverage is 0%. The description only implies that the brief is 'for a category' and does not specify the identifier's format, where to obtain it, or whether it comes from list_categories. This is a clear parameter-semantics gap.
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: get a structured brief for a category. It also enumerates the brief's contents (market overview, considering factors, gotchas, common questions, needs, keywords), so an agent can tell what the tool produces. It does not explicitly distinguish this from siblings such as list_categories or search_products.
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 provides no explicit guidance on when to use this tool versus alternatives like list_categories or search_products. Usage is only implied by the phrase 'for a category.' There are no stated prerequisites, exclusions, or alternate-tool routing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a product's latest price and product-page link.
| Name | Required | Description | Default |
|---|---|---|---|
| asin | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and idempotentHint, so the safety profile is covered. The description usefully adds that the response includes a product-page link, which is real behavioral value. It says nothing about currency, marketplace/locale resolution, or what happens when no price is available.
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 short sentence front-loads the primary output ('latest price') and appends the secondary one. No filler, no redundancy.
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 no output schema, the description does well to name the two returned values. For a one-parameter lookup tool that is close to sufficient, but the unexplained asin format and the undefined 'latest' (which marketplace, what currency, stale-data behavior) leave real gaps.
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 only parameter, 'asin', carries no documentation anywhere. The description never explains that asin is an Amazon product identifier, what format it takes, or whether a marketplace must be assumed, leaving the agent to guess.
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 ('Get a product's latest price') and adds the product-page link as a second output, so the purpose is unambiguous. It does not distinguish itself from siblings like get_price_change or compare_products, which also touch pricing, so it falls short of a 5.
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?
There is no statement of when to use this tool versus get_price_change, compare_products, or get_product. The agent must infer from the name alone that this returns a point-in-time price while the siblings handle history or comparison.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a product's 180-day price change summary from recorded history: current price, 180-day low/high/average, sample count, and where the current price sits among its own recorded observations. Answers "is now a good time to buy" style questions from historical data; it is a stored snapshot, not a real-time quote (call scrap_page for live price).
| Name | Required | Description | Default |
|---|---|---|---|
| asin | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and idempotentHint, so safety is covered; the description adds the important behavioral caveat that this is a stored snapshot rather than a live quote. It also discloses the temporal window (180 days) and that results are derived from recorded observations, which is genuine context beyond annotations. It stops short of describing data freshness or gaps in the recorded history.
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, front-loaded with the resource and scope, then the return payload, then the key caveat and alternative. Every clause carries information an agent would otherwise have to infer; nothing is redundant.
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 no output schema, the description must convey return values, and it does so completely: current price, 180-day low/high/average, sample count, and relative position. Combined with annotations covering the read-only profile and the explicit alternative for live data, an agent has everything needed to call this 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?
There is one parameter, 'asin', with 0% schema description coverage, so the description carries the burden. It implies the asin identifies 'a product' but never states the format or that it is an Amazon ASIN, so compensation is only partial. 'asin' is a reasonably well-known identifier, which keeps this at an adequate rather than poor level.
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 explicit scope: 'Get a product's 180-day price change summary from recorded history'. It also enumerates what the summary contains (current price, low/high/average, sample count, position), so an agent can distinguish it from get_price and scrap_page without opening any 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?
Gives a clear use case ('is now a good time to buy' style questions) and names the alternative explicitly by pointing to scrap_page for live prices, including the when-not-to-use condition (not real-time). It does not contrast against get_price, which appears to be the closest sibling for current pricing, leaving a small routing ambiguity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a product's full profile: specs, full description, feature bullets, ratings, price, trend, dimension scores/percentiles, three-source facts check, red-flag signals, and sentiment. profile.full_description carries the complete listing description paragraph when available in the source listing; otherwise it is null (specifications and feature_bullets remain present).
| Name | Required | Description | Default |
|---|---|---|---|
| asin | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the safety profile (readOnlyHint, idempotentHint), so the description's job is to add behavior — and it does, by disclosing that profile.full_description may be null while specifications and feature_bullets remain present. That partial-availability caveat is exactly the kind of thing an agent needs before promising a caller a full description. It stops short of covering ASIN format or not-found 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?
Front-loaded with the purpose and the field inventory, then a short caveat sentence about nullability. Dense but every clause carries information; the only mild redundancy is naming both 'full description' in the field list and 'full_description' in the caveat.
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 no output schema, the description must describe return content, and it does so thoroughly field-by-field, plus the one nullability edge case. For a one-parameter read tool that is nearly sufficient; only the identifier format and failure behavior are left uncovered.
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% and the single parameter (asin) is undocumented in the schema, so the description is the only place meaning could be added — but it never mentions the parameter at all. The agent must infer that 'asin' is an Amazon ASIN identifier and what format it takes, which is a real gap for a required 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?
Opens with a specific verb and resource ('Get a product's full profile') and then enumerates exactly what that profile contains — specs, description, feature bullets, ratings, price, trend, dimension scores, facts check, red flags, sentiment. That enumeration cleanly separates it from siblings like get_price, get_top100, and search_products, which return narrow slices or lists rather than one full profile.
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?
Usage is only implied: the field list makes it obvious this is the deep-dive tool versus get_price or search_products, but the description never says when to prefer it or when a cheaper sibling suffices. There are no exclusions or prerequisites stated, leaving the agent to infer routing from the sibling names.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the Amazon US Top-100 Best Sellers Rank list for a product category (US market only). Pass exactly one of: category_id (a top-level category slug from list_categories, e.g. "pet-supplies") or subcategory_id (a numeric subcategory node id from list_categories, e.g. "3742171"). Omitting both returns an error.
| Name | Required | Description | Default |
|---|---|---|---|
| category_id | No | ||
| subcategory_id | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and idempotentHint, so safety is covered. The description adds real behavioral context beyond that: market restriction to the US, mutually exclusive identifier inputs, and explicit error behavior on invalid input. It stops short of describing what the returned list contains, which matters since no output schema exists.
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?
Four sentences, zero filler. The core purpose is front-loaded, the mutual-exclusion rule follows immediately, and the error condition closes the paragraph.
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 two-parameter read tool with no output schema, the input side is fully specified and the safe-read profile is carried by annotations. The only remaining gap is return-value shape, which the agent must discover by calling the tool.
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 0% and both parameters are technically optional, so the description carries the full burden and does so well: it specifies that exactly one must be passed, that category_id is a top-level slug, that subcategory_id is a numeric node id, and gives concrete examples of each format. This resolves ambiguity the schema alone would leave open.
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: 'Get the Amazon US Top-100 Best Sellers Rank list for a product category', plus the scope constraint 'US market only'. This is clearly distinguishable from siblings like search_products, get_price, or compare_products without opening any 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?
Explains the required precondition (identifiers must come from list_categories) and the failure mode when neither id is supplied ('Omitting both returns an error'). It doesn't contrast against alternatives such as search_products or get_category_brief, so it stops short of full when/when-not routing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List top-level Amazon US product categories and their subcategories covered by this service (US market only).
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnlyHint=true and idempotentHint=true, so safety is covered by structured data. The description adds useful scoping behavior (US market only, only categories covered by this service, top-level plus their subcategories) but says nothing about result size, ordering, or caching.
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 front-loaded sentence with the scope qualification in parentheses; no filler, no restatement of the tool name beyond what is needed to define the resource.
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 no-argument read tool with annotations covering safety and no output schema, the description says enough: what is returned (top-level categories and their subcategories) and the market limitation. It could go further by indicating whether the result is hierarchical or flattened, but nothing essential to 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?
With zero parameters, there is no schema semantics to supplement, and the description correctly avoids inventing any. The baseline of 4 applies; it adds only the market-scope qualifier.
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 (List) and a precisely scoped resource (top-level Amazon US product categories and their subcategories), and it notes the service/market coverage limit. It is clearly distinguishable from siblings like get_category_brief or search_products, though it never states those relationships explicitly.
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?
Usage is only implied: the word 'List' plus the top-level framing suggests this is the discovery entry point for categories, but it never says 'use this first to find category identifiers' or points to get_category_brief as the next step. There are no exclusions or when-not-to-use cues.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch structured data by URL or ASIN with optional field filters. Pass either url (an Amazon product page URL) or asin (10-char alphanumeric). fields (optional enum): profile | price | trend | ratings | competitiveness | seller | facts_check | red_flags | sentiment | data_limitations. live (optional, default false): when true, additionally hits a live data endpoint (~15-30s) and appends a "live" block with the freshest price, stock, Buy Box seller, rating, and review count, plus data_as_of and is_stale flags. Unknown field values return an error with the full list of allowed fields.
| Name | Required | Description | Default |
|---|---|---|---|
| url | No | ||
| asin | No | ||
| live | No | ||
| fields | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the read-only and idempotent annotations, it discloses that live mode calls an additional endpoint, takes approximately 15-30 seconds, and appends a detailed live block with freshness flags. It also documents the error behavior for unknown field values.
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 identifier choice are front-loaded, followed by parameter details, live-mode behavior, and error handling in a logical order. The field list and live explanation are substantial but necessary given the bare schema, with no filler.
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 definition is sufficient for most correct invocations and sets useful latency and error expectations. Because there is no output schema, the unspecified default response when fields is omitted is a notable gap, as are the behavior when both or neither identifier is supplied and routing guidance among siblings.
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?
With 0% schema description coverage, the description supplies essential meaning for all four parameters: identifier formats, the complete fields vocabulary, and live's default and behavior. It does not explain what omitting fields returns or clarify less obvious values such as facts_check and data_limitations.
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 that the tool fetches structured Amazon product data by product URL or ASIN, with optional field filters. It does not distinguish this broadly named tool from siblings such as get_product, get_price, or scrap_page.
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 provides actionable context for choosing url or asin, narrowing results with fields, and enabling live when fresher price, stock, seller, and rating data are needed. It offers no guidance on when to prefer this tool over its product, price, or scraping siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Scrape a product page in real time via a live data endpoint (~15-30s) for the latest price, stock, Buy Box seller, rating, and review count. The response carries data_as_of (when the platform observed the data) and an is_stale flag for freshness judgment.
| Name | Required | Description | Default |
|---|---|---|---|
| url | No | ||
| asin | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnlyHint and idempotentHint annotations, the description adds meaningful behavior: a real-time live fetch, a notable 15-30s latency, and the presence of data_as_of and is_stale fields for judging freshness. It does not cover failure modes (e.g., what happens when a scrape fails or no Buy Box exists), which keeps it below 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?
Two tight sentences, front-loaded with the action and latency, then the return payload and freshness signals. Every clause carries information and nothing is redundant.
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 no output schema, the description does the work of explaining the return payload and freshness metadata, which is exactly what an agent needs. The remaining hole is parameter usage: with two undocumented identifiers and zero schema coverage, the agent lacks the instructions needed to actually construct the call.
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% and both parameters (url, asin) are bare strings with null defaults, so the description must compensate — but it never mentions either parameter. It does not say whether url or asin is expected, whether they are alternative or combinable, or what form an asin takes, leaving the agent to guess how to invoke the tool.
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 gives a specific verb and resource ('Scrape a product page') and enumerates the exact data returned: price, stock, Buy Box seller, rating, review count. It does not name any sibling such as get_price or get_product as the alternative, so the agent must infer differentiation from the 'real time / live endpoint' framing alone.
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?
Usage is only implied: the emphasis on 'in real time' plus the ~15-30s cost and is_stale flag hints that this tool is for cases where freshness matters, but there is no explicit statement of when to prefer it over get_price or get_product, and no when-not guidance. The agent must reason about the latency/freshness tradeoff itself.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search for candidate products matching a query, each with a data-maturity tier. query: 1-8 space-separated plain words (no SQL/special chars). category_id: optional top-level category slug from list_categories (e.g. "pet-supplies"). sort (enum): price_asc | price_desc | rating_desc | review_count_desc. Omit for relevance order. Filters: min_price / max_price in USD (floats), min_rating on a 0-5 scale. Invalid values return an error listing the allowed enum.
| Name | Required | Description | Default |
|---|---|---|---|
| sort | No | ||
| query | Yes | ||
| max_price | No | ||
| min_price | No | ||
| min_rating | No | ||
| category_id | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and idempotentHint, so safety is covered. The description adds real behavior beyond that: default relevance ordering when sort is omitted, currency and scale conventions for filters, and that invalid values return an error listing allowed enums. It omits result-count/pagination behavior, which is notable since no limit parameter exists.
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?
Front-loaded purpose sentence followed by one line per parameter group, with zero filler. The terse 'name: constraint' layout is easy to scan and nothing is repeated from structured fields unnecessarily.
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 six-parameter read-only search with no output schema, the coverage is strong: all params, enum fallback behavior, and defaults are documented. The gaps are the undefined 'data-maturity tier' concept and the absence of any statement about how many results are returned.
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 0%, so the description carries the full burden and does: query word count and character restrictions, category_id provenance and format, all four sort enum values plus the default, price units in USD as floats, and rating on a 0-5 scale. Every one of the six parameters gains meaning not present in the bare 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?
States a specific verb and resource ('Search for candidate products matching a query') plus a distinctive output trait ('each with a data-maturity tier'). It does not explicitly differentiate itself from siblings like get_product, compare_products, or get_top100, so an agent must infer the boundary.
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?
Implied usage is clear (use when you have a free-text query), and it routes to list_categories as the source of category_id slugs. However, it never says when to prefer get_product, compare_products, or get_top100 instead, and gives no exclusions or prerequisites.
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.
compare_productsget_category_briefget_priceget_price_changeget_productget_top100list_categoriesrequestscrap_pagesearch_productsRead-only Amazon seller analytics: sales, Buy Box, FBA inventory, alerts, revenue and fees.
Live Amazon product, review, search, deal, offer/stock and seller data across 23 marketplaces.
Top 100 of any Amazon Best Sellers list on 21 Amazon sites, no login: rank, price, stars, ratings.
Amazon (11 marketplaces) and Walmart US product data: search, prices, stock, history, sellers.
Add one secure layer between your agents and this server.
