amazon-product-research-mcp

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

Beyond the readOnlyHint annotation, the description discloses that the source is Serper, that results are text-only without price or photos, and that the user must click through to Alibaba for full details. This adds useful behavioral 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 concise at about 50 words, with the main action front-loaded and limitations clearly stated. No superfluous information.

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

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

Given the simplicity (1 param, no output schema), the description covers the essential inputs and outputs. It could be slightly improved by mentioning that the result is a list, but it is adequately complete.

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

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

The description adds meaning to the 'query' parameter by suggesting it should be a product/OEM query and brand-free for private label. This goes beyond the schema description which covers 100% due to single 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 verb 'Find' and the resource 'Alibaba supplier / manufacturer listings'. It specifies the input (query) and output (title, rating, snippet, link). The tool's purpose is distinct from siblings, as confirmed by the sibling list.

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

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

The description does not provide any guidance on when to use this tool versus alternatives like 'search_products' or 'web_search'. It lacks explicit when-to-use or when-not-to-use instructions.

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 adds significant behavioral detail beyond the readOnlyHint annotation: it describes the per-week breakdown, the monthly seller_count_monthly series, the seller_trend label, and additional product attributes (brand, title, price, fulfillment). This is rich context for a read-only tool. It does not cover edge cases like missing data or exact date boundaries, but the core behavior is well disclosed.

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

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

The description is well-structured: opening purpose, then return details, then usage examples. It is slightly longer than necessary but every sentence carries useful information. It earns a 4 rather than 5 because it could be tightened 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?

Given the tool's complexity (27 parameters, no output schema), the description gives a good high-level overview of return values and use cases, but it leaves many gaps. It does not explain the role of the many filter parameters, default time ranges for the weekly breakdown, or the exact structure of the returned data. An output schema or further parameter documentation would be needed for full completeness.

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 only 30%, and the description does not compensate. It mentions output fields but explains none of the 27 parameters (e.g., max_price, since_weeks, fulfillment_in). The only parameter context comes from the schema's sparse descriptions, which is insufficient for such a parameter-heavy tool.

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

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

The description clearly states the tool shows which sellers won the buybox over time and how the seller pool changed month over month. It is specific and names the resource (ASIN), but it does not explicitly distinguish itself from sibling tools like buybox_loss_alert or brand_buybox_trajectory, so it misses the full 'distinguishes from siblings' bar.

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 'Use when' guidance with multiple example queries (e.g., 'who has been winning buybox on this ASIN', 'seller rotation'), which clearly indicates when to invoke this tool. However, it does not mention when not to use it or name alternatives, so it stops short of a 5.

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

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

Annotations only provide readOnlyHint=true, so the description adds useful context by detailing what each comparable carries (product brand, title, price/range, fulfillment) and the matching criteria (brand, price band, seller count). This goes beyond the annotation without contradiction.

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

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

Three concise sentences: purpose, usage triggers, and return fields. No fluff, front-loaded with the core function, and 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 19-parameter tool with no output schema, the description provides a solid overview of behavior and return content, and the schema covers parameter types and some descriptions. It doesn't enumerate every filter, but the combination is sufficient for an agent to select and invoke the tool appropriately.

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 low (32%), so the description needs to compensate. It mentions the core dimensions (brand, price band, seller count) that map to several parameters, but leaves the many other filters (fulfillment, marketplace, days observed, etc.) unexplained. The parameter names are somewhat self-explanatory, but the description does not fully bridge the coverage gap.

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: 'Find ASINs similar to a given ASIN by brand, price band, and seller count.' It clearly distinguishes from siblings by emphasizing 'ASIN-level lookalike' and providing example queries, setting it apart from brand-level operations like 'brand_similar'.

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 the tool with direct user-phrase examples: 'Use when the user asks "ASINs like this one", "similar products", "comparable ASINs", ...' It offers clear context but does not explicitly mention when not to use it or list alternative tools, stopping just short of a full 5.

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

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

Annotations include readOnlyHint: true, covering safety. The description adds meaningful context beyond annotations by explaining the estimation logic (based on buybox price, fees) and detailing the return data (brand, title, price/price range, fulfillment breakdown), which is helpful for setting 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 concise and well-structured: two sentences. The first sentence states the core function, and the second provides usage triggers and output summary. No redundant words or filler, making it easy to parse.

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

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

Given there is no output schema, the description compensates by specifying the returned fields (brand, title, price/price range, fulfillment percentages). It also clarifies the estimation goal. It lacks exact output structure or error behavior, but for a read-only calculation tool, it is sufficiently 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?

The input schema already has 100% coverage with detailed descriptions for all parameters (asin, cogs, marketplace_id, target_margin_pct). The description mentions some conceptual inputs (buybox price, fees) but does not add specific parameter-level semantics beyond the schema, so it provides minimal added value.

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

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

The description clearly states the tool's purpose: 'Estimate whether an ASIN can hit a target profit margin' given specific inputs (buybox price, FBA fees, referral fee). It also lists additional outputs (brand, title, price, fulfillment), distinguishing it from sibling tools focused on other ASIN analyses.

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 usage triggers with concrete query examples ('can I make money on this ASIN', 'profit calculator', 'margin estimate for B08N5WRWNW'), effectively telling when to use the tool. However, it does not mention when not to use it or name alternative tools, so it falls short of a full 5.

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

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

Annotations already declare readOnlyHint=true, so the tool's safe read-only nature is covered. The description adds minimal behavioral context beyond purpose, such as 'saved' sellers, but does not disclose return format, pagination, or any edge case behavior. This is consistent with the annotation and adds a bit of nuance, but not significantly more than what annotations provide.

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 extremely concise: two sentences. The first states the purpose, and the second provides concrete example user queries. No wasted words or redundant details.

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 list tool with only three parameters and no output schema, the info is complete. The tool description, combined with schema and annotations, gives enough context for correct use. No additional return value documentation 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?

Schema description coverage is 100% — each parameter (brand, marketplace_id, seller_contains) has a description that fully explains its purpose and values. The tool description itself does not add extra 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 states the tool's function: 'List the saved authorized sellers for a brand.' This uses a specific verb ('List') and resource ('saved authorized sellers'), and the example queries reinforce its scope. It also distinguishes from sibling tools like authorized_seller_set and unauthorized_sellers.

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

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

