AMZScout Skill + MCP

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 genuine context: it is a 'pure data fetch (no AI analysis)', it excludes sales/price/review figures, and notably that a call without marketplace silently fails with 'MARKETPLACE NEEDED'. That failure-mode disclosure is valuable; only return-format detail is left unstated.

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

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

It is front-loaded with what the tool returns and the key exclusion, then 'When to call' and 'How to use'. It is somewhat long and partly restates the schema (marketplace, sections default), but each block guides invocation rather than padding.

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 full annotation coverage, complete parameter schema, and no output schema, the description covers everything an agent needs: scope, exclusions, default behavior, marketplace gating, and output-usage guidance. Nothing material is missing for correct invocation.

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, and the description reinforces meaning: it clarifies the default (catalog + identifiers) and points to optional sections, and stresses the marketplace requirement with a failure consequence. Most of this overlaps the schema's own descriptions, so it earns a light bump rather than a top score.

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?

It names a specific resource (extra catalog facts about one Amazon ASIN) and explicitly contrasts its scope against the named sibling amzscout_analyze_product, listing both what it returns and what it explicitly does not (no sales/price/review numbers). An agent can differentiate it from the sibling without opening either schema.

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

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

It gives an explicit 'When to call' pairing rule (with amzscout_analyze_product for one specific product, same ASIN/marketplace) and default-vs-optional guidance for `sections` (omit by default; add relations/media/buybox only when the question needs them). Alternatives and conditions are spelled out rather than implied.

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 readOnly and non-destructive; the description adds substantive behavior beyond that by stating 'Pure data fetch (no AI analysis)' and explaining the interpretation semantics of aggregates like revenueTop5SharePercent. This meaningfully shapes agent expectations about what the tool will and won't do.

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 a minimal two-liner, but each clause earns its place: deliverable, no-AI caveat, and a decision framework. The most important information is front-loaded, though the 'How to use' section is dense enough to slightly reduce skimmability.

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 listing the aggregate categories the agent will consume and explaining how to reason over them. It could be more explicit about the exact response shape or product fields, but it provides enough for an agent to select and invoke the tool correctly.

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

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

The input schema already describes all 4 parameters with 100% coverage and details like marketplace enums, currency, ranges, and filter semantics. The description adds no parameter-level meaning beyond framing keyword as a niche, which is only lightly useful given the schema's completeness.

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 resource ('Amazon niche/keyword') and a concrete deliverable: a market snapshot with top products by revenue and computed aggregates. It also separates itself from analytic siblings by calling itself 'pure data fetch,' which clarifies its role versus compare/analyze 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 a clear invocation context—when you want a market snapshot for a niche/keyword—and a rich 'How to use' section for judging niche attractiveness. It does not explicitly name alternative tools or state when not to use it, so it stops short of full routing 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/destructiveHint/openWorld, so safety is covered; the description goes further by disclosing that it is a pure data fetch with no AI analysis, the failure mode without `marketplace` ('fetches nothing and answers MARKETPLACE NEEDED'), that history is only present 'when available', and that money is returned in local currency.

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

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

Front-loaded with the payload description, then usage, then the sibling/alternative, then the marketplace constraint. All sentences are informative, though the marketplace warning is repeated in both the description and the schema and the 'How to use' analyst narrative is somewhat expansive, keeping it short of a 5.

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

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

There is no output schema, and the description compensates by enumerating exactly what is returned and what is not. Combined with the sibling routing and the marketplace prerequisite, an agent has everything needed to call the tool correctly and interpret the result.

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 operational meaning for `marketplace`: ask the user once per conversation, reuse the code, never assume US, and the consequence of omitting it. This is largely a reinforcement of the schema text rather than net-new semantics, so it lands just above baseline.

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

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

States a specific verb and resource ('Full raw data for a single Amazon product by ASIN') and enumerates the exact payload (price, sales/revenue, reviews, rating, listing quality, sellers, history). It also explicitly carves out what this tool does NOT return and names the sibling that does (amzscout_advanced_product_data), so an agent can distinguish it from all siblings without opening a schema.

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

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

