AMZScout Skill + MCP

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

The readOnlyHint annotation already covers safety, and the description adds valuable behavioral context: it pulls live data, runs analyses internally, and returns a user-ready report. This explains the orchestration behavior beyond a simple read operation, though it does not discuss limitations or edge cases.

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 three sentences long, front-loaded with the tool's role ('AMZScout all-in-one Amazon research assistant'), and every clause carries meaning—purpose, behavior, usage guidance, and output. No redundancy or 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 an open-ended natural language agent, the description provides sufficient context: what it does, how it behaves (internal analysis, no sub-tool selection), when to use it, and what it returns ('complete, user-ready report'). Even without an output schema, the return expectation is clear.

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 fully describes both parameters (message and history), so the description adds no additional parameter-level detail. It only reinforces that the message is a natural language request, which is already implied by the schema description. Baseline of 3 is appropriate given 100% schema coverage.

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

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

The description clearly identifies the tool as an all-in-one Amazon research assistant that accepts natural language queries and returns a finished analysis. It distinguishes itself from the granular sibling tools by stating that no sub-tool selection is needed, making the purpose unambiguous.

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

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

Explicitly states when to use this tool ('Best for a hands-off answer') and names the alternative ('the granular amzscout_* tools are the alternative when step-by-step orchestration is preferred'). This gives direct guidance on tool 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?

With readOnlyHint=true already marking it as safe, the description adds behavioral context: 'Pure data fetch (no AI analysis)' clarifies that no interpretation is performed, and it enumerates computed aggregates such as revenue concentration and brand spread. There is no contradiction with annotations, though a return-format disclaimer is absent.

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 front-loads the purpose in the first sentence, then adds a behavioral caveat and a structured how-to. The how-to is detailed but relevant to decision-making, with no filler content; it is somewhat long (~70 words) but well-organized.

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?

Since there is no output schema, the description compensates by listing output categories (price/sales/revenue/review distributions, revenue concentration, brand spread) and an example field (revenueTop5SharePercent). It doesn't fully specify return structure or pagination, but it provides enough context for a data-fetch snapshot 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?

The input schema already provides 100% coverage with descriptions for all four parameters (keyword, count, filters, marketplace). The description adds no parameter-level details beyond the schema, only implying the output depends on keyword and count.

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 — top products by revenue plus computed aggregates', clearly identifying the resource (niche/keyword) and what it delivers. The 'Pure data fetch (no AI analysis)' line and mention of aggregates distinguish it from siblings like amzscout_analyze_product or amzscout-agent.

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 'How to use' section provides clear context on when to use the tool: to judge niche attractiveness based on demand concentration, price bands, review moats, and brand spread. It also implies when not to use it ('Pure data fetch, no AI analysis'), but it doesn't explicitly name alternative tools or exclusions.

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 declare readOnlyHint=true, and the description reinforces this by stating 'Pure data fetch (no AI analysis)' and mentions 'when available' for history data, adding context about data availability and the lack of built-in analysis. It does not contradict annotations and provides useful behavioral context beyond the simple read-only flag.

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 reasonably concise, with the core purpose stated first and usage guidance following. It is not overly verbose, but the second sentence is a long, multi-clause instruction that could be more tightly structured. Every sentence contributes value, so it earns above average.

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

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

Given the tool's simplicity (2 params, no output schema), the description compensates well by listing the key data fields returned (price, sales, reviews, etc.) and providing a detailed workflow for interpreting the data. It covers what the tool does, what data it returns, and how to use it, making it comprehensive enough for an agent to select and invoke correctly.

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

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

The input schema already provides 100% description coverage for both parameters (asin and marketplace), so the tool description does not need to add parameter details. It mentions 'by ASIN' but does not elaborate beyond what the schema already states, 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?

The description clearly states 'Full raw data for a single Amazon product by ASIN' and explicitly notes 'Pure data fetch (no AI analysis)', establishing a specific verb (fetch) and resource (single product). It distinguishes from siblings like analyze_niche and analyze_product_set by focusing on a single 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?

The description provides a clear 'How to use' section that frames the tool for product sourcing audits, including specific actions like demand trend analysis and GO/NO-GO decisions. However, it does not explicitly state when to use this tool over alternatives such as analyze_product_set, though the single-product focus is implicit.

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; the description adds that it is a 'pure data fetch (no AI analysis)' and instructs the user to reason over the data themselves. This clarifies what the tool does not do, which is valuable beyond the annotation.

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 three sentences long: the first defines output, the second clarifies scope and alternative, the third gives usage guidance. Every sentence earns its place and the core information 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?

Despite lacking an output schema, the description clearly enumerates what is returned (product rows plus distributions and aggregates) and provides usage guidance. Together with the read-only annotation, this is complete for the tool's 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% with detailed descriptions for both parameters (ASINs range and marketplace enum). The description's mention of '2–100 ASINs' repeats the schema's asins description and does not add new semantic meaning, so it relies on 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 clearly states the tool fetches raw data for an explicit set of 2–100 ASINs and computes aggregates, distinguishing it from sibling tools. It even names an alternative (analyzeNiche) for keyword-based discovery, effectively differentiating the tool's purpose.

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

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