The description explicitly tells when to use it with example user phrasings ('who are my authorized sellers for X', 'show my approved resellers', 'what's my whitelist for this brand'). It does not explicitly state when not to use or name alternatives, but the context is clear enough for a simple list 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 only indicate readOnlyHint=false, so the description adds value by specifying that sellers must be passed exactly as they appear on Amazon and that the brand must be owned/managed. It does not detail overwrite-vs-append semantics, which is a minor gap.

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

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

The description is three sentences, front-loaded with the primary action. Every sentence provides useful information without redundancy or unnecessary detail.

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

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

The description covers purpose, usage examples, prerequisites, and input formatting. It lacks explicit mention of return behavior or whether the list is replaced or appended, but for a simple write operation with no output schema, 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 parameter descriptions are already present. The description adds extra nuance by requiring seller names to match Amazon exactly and clarifying the brand ownership condition, which goes beyond the schema.

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

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

The description uses the specific verb 'Save' with the resource 'authorized sellers for a brand', clearly establishing the tool's purpose. It explicitly connects to the whitelist for unauthorized-seller detection and distinguishes from sibling tools like 'authorized_seller_list' by focusing on the save/set action.

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 usage triggers with example user phrases and states a prerequisite (brand must already be tracked). It does not explicitly name alternatives or exclusions, but the examples make the intended scenario 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 discloses that the tool returns weekly seller counts and observed buybox days for a trailing window, adding value beyond the readOnlyHint annotation. It doesn't go into detail about filtering behavior or edge cases, but the annotation already signals a safe read operation, and this context is adequate.

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: purpose, output, and usage triggers. Every sentence earns its place, with no filler or repetition. It is front-loaded with the core action and output, making it efficient for an agent to parse.

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 (16 parameters, low schema coverage, no output schema), the description provides enough for selection and basic invocation (brand is required, output is described). However, it omits details about optional filters, default behavior, and response structure, which could leave an agent uncertain when constructing calls with non-default parameters.

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

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

Schema description coverage is only 38%, and the description does not compensate. It implies the 'brand' parameter via examples but does not explain any of the 16 parameters, the meaning of filter options, or the behavior of trend_in. The description adds no 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 the tool's purpose: showing how a brand's buybox concentration has changed over time, and specifies the output (weekly seller counts and observed buybox days). It uses a specific verb (Show) and resource (brand's buybox concentration), distinguishing it from sibling tools like asin_buybox_history or brands_gaining_sellers.

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 phrases ('is this brand getting more competitive', 'concentration trend for Nike', etc.) and a clear usage context. It does not mention exclusions or alternative tools, but the guidance is sufficient for an agent to route queries appropriately.

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 covers the safety profile, and the description adds useful behavioral context: it states that each ASIN carries brand, title, price/range, and fulfillment metrics. This goes beyond the annotation by describing output content, though it doesn't discuss pagination or default ordering, so a 4 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?

The description is three sentences with no fluff. It front-loads the main verb ('Show'), then gives usage trigger examples, then specifies return fields. Every sentence earns its place, making it highly concise and 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?

Given the high parameter count (26) and lack of output schema, the description is far from complete. It covers the core purpose and a few output fields, but leaves the vast majority of filtering nuances unexplained. An agent cannot fully understand the tool's capabilities from this description alone.

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 only 31%, leaving most of the 26 parameters undocumented. The description offers only vague hints about recency and price range, and does not explain key filters like min_price, max_seller_count, or fulfillment_in. The description fails to compensate for the schema's low 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 tool's function: 'Show ASINs that recently appeared for a brand.' It provides concrete example queries like 'new products for Nike' and 'recently added ASINs', which distinguishes it from sibling tools like brand_buybox_trajectory that track historical trends rather than new listings.

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 triggers are provided: 'Use when the user asks...' with several concrete examples. This gives strong contextual guidance for when to invoke the tool. It does not mention alternatives or when-not-to-use, but the clarity of the trigger phrases earns a 4.

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 only declare readOnlyHint=true; the description adds essential behavioral context that the 'new sellers' metric is an observation signal, not confirmed entry, due to sparse re-sampling. This prevents misinterpretation of results, though it does not cover output format or pagination.

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 single dense sentence with a parenthetical caveat and a list of use cases. It packs substantial meaning without fluff, though the long first sentence could be easier to parse.

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 17 parameters, no output schema, and minimal annotations, the description should cover return shape, filter interactions, and defaults. It explains the core purpose and the key caveat, but leaves many operational details unspecified, making it incomplete for a complex 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 only 35%, so the description should compensate by explaining many of the 17 parameters. It only references the category filter and implies a brand parameter, while leaving control_score, churn percentages, and count bounds unexplained. This is a significant gap.

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 finds brands that recently gained the most newly-OBSERVED sellers, defining the precise signal. It distinguishes this from confirmed market entry and from brand-specific tools by specifying category-scoped seller-growth signals.

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 enumerates example user queries ('brands gaining sellers in [category]', 'brands under hijacker pressure', etc.) and states 'Use when...' for category-scoped signals without a specific brand. It also warns that the signal is NOT confirmed market entry, helping agents decide when this tool is appropriate.

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 include readOnlyHint=true, so the description does not need to restate safety. It adds the selection criteria (category, price tier, competition level) but does not disclose output format, result limits, or other behavioral traits. This is consistent with the baseline for a read-only tool with light additional 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 two sentences, front-loads the core function, and the usage examples are concise. Every sentence contributes meaning, with no filler or redundancy.

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

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

Given the tool has 14 parameters, no output schema, and low schema coverage (29%), the description is incomplete. It fails to explain return values, parameter usage, or operational constraints, leaving significant gaps for an agent to 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?

Schema description coverage is only 29%, and the description does not explain the many filter parameters like min_asin_count, max_control_score, min_seller_count, etc. The phrase 'by category, price tier, and competition level' loosely maps to some parameters but does not provide the detailed semantics needed to use the 14-parameter input effectively.

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: 'Find brands similar to a given brand by category, price tier, and competition level.' This uses a specific verb (find) and resource (similar brands), and the example queries like 'brands like Nike' and 'what else is in this niche' distinguish it from sibling tools such as competitive_landscape or asin_comparables.

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 usage triggers: 'Use when the user asks 'brands like Nike', 'similar brands to source', ... or any cohort/lookalike question.' This clearly communicates when to use the tool. However, it does not mention alternatives or when not to use it, missing the full when/when-not contrast.

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 signals a safe read operation. The description adds behavioral context by explaining the ranking basis ('ranked by how many operators they share') and the conceptual graph ('operator graph'), which is useful beyond the annotation. It does not go into data freshness, pagination, or output limits, but the annotation lowers the burden and no contradiction exists.

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

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

The description is front-loaded with the core action and result, followed by usage examples and a brief conceptual statement. The quoted example phrases are somewhat repetitive and could be condensed, but every sentence contributes useful context, so it remains concise 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?

This is a complex tool with 12 parameters, no output schema, and only readOnlyHint as annotation. The description explains the high-level purpose and returns ranking concept, but it omits the semantics of most optional filters and does not describe the output structure or field details. Given the low schema coverage and lack of output schema, the description is not complete enough for an agent to confidently use the tool beyond simple queries.

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 only 33%, with 8 numeric filter parameters (control_score, observed_buybox_days, seller_count, shared_operators, limit) lacking descriptions in both schema and tool description. The description does not explain what these filters mean or how they interact, and it only weakly clarifies the 'shared operators' concept. This is insufficient for an agent to correctly construct parameter values.

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 uses a specific verb ('Find') and resource ('brands that share operators/sellers'), clearly stating what the tool does and how results are ranked. It distinguishes itself from siblings like brand_similar or operator_top_brands by framing the output around shared operators/sellers in a network, with concrete example queries.

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 and explicit usage contexts with example user phrasings ('what brands are in X's network?', 'brand family'), which helps an agent know when to invoke it. However, it does not mention when not to use it or explicitly point to alternatives, so it misses the full when-not/alternative 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 valuable methodological context: it uses brand-level first-seen to avoid scraper-coverage inflation. This goes beyond the annotations, though it does not describe output format 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?

Three focused sentences with no redundancy. The usage triggers are compact, and the methodology explanation is dense but clear. 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 detection tool with five parameters and no output schema, the description adequately covers core algorithm, use cases, and context. It lacks sample output or return-value details, but the detection purpose is well conveyed.

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 descriptions cover all parameters (100% coverage), so the baseline is 3. The description adds no parameter-specific details beyond the schema, but it frames the key concept (brand-level new-entrant rate) which indirectly informs the signals_in 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 identifies the tool as a detector of competitive brand attacks, using specific metrics (new-entrant rate + buy-box churn). It distinguishes itself from siblings like brand_buybox_trajectory and buybox_loss_alert by naming the exact detection logic.

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

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

It provides explicit user-phrase triggers ('is my brand being targeted', 'new sellers flooding my listings', etc.), which is clear when-to-use guidance. However, it does not mention alternatives or when not to use, so it stops short of a full 5.

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

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

Annotations indicate readOnlyHint=true, and the description confirms read-only behavior by describing a 'check' operation. It adds specific return fields, enhancing transparency about what the tool provides.

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 note, front-loaded with purpose and examples. Every sentence is essential, no waste.

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

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

The tool has 10 parameters and no output schema, yet the description does not specify the return structure (e.g., per-marketplace object) or explain the filter parameters. This leaves the agent with significant gaps in understanding how to invoke the tool and interpret results.

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 only 20%. The description only explains the brand parameter implicitly and marketplace_id_in vaguely, while the other 8 parameters (min/max filters) are left unexplained, despite low schema coverage requiring more 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 the tool checks brand presence on three specific marketplaces and lists the return metrics. It also provides example queries, 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 explicitly says when to use with example questions, but does not mention when not to use or differentiate from similar sibling tools like operator_xmarket_presence.

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 that results are ranked by estimated revenue at stake and that each ASIN includes brand, title, price, and fulfillment type. It also explains the fallback behavior when no authorized list is saved, which adds transparency.

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 packs essential information — purpose, ranking logic, output fields, prerequisite, and example queries — into three sentences with no filler. It is front-loaded with the most important action and differentiator.

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

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

For a tool with 26 parameters and no output schema, the description covers the primary purpose, output contents, ranking behavior, fallback logic, and usage triggers. It falls short of explaining all parameter interactions or return pagination, but given the tool's complexity, it provides enough context for selection and basic 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?

With only 27% schema description coverage, the description partially compensates by explaining the core 'brand' parameter and the notion of authorized sellers, and by defining the 'estimated revenue' metric. However, the numerous filter parameters (e.g., min/max thresholds) remain underexplained, leaving the agent to infer their 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 opens with a specific verb ('Find') and a clearly defined resource ('ASINs where a brand you own has LOST the buy box to a seller outside your authorized list'), and immediately distinguishes itself from sibling tools by focusing on unauthorized loss and revenue-based ranking.

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 the tool with example user queries ('where am I losing the buy box on <brand>', 'buy-box loss on my ASINs') and provides a prerequisite (save authorized list first). It does not explicitly discuss alternatives or exclusions, but the guidance is otherwise 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?

Annotations already provide readOnlyHint=true, so safety is covered. The description adds the ordering behavior and the meaning of 'retreating', which is useful context. However, it does not disclose any other behavioral traits such as how 'retreat magnitude' is computed, default marketplaces, or output structure beyond 'returns categories'.

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, front-loads the purpose, and then quickly gives the definition and usage triggers. Every sentence earns its place, with no fluff or repetition.

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 15 parameters and no output schema, the description gives the core concept and intended use but lacks detail about what the returned data includes and how the many filters interact with the retreat concept. It is adequate for a simple use case but not fully complete for a tool of this complexity.

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

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

Schema description coverage is only 27%, so the description must compensate. It explains the core metric ('amazon_expansion_net_90d < 0') but does not describe the many filter parameters (e.g., max_asin_count, min_brand_count, category_name_contains, etc.). This leaves most parameters unexplained, offering little added value over the sparse 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 uses a specific verb ('Find categories where Amazon is retreating') and defines the exact criterion (net brand exits exceed entries over 90 days, with the metric amazon_expansion_net_90d < 0). It also states the output ordering (by retreat magnitude), which clearly differentiates it from sibling tools like category_top_growers or category_new_entrants.

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 trigger phrases: 'where is Amazon pulling back?', 'which categories is Amazon leaving?', or 'Amazon retreat opportunities'. This gives clear context for when to use the tool, though it does not mention when not to use it or name alternatives.

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

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

Beyond the readOnlyHint annotation, the description details the metric groups (demand, competition, Amazon presence, price, ship-by, close-outs) and notes the tool works at any category depth. This adds meaningful behavioral context without contradicting the read-only 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?

Two sentences, front-loaded with the core purpose, followed by a concise metric breakdown and usage examples. Every sentence earns its place with no 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?

The description compensates well for the lack of an output schema by listing metric groups and usage scenarios. It does not specify the exact return format or behavior when no category identifier is provided, but overall it is a complete enough guide for a read-only metrics 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% with each parameter described. The description adds the 'one category' constraint and example niche but does not clarify mutual exclusivity of category_id/category_name or behavior when neither is provided. It adds minimal value beyond the schema.

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

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

The description clearly states the tool returns the full metric set for a single category, with a specific verb ('Return') and resource ('ONE category'). It enumerates the metric groups covered, which distinguishes it from sibling tools that focus on specific category lists like category_new_entrants.

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 usage examples like 'show me the metrics/stats for category X' and 'how big is the X category', giving clear context for when to use it. It implies a single-category scope but does not explicitly name alternative tools or state when not 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 only declare readOnlyHint, which the description aligns with. It adds substantial behavioral context about the daily sampling methodology and the risk of false positives due to sparse re-sampling, which is critical for interpreting results and goes beyond the structured 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 two sentences, front-loaded with the core purpose and a crucial caveat, followed by concrete usage examples. There is no redundancy or filler; 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?

The description covers the essential purpose, usage, and caveats well, making the core functionality clear. However, given the 17-parameter schema and no output schema, it leaves some gaps such as whether a category is required (schema shows 0 required) and how filters like price or ASIN count combine with the core query. These are not critical for basic use but would be helpful for advanced invocations.

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 low (35%), and the tool description does not compensate. It only references the date-window concept and category name in examples, leaving many parameters like min_avg_price, max_asin_count, and first_observed_to unexplained. The description adds little semantic value over the sparse 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 finds brands newly observed in a category based on the first-observed date window, and explicitly distinguishes it from confirmed first-ever entry. It provides concrete query examples ('new brands in Electronics', 'what brands just entered this category'), making the purpose immediately understandable and differentiating it from sibling tools like brand_new_asins.

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 gives when-to-use examples and clarifies the tool's limitation ('An observation signal, NOT confirmed first-ever entry'), which helps an agent decide when to use it. However, it does not name alternative tools or provide direct 'when-not-to-use' guidance for tool selection, relying instead on the semantic caveat.

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=true annotation already covers safety. The description adds context that growth is measured by both seller count and observations, and that it is category-scoped. No additional behavioral traits (e.g., rate limits, required inputs) are disclosed, but for a read-only tool this is adequate.

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: the first states purpose, the second gives usage examples. It is front-loaded, efficient, and contains no filler.

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

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

With 19 optional parameters and no output schema, the description lacks critical guidance on how to specify the category (category_id vs category_name), default marketplace behavior, parameter interactions, or what the response contains. The examples help but are insufficient for advanced use.

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 only 26%, so the description must compensate. It does not explain the many filter parameters (e.g., limit, thresholds, min/max sellers, observations) or how to specify the category beyond 'category-scoped.' The example queries imply category_name usage but leave most parameters undocumented.

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 it 'Find brands in a category with the biggest recent growth in seller count and observations,' which is a specific verb+resource+scope. It also includes example queries that clarify the intended usage and differentiate from non-category-scoped brand 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 explicit usage context with example user phrasings and states 'any category-scoped growth question.' However, it does not mention alternatives or when not to use this tool, so it falls short of full 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 set readOnlyHint=true, so the safety profile is already disclosed. The description adds behavioral context by explaining that the min-seller floor drops single-seller or brand-owner-only listings, and clarifies that the tool returns brands, not niches. Though the min-seller explanation partially duplicates the schema's min_sellers description, the explicit output type and exclusion of subcategories are non-obvious and useful.

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

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

The description is well-structured and efficient: it states the core purpose in the first sentence, the output type and key mechanism in the second, and then provides concrete example queries and an explicit negative boundary. Every sentence earns its place, and the structure is easy to scan for an AI agent.

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?

While the description covers the primary purpose and usage, it does not address the many optional filters (e.g., control score, velocity, ASIN counts) or the return format (no output schema exists). For a tool with 17 optional parameters and no output schema, the description is only moderately complete—it would benefit from a brief note that additional filters exist and a description of the response structure.

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 only 53%, leaving 8 of 17 parameters (limit, brand_contains, max_asin_count, min_asin_count, max_velocity_90d, min_velocity_90d, max_control_score, min_control_score) undocumented in both schema and description. The description does not compensate for these gaps; it only explains the min_sellers behavior already present in the schema. This leaves an agent without meaningful guidance for several filter 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 clearly states the tool's function: 'Find specific BRANDS within a category that have proven multi-seller demand but are still under-competed'. It names the resource (brands in a category) and the specific filter logic (min-seller floor). It also explicitly differentiates from niches and subcategories, and references sibling tool find_underserved_niches, 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 explicit usage guidance: 'Use for "undercompeted brands in <category>"...' and 'Do NOT use for...' with a named alternative tool (find_underserved_niches). This gives clear when-to-use and when-not-to-use instructions, fulfilling the dimension fully.

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 only include readOnlyHint:false, giving little safety context. The description adds useful behavioral details such as it returns live offers, sellers, and historical intelligence, and enforces one ASIN per call. However, it does not disclose potential side effects (e.g., whether it triggers a collection job) or latency, which would be valuable given the false 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 two sentences long and front-loaded with the core action. It contains useful details (returns, use cases, marketplace scope) without fluff. Slightly dense but each part earns its place; could be split for readability but remains effective.

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

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

For a tool with no output schema and sparse annotations, the description covers key contextual elements: what data is returned, when to use it, constraints (one ASIN, all marketplaces), and examples. It lacks detail on output format or prerequisites, but the schema covers parameter format. It is sufficiently complete for an agent to decide and invoke.

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 parameters are already fully documented in the schema. The description adds no extra semantic meaning beyond emphasizing 'specific ASIN' and 'every marketplace,' which are already implied by the schema. It meets the baseline but does not exceed 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's purpose: pulling a live, on-demand snapshot of a single ASIN including current price, offers, and sellers, plus historical intelligence. It uses a specific verb ('Pull') and resource ('Amazon ASIN'), and distinguishes itself from pre-collected data, making it highly clear and differentiating.

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

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

The description explicitly tells when to use this tool: when the user wants current/today's data for a specific ASIN rather than the pre-collected dataset, with concrete examples. It also notes 'one ASIN per call' and 'every marketplace,' but does not name specific alternative tools, just contrasts with the general dataset.

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 covers safety, and the description adds substantial context about what the tool returns (top 10 sellers/brands, deltas) and its scope (brand/category root). This goes beyond the annotation without contradicting it, though it doesn't disclose computation details or limitations.

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 long, front-loaded with the core purpose, and includes concrete output details and example queries. Every sentence earns its place with no fluff or redundancy.

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

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

With 30 optional parameters and no output schema, the description is far too sparse to guide correct invocation. It explains the high-level function but leaves the many filter parameters (e.g., min_control_score, max_winner_diversity) entirely unexplained, making it incomplete for a tool of this complexity.

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

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

Schema description coverage is only 10% (3 of 30 parameters have descriptions). The description only hints at 'brand or category root' as inputs but provides no explanation for the numerous min/max filter parameters, leaving the agent to guess their meanings. It fails to compensate for the low 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 tool's purpose with a specific verb+resource: 'Map the competitive landscape for a brand or category root.' It also details the exact outputs (top 10 sellers by buybox days, top 10 brands by HHI, week-over-week deltas), which distinguishes it from siblings that focus on other metrics. This is highly specific and 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 explicit usage context with example queries: 'who's winning this category?' or 'who controls the buybox here?'. It lacks explicit exclusions or alternative tool references, but the use-case framing is clear 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?

The description goes well beyond the readOnlyHint annotation, explaining subtle behaviors such as the data_coverage flag clarifying that a null demand indicates a coverage gap rather than zero sales. It also discloses the mix of metrics returned (score, breakdown, flags, red flags), giving the agent a thorough expectation of result semantics. This is significant context that the annotation alone does not provide.

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 dense but every sentence adds value. The lead sentence states the core purpose, and subsequent sentences detail outputs and usage. While it is a long run-on paragraph, the information density justifies the length. Slightly better formatting could improve scannability, but it remains efficient.

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

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

With no output schema, the description fully compensates by listing almost every returned field, including flags and their interpretation. It also covers when to use the tool and hints at the single-ASIN scope. Given the tool's complexity, the description provides sufficient context for an agent to set expectations and properly interpret results.

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 clear documentation for all three parameters (asin, qty, marketplace_id). The description does not add extra meaning to parameter usage; it focuses on outputs. Per the rubric, a baseline of 3 is appropriate given the schema adequately explains each 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 opens with a specific verb and resource: 'Evaluate a single ASIN for FBA sourcing.' This clearly distinguishes the tool from sibling tools like evaluate_brand or evaluate_category_for_private_label by focusing on a single ASIN and sourcing. It also enumerates concrete outputs, leaving no ambiguity about the tool's function.

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 usage trigger: 'Use when the user asks 'should I buy this?', 'how fast does this sell?', or shares an ASIN and wants a sourcing recommendation.' This is clear context for when to invoke the tool. It does not mention exclusions or alternative tools, but the guidance is direct 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?

The annotations declare readOnlyHint=true, and the description's 'Evaluate' and 'Returns' align as a read-only operation with no contradiction. The description adds substantial context by enumerating specific return metrics (e.g., 'winner diversity (HHI)', 'catalog churn rate') and the top-10 ASIN breakdown, going beyond the annotation's simple safety 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 two sentences: a crisp purpose statement followed by a dense list of return values and usage triggers. No filler words; the long enumeration is necessary to convey what the tool returns, and the 'Use when' clause is immediately actionable.

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

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

For a tool with 27 parameters and no output schema, the description covers the core use case well but omits how optional filters affect results (e.g., that min_price filters top_asins) and does not describe the result structure or edge cases. It is sufficient for basic brand evaluation but incomplete for advanced filtering.

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?

Only 6 of 27 parameters (22%) have schema descriptions, yet the tool description does not explain any of the optional filter parameters like min_price, max_gating, or fulfillment_in. It only references 'brand' through the usage examples, leaving the agent to infer parameter semantics from bare schema fields.

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 'Evaluate a brand for portfolio inclusion,' a specific verb+resource that distinguishes it from siblings like evaluate_asin_sourcing (ASIN-level) and brand_similar (similar brands). It enumerates a detailed list of brand-level metrics and top ASINs, clarifying the tool's exact scope.

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 triggers: 'Use when the user names a brand and asks ...' with four example questions. However, it does not mention when not to use this tool or name alternative tools for related tasks, so it lacks explicit exclusion/alternative guidance.

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

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

With readOnlyHint=true, the annotation already covers safety. The description adds meaningful context by detailing the return value: a 'per-signal pass/fail breakdown and a Strong / Moderate / Weak verdict' based on 'Amazon's footprint, seller fragmentation, demand, and price band'. This goes beyond the annotation and helps the agent anticipate output structure, but it does not disclose data freshness or any limitations.

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, front-loaded with the core purpose, followed by concrete usage examples, and ends with a concise summary of the output. No filler or redundant content. Efficient and 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?

The tool is reasonably complete given its moderate complexity and lack of an output schema. The description explains the return value (breakdown and verdict) and mentions the decision factors. The only gap is not clarifying whether category_id, category_name, or both are needed, but since all parameters are optional and the description implies flexibility, this is a minor omission.

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, including descriptions for every parameter and clear marketplace_id value mappings. The description adds only minor context like 'ANY depth' and 'fuzzy', which are also reflected in the schema. Since schema does the heavy lifting, the baseline 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 uses a specific verb ('Assess') and identifies a clear resource ('category or niche') with a distinct purpose ('winnable for a NEW private-label brand'). It provides concrete example queries like 'is X winnable for private label' and even mentions 'Terrariums' as an example, which distinguishes it from sibling evaluation tools like evaluate_brand or evaluate_asin_sourcing.

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 'Use for' and lists several phrasings that trigger this tool, which gives strong when-to-use guidance. It does not explicitly contrast with alternative sibling tools, but the clear use cases and the mention of 'NEW private-label brand' set it apart. This is slightly above minimum viable because alternatives are not named, but usage context is well established.

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 safety is established. The description adds valuable behavioral context by explaining how FBA share is computed and how to interpret thresholds (FBM-heavy vs FBA-dominated). It does not add details about default sorting, return shape, or filter combination behavior, but the given formula and interpretation exceed what annotations provide.

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 long, each earning its place: purpose, formula, usage examples, and alternative tool. It is front-loaded with the core action and avoids fluff. The structure makes it easy to scan and immediately understand the tool's role.

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 18 parameters, no output schema, and only a readOnlyHint annotation, this description is functional but incomplete. It clarifies the primary threshold and sort options, but does not explain what fields are returned per brand, the default sort, how the many filters combine, or pagination/limit behavior. This leaves significant gaps for an agent trying to use the tool effectively without further inference.

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 only 33% (6 of 18 parameters), so the description must compensate. It explains the core fba_share_value/fba_share_op relationship and lists sort_by options, but it does not describe the many min/max filter parameters (e.g., min_control_score, min_asins_touched_3m). Also, the description uses 'unique_sellers' while the schema enum is 'unique_sellers_3m', a minor mismatch. It covers the main threshold but not the full parameter space.

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+resource+scope: 'Return brands whose FBA buybox share is below or above a threshold.' It clearly differentiates from sibling evaluate_brand by stating it is for screening lists, not single brand profiles. The metric formula (fba_buybox_days / total_buybox_days * 100) further eliminates ambiguity.

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

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

The description gives explicit usage guidance with examples ('Use fba_share < 40 to find FBM-heavy brands... or fba_share > 80 for FBA-dominated brands') and names an alternative tool ('For a single NAMED brand's profile, evaluate_brand is the better first call'). This tells the agent both when to use and when not to use this tool.

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

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

The annotation readOnlyHint=true aligns with the description's read-only screening purpose. The description adds context beyond the annotation by explaining the FBA share scale (0-100) and interpreting thresholds, which helps the agent understand expected outcomes. 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?

The description is three sentences, front-loaded with the core purpose, then adds usage context and threshold guidance. Every sentence earns its place with no redundant statements.

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

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

For a tool with 20 parameters and no output schema, the description covers the essential screening use case and distinguishes it from profile tools. It doesn't enumerate every optional filter, but the schema provides some parameter descriptions and the main decision guidance is present. Reasonably complete for the tool's core function.

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 only 30%, so the description must compensate. It clarifies the key threshold semantics (fba_share_op, fba_share_value) and mentions the optional brand filter. However, many min/max parameters (e.g., min_avg_rating, max_asins_touched) remain unexplained in both schema and description, leaving partial gaps.

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: 'Return operators whose FBA buybox share is below or above a threshold.' It names the specific resource (operators) and filter criterion. It also distinguishes itself from operator_profile tools by noting it is for screening lists, not single-seller profiles.

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 guidance on when to use this tool vs. alternatives: 'For a single NAMED seller's profile, the operator-profile tools (operator_classifier / operator_top_brands) are the better first call — this tool is for screening lists.' It also gives concrete threshold usage: '< 50 for FBM-leaning operators' and '> 80 for FBA-heavy flippers.'

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 the exact threshold behavior and optional category filtering. However, it does not disclose behaviors around the many other filters, result ordering, or pagination, so while it adds some value beyond the annotation, it is not richly transparent.

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 and front-loaded, but there is minor redundancy between 'Find brands experiencing high seller churn relative to their category' and 'Returns brands where seller_churn_30d_delta_vs_cat_pp >= the specified threshold'. Overall it is concise with no fluff.

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

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

This is a complex tool with 13 parameters and no output schema, yet the description only covers the core threshold and category filter. It omits the meaning and usage of five undocumented parameters, as well as any return structure or additional behavior, leaving significant gaps 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?

Schema description coverage is 62%, so the schema carries most parameter meaning. The description adds the metric name (seller_churn_30d_delta_vs_cat_pp) and the default threshold, matching min_delta_pp, but it does not explain undocumented parameters like brand_contains, seller churn percentages, or velocity filters.

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 uses a specific verb ('Find') with a well-defined resource ('brands experiencing high seller churn relative to their category') and states the precise criterion (delta >= threshold). This clearly distinguishes it from sibling tools like brands_gaining_sellers (opposite direction) and find_deconcentrating_brands (different metric).

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 'Use when the user asks about brands losing sellers, high churn brands, or seller instability', providing clear context for when to invoke this tool. It does not mention exclusions or alternative tools, but the intent phrases are sufficiently specific.

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 agent knows it's a safe read. The description adds interpretive behavior: the tool measures a drop in buybox concentration over the last quarter and interprets that as more sellers entering. This goes beyond the annotation by explaining the analytical lens.

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, front-loaded with the core purpose, then usage triggers. No wasted words or repetition of schema details.

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 the clear purpose, the tool has 16 parameters and no output schema. The description does not explain what results look like, how 'deconcentration' is computed, or which thresholds matter. This is insufficient for an agent to confidently set parameters or interpret the returned data.

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 only 25% (4 of 16 parameters), and the description does not compensate. It gives no guidance on parameters like min_control_score, min_new_seller_count, or max_seller_growth_pct, which are likely essential for tuning the 'deconcentrating' definition. The phrase 'last quarter' hints at since_weeks but is not explicit.

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 ('Find') and resource ('brands where buybox concentration dropped over the last quarter'), and explains the underlying signal ('more sellers are entering'). It also ties to user phrasing like 'brands losing control' and 'deconcentrating brands', making it easy to distinguish from generic 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 explicitly lists when to use the tool via example queries ('brands losing control', 'gentrification opportunities', etc.), which clearly signals relevant contexts. However, it does not mention when to avoid it or point to alternatives like find_undercompeted_brands or brands_gaining_sellers.

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 include readOnlyHint=true, and the description builds on that with context about sparse sampling and the risk of surfacing long-present sellers. It clearly describes the behavioral nuance of 'first observed' rather than actual market entry, which goes well beyond the structured annotations.

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

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

Four sentences, each earning its place: definition, caveat, sibling distinction, and usage triggers. Front-loaded with the purpose and stays compact despite the complexity.

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, filter-based tool with no output schema, the description provides sufficient orientation: purpose, caveat, alternatives, and trigger phrases. It does not describe result format or default ordering, but the tool's overall role is clearly contextualized. Slightly more detail about how the many filters combine would be useful.

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 only 28%, and the description does little to compensate for the 18 parameters. It ties the date-window concept to early observations, but most filters (e.g., min_operator_fba_share_pct, max_total_observed_buybox_days) remain undefined. The description adds no meaning for the majority of 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?

Description opens with a specific verb and resource: 'Find operators (sellers) we FIRST OBSERVED selling recently' and defines the core mechanism ('earliest observation in our data falls in the window'). It also explicitly differentiates from top_expanding_operators, making the purpose unmistakable.

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

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

Provides explicit when-to-use trigger phrases ('new sellers this month', 'who just started selling', 'newly seen operators') and names the sibling alternative (top_expanding_operators) to avoid confusion. Also sets expectations by clarifying this is 'an observation signal, NOT confirmed market entry'.

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=false, suggesting the tool may perform actions beyond simple reads. The description adds value by explaining it is a 'live cross-retailer price check' and details the output fields (price, class, spread, durability read, Amazon anchor info). No contradictions with annotations. The description clarifies the behavioral traits 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?

The description is three sentences, front-loaded with the main purpose, and covers all essential elements without redundancy. Every sentence adds value, making it efficient for an AI agent to parse.

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 17 parameters and no output schema, the description provides a solid overview but lacks details on many filter parameters and how to use them effectively. It adequately covers basic usage but falls short for complex queries that might require filters.

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 has 65% coverage, and the description adds meaning to key parameters like identifier and mode, explaining their roles. However, many filter parameters (e.g., max_price, source_contains) remain undocumented in the description. Despite this, the description significantly enhances understanding of core 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 clearly states the tool's purpose: finding where a product sits across the open web, anchored to Amazon's buy-box. It specifies the action (find), resource (product across web), and scope (cross-retailer price check). This distinguishes it from sibling tools like asin_buybox_history or shopping_search.

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 lists the required identifier (asin, upc, gtin, or title+brand) and modes (price_compare, cheaper, dropship, supplier) with brief explanations. It implies usage context (one product per call) but does not explicitly say when not to use this tool or mention alternatives among 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 readOnlyHint annotation already signals a safe read operation, and the description adds interpretive context beyond that: 'These are either gated/exclusive or operator-acquired brands.' It also clarifies the core metric (100% of observed buybox days), which enriches 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 two sentences long and front-loads the primary function in the first sentence, then immediately provides use-case triggers in the second. There is zero fluff or repetition; every clause serves a 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?

For a tool with 13 parameters and no output schema, the description clearly explains the core concept and when to use it, which is sufficient for initial tool selection. However, it does not mention the filtering capabilities or result behavior beyond the definition, though the schema partially covers parameter details.

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 62% (8 of 13 parameters have descriptions), leaving several parameters undefined (limit, brand_contains, max_control_score, min_control_score, dominant_seller_contains). The tool description itself adds no parameter semantics, so it does not compensate for these gaps. With moderate schema coverage and zero parameter help from the description, this is a weak point.

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: 'Find brands where a single operator controls 100 percent of observed buybox days.' This is a specific verb+resource+condition that distinguishes it from sibling tools like find_deconcentrating_brands or find_brands_with_high_seller_churn, which focus on different market dynamics.

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

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

The description gives explicit when-to-use guidance by listing concrete user query patterns: 'brands with one seller', 'exclusive brands', 'single-seller brands', 'monopoly brands', or any question about brands with no competition. However, it does not explicitly mention when NOT to use it or name alternative tools, so it falls short of a 5.

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

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

Annotations provide readOnlyHint=true, consistent with the description describing a read-only diagnostic. The description adds significant behavioral context: it details the output components (viability qualifier, specific move, differentiation, economics, risks, validation steps) and sets expectations with 'honest sourcing read' and 'not get-rich advice'. No contradiction with annotations.

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

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

The description is concise while covering input, process, output, and tone. Each sentence adds value, but the phrase 'Scout+' is cryptic and may confuse agents unfamiliar with the brand. Front-loaded with input and key action verbs.

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 and lack of output schema, the description fully explains what the agent can expect: business model diagnosis, real-world matches, and a structured sourcing read. It covers viability, move, differentiation, economics, risks, and validation steps, making it actionable without additional 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 coverage is 100% with clear descriptions for both parameters: asin (10 chars) and marketplace_id (default 2, US). The description reiterates 'Given an Amazon ASIN' but does not add new meaning beyond the schema. Baseline score of 3 is appropriate per rules 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 specifies the exact input (ASIN), the diagnostic process (business model identification, supplier/wholesale/arbitrage matching), and the comprehensive output (viability qualifier, move, differentiation, economics, risks, validation steps). It clearly distinguishes from sibling tools like 'evaluate_asin_sourcing' by emphasizing real-world web matches and an 'honest sourcing read'.

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 implies use when analyzing an ASIN for sourcing opportunities and includes a qualifier 'not get-rich advice', but does not explicitly state when to avoid this tool or suggest alternatives among the many sibling tools (e.g., 'evaluate_asin_sourcing', 'alibaba_supplier_search'). Usage guidance is implicit, not directive.

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 adds meaningful behavioral context: it emphasizes 'real sales presence' and explains that seed_brand constrains results to the same root category. The schema parameter descriptions further disclose that the default seller window drops single-seller 'PL junk,' which helps set expectations. No contradiction with annotations.

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

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

The description is front-loaded with a clear purpose and keeps the main text to three sentences. The long list of example queries is somewhat verbose but earns its place by disambiguating natural-language variants. No filler beyond 'flagship,' which adds a small amount of positioning.

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 18 optional parameters and no output schema, the description explains the core discovery intent and seed_brand behavior, but it does not describe what the returned brand data looks like, whether results are paginated, or how the filter parameters combine. The detailed default explanations in the schema help, but the absence of output semantics leaves a noticeable gap for a flagship discovery 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 56%, and the description adds valuable semantic examples for seed_brand ('brands like Ninja', 'low competition in the same category as OXO'). However, 8 parameters (limit, brand_contains, asin_count, velocity_90d, control_score filters) lack descriptions in both the schema and the tool description, leaving their exact semantics underspecified. This is adequate but not comprehensive.

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: 'Find brands with low seller competition but real sales presence.' This clearly defines the tool's scope and differentiates it from sibling tools like find_single_seller_brands by emphasizing multi-seller demand. Calling it 'the flagship sourcing discovery tool' reinforces its primary role.

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

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

The description gives explicit 'Use when' guidance with concrete query examples ('find brands with few sellers', 'undercompeted brands under $50') and explains when to pass seed_brand. It does not, however, name alternatives or state when not to use this tool versus sibling discovery tools, so it falls short of a 5.

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

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

The readOnlyHint annotation already signals this is a safe read operation, and the description adds meaningful behavioral context: it returns subcategories only, never brands, ranks by private-label winnability, and leverages 2-year marketplace data. There is no contradiction with annotations, and the description goes beyond the structured metadata in explaining what the tool actually reveals.

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 strictly necessary but remains front-loaded: purpose first, then output constraints, then trigger phrases, then exclusions, then category_name usage. The example query list could be trimmed, but every sentence adds practical value for tool selection and invocation.

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

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

The core use case is covered very well—what the tool returns, when to use it, and when not to. However, with no output schema, the description does not explain return formatting, pagination, or default limit behavior, and the many optional filters remain semantically underdefined. Given the tool's complexity (21 parameters), this leaves some gaps for advanced or precise queries.

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 only 43%, and the description compensates only for category_name (telling the agent to pass a department when named). The other 21 parameters—such as niche_contains, competition values, min/max price/demand/rating thresholds, and pl_winnability_in—are left without sufficient explanation, so the agent may not know how to format or combine them correctly.

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

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

The description names a specific verb ('Find') and resource ('UNDER-SERVED NICHES' / subcategories), states that it returns categories and never brands, and clarifies it ranks by private-label winnability from 2-year marketplace data. It also explicitly distinguishes itself from brand-returning sibling tools like find_undercompeted_brands.

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

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

The description gives explicit when-to-use guidance with example queries ('under-served niches', 'find a niche to enter', etc.) and says it is the RIGHT tool for any niche-discovery question. It also names forbidden alternatives (category_undercompeted_brands, find_undercompeted_brands), explains why they are wrong (they return brands), and instructs the agent to pass category_name when the user mentions a department.

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 indicate readOnlyHint=true, and the description adds useful behavioral context by specifying the output structure (3-bullet rationale with specific metrics) and additional data returned (brand, title, price, fulfillment). This goes beyond the annotation's safety hint, though it does not disclose potential prerequisites or failure modes.

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: the first covers the main purpose and outputs, the second gives usage context. Every sentence adds value, with no filler or repetition.

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

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

Without an output schema, the description carries the burden of explaining return values. It does this well by listing the recommendation type, rationale length, metrics cited, and the extra product fields. It does not explain edge cases (e.g., when a metric is unavailable) but the coverage is solid for this 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 50%: marketplace_id is well-documented in the schema, while asin has no description. The tool description refers to 'an ASIN' but does not add further parameter semantics. The purpose of asin is self-evident from the tool name, and marketplace_id is fully covered in the schema, so the description is adequate but not strong.

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 uses a specific verb ('Recommend') and resource ('an ASIN'), and clearly distinguishes the tool's scope from siblings by naming the three decision types (ungate / arbitrage / avoid). It also mentions the unique output of a 3-bullet rationale with named metrics, making it distinct from other ASIN evaluation 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 explicitly states when to use the tool: 'Use for 'should I try to ungate this?' / 'how should I price this?'', which provides clear context. However, it does not mention when not to use it or alternatives, so it falls short of a full 5.

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

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

Beyond the readOnlyHint annotation, the description adds behavioral details such as exact-keyword matching, exclusion of volumes/rankings, and the scope to Amazon-owned autocomplete data. It also explains the output includes first/last observed dates and an example position, giving agents a clearer picture of behavior without needing an output schema. Minor gap: no mention of empty results or data freshness.

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

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

Three compact sentences: first states core purpose, second gives usage scenarios, third sets exclusions. Every sentence carries useful information with no filler or redundancy.

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

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

For a one-parameter tool with no output schema, the description fully explains what to expect: per-marketplace observed presence, dates, and an example position. It also clarifies limitations (exact match, Amazon only). No important context is missing for an agent to invoke 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 the description reinforces the exact-keyword requirement, but adds little beyond what the schema already specifies ('exact keyword to check'). The parameter is simple and well-documented; the description's addition is marginal but not harmful.

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 checks which of the 11 Amazon marketplaces a keyword appears in Amazon's autocomplete suggestions, including dates and position. It explicitly distinguishes from volumes/rankings tools and scopes to Amazon marketplaces, making it distinct from siblings like keyword_demand or brand_xmarket.

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 use cases: when a seller asks about cross-country search behavior, comparing presence, or planning marketplace expansion. It even names complementary tools (brand_xmarket / operator_xmarket_presence) and clarifies it's exact-match only, offering clear guidance on when to use this tool over alternatives.

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

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

With readOnlyHint=true, the description adds that it only returns observed suggestion vocabulary and no volume/ranking data, clarifying the data scope. No contradictory statements.

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: definition first, then use cases, then limitations. It is a bit dense but each sentence adds 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?

Despite lacking an output schema, the description explains the return content in detail: suggestion lists with positions, related vocabulary, and marketplaces. This is complete for a two-parameter read-only 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 covers both parameters with descriptions; the description adds that the seed term is used as a prefix for autocomplete suggestions and that results include positions 1-10, providing context beyond the schema.

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

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

The description clearly defines the tool as retrieving keywords observed in Amazon's autocomplete suggestions for a seed term, per marketplace, listing positions and related vocabulary. It distinguishes from siblings like keyword_cross_marketplace by specifying autocomplete suggestions and marketplace scope.

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 use cases: listing/backend keyword language, discovering buyer search phrasing, and seeding niche/product research. Also gives exclusions (no volume figures, no organic-ranking data), helping the agent decide when not to use.

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 tool is safe. The description adds 'active' but doesn't clarify the default time scope (e.g., whether 'today' is implied by name). Behavioral traits beyond safety are limited.

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-loading the core purpose. The second sentence adds useful query examples. No wasted words, but could be slightly more 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 18 parameters, no output schema, and low schema coverage, the description should explain key parameters (e.g., time filters, default behavior) but does not. It leaves significant gaps for the agent to understand proper usage.

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 only 39% (7 out of 18 parameters have descriptions). The tool description adds no information about any parameters, leaving the agent to infer from names alone, which is insufficient.

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 shows active MAP violations for workspace products, using specific verb and resource. The example queries and sibling context differentiate it from other 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 explicitly lists example user queries that trigger this tool (e.g., 'MAP violations', 'price violations today'), providing clear usage guidance. However, it does not mention when not to use it or suggest alternatives among the many sibling tools.

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

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

Annotations include readOnlyHint: true, so the read-only nature is already known. The description adds useful behavioral context by detailing the return content (buy-box winner, FBA/FBM, observed price, seller tenure, and the user's buy-box/undercut status) and the alternative aggregate mode. It also discloses the store connection requirement, enhancing transparency 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?

Each sentence serves a purpose: defining the tool scope, explaining both invocation modes, stating the prerequisite, and listing example queries. The description is somewhat detailed but efficiently packed with no wasted words, and the structure flows logically from purpose to behavior to usage.

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 detailing the response contents (competitor list, buy-box status, FBA/FBM, price, tenure) and both invocation modes. It also covers the prerequisite and example use queries, making it sufficiently complete for an AI agent to select and invoke the tool correctly in a variety of situations.

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 provides 100% coverage of both parameters, including a full list of marketplace IDs. The description goes beyond the schema by explaining that omitting ASIN triggers an aggregate mode (most-contested products) and that providing it returns a specific listing's competitor list, giving semantic meaning to the optionality.

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 'Who's competing with the seller on their OWN products' and details what information is returned when passing an ASIN, distinguishing it from sibling tools by focusing on the seller's own catalog. It also explicitly lists example queries like 'who am I competing with' and 'am I losing the buy-box', making the purpose clear and specific.

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 states when to use the tool ('Use for...') and describes two modes: with an ASIN for a specific listing's competitor list, or without it for most-contested products. It also sets a prerequisite ('Requires a connected store (Starter+)') and implicitly excludes non-own products with 'on their OWN products', giving clear usage context, though it doesn't mention alternative tools explicitly.

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 goes far beyond the readOnlyHint annotation by disclosing key behavioral details: it seeds specific engines (undercompeted-brand and underserved-niche), uses the seller's own connected catalog as a source, excludes brands the seller already carries, and requires a connected store. These are valuable operational insights that directly inform an agent's expectations about the tool's mechanics and prerequisites.

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 appropriately sized, front-loading the core purpose in the first phrase. Each sentence adds distinct value: purpose, source/algorithm, prerequisites, and usage examples. No redundant or filler content.

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

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

The description effectively covers the tool's purpose, inputs, prerequisite, and filtering logic. The only minor gap is the lack of an explicit description of the return value/format, but since there is no output schema, a little more detail could have been added. Still, the description is sufficiently complete for a single-parameter 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 for the single parameter marketplace_id, including a detailed list of marketplace values. The description does not add additional semantic meaning about the parameter, so it neither improves nor detracts from 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 clearly states the tool's purpose: 'What to source NEXT, adjacent to what the seller already sells.' It specifies the resource (sourcing opportunities) and the scope (adjacent to existing catalog). It also distinguishes from siblings by emphasizing the seller's OWN connected catalog and the exclusion of existing brands, which sets it apart from generic sourcing tools like find_undercompeted_brands.

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 use cases ('Use for 'what should I source next', 'expand my catalog', 'adjacent opportunities'...') and a prerequisite ('Requires a connected store (Starter+)'). While it doesn't explicitly name alternative tools, the phrase 'adjacent to what the seller already sells' implies when to use this tool versus broader discovery tools. This is clear context, but lacks explicit exclusion guidelines.

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 rich behavioral context by specifying the exact data dimensions returned (account data vs observed/estimated market data) and the requirement for a connected store. It avoids contradicting annotations and adds value beyond them.

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 dense but efficient, delivering the key concept (fused catalog) and usage in two sentences. Every phrase adds value, though the first sentence is long and could be slightly restructured for easier scanning. Still well within acceptable length.

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 enumerating the output fields and their nature (EXACT vs OBSERVED/ESTIMATED). It covers purpose, usage, prerequisites, and output semantics, making it complete for a read-only list tool. Slight gap: no mention of pagination or limits, but not critical.

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 each parameter is well-described in the input schema (sort enum, brand optional, marketplace_id values). The description itself does not add parameter-level detail beyond what's already present, so the baseline 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 clearly identifies the tool's function: showing the seller's own connected Amazon catalog fused with market intelligence. It distinguishes from siblings by emphasizing 'seller's OWN' products and listing the specific data fields, which separates it from competitor-focused or opportunity-focused 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?

Provides explicit usage triggers ('when the seller asks about their own products', 'how am I priced vs the market', etc.) and a prerequisite (connected store Starter+). It lacks explicit when-not-to-use or named alternatives, but the context is clear enough for correct selection.

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

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

Annotations already declare readOnlyHint=true, and the description adds useful context about the need for a connected store and that inventory units are 'EXACT, from the account,' indicating data provenance. It is consistent with annotations and describes no side effects, but doesn't go beyond prerequisite and data accuracy details.

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?

One dense sentence that front-loads the tool's purpose and lists all included metrics. While it runs long, every item adds value and there is no filler. It could be more scannable with bullet points, but the structure is efficient.

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

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

The tool is simple (one optional param, no output schema), and the description covers the summary content, prerequisites, and usage scenarios. The metric list doubles as expected output documentation. It lacks explicit return formatting or error handling but is adequate for a dashboard summary 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% because marketplace_id has a full description with allowed values and a default. The description itself does not mention the parameter, but the schema fully documents it, so the baseline of 3 applies without additional value from the 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 opens with 'Store-level summary of the seller's connected Amazon catalog' and enumerates specific metrics (products tracked, brands, FBA/FBM split, inventory, sourcing score, undercut count, Walmart opportunity), clearly distinguishing it from sibling tools like my_products or my_competitors. The verb 'summary' and resource 'catalog' are explicit and 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 use cases: 'Use for 'how is my store doing', 'summarise my catalog', or a dashboard overview.' Also states a prerequisite 'Requires a connected store (Starter+)'. However, it does not name alternative tools or give exclusion criteria, so it falls short of a 5.

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