Gives explicit when-to-use guidance ('audit the product like a sourcing analyst' with the demand/pricing/competition/LQS lenses) and a clear when-not + alternative: listing facts are not here, use amzscout_advanced_product_data, and call both for the same ASIN. It also specifies the marketplace prerequisite and the ask-once-reuse 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?

Annotations already mark this as read-only and non-destructive, and the description adds valuable behavior beyond that: it is a pure data fetch with no AI analysis, it returns nothing and answers 'MARKETPLACE NEEDED' when marketplace is omitted, it requires asking the user once and reusing the marketplace code, and it states that monetary values are in the marketplace's local currency.

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 and front-loaded with the core purpose, then alternative routing, usage guidance, and marketplace behavior. It is somewhat long and includes strategic 'how to use' advice that goes beyond basic invocation needs, but each section earns its place and no information is buried.

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

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

There is no output schema, but the description compensates by enumerating the returned data categories: product rows plus computed aggregates including price, sales, revenue, review distributions, revenue concentration, and brand spread. It also covers the required parameter, error behavior, currency semantics, and the alternative tool, so an agent has enough context to call it correctly.

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

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

Schema description coverage is 100%, and both `asins` and `marketplace` already carry thorough descriptions in the schema. The tool description repeats the marketplace guidance and adds output-focused context, but does not materially add new parameter-level semantics beyond what the schema already provides.

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

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

The description clearly states a specific action: fetching raw data for an explicit set of 2–100 ASINs, including computed aggregates such as price/sales/revenue/review distributions and revenue concentration. It explicitly contrasts itself with analyzeNiche for keyword-based discovery, and the 'no AI analysis' clause further distinguishes it from analysis-style 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?

It says exactly when to use this tool versus an alternative: 'To discover products from a keyword instead, analyzeNiche is the equivalent.' It also provides concrete how-to guidance about treating the ASIN set as a mini-market, segmenting products, spotting demand concentration, and flagging outliers, making the invocation context unmistakable.

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 context that this is a pure data fetch with no AI analysis, going slightly beyond annotations. It does not mention auth or rate limits, but the readOnly annotation covers the primary safety concern. No contradiction.

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

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

Four sentences with no filler. The purpose is front-loaded, followed by the no-AI-analysis clarification, the sibling alternative, and a 'How to use' guidance. The guidance is slightly verbose but adds interpretive value, so the structure earns a 4.

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 provides a reasonable summary of return content (per-niche product sets plus aggregates like price/sales/revenue distributions, revenue concentration, brand spread). It also explains how to interpret the data for a verdict, which is helpful for an agent calling the tool.

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

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

Schema description coverage is 100%, so the baseline is 3. The description reinforces the keywords count (2–5 niches) and refers to per-niche product sets, which aligns with the count parameter, but it does not add meaning beyond what the schema already provides.

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

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

The description clearly states the tool compares 2–5 Amazon niches/category keywords and returns per-niche product sets plus computed aggregates. It explicitly distinguishes itself from compare_products by noting that tool is for ASINs, which helps an agent route correctly.

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 an explicit alternative for ASINs ('For ASINs, compareProducts is the equivalent') and implies when to use this tool via 'Pure data fetch (no AI analysis) — do the comparison yourself.' This is clear context, though it doesn't enumerate other siblings like analyze_niche for single-niche 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?

Even though readOnlyHint and destructiveHint annotations already cover safety, the description adds meaningful behavioral detail: it is a pure data fetch with no AI analysis, it fetches nothing and returns 'MARKETPLACE NEEDED' without a marketplace, money is in local currency, and 0/O-swapped ASIN prefixes are auto-corrected. This goes well beyond the annotations and helps the agent set expectations.

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 every section earns its place: purpose, single-ASIN alternative, usage recipe, and marketplace protocol. It is front-loaded with the core purpose, though there is some redundancy with the schema's marketplace enum and 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?

With no output schema, the description does a good job of describing what the agent will receive: raw data with price, sales/revenue estimates, reviews, listing quality, and history when available. It also covers the required marketplace input, the no-AI-analysis boundary, and the follow-up analytical steps, making the tool fully usable without external context.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds value beyond the schema: it clarifies that marketplace is conversation-scoped and must be reused, that omitting it yields no data, and that prices are in the marketplace's local currency. The ASIN auto-correction detail also enriches the schema's plain description.

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 resource and action: side-by-side raw data for 2–5 Amazon products by ASIN, covering price, sales/revenue, reviews, and listing quality. It explicitly differentiates from the single-ASIN tool by naming analyzeProduct as the equivalent. The scope and exact input are 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?

