AMZScout Skill + MCP

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

The readOnlyHint=true annotation already declares this is a read-only operation, and the description adds useful behavior: it 'pulls live Amazon data,' 'runs the right analyses internally,' and 'returns a complete, user-ready report.' This adds behavioral context about internal orchestration and output format beyond the annotation, though it doesn't disclose rate limits or how history interacts with the internal analysis.

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 a focused single paragraph with example queries embedded for usability. It front-loads the purpose and includes the alternative-tool guidance efficiently. Slightly longer than strictly necessary due to the example queries and multiple clauses, but all content 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 natural-language agent tool with only 2 params and no output schema, the description adequately covers purpose, alternative tools, and return behavior. The examples illustrate both product-level and niche-level use cases. It's complete enough for an agent to know when and how to invoke it, though the exact report format could be more specific.

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

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

Schema coverage is 100%, so the schema already documents both parameters. The description reinforces the message parameter as a natural-language question with concrete examples, and implies history is for multi-turn context, but doesn't add meaning beyond what the schema descriptions already provide. 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 this is an all-in-one Amazon research assistant that accepts natural language queries and returns a finished analysis. It explicitly distinguishes itself from the granular amzscout_* sibling tools by noting no sub-tool selection is needed, which sets it apart from all 11 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 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'). It also provides concrete example queries showing the intended usage pattern.

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 safe-read profile is known. The description adds value by clarifying the tool is a pure data fetch with no AI analysis layer and enumerating the aggregation dimensions returned. However, it doesn't disclose rate-limit behavior, response size/pagination, or whether the data is live vs. cached snapshot. With readOnly annotations present, the bar is lower, but the behavioral disclosure of return-data shape is only partially covered.

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 well-structured: a purpose sentence, a clarifying caveat, then a bulleted 'How to use' section. Each sentence earns its place, and the analytical-application guidance is genuinely useful. Slightly verbose in the 'How to use' enumeration, but the density of practical value justifies the length. Not zero-waste like the TDQS-4.3 example, but appropriately 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?

For a data-fetch tool with readOnly annotation and 100% schema coverage, the description covers the core purpose, the interpretation guide, and the non-AI caveat. The complexity (nested filters object, 4 params, no output schema) is well-supported by the schema's detailed param descriptions. Gaps: no mention of the output structure/shape and no rate limits, but given the no-AI-nature disclosure and rich schema, completeness is strong.

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 (keyword, count, marketplace, filters) has its own schema description — the schema does the heavy lifting. The description adds marginal value by mentioning the aggregate dimensions (revenue concentration, brand spread) that help interpret the filter outputs, but it doesn't explain filter semantics beyond schema. Baseline 3 is correct given full schema coverage.

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

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

The description clearly states the verb+resource ('Market snapshot for an Amazon niche/keyword') and lists the specific computed outputs (top products, price/sales/revenue/review distributions, concentration, brand spread). It explicitly distinguishes from siblings by noting 'Pure data fetch (no AI analysis)' — differentiating it from amzscout_agent and amzscout_recommend_tool. The name and purpose align precisely.

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 full 'How to use' section on when to apply the tool — judging niche attractiveness through demand concentration, price bands, review moats, and brand dominance. It also includes the exclusion note 'no AI analysis — reason over the returned data yourself,' which clarifies when NOT to reach for this vs. agent-based tools. This is exceptional guidance beyond just stating 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 carry readOnlyHint=true, and the description reinforces this with 'Pure data fetch (no AI analysis) — reason over the returned data yourself.' This adds meaningful behavioral context beyond the annotation: it explicitly tells the agent the tool does NOT perform analysis and that history 'when available' may be absent. That's valuable behavioral disclosure.

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?

Well-structured two-sentence description: first sentence states data granularity and content, second gives usage guidance. No wasted words, but could be slightly tighter — the usage paragraph is a bit long relative to its informational density.

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, the description enumerates expected return fields (price, sales/revenue, reviews, rating, LQS, sellers, history) which substitutes well. The 2-param tool with full schema coverage and a thorough behavioral/usage narrative is complete for an agent to select and use 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% (both asin and marketplace documented in schema), so baseline is 3. The description adds marginal context by confirming the tool expects an ASIN and that marketplace defaults to COM. It doesn't heavily elaborate beyond the schema, but that's acceptable given full 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?

