Ecommerce Data API

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

Adds information the annotations do not carry: a concrete per-call credit cost, an explicit warning that repeated calls may be charged again, and an untrusted-data caution for the returned payload. This is exactly the kind of billing/trust context that prevents runaway agent loops. It stops short of describing result-set size, page limits, or the shape of the returned metrics.

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

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

Three short sentences, front-loaded with purpose, then cost, then a trust caveat; no filler. It could have used one of those sentences to name the sibling alternative instead of leaving the reader to infer cadence.

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 30 parameters, a nested sort object, and no output schema, the description should say something about what a response contains (keyword, rank, searches, clicks, conversion, etc.) and how paging behaves. It says nothing about returns, and the untrusted-data line is the only nod to the payload, leaving the agent under-informed for a high-complexity, credit-costing 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 100% (all 30 params, including the nested order object and enum marketplace), so the schema carries parameter meaning. The description adds nothing about how filters (min/max SPR, clicks, searches, departments, include/exclude keywords) combine or interact, so it stays at the 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: 'Research monthly Amazon Brand Analytics keyword metrics' – an agent knows it returns ABA keyword data at monthly granularity. The word 'monthly' implicitly distinguishes cadence, but the description never contrasts itself with amazon_aba_research_weekly or amazon_aba_research_trends, so sibling differentiation is left to the names.

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

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

No guidance on when to use this versus the weekly or trends variants, no prerequisites, no exclusions. The only usage-shaped signal is 'monthly' in the first sentence, which the agent must infer.

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 (readOnlyHint=true, destructiveHint=false), the description adds genuinely useful operational context: the default 1-credit cost, plan-dependent actual cost, the fact that repeated calls may charge again, and the untrusted-data handling note. The repeat-charge warning is consistent with idempotentHint=false, and none of this billing/trust information is available in 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?

Four short sentences with the core purpose front-loaded, followed by cost and trust caveats. Every sentence carries information; only mild redundancy in the cost/phrasing could be tightened.

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 four-parameter tool with no output schema, the description covers cost, repeat-charge behavior, and data trust, which is solid. What is missing is the relationship to the weekly/monthly sibling tools and any hint of return shape or granularity/value semantics, leaving a gap an agent must resolve by guesswork.

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 all four parameters are already documented in the schema (including the marketplace enum and the returnFields/optional semantics). The description adds no further parameter meaning beyond echoing the weekly/monthly distinction, 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 gives a specific verb and resource ('Retrieve weekly or monthly ABA trend data for a keyword'), and the granularity scope matches the timeGranularity parameter. However, it does not differentiate itself from the sibling tools amazon_aba_research_weekly and amazon_aba_research_monthly, which appear to cover the same ground, leaving the agent unsure which to pick.

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 or when-not-to-use guidance, and no alternatives are named. In particular, nothing explains why an agent would call this over amazon_aba_research_weekly or amazon_aba_research_monthly, so selection is left entirely to inference.

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 real context beyond annotations: a per-call credit cost, the note that repeated calls may charge again (corroborating idempotentHint=false), and a prompt-injection warning to treat returned data as untrusted. It doesn't cover rate limits or result caps, but the safety-relevant disclosure is genuinely useful.

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

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

Three short sentences, purpose front-loaded, then cost, then the untrusted-data caveat. The billing point is slightly spread across two sentences but nothing is wasted.

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 32-parameter research tool with no output schema, the description says nothing about the shape of the returned weekly metrics or how filtering/paging affects results, and doesn't mention the week-ending-Saturday date semantics that the schema encodes. Annotations and the rich schema cover most of the rest, so this is adequate but thin.

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 all 32 parameters including filters, sorting, paging, and returnFields are already documented in the schema. The description adds no meaning on top, which is the baseline 3 case.

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 granularity: 'Research weekly Amazon Brand Analytics keyword metrics.' Clear what data domain is returned, but it doesn't distinguish this from siblings amazon_aba_research_monthly or amazon_aba_research_trends despite them being obvious near-neighbors.

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

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

No guidance on when to pick weekly over monthly or trends, nor any prerequisites beyond the required marketplace. The only usage-adjacent content is billing behavior, which is not 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?

Adds real context beyond annotations: cost per successful call, repeat-call billing, and the untrusted-data warning. The repeat-charge note is consistent with idempotentHint=false and is exactly the kind of caveat an agent needs. It stops short of describing pagination or result-set behavior, which matters for a list tool with a size parameter.

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 followed by cost and trust caveats. No filler, though the space saved could have been spent differentiating it from its sibling.

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 should hint at the payload shape, but 'comparable product records' is undefined and there is no mention of pagination, default result count, or what fields returnFields can request. Adequate for billing and safety, thin on what an agent will actually get back.

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 asin, size, marketplace, and returnFields are all documented in the schema already. The description adds no parameter meaning beyond a vague 'comparable' framing, so baseline 3 applies.

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

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

States a specific verb and resource: 'Retrieve comparable product records for an ASIN.' That is clear enough to act on, but it does not distinguish this tool from the near-identical sibling amazon_product_competitor_lookup, leaving the agent to guess which competitor endpoint to use.

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

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

No guidance on when to use this versus amazon_product_competitor_lookup, amazon_asin_detail, or the market_* siblings. The only conditional information given is billing-related, not selection-related.

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, non-destructive), so the description correctly spends its words elsewhere: it discloses the credit cost, warns that repeat calls re-charge (consistent with idempotentHint=false), and flags returned data as untrusted. That 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?

Short and front-loaded: the operation comes first, then billing, then a safety note. Every sentence carries information; minor deduction only because the billing sentence is slightly 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?

For a read tool with full schema coverage and no output schema, the description covers cost and trust well but says nothing about the shape or granularity of the historical trend data returned, which is the main thing an agent might need to reason about.

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

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

Schema description coverage is 100% and each parameter is documented in the schema itself, so the description is not required to carry this load. It adds nothing about the ASIN format, marketplace enum, or returnFields syntax. Baseline 3.

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: 'Retrieve historical coupon activity for an ASIN.' An agent immediately knows the operation. It does not, however, distinguish itself from the close sibling amazon_asin_with_coupon_trend, which appears to cover similar territory.

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

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

