AMZScout Skill + MCP

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

Beyond the annotations (readOnlyHint=true, destructiveHint=false), the description adds significant behavioral context: it declares the operation is a pure data fetch with no AI analysis, and it specifies a mandatory output contract for handling 'Account notice:' paragraphs that must be copied verbatim. This is critical, non-obvious behavior that the schema and annotations do not convey, and nothing contradicts the read-only hint.

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

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

The description is long but every section earns its place: the purpose is front-loaded in the first line, the behavioral note and usage guidance are dense but actionable, and the output contract is mandatory critical information. The structure moves logically from what the tool does, to how to interpret results, to the required reply format, with no filler or redundancy.

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

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

Despite having no output schema, the description thoroughly explains the return content: top products by revenue, distribution aggregates, revenue concentration, brand spread, and a concrete example field (revenueTop5SharePercent). It also covers the account-notice edge case and gives interpretation guidance, so an agent has enough context to call the tool and process its result correctly.

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

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

The input schema already provides 100% descriptive coverage for all four parameters: keyword, count, filters, and marketplace, including currency context and marketplace rules. The tool description adds no additional parameter-specific meaning beyond what the schema details, so the baseline score 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 opens with 'Market snapshot for an Amazon niche/keyword' and enumerates exactly what is returned: top products by revenue plus computed aggregates across price, sales, revenue, reviews, concentration, and brand spread. This clearly distinguishes it from sibling tools like amzscout_analyze_product or amzscout_compare_niches by scope (single niche, data snapshot) and by the explicit 'Pure data fetch (no AI analysis)' disclaimer.

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?

A dedicated 'How to use' section explains how to interpret the returned data for judging niche attractiveness, covering demand concentration, price bands, review moats, and brand dominance. This provides clear context for when the tool's output is useful, though it does not explicitly name sibling tools to use instead or state when not to use this tool, so it stops short of a 5.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description adds meaningful behavior beyond that: no AI analysis, no fetch without marketplace with the exact 'MARKETPLACE NEEDED' response, local-currency handling, reuse of the chosen marketplace, and the mandatory Account notice output contract. No contradiction with annotations.

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

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

The description is longer than average but is organized into logical sections: overview, how to use, marketplace, and output contract. It front-loads the core purpose and only repeats the local-currency point once more than necessary.

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

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

With no output schema, the description carries the burden of explaining what the tool returns, listing price, sales/revenue, reviews, rating, LQS, sellers, and history. It also specifies the no-marketplace failure behavior and the mandatory account-notice handling, so an agent has what it needs to invoke and interpret the tool correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds valuable semantics for marketplace: ask once, reuse for every later call, never assume the US, and money is in local currency. The ASIN parameter is already clear from the schema and needs no extra explanation.

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 explicitly states a specific verb and resource: 'Full raw data for a single Amazon product by ASIN' and enumerates the included fields. It also says 'Pure data fetch (no AI analysis)', which helps distinguish it from analysis-oriented siblings like amzscout_analyze_product_set.

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 a detailed 'How to use' workflow—audit demand trend, pricing, competition, listing quality, then give a GO/NO-GO conclusion. It also gives clear guidance on asking once for a marketplace and reusing it, but it does not explicitly name alternative tools or state when not to use this tool.

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

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

Annotations already mark the tool read-only and non-destructive, and the description adds meaningful behavioral detail: pure data fetch with no AI analysis, the exact failure mode when marketplace is omitted, local-currency semantics, and the mandatory account-notice output contract. This goes well beyond what annotations alone convey, and nothing contradicts the annotations.

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

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

The description is front-loaded with the core purpose and organized into clear sections: purpose, usage guidance, marketplace handling, and output contract. It is longer than strictly necessary, but most sentences carry either invocation-relevant or analysis-relevant value, so it earns a strong score rather than a perfect 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?