The description provides explicit when-to-use guidance: use this tool for a set of ASINs, and use analyzeNiche instead for keyword discovery. It also gives a concrete 'How to use' section, which tells the agent how to reason over the data.

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

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

Annotations already mark the tool as read-only. The description adds value by stating it is a 'pure data fetch (no AI analysis)' and 'raw' data, clarifying that the output is unprocessed and requires manual interpretation. This goes beyond the simple readOnlyHint.

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 structured with a clear definition first, then a usage note and how-to instructions. It is slightly verbose but every sentence earns its place by conveying non-obvious details (e.g., no AI analysis, how to weigh metrics). Overall efficient and 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?

For a 3-parameter tool with no output schema, the description provides a solid overview of the returned data (distributions, concentration, brand spread) and the decision-making context. It could benefit from specifying exact output fields or examples, but it is adequately complete for an agent to understand what to expect.

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 covers 100% of parameters with descriptions, so the baseline is 3. The description does not add meaningful parameter-level detail beyond what the schema already provides; it focuses on output characteristics and usage, not parameter 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 clearly states the tool's purpose: it fetches raw head-to-head data for 2–5 Amazon niches/category keywords, including per-niche product sets and computed aggregates. It also explicitly distinguishes itself from compareProducts (for ASINs), making the scope unambiguous.

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

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

The description provides clear context for when to use the tool (comparing niches with raw data) and names an alternative for ASINs (compareProducts). However, it does not explicitly mention when to use the tool over other sibling tools like analyze_niche, missing full when/when-not coverage.

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

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

Annotations already mark readOnlyHint=true; description adds that it's a 'pure data fetch (no AI analysis)' and that history is 'when available', disclosing output limitations beyond the safe-read annotation.

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

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

Four sentences, each earning its place: purpose, mode, alternative, and usage guide. Front-loaded with the main action.

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 no output schema, description enumerates returned fields (price, sales/revenue, reviews, listing quality, history) and outlines a comparison workflow, making the tool's context complete for an agent.

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

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

Schema covers both parameters with 100% description coverage, including ASIN bounds and marketplace enum. Description reiterates ASIN count and purpose but adds no new parameter-level 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?

States 'Side-by-side raw data for 2–5 Amazon products by ASIN' with specific data fields; explicitly contrasts with analyzeProduct for single ASIN, distinguishing from 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?

Explicitly notes alternative for single ASIN ('For a single ASIN, analyzeProduct is the equivalent') and clarifies this is pure data fetch with no AI analysis, implying when to use it. Provides a step-by-step 'How to use' workflow.

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 meaningful behavior: pre-validates via cached AI check, filters keyword-search results to rows where 'brand' actually matches, and returns alternative brands on no-match. These details help an agent anticipate outcomes and edge cases.

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 four sentences with no fluff. The first sentence front-loads the core purpose, and the subsequent sentences add behavioral detail and practical usage guidance 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?

Given the tool's complexity (5 parameters, nested filters) and lack of an output schema, the description covers the main behavior, fallback handling, and intended use. However, it does not explicitly describe the success return format or how this tool relates to sibling tools like amzscout_search_products, leaving a small 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?

The schema already covers 80% of parameters with descriptions, so the baseline is 3. The description adds extra meaning for 'brand' by emphasizing it must 'actually match' and explaining the no-match fallback, which goes slightly beyond the schema's plain 'Amazon brand name to search by'.

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 'List products under a specific Amazon brand,' which clearly states the action and resource. It also distinguishes itself from sibling tools like amzscout_search_products by detailing the brand pre-validation and exact-field matching 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?

The description provides clear usage context with 'How to use: assess the brand's Amazon footprint — lineup breadth, price range...' but does not explicitly state when not to use it or name alternative tools. It implies the tool is for brand-focused analysis rather than generic product search.

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

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

The readOnlyHint annotation already declares this is a safe read. The description adds value by clarifying it returns raw data without AI analysis, indicating that competition data is provided 'where available', and explaining how to interpret organic vs sponsored ranks. This goes beyond the annotation without contradicting 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?

The description is moderately sized but well-structured: it front-loads the core purpose, then details return data, clarifies the non-analytical nature, and offers a compact 'How to use' list. Each sentence contributes useful information without redundancy, though it could be slightly tighter.

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

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

Given the simple optional parameters and no output schema, the description sufficiently covers what the tool returns and how to use it. It implies mutual exclusivity of the two scopes, mentions data availability caveats, and provides practical interpretation tips. The main minor gap is no explicit behavior when both asin and keyword are provided, but the 'either... or...' phrasing largely addresses this.

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 meaningful context beyond the schema by explaining the two usage modes (ASIN-scope vs keyword-scope) and linking parameter choices to strategic use cases like spotting listing-optimization gaps and gauging niche demand. This enriches the bare parameter definitions.

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 specifies the tool's function: retrieving Amazon keyword/SEO/PPC data for either an ASIN or a keyword. It names the returned fields (search volume, CPC, competition) and distinguishes itself from siblings by stating 'Pure data fetch (no AI analysis)', making the purpose unambiguous.

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

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

