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

With annotations already covering read-only/idempotent/open-world semantics, the description adds substantial non-obvious behavior: $0.003 per call pricing, page capped at 5 returning a 400 rather than 500, free 400s for unknown categories, and truncation behavior. This is real value beyond the structured fields.

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 is front-loaded, but the prose is long and repetitive - the amazon.com any-depth/fragment behavior and the per-marketplace department vocabulary are each stated more than once. Several sentences could be consolidated without losing 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?

For a 7-parameter, no-required-param tool with an output schema, the description covers the department-resolution vocabulary and error behavior an agent needs. It is close to complete, with only minor redundancy rather than a genuine gap.

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 beyond it: fragment resolution via category_resolution.via and its subcategory hint, the amazon.com any-depth node-id rule, and the ambiguous-name 400 behavior. Some of this restates the schema, so it lands at 4 rather than 5.

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+resource+scope up front ('Best-seller rankings for a department of one marketplace, 50 per page'), which cleanly distinguishes it from siblings like search, deals and product_details. An agent can identify the tool 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?

It conveys useful usage context - no required parameters and a bare call returns US appliances page 1 - but never states when to choose this over siblings such as search or deals, nor any explicit exclusions. Usage is implied rather than spelled out.

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?

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

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

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

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

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

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3, but the description adds genuine meaning on top: categories accepts an id or a localised name/fragment (with the free 400 listing valid names), brands accepts ids only, and it documents the legacy price_range/discount_range bucket and band encodings that do not appear in the schema at all.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

Opens with a specific verb+resource ('Returns the current Amazon deals feed') and enumerates the exact row fields delivered (ASIN, title, deal price, list price, discount, badge, times, links). This is clearly distinguishable from siblings like best_sellers and search, which are separate feeds.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

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

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

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?

Adds substantial context beyond the readOnly/idempotent annotations: per-item pricing ($0.0045, max 10), billing granularity tied to upstream requests, the empty-list-with-error case for ASINs lacking a featured offer, the filters_applied echo, and the /scrape legacy alias. This is exactly the operational detail an agent needs before calling.

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-loads the core purpose well, but the parenthetical historical notes ('it used to scope only the inventory check', 'it used to be silently treated as ALL') add length without helping selection or invocation. The dense run-on sentences make the cost and behavior points harder to parse than necessary.

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 need not be described, and the description still covers pricing, billing, filtering semantics, defaults, and edge cases. An agent has everything required to invoke 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?

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: offers_count=winner returns only the flagged offer while offers_total preserves the full count, and it notes the historical behavior change. This clarifies semantics the enum value alone would not convey.

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 precise verb and resource ('Returns the current offer list per ASIN') and enumerates the returned fields (seller, price, condition, buy-box winner) plus the optional inventory quantity. This clearly separates it from siblings like product_details, deals, and best_sellers.

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 cost/billing tradeoff of enabling check_inventory ('billed per upstream Amazon request, which is more than one per ASIN') and the effect of offers_count=winner, which tells the agent when the extra spend is justified. It stops short of naming sibling tools or explicit when-not-to-use conditions.

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 the safety profile (readOnly=true, idempotent=true, destructive=false, openWorld=true), yet the description adds substantial non-covered context: per-call cost of $0.003, that 404 IS billed while 503 is NOT, retry advice, null-field semantics, and the caveat that bullets/specs may describe the product family rather than the exact variant. This is exactly the behavioral detail annotations cannot 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?

Four tight sentences, front-loaded with what is fetched, then cost, then error semantics, then data caveats. No filler and every sentence carries distinct, 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?

