Apiguru Amazon Data

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

Beyond the readOnly/idempotent/openWorld annotations, the description discloses cost ($0.01 per call), hard limits (page capped at 5, a 400 not a 500), truncation signals (_truncated, _omitted_fields), and the full shape of the response envelope (category_resolution, available_categories, available_subcategories). That is substantial operational context the annotations do not 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?

The description repeats itself: the amazon.com any-depth node-id rule appears three times ('subcategory_code also takes any browse node id at any depth', 'the whole browse tree is known: subcategory_code takes any node id...') and the fragment-resolution hint is explained twice. The key routing information is buried mid-paragraph behind repeated asides, so several sentences do not earn their 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?

Given an output schema exists and annotations cover the safety profile, the description still supplies everything needed to call it correctly: defaults, geography vocabulary differences, pagination ceiling, cost, and error semantics. Nothing material is missing for a zero-required-parameter ranking 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 already 100%, so baseline is 3, but the description adds real meaning: category accepts slug, display name, legacy US names, or a unique fragment with category_resolution.via reporting which; subcategory_code takes any browse-node id at any depth on amazon.com or a resolved name. The ambiguity 400 behavior is also explained.

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 sentence names a specific resource ('Best-seller rankings for a department of one marketplace, 50 per page'), which is clearly distinct from a generic search or deals listing. It stops short of explicitly contrasting with siblings like search or deals, but the verb+resource+scope is unambiguous.

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 implied rather than stated: 'No required parameters - calling it bare returns US appliances page 1' tells the agent how a default call behaves, and the free-400 behavior for unknown names steers recovery. There is no explicit 'use this instead of X when Y' guidance against the search or deals siblings.

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?

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint. The description goes far beyond that: it discloses the $0.01 per-call price, pagination mechanics (30-row pages, next_offset, total_count cap at 500), that min/max price and discount filters are applied post-fetch (so a page can hold fewer than 30 rows), that deal prices expire (check deal_ends_at), that empty answers carry a hint, and that deprecated price_range/discount_range parameters still work. This is rich behavioral disclosure well beyond 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 long but well structured: purpose first, then filters, then pagination, then pricing, then deprecated params. Every sentence carries information. It could be tightened (e.g., the long list of US departments could be shortened since available_filters lists them), but it is front-loaded and organized, so it earns a 4.

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 14 parameters, an output schema, and many behavioral nuances, the description covers everything an agent needs: pagination, filtering rules, pricing, deprecated parameters, hints for empty results, and expiration. The output schema likely details the return structure, and the description complements it with explanations of filters_applied/filters_ignored, next_offset, and total_count. Nothing critical 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% – every parameter has a description. The description adds significant extra meaning: for categories it lists all US departments and explains name matching; for brands it explains where to get IDs and when names resolve; for limit it explains truncation and _truncated; for offset it ties to next_offset; for min_product_star_rating it explains the only accepted value and the free 400. It also clarifies deprecated bucket parameters. This is far above the baseline for high 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 description opens with 'Returns the current Amazon deals feed: ASIN, title, deal price, list price, discount, deal badge, start/end time and product links.' That is a specific verb (returns) + resource (deals feed) and enumerates the output fields. It clearly distinguishes this tool from siblings like search, best_sellers, or product_details because it is exclusively about the deals feed and its filters.

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 explains the main use case (fetching current deals with filters) and gives one explicit routing rule: 'for a brand by name use /search with brand=<name> and today_deals=true instead.' It also explains when certain filters are ignored (e.g., 'filters_applied / filters_ignored report what Amazon honoured'). It does not systematically compare against every sibling, but it gives enough context for an agent to know this is the deals tool and points to search for a specific alternative.

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?

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.

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive, but the description goes beyond them: it discloses the pricing model ($0.015 per item, billing per upstream request), that check_inventory multiplies requests, the exact behavior of offers_count=winner (including a historical change note), the legacy alias /scrape, and edge cases like empty lists and filters_applied. This is rich behavioral context with no contradiction.

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 (three sentences) and front-loaded with the core function, followed by pricing, then behavior details, then alias. No redundancy; every clause adds unique information. It avoids repeating schema content and stays under 100 words.

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 complexity (5 params, output schema, annotations), the description covers the essential behavioral nuances: billing, offer filtering, legacy alias, and edge cases. The output schema exists, so return format doesn't need to be described. The description is complete for an agent to call correctly and predict outcomes.

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% with detailed descriptions for all five parameters, so the baseline is 3. The description adds value by explaining cost implications (billing per request, more when check_inventory is true) and legacy behavior for offers_count, which are not in the schema. It doesn't fully re-explain parameter syntax but supplements with operational context, earning a 4.

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: returns the current offer list per ASIN with seller, price, condition, and buy-box winner, optionally adding the purchasable stock quantity. The title and description clearly distinguish it from siblings like product_details or product_reviews, making its scope unambiguous.

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 when to use it (for offers and inventory) and gives usage tips within the tool (e.g., 'leave off unless you need the number' for check_inventory), but it never explicitly compares it to sibling tools or states when not to use it. No exclusions or alternative routing are given, so the agent must infer from the tool's purpose.

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?

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.

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