No guidance on when to use this versus amazon_asin_with_coupon_trend, amazon_asin_history, or amazon_asin_sales_trend. The only 'usage' content is billing mechanics, not tool selection context.

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, non-destructive, open-world), so the description's added value is what it contributes beyond them: an explicit credit cost per successful call, the fact that repeated calls charge again (concretely explaining idempotentHint=false), and a warning to treat output as untrusted. That is meaningful operational context not present in 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?

Three tight sentences: capability first, cost second, security caveat last, with no filler. Slightly dense packing of cost detail but every clause is actionable.

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's field list is the only hint at payload shape, and it is vague (no indication of nested attributes or size). Combined with the absence of routing guidance among dozens of siblings, it is adequate but leaves real gaps for a fairly complex open-world 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 description coverage is 100%, including the ASIN pattern/example, the marketplace enum with default, and returnFields semantics, so the schema carries the burden. The description contributes nothing about parameters, which meets the baseline of 3 but no more.

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 leads with a specific verb and enumerates the resource's contents (metadata, pricing, ratings, category, listing attributes), so an agent knows exactly what a call returns. However, it never distinguishes this snapshot tool from the many sibling ASIN tools (amazon_asin_history, amazon_asin_sales_trend, amazon_asin_competitor), which is the main ambiguity here.

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 guidance on when to choose this over the ASIN/competitor/trend siblings; the only conditional language is the cost warning about repeated calls. An agent must infer usage from the tool name alone.

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 real context beyond the annotations: credit cost per successful call, the warning that repeated calls may charge again (consistent with idempotentHint=false), and a data-trust caution. Annotations already cover the read-only/safe profile, so this cost and trust guidance is a genuine value-add.

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 retrieved, then cost, then the trust caveat. Four short sentences with minimal waste, though 'default cost... actual cost follows your plan' is slightly 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?

For a 6-parameter read tool with full schema coverage and no output schema, the description covers purpose, cost, and data-trust sufficiently. It omits any hint of return shape or pagination, but the enumerated fields (price, rank, rating, snapshots) give a reasonable sense of the payload.

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

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

Schema description coverage is 100%, so the schema already documents all six parameters; baseline is 3. The description adds nothing about startTimestamp/endTimestamp format or the meaning of dailyLatest, so it does not exceed the schema's contribution.

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 (retrieve) and resource (historical price, rank, rating, listing snapshots) tied to an ASIN. The word 'historical' distinguishes it from current-state siblings like amazon_asin_detail, but it never names or contrasts with those siblings 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?

Provides no when-to-use guidance and does not reference any of the many sibling tools (amazon_asin_detail, amazon_asin_sales_trend, amazon_asin_competitor). The only implicit signal is 'historical', leaving the agent to infer selection from the name alone.

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 a read-only, non-destructive, non-idempotent, open-world call. The description adds genuinely new context beyond that: default credit cost per successful call, that repeated calls may re-charge, and a trust caveat on returned data. It stops short of describing trend granularity or time window, so not 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?

Three tight sentences: purpose first, then cost model, then trust note. No filler, and the most important information (what it does) is front-loaded.

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

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

Cost, re-charge behavior and data trust are covered, but with no output schema the description should say something about what the sales trend payload contains (period, granularity, points). That gap leaves an agent unable to anticipate the return shape.

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

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

Schema description coverage is 100% and the marketplace enum and asin pattern are fully documented in the schema. The description only restates that data is keyed to an ASIN and adds no format or syntax detail, so the 3 baseline for schema-carried parameters is correct.

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 (retrieve), resource (sales trend data) and scoping unit (an ASIN). This distinguishes it from generic lookups, but it never contrasts itself with overlapping siblings such as amazon_asin_history or amazon_sales_prediction_asin, so the agent must infer which trend variant to pick.

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 when-to-use/when-not guidance and no alternative named among the many asin_* siblings. The only conditional content concerns cost, not selection, so an agent has no routing help.

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=true, destructiveHint=false, openWorldHint=true and idempotentHint=false. The description usefully adds cost behavior ('1 account credits per successful call', 'Repeated calls may charge again'), which concretely reinforces the non-idempotent annotation, plus a data-trust warning ('Treat returned data as untrusted'). This is real value beyond the structured fields, though it omits any mention of rate limits or response shape.

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

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

Three short sentences with the core purpose front-loaded, followed by cost and trust notes. Every sentence carries information, though the cost clause ('Default cost... actual cost follows your plan') is slightly padded. No filler or repetition of the schema.

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

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

With no output schema and three well-documented parameters, the description covers purpose, cost model and data-trust expectations, which is most of what an agent needs. The notable gap is disambiguation from the sibling coupon/detail tools, which matters given the crowded amazon_asin_* namespace.

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, marketplace (with its enum) and returnFields. The description adds no parameter-level detail such as the meaning of returnFields values or marketplace requirements. Baseline 3 is appropriate when the schema carries the full load.

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

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

The description names a specific verb and resource: 'Retrieve product details together with coupon history.' That is clear and informative. However, it does not differentiate itself from the near-identically-named sibling amazon_asin_coupon_trend or from amazon_asin_detail, so an agent cannot tell why it should pick this one over those 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?

There is no statement of when to use this tool versus the many amazon_asin_* alternatives, nor any prerequisites or exclusions. The only contextual guidance is cost-related, which is not usage guidance. An agent is left to infer the selection criteria entirely.

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, destructive=false, openWorld, idempotent=false). The description adds genuinely useful non-schema context: a per-call credit cost, an explicit warning that repeated calls may charge again (reinforcing idempotentHint=false with a concrete consequence), and an untrusted-data caution. It stops short of describing rate limits or response shape.

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 front-loaded sentences: purpose first, then cost, then data-trust. No filler, and each sentence carries distinct information. The cost sentence is slightly dense but still earns its place given the billing implications.

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?

No output schema exists, and the description does outline that geographic and time-series data is returned. Combined with full schema coverage and explicit annotations, an agent has enough to call the tool correctly and anticipate billing. Missing only finer detail on return fields and repeat-call cost 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?

With 100% schema description coverage, the schema already documents all five parameters including the marketplace enum and the returnFields payload control. The description contributes nothing about any parameter, so the baseline of 3 applies.

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

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