An output schema exists, so return-value enumeration is not required, and the description still supplies the billing model, error-code handling, and null/variant caveats an agent needs to call and interpret this correctly. Nothing material 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 geo, asin, fields, and compact are already fully documented in the schema (including the batch-rejection note and the _omitted_fields behavior). The description adds no parameter-level detail beyond reinforcing the single-ASIN constraint, so the 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 states a specific verb and resource ("fetches the complete product record for one ASIN on one marketplace") and enumerates the returned fields, so the agent knows exactly what it gets. It stops short of naming the sibling it contrasts with (product_details_batch), which the schema mentions instead, so differentiation is implicit rather than explicit.

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 explicit when-to-use / when-not-to-use guidance versus siblings like search or product_details_batch, but the scoping phrase "one ASIN on one marketplace" implies the single-item case. Error-path guidance (404 vs 503, retry) is present, which is operationally useful but not alternative-selection guidance.

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 cover the safety profile (readOnly, idempotent, openWorld, non-destructive), and the description goes well beyond them with pricing ($0.0024/item), billing behavior on misses, dedup behavior, the 413 threshold, and two data-quality caveats (family-level bullets on variant listings, null = not shown by Amazon). This is exactly the kind of extra context the bar rewards.

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 identity and the batch advantage, then cost, then limits, then data caveats. Every sentence conveys a distinct operational fact; nothing is redundant with the schema or annotations.

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-value detail is not required, and the description still pre-empts the two most likely misinterpretations of the response (variant-level bullets, null fields). It omits any mention of the geo parameter's effect on results, a minor gap given a 4-parameter 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 the schema carries the syntax. The description nevertheless adds non-obvious semantics about the asins parameter: it is de-duplicated before processing and billed per ASIN including not-found ones. That is genuine value beyond the structured fields.

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 ('fetch all of them concurrently') and explicitly frames itself as the 'batch variant of product_details', which names the sibling it must be distinguished from. An agent can immediately tell this apart from the single-ASIN product_details.

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 clear selection logic: 'Far cheaper and faster than N single calls', plus the hard limit 'More than 20 ASINs returns 413'. There is no explicit when-not-to-use (e.g. for a single ASIN, use product_details), but the context is strong enough to route correctly.

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 the read-only/idempotent safety profile, but the description adds substantial context beyond them: per-call price ($0.003), 404-billed vs 503-not-billed semantics, and the signed-in-customer auth limitation that explains the absence of filtering. This is rich disclosure that structured fields cannot carry.

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 return payload and every sentence earns its place (pricing, error semantics, scope, alternative). Slight redundancy in restating the returned fields a second time, keeping it just short of 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 3-param read tool with a full output schema, the description supplies everything else an agent needs: cost, error-billing behavior, auth constraints, and the routing alternative. Nothing material 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%, so the baseline is 3, but the description adds meaning the schema cannot express: that there are deliberately no filter/paging/sort parameters and why. It does not re-explain geo or max_reviews, which the schema already documents well.

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 review block for one ASIN') and enumerates exactly what comes back: star rating, rating count, 'customers say' summary, and review list. It also implicitly differentiates from siblings by pointing to product_details for per-star histogram 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?

Explicitly scopes usage ('one ASIN', 'takes no filters') and enumerates the alternatives that do not exist (no paging, star filter, or sort), explaining why. It routes the agent to product_details for per-star counts, giving a concrete when-to-use-other-tool rule.

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 read-only/idempotent/open-world, and the description goes well beyond them: per-call cost ($0.003), free-400 invalid-input semantics, unbilled retryable 503 with reason codes, filters_ignored fallback behavior per marketplace, and truncation flags. This is unusually rich behavioral disclosure for a read tool.

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?

Purpose and filters are front-loaded, and every clause is information-dense rather than filler. It is nonetheless a very long single block of prose that packs field-type, pricing, and error semantics together, which taxes scanning a bit.

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, open-world, output-schema-backed tool, it covers the gaps an agent would otherwise hit: null-field meaning, empty-result validity, pagination via metadata.total_pages, and failure taxonomy. Nothing material for correct invocation appears 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%, so baseline is 3, but the description adds real meaning: blank and literal 'null' treated as unset, invalid page/sort_by/price/condition/deal_type producing a free 400 naming allowed values, and per-marketplace node-id sourcing for category/condition/deal filters. It clarifies semantics the schema cannot express, though some params (geo, seller_id, limit) get nothing extra.

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 Amazon products by keyword') and immediately enumerates the filter surface, so the scope is unambiguous. It also distinguishes itself from siblings by directing rank claims to product_details or best_sellers, which is exactly the differentiation an agent needs against best_sellers and 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?