With no output schema, the description carries the return-value burden, and it does so explicitly by listing product rows plus aggregate distributions and by defining the account-notice output contract. It also covers marketplace prerequisites, the no-marketplace failure mode, and the expected analytical posture, leaving no obvious gap for an agent to call the tool correctly.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description adds real value beyond the schema: do not assume the US marketplace, ask once and reuse the chosen marketplace, and expect no results when marketplace is absent. It also orients the agent on how to reason about the ASIN set as a market segment rather than a flat list.

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 operation: retrieve raw data for an explicit set of 2–100 ASINs and return product rows plus computed aggregates. It also explicitly positions itself as a pure data fetch with no AI analysis and names analyzeNiche as the keyword-discovery equivalent, so an agent can distinguish it from siblings without opening 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?

It gives clear context for when to use the tool: when an explicit set of ASINs should be treated as a mini-market, and it directs agents away to analyzeNiche for keyword-based discovery. However, it does not spell out when to prefer related siblings such as compare_products or analyze_product for single-ASIN analysis.

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, so the safety profile is covered. The description adds meaningful behavioral context beyond annotations: it is a 'pure data fetch (no AI analysis),' and it discloses the mandatory account-notice handling contract including exact copying and never omitting it. This is exactly the kind of behavior an agent needs to know.

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 longer than average, but each section earns its place: purpose is front-loaded, usage guidance follows, and the output contract is critical operational detail. Some redundancy exists ('Never omit, shorten, or paraphrase it' after 'copied verbatim'), so it is not perfectly concise, but it is well-structured 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?

For a read-only data-fetch tool with no output schema, the description covers what the tool returns (per-niche product sets plus aggregates), how to interpret it, when to use an alternative, and the unusual account-notice output behavior. Nothing an agent needs to call the tool correctly and handle its output 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 baseline is 3; the schema already explains keywords, count, and marketplace thoroughly. The description adds no parameter-level detail beyond the schema, though it reinforces what keywords mean ('niches / category keywords'). It does not need to compensate for gaps because there are none.

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

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

The description states a specific verb+resource: it fetches raw head-to-head data for 2–5 Amazon niches with per-niche product sets and computed aggregates. It also explicitly distances itself from AI analysis and names compare_products as the equivalent for ASINs, so an agent can distinguish it from sibling tools without opening schemas.

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

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

Gives clear when-to-use guidance: compare 2–5 niches or category keywords, and explicitly says 'For ASINs, compareProducts is the equivalent.' It also provides a practical analysis workflow (weigh demand vs. competition vs. price levels) and a mandatory output contract, leaving little 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?

Beyond the readOnlyHint annotation, the description discloses key behaviors: it fetches nothing without a marketplace parameter, returns money in the marketplace's local currency, and has a strict mandatory output contract for Account notice paragraphs. These are material behavioral details that an agent could not infer from the annotations alone.

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, then organized into clear labeled sections: usage, marketplace handling, and output contract. The longer output-contract section is justified because it imposes a critical, mandatory response behavior that cannot be paraphrased or omitted.

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

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

The description covers what the tool returns, how to invoke it correctly, the critical marketplace prerequisite and failure mode, currency semantics, and a mandatory output contract. Since there is no output schema, the description also names the main data fields, making it complete enough for an agent to call the tool correctly and process its response.

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 schema already explains ASIN requirements, marketplace codes, the 'MARKETPLACE NEEDED' failure, and currency context. The description reinforces these points and adds the 'ask once, reuse' instruction, but most parameter meaning is already carried by the input schema, so the description does not add substantial new parameter-level semantics.

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

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

The description names the exact operation — side-by-side raw data for 2–5 Amazon products by ASIN — and lists concrete metrics (price, sales/revenue estimates, reviews, listing quality, history). It also explicitly contrasts with analyzeProduct for single ASINs, which distinguishes it from a sibling.

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 explicit when-to-use guidance: 2–5 ASINs for this tool, a single ASIN should use analyzeProduct, and this tool is a pure data fetch where the agent must perform the comparison itself. It also provides a clear conditional workflow for determining the marketplace, including 'ask once and reuse' and the 'MARKETPLACE NEEDED' failure mode.

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. The description adds useful behavioral context beyond those annotations: it returns a welcome message and example questions, and it specifies that the output should be relayed verbatim. This is sufficient for such a simple zero-argument tool.

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

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