The description provides concrete guidance on how to use the data (e.g., 'pick high-volume / low-competition terms for SEO and PPC targeting') and clearly states it is a raw data fetch without AI analysis, implying that analysis tools are alternatives. However, it does not explicitly name those sibling tools or give exclusions beyond 'no AI 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, so the safety profile is covered. The description adds useful context by stating the tool returns a catalog 'with tracking links' and notes that the agent is expected to use it 'so you can recommend' the right product, clarifying that the tool provides informational output rather than performing the recommendation autonomously.

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 two sentences, immediately states the purpose, and then provides the usage trigger phrase. No wasted words, and key information 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?

For a simple tool with one parameter and no output schema, the description sufficiently explains the purpose and output (catalog with tracking links). It lacks details about the catalog format, but given the tool's simplicity and the explicit use-case trigger, it is reasonably complete. A slightly richer description could clarify what the catalog contains, but it's not a critical 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?

The schema description coverage is 100% for the single parameter 'useCase', which already explains what the user is trying to do. The description does not add extra parameter information, but the baseline of 3 is appropriate since the schema fully documents the parameter.

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

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

The description clearly states the tool's function: 'returns the AMZScout tools & Sellerhook services catalog' based on a user use-case. It also explicitly differentiates from sibling tools by saying it is for 'which AMZScout tool should I use for X' questions, making it distinct from analysis/search 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?

The description provides an explicit when-to-use: 'Use for "which AMZScout tool should I use for X" questions.' This gives clear context, but it does not explicitly state alternatives or when not to use it. It implies this is for recommendations rather than direct data retrieval, but lacks explicit exclusions.

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 annotation indicates readOnlyHint=true, lowering the burden. The description adds meaningful behavioral context: it reveals the search algorithm (TF-IDF), the content scope, and the return structure (top-K chunks with title, URL, text). This goes beyond simply stating the tool is a safe read.

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 three concise sentences: purpose, return format, and usage. It is front-loaded with the verb and resource, no filler, and every clause contributes value.

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

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

For a simple read-only search tool with two well-documented parameters and no output schema, the description fully covers what the tool does and returns. It is complete and needs no further explanation.

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% for both parameters (query and topK), so per rubric the baseline is 3. The description does not add significant parameter-level meaning beyond what the schema already provides, though it does contextualize 'top-K' and 'search'.

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 specifies a distinct verb ('search') and resource ('AMZScout knowledge base') with content types (tutorials, brand reference, glossary). It clearly identifies the return payload (chunks with title, source URL, text), which distinguishes it from sibling analysis tool.

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

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

The description provides clear context for when to use the tool ('Use this to ground answers in factual material') but does not explicitly name alternatives or state when not to use it. This is a clear usage context without exclusions.

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 the description adds behavioral context: 'Pure data fetch (no AI analysis)' clarifies the tool's non-analytical nature. It also conveys that returned rows are raw and supports specific sort/filter, adding value beyond the annotation.

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 are used: purpose, comparison/usage, and a practical scan heuristic. Each sentence carries information, but the 'How to use' clause is slightly more verbose than strictly necessary. Still, the description is well-structured and front-loaded with the core purpose.

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 compensates by stating the returned fields. It covers use cases, alternatives, and a usage heuristic. Some details like marketplace default and limit ranges are left to the schema, but given the schema's richness, this is 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%, with all parameters and enum values documented in the input schema. The description adds only high-level context ('top N', 'sort order or filters') without duplicating or enriching individual parameter semantics, 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?

The description clearly identifies the action ('Keyword search against Amazon'), the resource ('Amazon'), and the output ('top N products with price, sales, revenue, reviews, rating'). It also distinguishes itself from the sibling analyzeNiche by contrasting raw rows vs computed aggregates.

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?

Explicit usage guidance is provided: 'Best when you need raw product rows (specific sort order or filters)' and directly names the alternative tool for computed aggregates ('analyzeNiche additionally returns computed market aggregates'). The 'How to use' sentence further clarifies intended application.

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 adds key behavioral context: the call is free and does not charge tokens. It also instructs to report the remaining figure first, which sets response expectations. No side effects exist due to read-only nature, so this is sufficient.

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 concise sentences each serve a purpose: resource definition, cost disclosure, and usage guidance. Front-loaded with the core purpose, no redundant words, and tightly structured for quick comprehension.

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

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

For a simple zero-parameter read-only tool, the description fully covers purpose, usage triggers, cost implications, and response emphasis. It is complete enough for an agent to invoke correctly without an output 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?

The tool has zero parameters, so schema coverage is trivially 100%. The description compensates by clarifying the output semantics (remaining, used, limit) and the free-of-charge behavior, which adds value beyond the empty 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 clearly states the tool reports the caller's AMZScout AI-agents token balance (remaining, used, and limit). It uses a specific noun phrase ('token balance') and differentiates from sibling analysis tools by focusing on usage metadata, not product/niche insights.

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 provides when to use: answer questions like 'how many tokens do I have left' or 'usage/balance/limit', and also when a call fails on quota. It clearly implies this is the go-to tool for token accounting, contrasting with the analytical siblings.

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