It tells the agent exactly when to use this tool (comparing 2–5 ASINs) and when not to (single ASIN → analyzeProduct). It also gives a crisp usage recipe: compare sales, revenue, review moat, rating, price positioning, listing quality, and history trends, then deliver a verdict. The marketplace-ask-once instruction is actionable and prevents a common 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, destructiveHint=false, and openWorldHint=true. The description adds meaningful behavioral details beyond those: the brand is pre-validated via a cached AI check, results are post-filtered to actual `brand` matches, and on no-match the tool returns brands that did appear in the keyword pool. This extra context helps an agent predict edge-case behavior.

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 cover the core action, the internal validation/filtering behavior, the no-match fallback, and the intended analytical use. The most important information is front-loaded in the first sentence, and every sentence serves a distinct purpose. There is no redundant or filler text.

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 moderate complexity — nested `filters`, multiple enums, and no output schema — the description covers the key contextual points an agent needs: the core listing action, the validation process, and the no-match fallback. It does not describe the full return shape, but the schema already covers parameters, and the description offers enough behavioral context to invoke and interpret the tool confidently.

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 high at 80%, so the schema already documents parameters like `brand`, `sort`, `count`, `filters`, and `marketplace` in detail. The description does not add parameter-level semantics beyond mentioning that rows are filtered by the `brand` field. With high schema coverage, the baseline score of 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 opens with a specific verb and resource: 'List products under a specific Amazon brand.' It further differentiates the tool by describing its internal behavior: pre-validating the brand and filtering keyword-search results to rows whose `brand` field matches. This makes it clear how it differs from a general keyword product search or niche 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 usage context with 'How to use: assess the brand's Amazon footprint — lineup breadth, price range, which products carry the revenue, and how strong its review moat is.' It does not explicitly name alternatives or when-not-to-use conditions, but the intended analytical scenario is clear. The no-match fallback also guides callers on what to do when the brand is absent from the pool.

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

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

Annotations cover the safety profile (readOnly), but the description adds substantial behavioral context: the exact-match row semantics, the look-alike caveat, and critically that omitting `marketplace` fetches nothing and returns 'MARKETPLACE NEEDED'. It also discloses the local-currency behavior of monetary fields.

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

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

The core mode distinction is front-loaded and every sentence carries information given the tool's dual-mode complexity. It is on the long side and the marketplace requirement is restated in both description and schema, costing some tightness.

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-shape burden and does so: keyword rows carry search volume, average sales, CPC and trend; ASIN-scope rows add organic rank/page, sponsored page, and relevance score. Nothing an agent needs to call it correctly 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 schema descriptions are already detailed, so the baseline is 3. The description adds genuine meaning beyond the schema by explaining the combined asin+keyword exact-match behavior and the 'never report a look-alike's rank' constraint, which the schema does not convey.

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

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

States a specific verb (fetch keyword/SEO/PPC data) and resource, and crisply distinguishes its two operating modes (ASIN-scope vs keyword-scope) plus the both-params case. An agent can tell exactly what this returns versus sibling analyze_* 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?

Explicit when-to-use guidance: how to select high-volume/low-competition terms, use CPC for ad-cost pressure, sum volumes for niche demand, and check organic vs sponsored ranks for ASIN-scope. It also contrasts itself as a 'pure data fetch (no AI analysis)' against analysis siblings, and gives the marketplace ask-once-then-reuse rule.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false; the description adds material context beyond that: token cost per marketplace per ASIN (1 000 tokens each, 14 000 per ASIN), the per-marketplace return shape (title, local-currency price, estimated monthly sales), and the recommended output presentation. This is exactly the kind of behavioral disclosure the rubric rewards.

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

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

Front-loaded with the core purpose, then the marketplace list, return fields, cost, and usage rules. The marketplace enumeration and cost warning are long but each earns its place: the cost information changes agent behavior, and the do-not-call rule prevents expensive misuse. No filler sentences.

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

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