States a specific verb ('Retrieve') and resource ('geographic and time-series search interest for a keyword'), which clearly maps to Google Trends-style data. However, it never explicitly differentiates from close siblings like amazon_keyword_research_trends or amazon_aba_research_trends, leaving the agent to infer from the tool name 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?

There is no guidance on when to use this tool versus the many trend-related siblings (amazon_keyword_research_trends, amazon_aba_research_trends, amazon_asin_sales_trend). The cost note implies a paid call but does not help the agent choose between alternatives, and no prerequisites or exclusions are given.

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=true, openWorldHint=true, destructiveHint=false, and idempotentHint=false. The description genuinely adds to them: a per-call credit cost with repeated charges, consistent with idempotentHint=false, and a prompt to treat returned data as untrusted. It says nothing about pagination in the multi-page result set, but because annotations cover the safety profile, a 3 is fair.

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

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

Three short sentences, with the core purpose front-loaded and no wasted preamble. The billing line is slightly hedged ('actual cost follows your plan') but still earns its place as cost disclosure.

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

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

There are 36 parameters and no output schema, yet the description never says what the returned 'conversion metrics' contain, what fields are available for returnFields, or how the many min and max filters interact. For a tool this complex with no output schema, the description should carry more of that burden.

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 all 36 parameters, including the marketplace and timeType enums, are documented in the schema. The description adds no meaning about the min and max filter pairs, returnFields, or matchType, so the baseline of 3 applies.

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

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

A specific verb and resource: 'Retrieve keyword conversion metrics for an Amazon keyword.' That is unambiguous about the operation. However, it gives no hint of how it differs from several close siblings such as amazon_keyword_research, amazon_keyword_miner, amazon_keyword_order, and amazon_traffic_keyword, so the agent must guess which one to use.

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 never says when to pick this tool rather than a sibling, nor does it name the conditions under which another tool is appropriate. The only extra context is billing, which is not usage guidance. The agent is left to infer that this is for conversion metrics on a single keyword.

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, non-destructive, non-idempotent, open-world behavior. The description adds genuinely new context on top: a 1-credit default cost, that actual cost follows the plan, that repeated calls may charge again (reinforcing the non-idempotent hint with a concrete consequence), and that returned data must be treated as untrusted. This is unusually useful operational context.

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 tight sentences, purpose front-loaded before cost and safety notes, with no filler. It could be marginally tighter, but every sentence carries distinct 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 44-parameter tool with no output schema, the description covers billing and trust but says nothing about the returned payload, pagination (the page/size params), or how filter combinations behave. The safety profile and cost are complete; the result-shape and scale context are not.

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% across 44 parameters, so the schema already carries parameter meaning. The description only loosely groups inputs into 'demand, competition, and PPC filters' without mapping them to specific fields such as SPR, bid, or search rank. Baseline 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?

States a specific verb (discover) and resource (keyword opportunities) plus the filter categories it exposes (demand, competition, PPC). However, it does not differentiate this tool from close siblings like amazon_keyword_research or amazon_keyword_research_trends, so an agent cannot tell 'miner' apart from 'research' 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?

Says nothing about when to pick this tool over the many sibling keyword tools, nor when not to use it. The filter mention implies what it can do but gives no routing guidance among amazon_keyword_research, amazon_keyword_conversion, amazon_traffic_keyword, etc.

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 safety (readOnlyHint, destructiveHint=false) and the non-idempotent nature, but the description adds genuinely useful operational context beyond them: credit cost per successful call, plan-dependent actual cost, and re-charging on repeated calls. The untrusted-data warning is a valuable security note that 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?

Three short sentences, purpose front-loaded, no filler or repetition of the tool title. It is efficiently sized, though the brevity leaves useful usage context out rather than being maximally informative.

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 10-parameter tool with a nested sort object and no output schema, the description is thin: it never characterizes the response payload, pagination behavior, or which reverseType/conversionType values mean. The schema carries the parameter burden well, but the missing return-shape context leaves a real 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 description coverage is 100%, so the schema already documents date formats, page/size limits, marketplace enums, ASIN constraints, and the nested sort object. The description adds no parameter-level meaning (e.g., what reverseType W vs M means beyond the schema), 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?

Names a specific verb (Retrieve) plus the exact resource (keywords that generate orders for ASINs), which is more precise than a generic 'keyword lookup'. However, it does nothing to distinguish itself from sibling keyword tools such as amazon_keyword_conversion, amazon_keyword_research, or amazon_traffic_keyword, so selection among siblings still requires schema inspection.

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 contains no when-to-use or when-not-to-use guidance and never names an alternative tool. The only conditional statements are about billing, not about selecting this tool over its many keyword 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 read-only, non-destructive, open-world, non-idempotent behavior, so the bar is lower. The description still adds genuinely non-obvious context: per-call credit cost, the fact that repeat calls re-charge (consistent with idempotentHint=false), and a prompt-injection warning to treat returned data as untrusted.

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

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

Three short sentences, front-loaded with what the tool does, followed by cost and trust caveats. No filler and nothing repeated from the schema.

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

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

For a 45-parameter tool with a nested sort object and no output schema, the description covers cost and trust but not the response payload (what fields come back, whether returnFields is required for narrow responses) or the interaction between filters. Adequate given the rich schema, but not complete.

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 all 45 filters, the sort object, and the marketplace enum are already documented in structured fields. The description adds no extra semantics — nothing about how min/max filters combine, how marketPeriod interacts with month, or how returnFields should be composed.

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 ('Research keyword') and enumerates the metric families returned (demand, growth, competition, conversion, PPC), so an agent knows the shape of the output. However, it never distinguishes itself from near-identical siblings such as amazon_keyword_miner, amazon_keyword_conversion, or amazon_keyword_research_trends.

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 no when-to-use guidance, no prerequisites, and no exclusions. It also fails to route the agent between this tool and the many sibling keyword tools, leaving selection entirely to name inference.

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, non-idempotent and non-destructive. The description usefully adds credit cost per call, that repeated calls may charge again (reinforcing the non-idempotent hint), and a data-trust warning — real behavioral context 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?