Description states specific verb+resource ('Full raw data for a single Amazon product by ASIN') and enumerates the exact fields returned (price, sales/revenue, reviews, rating, LQS, sellers, history). It clearly distinguishes from siblings like analyze_niche and compare_products by emphasizing 'single product' and 'full raw data'.

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

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

Provides explicit usage context ('audit the product like a sourcing analyst... conclude whether a new seller should enter GO/NO-GO'). Does not explicitly name alternative tools or state when NOT to use it, but the 'single product' vs set/niche distinction is clear enough given sibling names.

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, so the bar is lower. The description adds the key behavioral detail that this is a pure data fetch with no AI analysis, which is useful for setting agent expectations. However, it doesn't disclose what happens with invalid/nonexistent ASINs, error cases, or rate limits. Beyond the no-analysis trait, behavioral disclosure is modest, though annotations already cover the safety profile.

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 roughly three sentences with useful content packed efficiently. The 'How to use' section adds real value despite being somewhat long. Front-loads the core purpose clearly. Slightly verbose in the guidance section but every sentence earns its place. Could trim marginally, but overall well-structured.

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 partially compensates by listing what's returned (product rows plus computed aggregates across price/sales/revenue/review distributions, revenue concentration, brand spread). This is genuinely useful. Given the tool's moderate complexity (2 params, clear scope) and the explicit no-AI-analysis boundary, the description is largely complete. Could mention pagination or response size but the explicit ASIN cap bounds expectation.

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 baseline is 3. The asins param is well-documented in-schema (format, range, auto-correction behavior). The description adds the conceptual framing that the set should be treated as a mini-market, but doesn't add parameter-level detail beyond what the schema provides. Marketplace is fully documented by its enum.

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?

Description states a specific verb+resource: fetch raw data across an explicit set of 2-100 ASINs, computing aggregates. It clearly distinguishes from siblings by noting it reasons over raw product rows rather than doing AI analysis, and names analyzeNiche as the keyword-based equivalent. The scope (explicit set vs keyword discovery) is unambiguous.

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

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

Provides explicit when-to-use: use for an explicit ASIN set treated as a mini-market. Names the alternative (analyzeNiche) for keyword-based discovery. Gives concrete guidance on what to do with results — segment products, spot demand concentration, flag outliers. The exclusions are explicit and actionable.

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 with 'Pure data fetch (no AI analysis)', adding value beyond the annotation by clarifying the tool returns raw data requiring the caller to do interpretation. However, it doesn't detail output structure, pagination limits, or rate-limit behavior, leaving some transparency gaps despite the annotation coverage.

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?

Compact but dense single paragraph. Every sentence earns its place: purpose, AO distinction, usage guidance, and actionable framework all in a few lines. Slightly wordy toward the end with the 'how to use' guidance, but it's genuinely useful instruction rather than 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 data-fetch tool with no output schema and good annotations, the description covers purpose, output contents, differentiation from siblings, and a concrete usage framework. It doesn't describe exact return shape (arrays, distribution stats format), but for a raw-data tool whose schema declares readOnly, this is reasonably 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 the schema already documents count, keywords, and marketplace with descriptions and constraints. The description adds the niche keyword format example ('yoga mat', 'resistance bands') and mentions the 2-5 range, but the schema already covers these. Baseline 3 is appropriate since 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?

Clear specific verb+resource: 'head-to-head data for 2-5 Amazon niches'. Distinguishes from sibling amzscout_analyze_niche by explicitly noting 'Pure data fetch (no AI analysis) — do the comparison yourself'. Also contrasts with amzscout_compare_products for ASIN-level comparison, differentiating at the resource level.

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 this is raw data fetching requiring the agent to do the comparison itself (vs analyze tools). Names the ASIN equivalent (compareProducts) and gives a concrete usage framework: weigh demand against competition and price, then give a verdict on conditions. This gives the agent clear context on when and how to use it.

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 value by stating it's 'Pure data fetch (no AI analysis) — do the comparison yourself', clarifying the behavioral expectation that the agent must perform analysis rather than rely on tool output. This is meaningful added context beyond 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?