Beyond the readOnly and idempotent annotations, the description discloses deduplication, concurrent fetching, pricing per ASIN including not-found results, a 413 error for over 20 ASINs, the caveat about multi-variant listing data, and the meaning of null fields. This is substantial behavioral context that annotations alone would not 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?

The description is compact yet information-dense: it states the tool's relationship to product_details, the core behavior, pricing, limits, and important data caveats in a few sentences. Every sentence adds useful information without 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?

The description covers what the tool does, when to use it, cost, limits, error behavior, data quality caveats, and response field meanings. Given that an output schema exists and annotations cover safety, nothing essential is missing for an agent to select and invoke this 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 input schema already fully documents all four parameters, so the baseline is 3. The description adds valuable semantics by explaining that ASINs are deduplicated, that billing applies even to not-found ASINs, and that bullet/spec fields may describe the product family rather than the exact variant.

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 ('fetches'), a resource (product details for ASINs), and a defining constraint (up to 20 ASINs per call). It explicitly identifies itself as a 'Batch variant of product_details', which immediately distinguishes it from the sibling 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 clearly establishes when to use this tool: for multiple ASINs, because it is 'far cheaper and faster than N single calls', and the 20-ASIN limit sets a boundary. It does not explicitly name the alternative tool for single calls, but 'Batch variant of product_details' makes the alternative obvious.

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?

Beyond the annotations, the description discloses pricing per call, billing semantics for 404 vs 503 responses, and the reason no paging exists: Amazon's review pages require a signed-in customer and the API does not sign in. This adds substantial behavioral context beyond the structured hints.

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 and front-loaded, with each sentence earning its place: what it returns, cost and billing context, constraints, and an alternative. No filler or repetition.

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 annotations, complete schema coverage, and the presence of an output schema, the description covers the key operational constraints, pricing, and alternative routing. An agent has everything needed to decide whether and how to call it.

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 asin, geo, and max_reviews clearly. The tool description adds general behavioral context but no additional parameter-level semantics beyond what the input schema provides.

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' and enumerates the exact contents (star rating, rating count, 'customers say' summary, review list). It also distinguishes itself from product_details by explicitly noting what it does not provide, such as star filters and paging.

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 clearly states that this tool takes no filters and has no paging, star filter, or sort, which tells an agent what not to expect. It explicitly directs agents to product_details for per-star counts, giving an actionable alternative.

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?

Annotations only say read-only, open-world, and idempotent; the description adds a huge amount of behavioral context: $0.01 pricing, free 400s naming invalid parameters, blank/null semantics, marketplace-specific node fallbacks with filters_ignored, truncation, is_prime derivation, upstream 503 retry behavior, and exact empty-result semantics. Nothing contradicts 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 long, but the tool is complex with 15 parameters and rich failure modes. It is front-loaded with the purpose and filter list, and nearly every sentence adds operational value; minor redundancy with schema descriptions and output-schema field notes keeps it from a 5.

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 of this complexity, nothing necessary for correct invocation is missing: pagination bounds, field types, projection/truncation behavior, marketplace caveats, error codes with retry semantics, and cost are all covered. The output schema handles return-value structure, leaving the description free to focus on behavior.

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 schema already documents every parameter; the description earns extra credit by explaining cross-cutting semantics such as unset blank/'null' values, invalid value error behavior, decimal price handling, and per-marketplace availability for deal_type and product_condition. It does not restate each schema description but adds meaning beyond the JSON 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 first sentence states a specific verb and resource: 'Search Amazon products by keyword', and the description immediately enumerates the available filters. This cleanly separates it from siblings like deals, best_sellers, and product_details, whose names imply different entry points.

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 keyword-search scope provides clear context for when to choose it over the other product-listing tools, and it explicitly routes rank claims to 'product_details or best_sellers'. There is no general exclusion list for deals or seller tools, but the core use case is unambiguous.

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?

Beyond annotations, it discloses pricing ($0.01 per call), page size (48 rows), output keys (filters_applied, filters_ignored, available_filters), and free 400 errors listing allowed values for invalid filters. It also calls out the seller_id validation difference versus seller_profile_batch, which is useful non-obvious 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?

The description is compact, with the core purpose first and high-value caveats (cost, validation, pagination) following in a few sentences. No sentence is redundant with the annotations, and the structure lets an agent scan the key facts quickly.

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 15-parameter tool, the description plus the detailed schema and output schema covers selection and invocation: cost, error behavior, pagination, and output shape. The annotations already supply the read-only/idempotent safety profile, so nothing critical 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 100% schema description coverage, the schema already documents all 15 parameters; the description adds semantic grouping by saying they are the same filters as search and that invalid values yield a free 400. This is meaningful context beyond the individual schema entries.

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 'Products listed by a seller: a storefront search' and immediately establishes the resource and scoped operation. It differentiates from siblings by noting that seller_id is not pattern-validated, unlike seller_profile_batch, though it lacks a direct imperative verb like 'lists' or 'searches'.

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 tells the agent that this is a storefront search taking the same filters as search, giving clear context for when the tool applies. It contrasts seller_id handling with seller_profile_batch but does not explicitly spell out when to choose this over marketplace-wide search.

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?