Three short sentences, purpose front-loaded before the cost and trust caveats. Every sentence carries information; only minor tightening would be possible.

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 should hint at what 'research metrics' are returned (volume, rank, trend series?), but it does not, and the mismatch between the 'trends' name and 'historical research metrics' phrasing is unresolved. Cost and trust info partially compensate.

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 all four parameters are fully documented in the schema. The description adds no syntax, format, or default guidance for keyword, marketplace, month, or returnFields, so baseline 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?

States a specific verb (Retrieve) and resource (historical research metrics for a keyword), so the agent knows the general operation. However, it does not differentiate from the very similarly named sibling amazon_keyword_research or from amazon_aba_research_trends, leaving the 'trends' aspect undefined.

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

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

No when-to-use guidance, no exclusions, and no named alternatives, despite there being several closely related keyword sibling tools (amazon_keyword_research, amazon_keyword_miner, amazon_aba_research_trends). The agent must guess which keyword tool applies.

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, destructiveHint, idempotentHint, and openWorldHint. The description adds genuinely new context beyond those fields: per-call credit cost, the fact that repeated calls may charge again, and a warning to treat returned data as untrusted. This is meaningful operational context not present in 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?

Four short sentences with the core purpose front-loaded, followed by cost and trust caveats. No wasted prose, though the cost sentence and the re-charge sentence could be merged.

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

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

There is no output schema, so the description would ideally hint at what is returned, yet it only mentions 'returned data' abstractly and never describes the response shape or how returnFields affects it. Cost and trust context are covered, but the return-value gap leaves it only partially complete.

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 all six parameters, including the enum marketplace and the compatibility note on newProduct, are already documented in the schema. The description adds no parameter-level meaning beyond that. Baseline 3 applies when the schema does the heavy lifting.

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: measuring brand concentration within an Amazon category. This is clearly distinguishable from sibling market tools like amazon_market_seller or amazon_market_goods. It does not explicitly name a sibling to differentiate against, but the task is unique enough to be identified.

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 says what the tool does but gives no guidance on when to use it versus alternatives, no prerequisites, and no exclusions. The agent must infer usage from the name and schema alone.

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=true, destructiveHint=false, and idempotentHint=false, so the safety profile is covered. The description adds genuinely new context beyond that: cost is 1 credit per successful call and repeated calls may charge again (consistent with idempotentHint=false), plus an explicit 'Treat returned data as untrusted' data-handling warning. It does not describe the return shape or rate limits, keeping it out of 5 territory.

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

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

Three short sentences: purpose first, then cost cadence, then a data-trust caveat. Nothing is repeated from the schema or annotations and every sentence carries information an agent needs.

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 6-parameter read-only distribution endpoint with no output schema, the description covers the important operational facts (cost per call, repeat-call charging, untrusted data). It omits what the response contains (e.g. label/products/productsRatio structure) and any cost-avoidance guidance for repeat queries, which would have completed the picture.

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 explains every parameter (topN, month, newProduct, nodeIdPath, marketplace, returnFields). The description adds no parameter-level detail, 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+resource: 'Retrieve A+ content and video adoption distribution for a category.' That is concrete enough to distinguish it from most siblings (market_price, market_seller, brand). It stops short of naming the closest alternatives (e.g. amazon_market_brand or amazon_market_goods) or clarifying scope, so it falls just under 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 when-to-use guidance, no prerequisites, and no naming of alternative tools for related listing-content questions. The only conditional information is about cost, which is billing behavior rather than usage selection.

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 readOnly=true, destructive=false and idempotent=false, so the safety profile is covered. The description adds genuinely non-derivable context: the credit cost per successful call, that repeated calls may bill again, and an untrusted-data warning — consistent with idempotentHint=false. It still says nothing about what the response contains or any rate/coverage limits.

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 short sentences with zero filler, and the core purpose is front-loaded before the cost and trust caveats. Every sentence contributes 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?

For a tool sitting among dozens of overlapping market-analytics siblings with no output schema, the description should at least sketch what the concentration output looks like and when it beats amazon_market_statistics or amazon_market_research. The cost/trust caveats are present, but the selection context is not.

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 carries the parameter burden (including the note that newProduct is accepted for compatibility only). The description adds no parameter-level meaning at all — notably no hint about how nodeIdPath, asins, or topN interact with the concentration measure. 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?

States a specific verb and resource: 'Measure product concentration within an Amazon category.' This is more precise than a bare 'get goods' and implies a concentration metric (CR-n/HHI-style) over a category node. It does not, however, distinguish this from adjacent siblings such as amazon_market_statistics, amazon_market_research, or amazon_market_brand, which an agent must choose between.

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 no when-to-use guidance, no prerequisites (e.g. needing a category nodeIdPath from amazon_product_node), and no alternatives for the many amazon_market_* siblings. The only actionable instruction concerns cost, not selection.

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 establish a safe, non-destructive read with non-idempotent semantics, so the bar is lower. The description earns credit for adding the per-call credit cost, the warning that repeated calls may re-charge (reinforcing idempotentHint=false), and the untrusted-data handling instruction — none of which appear in 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?

Three short sentences, front-loaded with the purpose before cost and security caveats. Nothing is padded, though the cost and trust notes are terse enough that a slightly richer purpose statement could have fit without bloat.

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 should ideally indicate what the returned trend data looks like (the returnFields parameter implies selectable fields but the description never explains this). It covers cost and trust adequately but leaves the return shape under-described for a six-parameter analytics endpoint.

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 all six parameters are already documented, including the marketplace enum and the compatibility-only newProduct note. The description adds no param-level meaning, 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 ("Retrieve category-level product demand trends") that aligns with the title. However, it offers no differentiation from the many sibling market tools (amazon_market_research, amazon_market_statistics, amazon_market_shelf_trend), so an agent can't tell which of these overlapping "market" endpoints is the right one.

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 guidance on when to use this tool versus the numerous alternatives, no mention of prerequisites, and no exclusion conditions. The only context is a cost note, which does not help selection.

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, open-world, non-idempotent, and non-destructive behavior. The description adds valuable cost model details (default 1 credit, plan-dependent, repeated calls may charge again) and a data trust warning, both beyond annotations. It does not cover authentication needs or rate limits beyond cost.

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 short sentences, front-loaded with purpose, then cost, cost repetition, and trust warning. No filler; each sentence addresses a distinct operational concern.

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 read-only retrieval tool with no output schema and rich schema descriptions, the description covers purpose, cost, and data trust. It omits usage differentiation from siblings, but that is assessed separately; the core call context is otherwise complete.

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 each parameter is documented in the schema. The description adds no parameter-specific meaning beyond the 'category' framing that maps to nodeIdPath; baseline 3 applies when the schema does the heavy lifting.

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 ('Retrieve') and resource ('product price distribution for a category'), making the tool's output clear. It does not explicitly name or distinguish against sibling tools such as amazon_market_rating or amazon_market_statistics, so it falls short of the highest clarity tier.

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?