Gives clear routing for one important conflict ('For a rank claim, use product_details or best_sellers') and explains a non-obvious success condition (empty products only valid when metadata.total is 0). It does not, however, broadly frame when to prefer this tool over deals or seller_products, so it falls short of full when/when-not coverage.

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 annotations it discloses cost ($0.003 per call), pagination granularity (48 rows/page via metadata.total_pages), truncation behavior (_truncated) and the light-vs-full row size tradeoff. It also documents a distinctive behavioral trait: invalid sort_by/price/product_condition/deal_type yields a free 400 listing allowed 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?

Front-loaded with the purpose, then dense factual clauses on filters, cost, pagination and error behavior. Every sentence carries information, though the filter/response sentence runs long and could be split for scanability.

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 open-world search with an output schema, it covers cost, paging, truncation, field projection and error handling. Return-value structure is left to the output schema, which is the correct division of labor.

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 cross-parameter semantics the schema lacks: how filters map to filters_applied/filters_ignored/available_filters, and that unvalidated seller_id format differs from seller_profile_batch. It does not restate most per-field syntax, so it is modestly above baseline.

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 ('Products listed by a seller: a storefront search'), which immediately separates it from generic `search` and from `seller_profile_batch`. An agent can tell what it returns and what it is scoped to 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?

Positions the tool against siblings by noting it 'takes the same filters as search' but is scoped to one seller, and contrasts it with seller_profile_batch on seller_id validation. It does not explicitly say when to prefer it over `search` or `best_sellers`, so routing is clear but not fully spelled out.

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?

Goes well beyond the read-only/idempotent annotations: discloses per-item pricing ($0.0036, max 10), all-or-nothing ID validation with a 400, the three-valued `status` semantics, which statuses are billed, that rows are never null, and how billable_requests_count is computed. This is exactly the billing/error context annotations cannot carry.

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-loads what is returned and then layers billing and status semantics; every clause carries information. Slightly dense with a long final sentence about the pay-per-call rail, but 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?

For a paid, validated batch tool with two params and an output schema, the description supplies the pricing, validation failure mode, row-status contract, and retry strategy an agent needs. Nothing material is missing, and it does not waste space re-explaining the output schema's fields.

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 both params including the 13-15 char pattern and max-10 constraint. The description restates the all-or-nothing validation rule but adds no syntax or format detail beyond the schema, so baseline 3 applies; `geo` is never discussed.

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+resource+scope: returns storefront profiles for up to 10 seller ids, and enumerates the fields returned (business name, rating, feedback counts, address, marketplace presence). An agent can distinguish this batch profile lookup from seller_products and seller_reviews without inspecting schemas.

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 operational guidance: retry `unavailable` ids in a separate call rather than expecting a refund, and explains when `not_found` vs `unavailable` occur. It does not name alternative sibling tools (e.g. seller_reviews for review data), so it stops short of explicit when-not guidance.

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, open-world, and non-destructive behavior. The description adds important behavioral context: per-call pricing, page size, current_page/has_next_page, no total count, and the upper page limit.

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 efficient sentences, front-loaded with the core return behavior, then pricing and pagination details. Every sentence contributes useful information without 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?

With rich annotations, full schema descriptions, and an output schema, the description covers the remaining agent-relevant concerns: cost, filtering behavior, pagination mechanics, and the page cap. Nothing critical 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%, so the baseline is 3. The description adds meaning for from_rating/to_rating by noting they are optional and that omitting both yields unfiltered feedback, plus it adds the undocumented page 100 limit.

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 paginated seller feedback, optionally filtered to a star-rating window. This distinguishes it from sibling product_reviews because it targets seller feedback rather than product 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?

Explains when to omit rating filters for unfiltered feedback and how to page until has_next_page is false, including the page 100 cap. It gives clear usage context but does not explicitly compare against alternatives such as product_reviews.

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.