The description goes far beyond annotations: it discloses all-or-nothing validation, billing rules for each status, that rows are never null, the billable_requests_count semantics, and the pay-per-call settlement. It also explains the 'unavailable' status is not billed and is retryable. This is comprehensive behavioral disclosure that annotations alone do not 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?

The description is dense but every sentence adds value: return contents, pricing, validation rule, status semantics, billing count, and retry advice. It is front-loaded with the core purpose and then details edge cases. No wasted words or 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 an output schema present, return format is covered. The description thoroughly addresses edge cases (malformed IDs, not_found, unavailable), billing behavior, retry strategy, and the max limit. For a batch tool with nuanced error handling, this is complete and actionable.

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%, with both parameters already well-documented in the schema (geo enum with default, seller_ids pattern and max 10). The description adds minor context about validation and pricing, but the schema already carries the semantic weight. Baseline 3 is appropriate given high 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 description clearly states the tool returns storefront profiles for seller IDs, listing specific data fields (business name, rating, feedback counts, address, marketplace presence). The verb 'returns' and resource 'storefront profile' are unambiguous, and the batch nature distinguishes it from singular profile tools among siblings 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 provides explicit usage guidance on handling different statuses (ok, not_found, unavailable), billing implications, and a direct instruction to retry unavailable IDs in a separate call. However, it does not explicitly compare against alternative tools or state when to prefer this over siblings, so a slight gap remains.

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?

Annotations already cover read-only, idempotent, and non-destructive behavior. The description adds valuable context beyond annotations: the $0.01 per-call cost, the 5-review page size, the lack of a total count, and the page-100 cap. This gives an agent important operational expectations.

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: three sentences, each earning its place. It front-loads the core purpose, then adds cost, filtering, and pagination guidance. No filler or redundant restating of the tool name.

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, output schema, and strong annotations, the description covers the essential operational details well. The only gap is the unresolved contradiction between the stated page size and the `limit` parameter's description, which prevents it from being fully complete for an autonomous agent.

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. The description adds meaning by explaining that from_rating/to_rating are optional and omitting both yields unfiltered feedback, and by clarifying pagination behavior. However, it does not reconcile the internal inconsistency between the '5 reviews a page' statement and the `limit` parameter's 'full page is up to 48 rows' description, so it could confuse agents about page size and limit semantics.

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 paginated seller feedback'. It also clarifies the optional star-rating window, immediately distinguishing it from sibling tools like product_reviews. This is unambiguous and names exactly what the tool does.

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 gives concrete instructions: omit both rating parameters for unfiltered feedback, and page until has_next_page is false (up to page 100). It does not explicitly name sibling alternatives or state when not to use this tool, so it falls just short of a 5.

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

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

Annotations already declare this is a non-read-only, open-world, non-idempotent but non-destructive call. The description adds real value beyond that: no billing, no API key, contact details are shown publicly on the wall, and replies do not come back on this channel. It stops short of stating what a submission returns or whether repeated submissions create duplicate entries, so not a full 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?

Front-loaded with purpose, then routing advice, then a clean per-field block — a sensible order with no filler sentences. It runs somewhat long and the embedded advice about 'one issue per entry / five-point list' blurs the line between guidance and field definition, but nothing is truly wasteful.

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?

An output schema exists, so return values need not be explained. The description covers the remaining obligations: purpose, routing rule, privacy of contact, cost/auth profile, and per-parameter meaning. For a 5-parameter, 0%-coverage schema this is complete enough to invoke 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 description coverage is 0%, so the description carries the entire burden and does so: every one of the five parameters is explained with intent and examples (category values bug|wish|praise|question|other, endpoint e.g. 'search', agent e.g. 'acme-pricing-bot/2.1', contact as GitHub handle/email, message content guidance). It also flags agent and contact as optional, matching the required-only 'message' in 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 opening sentence states a specific action (report a bug, request a field, give feedback) and the resource (this API itself), which is a sharp contrast to every sibling tool (best_sellers, search, product_details) that queries catalog data. An agent can immediately tell this is the only write/feedback channel in the toolset. The 'free / no API key' clause further frames it as a zero-cost fallback path.

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?

Explicitly names the preferred alternative (GitHub issue on apiguru-app/agent-kit, which gets a threaded reply) and the precise condition for selecting this tool instead ('when you have no GitHub account or nothing to attach one to'). This is exactly the when/when-not/alternative structure that earns a top score.

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