Provides no when-to-use guidance, prerequisites, or alternatives. An agent must infer usage from the name and schema alone; no condition selects this tool over the many other amazon_market_* 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=true, destructiveHint=false, and idempotentHint=false. The description usefully adds the credit cost model (1 credit default, plan-dependent), warns that repeated calls may re-charge (corroborating idempotentHint=false), and flags returned data as untrusted. This is meaningful context 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?

Three short sentences, purpose front-loaded, with cost and trust caveats following. No wasted 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?

No output schema exists, so return values need not be described. Cost, trust, and safety context are covered, but the description omits any disambiguation from the near-identical amazon_market_ratings sibling, which is the main remaining 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 description coverage is 100%, so the schema already documents all six parameters including the marketplace enum and nodeIdPath. The description adds no parameter-level detail, 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?

States a specific verb (retrieve), resource (star-rating distribution), and scope (for a category), which is clear and actionable. However, it does nothing to distinguish itself from the very similar sibling amazon_market_ratings (plural), leaving the agent to guess which one to pick.

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?

Provides no when-to-use guidance, prerequisites, or alternatives. The only guidance is cost-related, not about selection between this tool and the many sibling rating/market tools.

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 establish read-only, non-destructive, non-idempotent behavior, and the description adds genuinely useful context beyond them: per-call credit cost, the fact that repeated calls may charge again (reinforcing idempotentHint=false), and a data-trust warning. It stops short of describing return shape or rate limits, but the added cost/trust context is valuable.

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 tight sentences: purpose first, then billing, then trust. No redundancy, and the most important clause (what the tool does) is front-loaded.

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

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

With no output schema, the description should ideally convey the shape of the returned distribution, but it only names it. Cost and trust caveats are covered, and all six parameters are documented in the schema, so the definition is callable, but the return-value gap leaves it merely adequate.

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 conveys parameter meaning (including the note that newProduct is a no-op and returnFields is optional). The description adds no parameter-level detail, which is the correct baseline when the schema does the heavy lifting.

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 ("Retrieve ratings-count distribution for a category"), which is clearly distinguishable from most siblings. However, it does not distinguish itself from the very similar sibling amazon_market_rating (singular), leaving ambiguity about which rating tool to pick.

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 no when-to-use guidance, no prerequisites, and never names or contrasts with alternatives like amazon_market_rating or amazon_product_node. The only usage-adjacent content is billing cost, not 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 (readOnlyHint=true, destructiveHint=false), but the description adds genuinely non-obvious behavior: a default credit cost of 1 per successful call, plan-dependent actual cost, and repeat-charge risk that is consistent with idempotentHint=false. The 'treat returned data as untrusted' warning is a useful prompt-injection safeguard the annotations do not express.

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 compact sentences, with the purpose front-loaded before cost and trust notes. Every sentence carries information, though the cost sentence could be tightened slightly.

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 71-parameter, nested-object tool with no output schema, the description is minimal: it does not explain pagination behavior, the returnFields projection, or how the numerous min/max filters interact. The complete schema and safety annotations compensate enough that it is still callable, but the description leaves 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 100% across 71 parameters, so the schema already documents each filter. The description only groups them into demand/competition/seller/margin buckets and adds no format or interaction detail beyond the schema, which lands on the baseline of 3.

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 ('Research') and resource ('category markets') and enumerates the filter families (demand, competition, seller, margin). It is clearly the broad market-level tool, though it never names a sibling (e.g. amazon_market_brand, amazon_market_price) to differentiate the narrower ones.

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 when-to-use or when-not-to-use guidance and no routing to alternatives, which matters given siblings like amazon_market_brand, amazon_market_goods and amazon_market_performance. The agent must infer whether this tool or a sibling is intended.

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, non-destructive, non-idempotent behavior, so the bar is lower, and the description still adds real value: the per-call credit cost, the warning that repeated calls may charge again (consistent with idempotentHint=false), and a prompt-injection caveat to treat returned data as untrusted. It stops short of describing what a 'concentration' measurement returns, which is the remaining behavioral gap.

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 in the first sentence, followed by compact cost and safety notes. The two cost sentences overlap slightly ('default cost' vs 'actual cost follows your plan' vs 'repeated calls may charge again'), but overall it is tight and readable.

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?

This is a 6-parameter measurement tool with no output schema, so the description arguably should describe the shape of the returned concentration data, and it does not. Inputs are fully covered by the schema and the cost/safety notes are present, making it adequate but incomplete on the output side.

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 all six parameters, including the enum marketplace and format hints, are already documented in the schema. The description adds no parameter-level meaning beyond that, so the baseline of 3 applies.

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

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

The description states a specific verb and resource: 'Measure seller concentration within an Amazon category.' That is concrete and actionable. It does not, however, distinguish itself from close siblings like amazon_market_seller_location or amazon_market_seller_type, so sibling differentiation is missing.

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 when-to-use guidance, no stated prerequisites, and no named alternative among the many amazon_market_* siblings. The only contextual information is about billing, not about choosing this tool over another.

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 (readOnlyHint=true, destructiveHint=false), and the description adds genuinely non-structured information: the credit cost per successful call, that repeat calls may be recharged, and that returned data should be treated as untrusted. The billing note is consistent with idempotentHint=false, so there is 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?

Three short sentences with the purpose front-loaded, followed by cost and trust notes; nothing is padded. The cost sentence is slightly hedged ('actual cost follows your plan') but still earns its place.

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

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