The description is front-loaded with the tool's purpose and then gives precise trigger conditions. It is somewhat long because of the exhaustive trigger list, but every element serves a practical purpose for an agent deciding when to invoke it. Minor redundancy exists in the repeated 'Ask AMZScout' capitalization examples.

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 zero-parameter demo tool with no output schema, the description is complete: it states what the tool does, when to call it, what to expect back, and how to handle the output. Nothing needed for correct invocation is missing.

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

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

The tool takes zero parameters, so there is nothing meaningful for the description to add beyond the schema. The baseline for a zero-parameter tool is 4; the description correctly avoids inventing unnecessary parameter details.

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

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

The description clearly states a specific verb ('Start AMZScout') and its resource, along with the concrete result: a welcome message and example questions. This clearly distinguishes it from the sibling analysis/search tools, which perform data operations rather than greeting/demo behavior.

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

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

It explicitly tells the agent when to call this tool: at the very start of the conversation and whenever the user greets or says triggers like 'Ask AMZScout', 'demo', 'begin', 'help', and similar phrases. It even clarifies case-insensitivity and instructs to relay output verbatim, which is actionable and unambiguous.

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

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

The description discloses substantial behavior beyond annotations: pre-validation via cached AI check, filtering to exact brand matches, fallback to returning brands that appeared in the keyword pool, and the mandatory output contract for 'Account notice' paragraphs. This is rich context that readOnlyHint/openWorldHint do not convey.

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

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

The description is moderately long but well-structured: core purpose first, then mechanism, then fallback, then usage guidance, then a clearly delimited output contract. Each section earns its place, especially the mandatory output contract which is critical. No waste, though the 'How to use' and output contract could be seen as 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?

With no output schema, the description covers key output behaviors: no-match fallback and the 'Account notice' prefix. It explains the pre-validation and filtering. It doesn't describe result formatting or pagination, but those are covered by schema and typical tool patterns. Given the complexity (nested filters, 5 params), it is adequately 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 80%, so the baseline is 3. The description adds high-level usage context (e.g., price range, revenue, reviews) that hints at how to use filters, but it doesn't provide specific parameter guidance beyond what the schema already offers. It adds marginal value.

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: 'List products under a specific Amazon brand.' It differentiates from siblings by focusing on brand-specific listing and explains the internal mechanism (pre-validates brand, filters keyword-search results). This makes the tool's unique role unmistakable.

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

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

It provides explicit 'How to use' guidance: assess brand footprint (lineup breadth, price range, revenue carriers, review moat). This implies when to use it but doesn't explicitly name alternatives or exclusion criteria. Sibling differentiation is indirect, relying on the word 'brand' rather than naming search_products.

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, and the description adds substantial behavioral context beyond that: the tool fetches nothing without a marketplace and replies 'MARKETPLACE NEEDED', money is in local currency, and the mandatory output contract for the 'Account notice' paragraph. This fully informs the agent of expected side effects and response formatting.

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

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

The description is long but every section earns its place: purpose, row contents, usage guidance, marketplace rule, and mandatory output contract. It is front-loaded with the core purpose and uses structured, scannable sentences without redundancy.

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

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

With no output schema, the description fully explains the shape of returned data (search volume, average sales, CPC, trend, placement fields) and the special account-notice response. It also covers the marketplace prerequisite and the 'MARKETPLACE NEEDED' failure mode, leaving no critical gap for correct invocation and interpretation.

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?

Although schema coverage is 100%, the description adds crucial semantics: ASIN and keyword are mutually exclusive scopes, ASIN-scope enriches rows with placement data, marketplace is practically required despite being marked optional, and currency is marketplace-dependent. These meanings are not inferable from the schema alone.

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

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

The description opens with a specific verb and resource: fetches Amazon keyword/SEO/PPC data for either an ASIN-scope or keyword-scope. It clearly distinguishes the two operation modes and states that it is a pure data fetch with no AI analysis, which separates it from the analyze_* siblings.

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 concrete 'How to use' guidance: picking high-volume/low-competition terms, using CPC as ad-cost pressure, summing search volumes for niche demand, and checking organic vs sponsored ranks. It also gives explicit marketplace-handling instructions. It does not name specific sibling tools, but the 'no AI analysis' note implicitly routes analysis use cases elsewhere.

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

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