No output schema exists, so the description carries the burden of explaining return values — and it does: 'title, price in that marketplace's local currency, estimated monthly sales' plus the presentation format '(country, link, local price, sales)'. Combined with cost, usage restrictions, and sibling routing, nothing an agent needs to invoke this correctly 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 schema already specifies '1–5 ASINs to locate (B0 + 8 characters). Pass several only when they will be analyzed together.' The description adds value by explaining the per-ASIN cost scaling and that multiple ASINs are checked across all marketplaces, which informs how many the agent should pass. Slight overlap with the schema keeps this at a 4 rather than 5.

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

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

States a specific verb and resource: 'Find which Amazon marketplaces list an ASIN, and get its product link on every marketplace.' It enumerates the 14 covered marketplaces, describes the returned fields, and differentiates itself from siblings by naming amzscout_analyze_product / amzscout_get_keywords as the downstream tools for analysis, so an agent can distinguish it without opening other 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 states when to call it ('ONLY when the user asks where / on which Amazon marketplaces a product is sold'), when NOT to call it ('Do NOT call it just to choose a marketplace for analysis'), gives the alternative behavior (ask the user once and reuse the marketplace), and routes follow-up to specific sibling tools. This is model 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 declare readOnlyHint=true and destructiveHint=false, so the safety profile is already known. The description adds that it returns a catalog with tracking links, which is a useful behavioral detail beyond the annotations. 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?

Two sentences with no redundancy. The main action and purpose are front-loaded, and the usage guideline is a single clear sentence. Every word 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 simple tool with one parameter and read-only annotations, the description covers the essential context: what it does, when to use it, and that it returns a catalog with tracking links. The output format is not detailed, but given the absence of an output schema and the tool's simplicity, this is acceptable.

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% (the sole parameter 'useCase' is described with an example). The description adds no new information about the parameter beyond what the schema already provides. The description's 'Given a user use-case' mirrors the schema, so it meets the baseline for high coverage.

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

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

The description states a specific verb ('returns') and resource (the AMZScout tools & Sellerhook services catalog) and explicitly frames its purpose as recommending the right product/feature. It also distinguishes itself from sibling analysis/search tools by clarifying it handles 'which tool' questions.

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 an explicit trigger condition: 'Use for "which AMZScout tool should I use for X" questions.' This is clear when-to-use guidance, though it does not explicitly list when-not-to-use or name alternative tools. The sibling tools are implied as the alternatives for actual analysis, but the description doesn't make that contrast explicit.

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 reinforces this with 'Pure data fetch (no AI analysis).' Beyond that, it discloses two important behaviors the annotations cannot express: calling without `marketplace` fetches nothing and returns "MARKETPLACE NEEDED", and calling without `sections` returns a summary plus a list of which sections hold data. The 'several KB of detail you will rarely need' warning about requesting all six sections is genuinely additive context.

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

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

The description is long but not padded: core function and contents are front-loaded, followed by purpose differentiation, the sections call-pattern warning, interpretation guidance, and the marketplace rule. Every sentence carries operational value for a tool with two optional parameters and no output schema, though it could be tightened slightly without losing 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?

For a data-fetch tool with no output schema, the description is complete: it enumerates the response contents in detail, explains the default summary behavior and how to discover available sections, states the marketplace requirement and its failure mode, and notes that money is in the marketplace's local currency. Nothing an agent needs for a correct first call is missing.

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

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

Schema coverage is 100%, so the baseline is 3 — the schema already documents asin, sections, and marketplace well. The description adds practical semantics above that baseline: `sections` should be omitted first and requested only when the summary is insufficient, and `marketplace` must be the user-named code reused across the conversation with the failure mode spelled out. This exceeds what the schema alone conveys.

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 — fetching buy box, competing offers, and price/rank statistics for a single Amazon ASIN — and enumerates the exact data returned (FBA vs FBM counts, price levels, out-of-stock share, ownership history). It also distinguishes itself from siblings explicitly: 'for demand and revenue estimates use analyzeProduct instead.' An agent can tell this apart from the 12 siblings without inspecting schemas.

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

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