Cost, trust handling, and required parameters are covered, and with no output schema the description responsibly defers return-shape details. However, for a tool with six parameters sitting in a dense family of near-identical seller/market tools, the absence of any placement guidance leaves a real completeness 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 description coverage is 100%, so every parameter including the enum marketplace and the compatibility-only newProduct is already documented in the schema. The description adds no format, default, or interaction detail beyond that, which is the expected baseline when the schema carries the load.

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 names a specific verb and resource: 'Retrieve seller-country distribution for a category,' which clearly states what is produced and its scope. It does not, however, differentiate from close siblings such as amazon_market_seller or amazon_market_seller_type, leaving the agent to guess which seller-related tool fits.

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 when-to-use guidance, no prerequisites, and no naming of alternatives among the many amazon_market_* siblings. The only conditional guidance is financial (cost per call), not selection guidance, so the agent has no signal for choosing this tool over the adjacent seller tools.

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 readOnly, openWorld, and non-idempotent. The description goes beyond them by disclosing cost behavior (1 credit default, repeated calls may charge again) and a data-trust caveat ('Treat returned data as untrusted'), both of which are actionable for an agent. It does not contradict the non-idempotent hint; it corroborates it.

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 sentences, front-loaded with purpose before the cost and trust boilerplate. Efficient, though the credit/plan wording is generic template text that could be trimmed further.

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 read-only distribution query with full schema coverage and no output schema, the description covers purpose, cost, and trust sufficiently. It could add more on what the returned distribution fields represent, but nothing an agent needs in order to call it is missing.

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

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

Schema description coverage is 100%, so the schema already documents all six parameters (including the marketplace enum and the compatibility-only 'newProduct'). The description adds no parameter-specific meaning, 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 gives a specific verb and resource: 'Retrieve fulfillment and seller-type distribution for a category.' This is clearer than the bare name and adds the 'fulfillment' dimension, which helps separate it from siblings like amazon_market_seller or amazon_market_seller_location. It stops short of naming an alternative, so it doesn't reach 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?

The description gives no when-to-use guidance, no prerequisites, and no alternatives. With many sibling seller/market tools (amazon_market_seller, amazon_market_seller_location), the agent has to infer the routing decision on its own.

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 real behavioral context beyond the annotations: per-call credit cost, the fact that repeated calls are billed again (consistent with idempotentHint=false), and a data-trust warning. It does not restate the readOnly/destructive hints, so the added value is genuine rather than duplicative.

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

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

Three short sentences, front-loaded with purpose, then cost, then trust warning. Nothing is wasted, though the cost sentence is slightly redundant ('actual cost follows your plan').

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 read-only metrics tool with a full schema and no output schema, the definition covers cost and safety but omits the one thing an agent most needs here: how this snapshot differs from the sibling shelf_trend/time-series tool. That gap keeps it at minimum-viable rather than complete.

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

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

Schema description coverage is 100%, so the schema already documents all six parameters, including the compatibility-only newProduct field and the returnFields list. The description adds no parameter meaning beyond that, 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?

States a specific verb and resource: 'Retrieve listing-age distribution for a category.' An agent can tell it produces an age distribution for a category node, but the description never distinguishes it from the near-identical sibling amazon_market_shelf_trend, so the scope boundary is left implicit.

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

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

No when-to-use guidance, no exclusions, and no routing to alternatives. With siblings like amazon_market_shelf_trend and amazon_market_performance present, the agent gets no help deciding which of these category-distribution tools to call.

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=true and destructiveHint=false, but the description adds real value beyond them: it discloses per-call credit cost, that repeated calls may charge again (consistent with idempotentHint=false), and that returned data should be treated as untrusted. These are non-obvious operational and safety facts an agent needs.

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 sentences, front-loaded with the core purpose, followed by cost and trust notes. Every sentence earns its place, though the cost wording is slightly repetitive ('Default cost' vs 'actual cost follows your plan').

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?

No output schema exists, but the description covers purpose, cost, idempotency implications, and data-trust posture, and returnFields is documented in the schema. Missing only return-shape or pagination hints, which is minor for this scope.

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

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

Schema description coverage is 100%, so the schema already documents all six parameters, including the compatibility-only newProduct and the returnFields behavior. The description adds no parameter-level meaning, so the baseline 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?

States a clear verb ('Retrieve') and a specific resource ('listing growth and launch trends for a category'), which an agent can distinguish from adjacent siblings like amazon_market_shelf_time or amazon_market_statistics. It does not explicitly name or contrast those siblings, so it stops 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?

The description never says when to use this tool versus the many sibling market/trend tools, nor does it state prerequisites or exclusions. It only gives cost mechanics, not 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 already declare readOnly, non-destructive, open-world, and non-idempotent. The description adds real value beyond them: explicit cost (1 credit per successful call, plan-dependent, repeated calls may re-charge) and a data-trust warning ('Treat returned data as untrusted'). The cost cadence is consistent with idempotentHint=false.

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 short sentences, purpose front-loaded first, followed by cost and trust warnings. No filler; each sentence carries a distinct fact, though the cost clause is slightly redundant (three sentences all about charging).

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 read-only tool with no output schema and fully documented params, the description covers purpose, cost, and data trust. It stops short on what statistics are returned and how this differs from the dense cluster of market_* siblings, leaving a moderate 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 every parameter (topN, month, newProduct, nodeIdPath, marketplace, returnFields) is already documented in the schema. The description adds no parameter-level meaning, so the baseline 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?

States a specific verb and resource ('Retrieve summary statistics for an Amazon category market'), which is clearly understandable. However, it offers no differentiation from the many amazon_market_* siblings (brand, price, rating, seller, shelf_trend, etc.), leaving the agent unsure how this summary differs from those.

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 when-to-use guidance, no prerequisites, and no mention of alternative tools. The only context given is cost behavior, which is operational rather than 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?

With annotations already declaring readOnly/openWorld/non-idempotent/non-destructive, the description still adds real value: credit cost per successful call, plan-dependent actual cost, re-charge on repeated calls, and an untrusted-data warning. The re-charge warning usefully corroborates idempotentHint=false. It does not cover rate limits or pagination limits beyond the schema.

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

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