Well-structured with purposeful sentences: purpose, functional guardrail, sibling pointer, and usage guidance. The 'How to use' section is arguably slightly verbose but earns its place by operationalizing the comparison. Could trim a couple words but is tightly written overall.

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 comparison tool with 2 params, 100% schema coverage, and clear sibling differentiation, the description is complete. It covers what data comes back, how to use it, and warns against expecting AI analysis. No output schema exists, but the description adequately enumerates the data fields returned.

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%, giving baseline 3. The description adds value by naming the exact comparison dimensions (demand, revenue, review moat, rating, price, listing quality, history trends), which guides how the asins parameter should be selected and what to do with the results. Slight extra beyond 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?

Clear verb+resource: 'Side-by-side raw data for 2–5 Amazon products by ASIN' with specific data categories listed (price, sales/revenue, reviews, listing quality, history). Distinguishes from sibling analyzeProduct by explicitly noting the single-ASIN equivalent.

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 (compare 2-5 products) and gives the alternative (analyzeProduct for single ASIN). Provides a concrete 'How to use' walkthrough of comparison dimensions. Lacks explicit 'when NOT to use' exclusion beyond the single-ASIN case, but the context is clear.

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

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

The description states it returns a welcome message and example questions, and instructs to relay output verbatim. While the readOnly annotation is present, the description adds context about the output and handling, which is useful for the agent.

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 enough, though it repeats the trigger examples. It is not overly verbose and is structured in a single clear sentence, which is acceptable.

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 nature (no params, no output schema), the description fully covers what the tool does, when to use it, and how to handle its output. No additional information is needed.

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

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

The tool has zero parameters, so the baseline is 4. The description does not need to explain any parameter details, and the empty schema is fully covered.

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?

Clearly states it returns a welcome message and example questions, and explicitly distinguishes itself from other AMZScout tools by its demo/greeting purpose. The name 'amzscout_demo' is reinforced by the description, making its function 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?

Provides explicit usage triggers: call at the very start of conversation, on greetings, or when user says specific phrases like 'Ask AMZScout', 'demo', 'begin', etc. This leaves no ambiguity about when to invoke the 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 declare readOnlyHint=true, covering the safety profile. The description goes beyond annotations by disclosing real behavioral traits: cached AI pre-validation, the internal mechanism (keyword search then brand-field filtering), the no-match fallback that returns alternative brands, and that results are restricted to rows whose brand field actually matches. This enriches what the agent can predict about behavior beyond 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 compact — three sentences plus a brief 'How to use' framing. It front-loads the primary action, then explains the mechanism and fallback, and closes with the intended analytical application. No wasted words, though the 'How to use' sentence is somewhat abstract and could arguably be trimmed without loss.

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 listing tool with a rich schema (80% param coverage, nested filters object, enums for sort and marketplace), the description covers the distinctive behaviors (AI pre-validation, brand matching, no-match alternative suggestion). No output schema exists, so the description could have mentioned return structure, but the emphasis on which rows are included is sufficient for a filtered-list tool. Solid coverage overall.

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 schema does most of the parameter documentation work (brand, count, sort, marketplace, filters are all described inline). The description adds the semantics of the 'brand' parameter (that it is pre-validated and matched against the brand field) but does not add further detail on sort/count/marketplace/filters beyond what the schema already provides. At 80% coverage 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?