Annotations already mark this as read-only and non-destructive, and the description adds valuable behavioral context: token cost per marketplace, the exact data returned, and the mandatory 'Account notice:' output contract with verbatim copy requirements. This goes well beyond the structured annotations.

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

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

The description is front-loaded with a crisp purpose sentence and is organized into clear sections for behavior, cost, usage, and output contract. It is somewhat long, and the grouping instruction is repeated from the schema, but every section earns its place given the mandatory account-notice handling.

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

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

Given there is no output schema, the description compensates fully by specifying the returned fields, the marketplace list, cost, and the exact handling of account-notice results. It also tells the agent how to continue the workflow if the user later wants analysis, so nothing needed for correct invocation is missing.

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

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

The single parameter 'asins' is fully documented in the input schema with format, count, and grouping guidance, so the schema carries the burden. The description adds little beyond 'per ASIN' and largely duplicates the schema's 'Pass several only when they will be analyzed together' instruction, keeping this 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?

The description states a specific action with a resource: find which Amazon marketplaces list an ASIN and get its product link on every marketplace. It also enumerates the return fields (title, local price, estimated monthly sales), making the tool's purpose unmistakable and distinguishable from siblings like analyze_product or search_products.

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

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

The description gives an explicit invocation condition: call it ONLY when the user asks where a product is sold or wants links on other marketplaces. It also provides a clear exclusion — do not call it just to choose a marketplace for analysis — and routes follow-up analysis to amzscout_analyze_product / amzscout_get_keywords.

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

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

Beyond the readOnly/destructive annotations, the description adds a mandatory output contract: if the result begins with an 'Account notice:' paragraph, the reply must copy it verbatim. This is critical behavioral guidance that an agent must follow. The tracking-links detail is also 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?

The description is efficiently structured: purpose, use case, then output contract. It's slightly dense but every sentence serves a purpose, and the output contract is front-loaded after the core purpose. 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?

For a single-parameter, read-only tool, this description is complete: it explains the tool's role, the exact use case, and the mandatory handling of the output. The output contract ensures correct behavior even without an output schema. Nothing an agent needs is missing.

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

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

Schema coverage is 100% and the parameter 'useCase' already has a clear description with examples. The tool description adds no extra parameter semantics, so a 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 exactly what the tool does: given a use case, it returns the AMZScout/Sellerhook catalog with tracking links for recommendation. This clearly distinguishes it from sibling analysis tools. The explicit 'Use for...' phrase further sharpens the purpose.

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

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

Provides a clear trigger: 'which AMZScout tool should I use for X' questions. It doesn't enumerate alternatives but the sibling tools are all analysis-oriented, so the use case is unambiguous. A brief note on when not to use (e.g., for direct product analysis) would make it a 5.

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

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

Beyond the readOnlyHint/destructiveHint annotations, the description discloses non-obvious behaviors: it is 'Pure data fetch (no AI analysis)', fetches nothing and returns "MARKETPLACE NEEDED" without a marketplace, and imposes a mandatory output contract for 'Account notice:' paragraphs. This is exactly the kind of behavioral context 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?

Every sentence earns its place: purpose, sibling routing, failure mode, output contract, and marketplace protocol are all load-bearing. However, it is a single dense wall of text with an embedded enumeration; bulleted structure would improve scannability for an agent, and some marketplace content duplicates the schema's parameter description.

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

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

For a 3-parameter tool with no output schema, the description is remarkably complete: it enumerates the returned data categories, explains the marketplace failure case, the currency semantics, and the mandatory account-notice output contract. An agent has everything needed to invoke it correctly and handle unusual responses, with only trivial gaps (e.g., invalid-ASIN behavior).

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

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

Schema coverage is 100% and the schema already documents all three parameters thoroughly, so the baseline is 3. The description adds real strategic value beyond the schema by recommending the tool be called first without `sections` and by explaining how to interpret section data (e.g., 'many FBA offers means price competition') — though some marketplace guidance in the description repeats the schema text.

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

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

The opening sentence names a specific verb+resource ('buy box, competing offers and price/rank statistics for one Amazon ASIN') and enumerates the exact data categories returned. It also differentiates from the closest sibling by stating it is 'not private-label research — for demand and revenue estimates use analyzeProduct instead', so an agent can route correctly without opening 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?