Four short sentences, front-loaded with purpose, then cost, then a safety note. Every sentence carries information; the only gap is that the purpose sentence is narrower than the tool actually is.

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 with a nested sort object and no output schema, the description leaves the response shape unexplained (returnFields is only described in the schema) and does not mention the non-keyword filter modes. Annotations plus full schema coverage keep it merely adequate rather than inadequate.

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

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

Schema description coverage is 100%, so the schema already documents all 15 parameters including enums, defaults and nested sort fields. The description adds only that keyword/ASIN are the two headline modes and omits that brand, sellerName and nodeIdPath can be used alone, so it neither compensates nor misleads.

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 products") and names the two primary input modes (keyword, ASIN list). However, it under-describes the tool: the schema also accepts brand, sellerName and nodeIdPath as standalone filters, and nothing distinguishes this from siblings like amazon_product_research or amazon_market_goods.

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 when-to-use guidance and no named alternative among the ~45 sibling tools, several of which (amazon_product_research, amazon_market_goods, amazon_asin_detail) plausibly overlap. The only contextual guidance is cost-related, not selection-related.

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=true, destructiveHint=false, idempotentHint=false, and openWorldHint=true. The description adds genuinely incremental behavior: the credit cost per successful call, that repeated calls may charge again (which is consistent with idempotentHint=false), and that returned data is untrusted. It stops short of describing pagination or response shape.

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

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

Three short sentences, front-loaded with the core purpose before the cost and trust notes. No filler, though the cost sentence is slightly verbose for what it conveys.

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 would ideally hint at the return payload, but 'search category nodes and category paths' plus the returnFields parameter make the shape reasonably inferable. Cost, billing, and data-trust caveats are a useful addition, so an agent has what it needs 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?

Schema description coverage is 100%, so every parameter including marketplace, nodeIdPath, keyword, month, and returnFields is already documented in the schema. The description adds no syntax, format, or interaction detail beyond that, 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?

States a specific verb and resource: 'Search category nodes and category paths.' Combined with the title 'Amazon Product Categories', an agent can tell this is a taxonomy-lookup tool rather than a sales/keyword tool. It does not, however, name any sibling to differentiate itself 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?

No guidance on when to use this versus alternatives such as amazon_product_research or amazon_product_competitor_lookup, despite the crowded sibling list. The only conditional content is cost-related, not task-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 already declare readOnlyHint=true, openWorldHint=true, and idempotentHint=false, so the safety profile is covered. The description adds genuinely non-structured context: the credit cost per successful call, the fact that repeated calls may charge again (reinforcing non-idempotency in billing terms), and a data-trust warning about returned 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?

Three short sentences, front-loaded with the capability statement, followed by cost and trust caveats. Nothing is padded, though the cost sentence could be slightly tighter ('default cost 1 credit, actual per your plan').

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 64-parameter tool with no output schema, the description covers cost and data trust but says nothing about what a result set looks like, the ~2,000-record retrieval ceiling, or how returnFields/pagination should be reasoned about. The schema carries parameter detail, but response-shape expectations are left entirely implicit.

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 every one of the 64 parameters is already documented in the schema, which sets the baseline at 3. The description's enumeration of filter categories gives only light orientation and adds no syntax, defaults, or interaction rules beyond what the 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?

States a concrete verb and resource ('Research products') and enumerates the filter dimensions it supports (category, sales, price, review, seller), which tells an agent what kind of query it can build. It does not, however, distinguish this tool from close siblings such as amazon_market_research, amazon_market_goods, or amazon_product_competitor_lookup, leaving ambiguity in a 48-tool family.

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 the many sibling research endpoints, no prerequisites, and no exclusions. The only guidance given is billing-related ('1 account credits per successful call'), not 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 already declare readOnlyHint=true, destructiveHint=false, openWorldHint=true, and idempotentHint=false. The description adds useful operational context: a default cost of 1 credit per successful call, plan-dependent actual cost, repeated-call charges, and a security warning to treat returned data as untrusted.

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 front-loaded with the core purpose, followed by cost and trust warnings in three efficient sentences. Every sentence adds operational value without 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 read-only retrieval tool with nine parameters, full schema coverage, and annotations, the description covers cost and trust but does not describe return structure. Since there is no output schema, the description should do more to explain what the response contains, beyond the mention of pagination.

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 all nine parameters are already documented in the input schema. The description adds only broad mentions of pagination and star filters, which map to existing parameters but do not add syntax or format details beyond the schema.

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

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

The description states a specific verb and resource: 'Retrieve paginated product reviews.' It also mentions optional star filters and pagination, making the tool's scope immediately clear and distinguishable from sibling tools focused on keywords, market data, or sales predictions.

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

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

The description does not say when to use this tool versus alternatives such as amazon_market_rating or amazon_product_research. It implies usage by naming the resource, but provides no explicit contexts, exclusions, or alternatives.

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 readOnly, openWorld and non-idempotent hints, but the description adds genuinely new operational context: credit cost per successful call, that repeated calls may charge again (consistent with idempotentHint=false), and that returned data should be treated as untrusted. It does not state rate limits or historical depth.

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 short sentences, front-loaded with purpose, followed by cost, repeat-charge and trust warnings. Every sentence carries distinct operational information 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?

With no output schema and full parameter coverage, the description is largely sufficient; the credit-cost and untrusted-data notes are valuable for an open-world paid API. It could say more about the historical range and update cadence of the returned estimates.

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%, including the ASIN pattern, marketplace enum and returnFields usage, so the schema does the heavy lifting. The description adds nothing about parameter behavior (e.g., how marketplace affects historical coverage), so baseline 3 applies.

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

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

States a specific verb and resource: 'Retrieve current and historical sales estimates for an ASIN.' An agent can distinguish it from amazon_sales_prediction_bsr only by inference from the 'ASIN' phrasing, since no sibling is named 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?

No guidance on when to choose this over amazon_sales_prediction_bsr or amazon_asin_sales_trend, and no exclusions or prerequisites beyond a cost warning. The agent must infer selection criteria from tool names alone.

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 establish readOnlyHint=true, destructiveHint=false, and idempotentHint=false. The description adds genuinely useful context beyond them: per-call credit cost, the possibility of repeat charges on repeated calls (reinforcing non-idempotency), and an explicit instruction to treat returned data as untrusted. The billing and trust details are the value-add here.

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

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