The description states a specific verb+resource ('List products under a specific Amazon brand') plus a distinctive mechanism (pre-validates via cached AI, filters keyword results by brand match, returns alternatives on no-match). It clearly distinguishes this from sibling tools like amzscout_search_products (keyword search) and amzscout_analyze_product (deep dive on a single product). The 'How to use' line gives the analytical framing that differentiates it from pure listing 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 explains when to use it ('assess the brand's Amazon footprint') and how the tool behaves on no-match (returns alternative brands), which guides a caller to suggest alternatives. It does not explicitly name competing sibling tools for exclusion, but the brand-scoped mechanism plus the no-match fallback is clear enough context. Slightly short of truly explicit when-not-to-use 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?

The readOnlyHint annotation already declares a safe read operation, so the bar is lower. The description adds value by explicitly stating 'Pure data fetch (no AI analysis)', which sets clear expectations that no interpretation or recommendations will be provided — a key behavioral distinction given the sibling analyze/agent/recommend tools exist. It also notes 'where available' qualifying data completeness.

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 somewhat dense, packing dual-scope explanation, returned fields, and usage guidance into a fairly long paragraph. The 'How to use' section is useful but could be tightened. It's not wasteful, but a two-part structure (what → how) rather than one flowing sentence block would improve scannability.

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 with 100% schema coverage and no output schema needed, the description is complete. It explains scope selection, returned data, and practical application. The readOnlyHint annotation plus the explicit 'no AI analysis' note fully satisfy behavioral expectations for a fetch tool.

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

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

Schema coverage is 100%, so the schema already documents all three parameters. The description adds value by explaining the semantic relationship between asin and keyword asmutually exclusive scope selectors (ASIN-scope vs keyword-scope) and the functional difference between them — which the schema alone does not convey, since it presents them as independent params.

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 dual scope (ASIN-scope for product ranks, keyword-scope for niche search data), explicitly notes it's a pure data fetch with no AI analysis, and lists returned fields (search volume, CPC, competition). This distinguishes it from sibling analysis tools like amzscout_analyze_product and amzscout_analyze_niche which imply deeper AI-driven analysis.

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 gives concrete guidance: picking high-volume/low-competition terms for SEO/PPC, using CPC as ad-cost pressure, summing volumes for niche demand, and checking organic vs sponsored ranks for ASIN scope. It lacks explicit 'when NOT to use' or named alternatives, but the dual-scope explanation gives clear situational context distinguishing it from compare/analyze 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?

The description notes it returns a catalog with tracking links, which adds behavioral context. However, the readOnlyHint annotation already covers the safety profile. The description doesn't clarify whether the catalog is cached/static or reflects real-time availability, nor what happens if the use-case doesn't match any tool. With annotations present, a 3 is appropriate.

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 sentences, no filler, front-loaded with purpose and usage context. The tracking-links detail is relevant and earns its place. Efficient and well-structured for an informational/recommendation tool.

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 catalog-recommendation tool with readOnlyHint annotation and full schema coverage, the description covers purpose, usage, output nature (catalog with tracking links), and trigger phrasing. It's reasonably complete for this tool's complexity level. It could mention what the return looks like more explicitly, but no output schema exists and the value here is the catalog content itself.

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 the single useCase parameter, which already documents its meaning with examples. The description adds context by framing useCase as 'what the user is trying to do' but doesn't add meaning beyond the schema. Baseline 3 is appropriate when the schema fully documents 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?

The description states a clear purpose: given a user use-case, it returns the AMZScout tools & Sellerhook services catalog for recommending the right product/feature. It has a specific verb (recommends) and resource (AMZScout tools catalog), and the usage example distinguishes it from siblings like amzscout_analyze_niche by focusing on catalog recommendations rather than analysis.

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 notes it's for "which AMZScout tool should I use for X" questions, implying usage context. However, it doesn't explicitly exclude cases where a sibling analysis tool would be more appropriate, nor mention when NOT to use it. The context is clear but lacks exclusions or alternative tool references.

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 safe-read nature is covered structurally. The description adds that it returns titles, URLs, and text chunks, giving the agent expectations of the response shape. It does not describe pagination, result count default behavior, or ranking semantics beyond the TF-IDF mention, but with annotations present the bar is met at a moderate level.

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 tightly written sentences carry purpose, domain scope, return format, and a usage directive with zero filler. Every clause earns its place, and the most essential information (what + scope) 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 moderate-complexity search tool with 100% schema coverage and no output schema, the description competently covers operation, purpose, and return content. The response type (text chunks with URLs) is partially described but not fully enumerated; it could mention handling of zero-result cases or relevance thresholds, but overall it is adequate given the tool's simplicity.

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 query and topK are already documented in the schema (with ranges and defaults). The description nevertheless adds value by noting the mechanism ('TF-IDF') which informs how the query string interacts with results, and clarifies that top-K chunks are returned, reinforcing the topK semantics beyond just a schema range.

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 clear verb+resource ('TF-IDF search across the AMZScout knowledge base') and enumerates the content domain (tutorials, brand reference, glossary). It explicitly states the return format (top-K chunks with title, source URL, text), which strongly distinguishes it from siblings like amzscout_search_products and amzscout_find_by_brand that search product data.

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

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

The description ends with 'Use this to ground answers in factual material,' which implies the use case of retrieving authoritative content for grounding. This provides clear context for when to invoke it, though it does not explicitly name exclusion conditions or directly contrast with alternative tools like amzscout_recommend_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?

The description states 'Pure data fetch (no AI analysis)', clarifying that this tool performs a direct retrieval without compute. The readOnlyHint annotation already declares this is a read operation, so the bar is lower; the description's honesty about the non-analytical nature adds useful context beyond what the annotation provides (that the data is raw and requires the agent to do interpretation). It could mention pagination or rate limits, but with annotation coverage this is solid.

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 plus a usage-dependent clause, all tightly packed with high-value information: what it returns, its non-analytical nature, sibling comparison, and interpretation guidance. No filler, every sentence adds meaning.

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 has 100% schema coverage, readOnlyHint annotation, and 5 parameters (1 required), the description covers purpose, differentiation, and usage interpretation adequately. It doesn't explain return value structure, but there is no output schema and the returned rows are described generically; for a search tool with this complexity, the coverage is good but could mention how results are ordered when no sort is specified (default revenue is in 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 fully documents all 5 parameters. The description adds modest value by clarifying sort order behavior (mentioning desc/asc interpretation is in schema already) and connecting the rows to interpretation guidance. Baseline 3 is appropriate since the schema does the heavy lifting and the description provides supplementary framing without duplicating schema 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?

Description states a specific verb+resource ('Keyword search against Amazon') and clearly specifies the returned data (price, sales, revenue, reviews, rating). It explicitly differentiates from sibling analyzeNiche by noting the difference between raw product rows and computed market aggregates. This is a strong, specific, and distinguishing purpose statement.

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 states when to use this tool ('Best when you need raw product rows with specific sort order or filters') and names the alternative (analyzeNiche) with its distinguishing behavior. It also provides concrete usage guidance on how to interpret the rows ('scan the rows for demand leaders, price clusters, and low-review listings that still sell'). This is exemplary usage 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, and the description adds that the call is free (no tokens charged), which is valuable behavioral context beyond the annotation. It doesn't describe return format, but for a no-parameter read tool with readOnlyHint set, this is reasonable coverage.

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, all purposeful: what it reports, that it's free, and how to use it. No wasted words, critical usage patterns front-loaded in the first line.

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, read-only status tool, the description covers purpose, usage triggers, cost behavior, and reporting precedence. The only minor gap is not describing the expected return shape, but with no output schema and a simple balance-reporting purpose 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?

The tool has zero parameters, and schema coverage is 100% (trivially, since there are no params). The baseline for 0-param tools is 4, and the description adds no param information needed since there are no parameters to document.

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 token balance (remaining, used, limit), naming the specific resource (token balance) and the purpose. It distinguishes itself from sibling tools like amzscout_get_keywords and amzscout_search_products, which are functionally unrelated.

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 provides when-to-use guidance: answer 'how many tokens do I have left', 'what's my usage/balance/limit', or when a call fails on quota. It also instructs to report the remaining figure first, which is clear operational guidance.

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