Explicitly scopes the tool to reseller/online-arbitrage questions and excludes private-label research with a named alternative. It adds concrete interpretation guidance (buy box held by Amazon or one seller means little room, many FBA offers means price competition, high out-of-stock share means supply gaps) and a precise marketplace protocol: ask once, reuse the code for every later call, never assume 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?

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds meaningful behavioral detail beyond that: it reveals the TF-IDF retrieval mechanism, that results are relevance-ranked chunks, and that each result includes title, source URL, and text. 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?

Two tightly scoped sentences with no filler. The search target and result fields are stated first, and the usage directive is a clear closing instruction. 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 simple two-parameter read-only search tool with no output schema, the description is complete: it names the resource, the search mechanism, the result contents, and the intended use. An agent has enough information to invoke it appropriately and interpret 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%, with both 'query' and 'topK' already documented. The description adds context that 'top-K' refers to returned chunks SubstituteScore and implies the query is the search phrase, but it does not need to do much more because the schema carries the parameter meaning.

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 retrieval method (TF-IDF search), a distinct resource (AMZScout knowledge base), and the return shape (top-K chunks with title, source URL, text). This clearly distinguishes it from sibling tools that analyze products, niches, or keywords.

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 instruction 'Use this to ground answers in factual material' gives a clear context for when to invoke this tool. It does not explicitly name alternatives or provide when-not-to-use guidance, but the knowledge-base purpose is evident against the analytical siblings.

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

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

Annotations already establish readOnlyHint=true and destructiveHint=false. The description adds useful behavioral context beyond those: 'Pure data fetch (no AI analysis)' and that results are raw product rows rather than analyzed insights. It does not go deep into output shape or pagination, but the safety profile is already covered by annotations.

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

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

Three sentences, each earning its place: the function, the use-case/alternative, and a practical how-to-use signal. The most important information is front-loaded and there is no redundancy with the schema or annotations.

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

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

Given the detailed schema, safety annotations, and no output schema, the description gives enough to understand what the tool returns and when to invoke it. It also explains how to interpret results for opportunity signals. Marginally less complete than ideal only because it doesn't address result-shape expectations beyond the listed metrics, but the schema carries the remaining burden.

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

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

Schema description coverage is 100%, so the schema fully documents all 5 parameters and nested filters. The description adds no parameter-level meaning beyond pointing at 'specific sort order or filters,' which is already visible in the schema. 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 and resource: 'Keyword search against Amazon — returns the top N products with price, sales, revenue, reviews, rating.' It also distinguishes itself from analyzeNiche by clarifying it provides raw rows rather than AI analysis, so an agent can differentiate it from the closest 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 explicitly says when to use this tool: 'Best when you need raw product rows (specific sort order or filters).' It also names the alternative, analyzeNiche, and explains the condition that selects it: when computed market aggregates are also needed. This is clear routing 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 destructiveHint=false, so the read-only nature is known. The description adds extra behavioral context: the call is free (no tokens charged) and instructs the agent to report the remaining figure first. This goes beyond annotations and helps the agent respond correctly.

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 concise sentences, front-loaded with the core purpose, and includes usage triggers and reporting order without any wasted words. 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 simple, parameterless, read-only tool, the description fully covers purpose, usage scenarios, and even the free/charge-free aspect. There is no output schema, but the description explains the content (remaining, used, limit) and the reporting preference, making it complete for an agent to call correctly.

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

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

The tool has zero parameters, so the schema fully covers parameter definitions (trivially). The description clarifies what the tool reports — remaining, used, and limit — which adds semantic meaning about the return content beyond the empty schema. Baseline for 0 params is 4, and the description meets it.

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

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

The description clearly states the tool returns the caller's token balance — remaining, used, and limit — and explicitly names the resource ('AMZScout AI-agents token balance'). It is obviously distinct from sibling analysis/search tools, which are all about niche, product, or keyword 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 provides explicit trigger conditions: answering 'how many tokens do I have left', 'what's my usage / balance / limit', or when a call fails on quota. This gives clear when-to-use guidance and implicitly differentiates from all sibling tools, none of which handle token usage.

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