Three short sentences, front-loaded with the core purpose before billing and safety notes. Every sentence carries information, though the two cost sentences could be tightened into one.

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 four-parameter estimate tool with no output schema, the description covers purpose, cost, and trust but omits any indication of what the estimate returns or how it relates to the ASIN-based sibling. Adequate but with a clear differentiation 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 description coverage is 100%, so all four parameters including the marketplace enum and returnFields are already documented in the schema. The description only loosely maps 'category and BSR rank' to two of the required inputs and adds no format or syntax detail, so it meets the baseline without exceeding it.

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: 'Estimate product sales from category and BSR rank,' which is concrete and actionable. It fails to distinguish itself from the sibling amazon_sales_prediction_asin, which is the closest alternative and differs only in input basis (BSR vs ASIN).

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 guidance on when to use this tool versus amazon_sales_prediction_asin or amazon_asin_sales_trend. The only conditional content concerns billing ('Repeated calls may charge again'), which is cost guidance rather than usage routing.

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 readOnly/openWorld/non-idempotent, and the description adds real context beyond them: the 1-credit default cost, that repeated calls may charge again (reinforcing non-idempotency), and an untrusted-data warning. What's missing is disclosure of pagination caps or result-volume behavior for a 43-param query.

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

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

Three short sentences, front-loaded with the purpose, then cost and trust caveats. No wasted text. It is arguably too compressed for a 43-parameter tool, but every sentence earns its place.

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

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

For a wide, filter-heavy, non-idempotent query with no output schema, the description covers cost and data trust but says nothing about expected return shape (keyword rows with metrics), result caps, or how the many min/max filters interact. Adequate but with clear gaps against this complexity.

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 carries parameter meaning and the baseline is 3. The description adds nothing parameter-specific beyond the generic 'market filters' phrase and the ASIN-list input, leaving ambiguous fields like queryType and historyDate entirely to 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?

States a specific verb and resource: 'Expand traffic keywords from an ASIN list with market filters.' An agent can tell it produces keyword expansions from ASINs. However, it never distinguishes itself from near-neighbors like amazon_traffic_keyword, amazon_traffic_source, or amazon_keyword_miner, so sibling disambiguation is left to the 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?

Usage is only implied by the required params (asinList, marketplace, queryType) and the phrase 'from an ASIN list.' There is no explicit when-to-use vs when-to-use-an-alternative guidance, and no prerequisite or exclusion statements, which matters with 40+ traffic/keyword 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 establish read-only, open-world, non-idempotent behavior. The description adds meaningful operational context: credit cost, repeated-call charging, and that returned data should be treated as untrusted.

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 compact sentences: purpose first, then cost model, then data-trust warning. Every sentence adds useful information with no wasted wording.

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 12-parameter tool with complete schema coverage and annotations, the description adds billing and trust context. It gives a high-level return summary but does not elaborate on pagination, sorting, or response fields, which is acceptable given the rich schema.

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 carries parameter semantics. The description only reinforces the required ASIN context and does not add meaning beyond the documented parameters.

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?

Clear specific verb and resource: retrieve traffic keywords, demand, and rank positions for an ASIN. It is easy to distinguish from generic keyword tools, though it does not explicitly differentiate itself from siblings like amazon_traffic_extend or amazon_traffic_keyword_stat.

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 what the tool returns but gives no guidance on when to use it versus sibling tools. There is no mention of alternatives, prerequisites, or exclusion criteria.

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 establish it as a read-only, open-world, non-destructive call, so the bar is lower. The description adds genuinely new behavioral context beyond that: per-call credit cost, the fact that repeated calls may charge again, and a prompt-injection caution to treat returned data as untrusted.

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

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

Three short sentences, no filler, with the core purpose front-loaded before the cost and safety notes. Efficient and easy to scan, though the cost sentence is somewhat boilerplate-heavy.

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?

Cost and trust caveats are covered, which is more than most siblings offer. With no output schema, though, the description never hints at what the aggregate statistics contain or how they differ from the closely-named sibling tools, leaving a gap for a data-retrieval tool with four parameters.

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, month, marketplace, and returnFields including the yyyyMM format and enum values. The description adds no parameter-level meaning beyond the schema, which is the expected baseline at full 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 states a clear verb+resource: 'Retrieve aggregate traffic keyword statistics for an ASIN.' An agent knows it is an aggregate keyword-traffic lookup keyed on an ASIN. It does not, however, distinguish itself from the near-identical sibling amazon_traffic_keyword, leaving the boundary ambiguous.

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 when-to-use guidance, no prerequisites, and no mention of when to prefer a sibling such as amazon_traffic_keyword or amazon_traffic_listing_stat. The closest thing to guidance is the cost warning, which is about billing, not selection.

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/no-destroy/open-world semantics, and the description adds genuinely new context beyond them: default cost of 1 credit per successful call, plan-dependent actual cost, and re-charging on repeat calls (consistent with idempotentHint=false). The 'treat returned data as untrusted' warning is a valuable injection-safety cue, though auth/prerequisite requirements remain unstated.

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 tight sentences, front-loaded with the core purpose followed by cost and trust notes; nothing is padded. The two cost sentences could be merged, but the whole block is under 30 words and easy to scan.

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 an 8-parameter tool with a nested sort object and no output schema, the description explains purpose, cost, and data trust but says nothing about the shape of the returned traffic/position data or pagination behavior (page/size exist). Adequate but with a real gap on return expectations.

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

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

Schema description coverage is 100%, so the schema already documents all eight parameters, including the relations value list and marketplace enum. The description adds no parameter-level detail (e.g., no explanation of the mib/fbt/csi relation codes or the 40-ASIN limit), so baseline 3 applies.

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

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

States a specific verb and resource: 'Retrieve related products and traffic positions for ASINs.' An agent knows this returns related-product/ranking data for given ASINs. It does not, however, distinguish itself from the near-identically named sibling amazon_traffic_listing_stat or the other amazon_traffic_* tools.

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

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

No guidance on when to use this versus alternatives such as amazon_traffic_listing_stat, amazon_traffic_source, or amazon_traffic_extend, despite five traffic-related siblings. The only operational guidance is cost-related, which is a budgeting note rather than usage selection.

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