Explicitly names when to use this tool ('Built for reseller / online-arbitrage questions') and the alternative for other cases ('use analyzeProduct instead'). It also gives a concrete invocation protocol (call first WITHOUT sections, only request sections when the summary is insufficient) and tells the agent to ask once for marketplace rather than assuming the US.

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

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

Beyond the readOnly/destructive annotations, the description discloses a crucial behavioral contract: results may begin with an 'Account notice' paragraph, and the agent must copy it verbatim. It also documents the return structure (title, source URL, text), which is especially valuable because no output schema is provided.

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 concise and front-loaded: it states the core purpose and return format first, then gives a clearly marked mandatory output contract. Every sentence earns its place, and the contract formatting is unambiguous.

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?

Without an output schema, the description fully covers what the agent receives and how it must behave with certain results. Combined with the complete parameter schema, there are no significant gaps an agent would need filled to invoke this tool correctly.

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

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

Schema description coverage is 100%, so both parameters are already documented in the schema. The description adds the 'top-K' framing and the TF-IDF search context, which slightly enriches understanding of the query and topK behavior, but it does not substantially go beyond the structured parameter descriptions.

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 operation and resource: 'TF-IDF search across the AMZScout knowledge base'. It also explains the output artifact (top-K relevant chunks with title, source URL, and text), and the phrase 'ground answers in factual material' clearly distinguishes it from the product/niche analysis siblings.

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

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

The description explicitly tells the agent when to use the tool: 'Use this to ground answers in factual material.' It does not enumerate exclusions or compare directly to sibling tools, but the knowledge-base purpose is distinct enough from the analysis tools to provide clear usage 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 declare readOnlyHint=true and destructiveHint=false; the description adds 'Pure data fetch (no AI analysis)' and a mandatory OUTPUT CONTRACT for the 'Account notice:' prefix, which is important behavior not captured in annotations or schema. No contradiction found, though rate limits and result-error behavior are not disclosed.

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 purpose, then routes to a sibling, then gives operational guidance and the critical output contract. The 'How to use' sentence is useful but slightly beyond selection/invocation needs; otherwise 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 tool with no output schema and a nested filters object, the description covers the returned fields, the raw-vs-analyzed distinction, and the unusual account-notice behavior. It lacks explicit empty-result/error handling and pagination, but those are not critical for correct invocation here.

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

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

Schema description coverage is 100%, so the baseline is 3 and the description doesn't need to compensate. It adds only light semantic context by referencing sort order/filters and the returned fields; it doesn't materially enrich parameter meaning 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 names a specific action ('keyword search'), resource ('Amazon'), and concrete output ('top N products with price, sales, revenue, reviews, rating'). It also distinguishes itself from analyzeNiche ('Pure data fetch (no AI analysis)'), so an agent can discriminate it from the closest sibling without opening 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?

It explicitly states the best use case ('raw product rows (specific sort order or filters)') and names the alternative tool with the exact differentiating condition ('analyzeNiche additionally returns computed market aggregates'). This is explicit routing, not just implied 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 mark this as read-only and non-destructive, and the description adds meaningful behavior: the call is free, the remaining figure should be reported first, and there is a mandatory 'Account notice' verbatim output contract. No contradiction with annotations exists.

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

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

The description is front-loaded with the core purpose and each section serves a purpose, especially the output contract. It is somewhat verbose, and the 'How to use' guidance overlaps slightly with the 'Report the remaining figure first' instruction, keeping it from a perfect score.

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?

Even without an output schema, the description specifies the returned balance dimensions and the exact handling of the account-notice case. For a zero-parameter read-only tool, no critical usage or response information 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?

There are zero parameters, so the schema is already complete. The description adds no parameter-specific semantics but does explain what the call returns and that it is free, which is enough for a parameterless tool.

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

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

The description opens with the exact object: 'The caller's AMZScout AI-agents token balance — remaining, used, and limit.' It also clarifies that the call is free. This is clearly distinct from the sibling tools, which are all analysis, search, or recommendation 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?

It gives explicit triggers: answer token-balance/usage/limit questions and use it 'when a call fails on quota.' It does not list alternatives or exclusions, but for a 0-parameter usage-status tool, the stated use cases are sufficient.

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