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

The description complements the readOnlyHint annotation by adding behavioral details: it returns only text, no price or photos, and the user must click for more info. No contradictions 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 a single sentence plus a clarifying note. It is front-loaded with the main action and efficient, with no wasted words.

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

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

Given no output schema, the description adequately explains what the tool returns (title, rating, snippet, link) and what it does not. It could mention pagination or result limits, but for a search 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 provides a clear description for the 'query' parameter. The description adds useful context: query should be a product/OEM query, brand-free for private label. This adds meaning beyond the schema, though schema coverage is high.

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 Alibaba supplier/manufacturer listings for a query via Serper site:alibaba.com, and specifies the return fields (title, rating, snippet, link). It distinguishes from other tools by highlighting its text-only nature and the absence of price/photo.

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 'TEXT ONLY: no price or photo available via this source (the user sees price / MOQ / photos on Alibaba after clicking).' This tells the agent when to use this tool (when text info suffices) and when not to (if price/photo needed, use another method), providing clear usage boundaries.

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 disclosure of return values (per-week breakdown, monthly seller count series, seller_trend label, product details) adds useful context beyond the readOnlyHint annotation. It does not mention rate limits or data freshness, but the behavioral description is consistent with a read-only tool and provides meaningful 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 is information-dense but somewhat lengthy. It front-loads the core purpose and then details return values and use cases. Every sentence adds value, though slight tightening could improve conciseness.

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 27 parameters and no output schema, the description provides a strong overview of the main outputs and usage context. It covers the essential return structure and common query intents, but could be more complete by addressing more filter parameters or error conditions.

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 30%, so the description must compensate. It explains the key parameters (asin, since_weeks, marketplace_id) and describes derived output fields not in the schema (e.g., seller_count_monthly, seller_trend). However, many filter parameters remain undocumented in both schema and description, limiting the value added.

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 have been winning the buybox for an ASIN over time and how the competing-seller pool changes month over month. It uses specific verbs and resources, and the detailed example queries effectively distinguish it from sibling tools like brand_buybox_trajectory or buybox_loss_alert.

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 with example user queries, such as 'who has been winning buybox on this ASIN' or 'is the seller pool stable or volatile'. It does not mention when not to use the tool or explicitly name alternatives, but the context is sufficiently clear for an agent to understand applicability.

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, and the description adds detail about what each comparable includes: 'product brand, title, price (or price range) and fulfillment (FBA/FBM/AMZ + amz/fba pct).' This gives valuable output context beyond the readonly fact.

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—two sentences—with the first sentence stating the purpose and criteria, and the second listing output fields. It is front-loaded and contains no unnecessary words.

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

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

With 19 parameters and no output schema, the description gives a basic overview of the tool's functionality and output, but does not explain how parameters interact (e.g., whether filters are combined, how limit works, or how marketplace_id affects results). It is adequate but not comprehensive.

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 32%, meaning most parameters lack descriptions. The description mentions filtering by 'brand, price band, and seller count' which maps to a few parameters, but does not explain the many other optional filters like limit, min_days_observed, or buybox_seller_contains. The description 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: 'Find ASINs similar to a given ASIN by brand, price band, and seller count.' It lists specific user queries that trigger its use, distinguishing it from sibling tools like asin_buybox_history or asin_profit_calc.

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: 'Use when the user asks ASINs like this one, similar products, comparable ASINs, what else is like B08N5WRWNW, or any ASIN-level lookalike question.' It provides clear context, though it doesn't discuss alternatives or 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 already declare readOnlyHint=true, so the safety profile is clear. The description adds context about return fields (brand, title, price, fulfillment) but does not disclose additional behavioral traits like API calls or estimation methodology. With annotations present, a score of 3 is appropriate.

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

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

The description is two concise sentences with no wasted words. The first sentence states the primary purpose, and the second adds use case examples and return information. It is front-loaded and 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?

Given the tool has 4 parameters and no output schema, the description provides sufficient context by listing return fields (brand, title, price, fulfillment). It does not explain the profit calculation formula, but for an agent, the description is complete enough to use the tool correctly.

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

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

Schema description coverage is 100%, so baseline is 3. The description does not add extra meaning beyond what the schema already provides for parameters (asin, target_margin_pct, cogs, marketplace_id). The description focuses on output rather than parameter semantics.

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

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

The description clearly states the tool estimates profit margin for an ASIN, with specific verb 'estimate' and resource 'ASIN'. It provides example queries like 'can I make money on this ASIN' and differentiates from siblings like asin_buybox_history or asin_comparables by focusing on profitability.

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 use cases ('can I make money on this ASIN', 'profit calculator', etc.) and mentions when to use it. It does not exclude alternatives, but with many sibling tools, the context is sufficient for an agent to decide.

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 that the tool lists 'saved' authorized sellers, indicating it returns existing data. The annotation readOnlyHint=true already signals a safe read operation. No further behavioral details (e.g., pagination, authorization) are provided, but this is adequate for a simple list tool.

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

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

The description is two concise sentences: the first states the action, the second gives usage examples. No extraneous information; front-loaded and 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?

Given a simple 3-parameter tool with readOnlyHint and no output schema, the description covers the purpose and typical usage scenarios. It could optionally mention that it returns a list of seller names, but overall it is complete enough.

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 has 100% description coverage, so the schema alone documents all parameters' meanings. The description does not add any parameter-level details beyond what is in the schema, 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 specifies the verb 'List' and the resource 'saved authorized sellers for a brand'. It provides concrete user query examples ('who are my authorized sellers for X'), clearly distinguishing it from sibling tools like authorized_seller_set (write) and unauthorized_sellers (different set).

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

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

The description includes explicit usage cues: 'Use when the user asks...' with three example queries. While it does not state when not to use, the examples clearly delineate the tool's purpose, making it easy for an agent to match.

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=false, consistent with write operation described. Description doesn't add behavioral details beyond basic mutation, such as overwrite behavior or side effects. Adequate but not enhanced.

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

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

Three sentences, front-loaded with purpose, no wasted words. Every sentence adds value: what it does, prerequisite, and example 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?

For a write operation with no output schema, description covers purpose, prerequisite, and parameter tips. Missing response info, but with 100% schema coverage, it's nearly 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% with descriptions for all 3 params. Description adds minimal extra meaning: only 'exactly as they appear on Amazon' for sellers. 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?

Description clearly states the verb 'Save' and the resource 'authorized sellers for a brand', with context of making unauthorized seller detection possible. This differentiates from sibling 'authorized_seller_list' which lists.

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: 'these are my authorized sellers for X', 'add Y', 'set my brand's approved resellers'. Mentions prerequisite that brand must be tracked. Lacks explicit when-not but covers key scenarios.

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

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

Annotations already declare readOnlyHint: true. The description adds that it returns weekly data for a trailing window, but does not disclose limits (e.g., max 52 weeks from schema), behavior for insufficient data, or how filtering parameters affect results. It does not contradict 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 extremely concise: two sentences with key purpose and output, followed by example queries. Every sentence adds value, and the most critical information is front-loaded.

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

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

Despite good annotations, the tool has 16 parameters and no output schema. The description provides minimal behavioral context (trailing window, weekly seller counts) but omits explanation of filtering parameters (e.g., trend_in, min_seller_count_change_pct) and the structure of the return data. This leaves agents underinformed for correctly invoking the tool or interpreting 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 38% (most parameters lack descriptions). The description adds no parameter-specific information beyond what the schema provides, failing to compensate for the low coverage. Only 'brand', 'since_weeks', and 'marketplace_id' are somewhat explained in the schema; the many filter parameters are opaque.

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 buybox concentration change over time, specifies the output (weekly seller counts and observed buybox days), and provides example queries that distinguish it from siblings like brand_under_attack or find_deconcentrating_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 explicitly lists use cases and example queries ('is this brand getting more competitive', 'concentration trend for Nike'), guiding when to invoke. It does not explicitly state when not to use or offer alternatives, but the context is clear enough for most scenarios.

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 description adds behavioral details: output includes brand, title, price/price range, and fulfillment info (FBA/FBM/AMZ + percentages). No contradictions.

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

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

Three sentences with clear, front-loaded purpose and usage examples. Every 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?

With 26 parameters and no output schema, the description explains output fields but omits pagination, ordering, or default behavior. Adequate but not fully comprehensive.

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%. The description mentions key output fields but does not explain many filtering parameters (e.g., first_seen_from, last_seen_to, fulfillment percentages). Insufficient compensation for 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?

Description clearly states the tool shows new ASINs for a brand, with specific user query examples like 'new products for Nike' and 'recently added ASINs'. It differentiates from sibling tools that focus on other brand metrics.

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 tells when to use the tool with example queries. Does not provide exclusions or alternatives, but context is clear for common use cases.

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 set readOnlyHint=true. Description adds critical context about it being an observation signal, not confirmed market entry, and warns about sparse re-sampling. 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?

Three sentences, front-loads action and nuance. Every sentence adds value; 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?

Covers core purpose and key nuance, but with 17 parameters and no output schema, the description does not explain filtering options or return format, leaving gaps for the agent.

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

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

With only 35% schema description coverage, the description adds minimal parameter context beyond mentioning an optional category filter. Does not compensate for the many undocumented 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 it finds brands that recently gained newly-observed sellers, using specific verb 'Find' and resource. It distinguishes from siblings by focusing on brands gaining sellers, but does not explicitly differentiate from similar tools like 'find_new_operators'.

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 example queries and usage contexts (e.g., 'brands gaining sellers in [category]', 'brands under hijacker pressure'). However, no alternatives or when-not-to-use guidance is given.

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 aligns with the readOnlyHint annotation, indicating a read operation, but adds no additional behavioral context such as rate limits 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 a single sentence plus a usage clause, very concise and front-loaded with key purpose and examples.

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

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

With 14 parameters, no output schema, and minimal parameter explanations, the description lacks completeness for effective agent 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 29%, and the description does not explain the majority of parameters. It only mentions category, price tier, and competition level, which are not explicit 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 'Find brands similar to a given brand by category, price tier, and competition level' and provides explicit example queries, making purpose unambiguous. It distinguishes from sibling tools by focusing on brand lookalikes.

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 via example queries like 'brands like Nike', but does not mention when not to use or alternative 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 already declare readOnlyHint: true. The description adds context about the operator graph and ranking, but does not disclose additional behavioral traits like pagination or rate limits.

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 (3 sentences) and front-loaded with purpose and usage examples. Every sentence adds value without 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 12 parameters and no output schema, the description lacks details on return format, pagination, or how results are ranked. It covers the core idea but is 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?

With only 33% schema description coverage, the description does not explain most parameters beyond the target brand. It fails to compensate for the lack of schema descriptions for 12 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 finds brands sharing operators with a target brand and ranks them, with specific example queries like 'what brands are in X's network?' This distinguishes it from siblings like brand_similar or operator_brands_by_competition.

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 example queries for when to use the tool (e.g., 'who else do Ninja's sellers carry?'). However, it does not explicitly state when not to use it or suggest alternative 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 already declare readOnlyHint=true, indicating safe read operation. The description adds behavioral context: explains the use of brand-level first-seen, which is stable under scraper-coverage growth, and notes it is not inflated like per-ASIN counts. No contradictions 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 three sentences, each earning its place: purpose and methodology, technical nuance, and usage examples. No fluff, front-loaded with primary 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?

Given rich schema descriptions and annotations, the description covers key aspects. It could optionally mention the output format (e.g., threat levels), but absence of output schema makes it acceptable. Provides sufficient context for an agent to select and invoke the tool.

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

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

Schema coverage is 100% with each parameter described. The tool description does not add further parameter-specific meaning beyond the schema, so baseline score of 3 is appropriate.

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

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

The description clearly states the tool's purpose: detecting if a brand is under competitive attack using new-entrant rate and buy-box churn. It also provides example user queries, distinguishing it from sibling tools like brand_buybox_trajectory 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?

Explicitly tells when to use the tool via example user queries ('use when the user asks...'). It explains the methodology (brand-level first-seen) implying why this tool is better than per-ASIN alternatives, but does not explicitly state when not to use it or list alternative 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 already indicate readOnlyHint=true. The description adds value by specifying return fields (seller count, ASIN count, buybox days, control score) and per-marketplace behavior, confirming it is a safe query.

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 purpose and returns, followed by usage examples. No redundant 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?

Covers core purpose and return fields, but lacks details on threshold parameters (min/max) and explanation of control score. No output schema, so description could provide more 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 20% (only 'brand' described). The description does not explain the other 9 parameters (marketplace_id_in, min/max counts, etc.), leaving the agent without guidance on filtering options.

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 Amazon US, UK, and Walmart, and lists specific return metrics. It distinguishes from siblings by focusing on multi-marketplace brand presence, with explicit user query examples.

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 example user queries ('does this brand sell on Walmart', 'cross-marketplace presence for Nike'), making it clear when to use. No when-not-to-use guidance, but the context is sufficient.

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 description adds that results are ranked by revenue, includes product brand/title/price/fulfillment. Describes fallback behavior when no authorized list set. 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?

Description is front-loaded with purpose, then output details, then prerequisite and examples. Slightly verbose but 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 26 parameters and no output schema, the description adequately covers the core function, output fields, and prerequisite. Does not explain all filter combinations but sufficient for an alert 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 only 27%, but description does not explain any parameters beyond what is already in the schema. It mentions the 'brand' parameter implicitly but does not add detail for the many 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 uses specific verbs ('Find') and clearly states the resource (ASINs where brand lost buy box), ranking by revenue at stake. It differentiates from siblings like authorized_seller_set and operator_buybox_losses by focusing on brand-owned ASINs and requiring authorized 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?

Provides explicit example queries ('where am I losing the buy box') and mentions prerequisite (save authorized list). Lacks explicit when-not-to-use, but context is clear.

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

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

Annotations already mark the tool as read-only. The description adds that results are ordered by retreat magnitude, but does not disclose output format, pagination, or limits. Some behavioral context is added, but not extensively.

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 3 sentences, front-loads the main purpose, and avoids unnecessary detail. It is well-structured for quick understanding.

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 15 parameters, no output schema, and many sibling tools, the description is too brief. It lacks information on output format, filtering options, and how to interpret results, making it incomplete for effective tool 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?

Only 27% of parameters have schema descriptions, and the tool description does not provide additional parameter documentation. It fails to compensate for the low schema coverage, leaving many 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 the tool finds categories with net Amazon brand exits over 90 days and gives example user queries. However, it does not differentiate from similar sibling tools like category_new_entrants or category_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 example queries for when to use it but does not specify when not to use it or mention alternative tools, which are abundant 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?

Annotations already declare readOnlyHint=true, so the description mainly adds content details (list of metric groups) rather than behavioral traits. It does not disclose pagination, performance, or rate limits, which is acceptable given the annotation coverage.

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

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

The description is concise: two front-loaded sentences cover purpose and supported queries, followed by a bullet list of metric groups. Every sentence adds value without redundancy.

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

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

Given no output schema, the description compensates well by enumerating the metric groups (demand, competition, Amazon presence, etc.) and providing example use cases. It covers what the tool returns but could be slightly more precise about the return format.

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

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

Schema description coverage is 100%, so the baseline is 3. The description does not add additional semantics beyond the schema; it lists the returned metrics but not parameter-specific details like mutual exclusivity of category_id and category_name.

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 'Return' and the resource 'full metric set for ONE category', differentiating from sibling tools by specifying single-category scope and any depth, including a concrete example like 'Terrariums'.

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 ('show me the metrics/stats for category X', 'how big is the X category') that guide the agent on when to invoke this tool, but does not mention when not to use it or directly compare to 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?

Annotations already declare readOnlyHint=true. The description adds valuable behavioral context: it's an observation signal, not a confirmed first-ever entry, due to sparse re-sampling. No contradictions 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?

Three sentences cover purpose, clarification, and usage examples. Front-loaded with the key action and limitation. No wasted words.

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

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

The tool has 17 parameters but no output schema. The description explains the core concept and limitation, but does not describe the return format or how to interpret results. Given the complexity, more guidance on output would be beneficial.

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 35% (6 of 17 parameters have descriptions). The description does not provide additional meaning for the undocumented parameters (e.g., brand_contains, min_seller_count). It hints at date-related parameters but does not compensate for the 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 it finds brands newly observed in a category within a date window, with specific verb and resource. It distinguishes from siblings by explaining it's an observation signal and provides example user queries that clarify usage.

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 includes explicit example queries (e.g., 'new brands in Electronics') and a warning about the limitation of sparse sampling. It does not explicitly list when not to use or name alternatives, but the examples sufficiently guide typical usage.

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 description adds little behavioral detail beyond the purpose. It does not explain how results are sorted, default limits, or other behavior, leaving the agent to guess.

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 with two sentences and a front-loaded purpose. No fluff, but it could be improved by adding a brief note on ordering or defaults without becoming verbose.

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

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

Given the 19 parameters and no output schema, the description is insufficient. It does not explain what 'biggest recent growth' means, default returned count, or how to interpret results, leaving significant gaps.

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 26% schema description coverage, the description fails to compensate for the many undocumented parameters. It provides no parameter-level guidance, making it hard for the agent to use filters 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 finds brands in a category with the biggest recent growth in seller count and observations, and provides example user queries. However, it does not explicitly differentiate from similar sibling tools like '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 gives example queries and specifies 'any category-scoped growth question', indicating when to use it. However, it lacks guidance on when not to use it or alternatives, leaving boundaries unclear.

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. Description adds context about the min_sellers floor behavior and that results show 'proven multi-seller demand'. However, it does not disclose output format, pagination, or rate limits. 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?

Description is well-structured, front-loading the key function. Every sentence serves a purpose: definition, usage, exclusions. No unnecessary words. Efficient for its information density.

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

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

Given the tool complexity (17 params, no output schema), the description covers core concept and usage boundaries well. Lacks output description and default behavior, but the annotations and sibling context compensate. Could be more complete but adequate.

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

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

Schema description coverage is 53%. Description adds meaning for the 'min_sellers' parameter by explaining its role in filtering out single-seller listings. Other parameters are not elaborated, but the overall purpose is clear. Baseline for moderate coverage is around 3.

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 clearly states verb 'find', resource 'BRANDS', and scope 'within a category that have proven multi-seller demand but are still under-competed'. It explicitly distinguishes from sibling tool 'find_underserved_niches' by stating what it returns and what not.

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 examples ('undercompeted brands in <category>') and contraindications ('Do NOT use for under-served niches...') with a direct sibling reference. Tells agent exactly when and 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?

With readOnlyHint=false in annotations, the agent already knows the tool is not read-only. The description adds the 'LIVE' and 'on-demand' qualifiers, implying a real-time API call with potential cost or rate limits. It does not explicitly disclose side effects like query limits or costs, but the annotations already carry the primary behavioral signal, so a score of 3 is appropriate.

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

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

The description is three sentences and efficiently front-loads the purpose, data returned, and usage context. The first sentence is somewhat long (49 words) but no unnecessary repetition. It is structured logically: what it does, when to use, constraints. Slight verbosity prevents a 5.

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

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

Given no output schema, the description details the return data comprehensively (title, price, offers, sellers, historical intelligence, fulfillment). It also states constraints (US only, single ASIN). Missing operational details like error handling or rate limits, but the context provided is sufficient for agent decision-making.

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 has 100% coverage with descriptions for both parameters (asin and marketplace_id). The description reinforces these by stating 'one ASIN per call' and 'Amazon US only,' but does not add new meaning beyond the schema. Baseline score of 3 is justified.

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 'pull' and clearly defines the resource as a single Amazon ASIN with live data. It explicitly lists the included data (title, price, offers, sellers, historical intelligence) and distinguishes itself from pre-collected datasets, making it distinct from sibling tools like asin_buybox_history or asin_profit_calc.

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: 'Use when the user gives a specific ASIN and wants its CURRENT/today's data rather than the pre-collected dataset.' It gives example queries and constraints (Amazon US only, one ASIN per call). However, it does not mention alternative sibling tools by name, so guidance on when not to use is implicit rather than explicit.

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

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

Annotations already indicate readOnlyHint=true. The description adds value by specifying that it returns week-over-week deltas, which is behavioral context beyond the annotation. It does not mention any destructive actions, confirming the read-only nature.

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: first states purpose and outputs, second gives usage context. No fluff, front-loaded with essential information. Every 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 30 parameters and no output schema, the description only outlines three output fields (top sellers, top brands, deltas) and does not explain the filtering parameters or which inputs are required (e.g., category_root_id or brand is implied but not explicit). For a complex tool with many options, this is incomplete.

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 10% (3 of 30 parameters have descriptions). The description does not explain the meaning or usage of most parameters, including required context like brand or category_root_id. It only hints at needing a brand or category root but doesn't specify which parameters to use. With such low schema coverage, the description fails to compensate.

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 maps competitive landscape for a brand or category root, specifying exact outputs: top 10 sellers by buybox days, top 10 brands by HHI, and week-over-week deltas. It also provides example queries ('who's winning this category?'), making the purpose distinct from siblings like brand_buybox_trajectory or operator_concentration.

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 the tool with example questions ('who's winning this category?', 'who controls the buybox here?'), which is strong usage guidance. It does not mention when not to use it or alternatives, but the clear context suffices for an agent to decide.

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 description consistently details all return fields, including coverage flags and explanation of null demand, adding value 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 well-structured, listing outputs then usage guidance. It is somewhat lengthy but every sentence adds value; could be slightly more concise.

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 complexity (no output schema), the description thoroughly explains all return values including edge cases like data_coverage flag. Context including sibling tools is comprehensive.

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 100% of parameters with descriptions. The tool description does not add significant extra meaning beyond what the schema already provides, 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 'Evaluate a single ASIN for FBA sourcing' and lists specific outputs, distinguishing it from sibling tools like find_sourcing_opportunities or asin_profit_calc.

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 says 'Use when the user asks 'should I buy this?', 'how fast does this sell?', or shares an ASIN and wants a sourcing recommendation.' This provides clear context for when to invoke.

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 details the output (control posture, HHI, etc.) beyond annotations. Doesn't mention error handling or rate limits, but sufficient for a read-only tool.

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

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

The description is front-loaded with the main purpose and uses three sentences to cover key points. It could be slightly more structured (e.g., separating output list from usage), but is efficient and not verbose.

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

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

Despite lacking an output schema, the description explains the return structure (brand-level metrics and top 10 ASINs with details) comprehensively. For a tool with 27 params, it covers the essentials, though parameter explanations are missing.

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

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

Schema description coverage is only 22%, yet the description does not elaborate on parameter meanings beyond the schema. Most parameters (e.g., min_composite_score, max_velocity) are left unexplained, failing to compensate for 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 'Evaluate a brand for portfolio inclusion' and lists specific metrics returned, making the purpose distinct. However, it does not explicitly differentiate from sibling tools like 'brand_similar' or 'brand_buybox_trajectory', so it's not a 5.

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

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

Provides concrete examples of user queries ('is this worth carrying?', 'how does this brand look?') that trigger this tool. Missing explicit exclusion guidance or alternatives, so not 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. Description adds behavioral detail by specifying that the tool returns a per-signal pass/fail breakdown and a Strong/Moderate/Weak verdict. No contradiction between description and 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?

Description is a single paragraph with purpose front-loaded. Sentences are functional and concise, though slightly verbose in listing example queries. No wasted words 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?

Given no output schema, the description adequately explains the return structure (per-signal pass/fail and verdict) and the evaluation factors (Amazon footprint, seller fragmentation, demand, price band). Covers all needed context.

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

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

Schema description coverage is 100%. Description repeats the schema's parameter descriptions without adding new meaning. Per guidelines, baseline is 3 when coverage is high.

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 clearly states the verb 'assess' and the resource 'category or niche' (any depth). Provides example queries that map to user intent, and distinguishes from siblings like evaluate_asin_sourcing and evaluate_brand.

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?

Description includes explicit use cases such as 'is X winnable for private label' and 'should I private-label X'. While it does not explicitly state when not to use or list alternatives, the examples provide clear context for appropriate usage.

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 no safety concerns. Description adds context on the metric computation and purpose but does not disclose return format, pagination, or any behavioral quirks beyond 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?

Four sentences, efficiently front-loading purpose, then usage, then sort. No fluff, though slightly more structure (e.g., listing all parameters) could improve readability.

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 many sibling tools, the description lacks details on return values (fields returned) and does not cover the extensive filtering options. It leaves the agent guessing about output structure and full capabilities.

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 33%, but description explains only a few key parameters (fba_share_op, fba_share_value, sort_by, marketplace) with examples. Many filtering parameters (min_sourcing_score, limit, brand_contains, etc.) are left unexplained, failing to compensate for 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 returns brands based on FBA buybox share threshold, including the formula and examples. It implicitly distinguishes from sibling 'filter_operators_by_fba_share' by focusing on brands, but does not explicitly differentiate.

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

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

Provides concrete usage examples: 'use fba_share < 40 to find FBM-heavy brands' and 'fba_share > 80 for FBA-dominated brands'. Also mentions sort options. Lacks explicit alternatives or when-not-to-use scenarios.

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, consistent with description. Description adds interpretation of FBA share (0-100 percentage) and threshold meaning. Missing details like default sort order, limit, or response format.

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

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

Three sentences, no fluff. Purpose is front-loaded. 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?

Given 20 parameters and no output schema, the description covers the essential filtering logic but omits sorting, limit, and other filter fields. Adequate for core use but not fully complete for power users.

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 30% schema coverage, description adds value for core parameters (fba_share_op, fba_share_value, brand) by providing examples and context. However, many optional parameters remain unexplained, which is a gap given 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?

Description clearly states it returns operators filtered by FBA buybox share threshold. It provides specific use cases (FBM-leaning vs FBA-heavy flippers), distinguishing it from sibling tools like operator_brands_by_competition.

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 scenarios given: 'Use fba_share < 50 ... or fba_share > 80 ...' and optional brand filter. Does not explicitly exclude alternatives, but context is sufficient for most use cases.

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

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

Annotations already declare readOnlyHint=true. The description adds context about the filtering logic (delta vs category, default threshold) which is helpful but not extensive. No contradictions.

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

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

Three sentences, front-loaded with purpose, no redundant information. Every 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?

Core purpose and metric are clear, but the tool has 13 parameters and no output schema. The description does not explain the shape of the results or how the multiple optional filters interact, leaving some ambiguity for complete 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 62%, between the 50-80% range. The description only explains two parameters (min_delta_pp and category) implicitly, leaving many others (e.g., scope, marketplace, brand filters) unexplained. It does not adequately compensate for undocumented 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 clearly states the tool finds brands with high seller churn relative to category, specifying the metric and threshold. It uses a specific verb ('find') and resource ('brands'), but does not explicitly distinguish from siblings like '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?

Description provides explicit usage hints ('Use when the user asks about...') that guide typical queries. However, it does not mention when not to use the tool or suggest alternatives from the sibling list.

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?

Discloses that the tool compares first and second halves of a window (via 'since_weeks'), indicating temporal analysis. The readOnlyHint annotation is already present, and the description adds context about the business implication (opportunity for new entrants). No contradictions.

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 cover purpose and usage triggers. No redundant words. Each part is essential: first defines the action, second provides invocation cues.

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?

Covers overall purpose and when to use, but given 16 parameters and no output schema, more detail on default behavior, parameter interactions, and expected output would improve invocation accuracy. Adequate for a read tool but could be richer.

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 4 of 16 parameters are described in the schema (25% coverage). The tool description does not add any parameter explanations beyond what's in the schema. Key parameters like min_old_seller_count, min_control_score, etc., lack documentation, making it hard for agents to set 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?

Uses specific verb 'find' and clear resource 'brands where buybox concentration dropped'. Includes concrete example queries covering synonyms like 'brands losing control', making purpose unmistakable. Differentiates from siblings by focusing on concentration drop rather than seller count growth.

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 lists user query patterns that should trigger this tool ('brands losing control', 'deconcentrating brands', etc.). No explicit exclusions or alternatives, but the examples effectively guide when 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?

Beyond the readOnlyHint annotation, the description explains that this is an 'observation signal, NOT confirmed market entry' and warns that 'sparse sampling can surface a long-present seller the first time we see them', which adds crucial 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 two sentences plus a usage note, front-loaded with the core concept and differentiation, with no wasted words.

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

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

While the description excels at explaining the tool's purpose and usage, it does not address the 18 parameters or output format. Given the complexity (many parameters, no output schema), the description could be more complete for an AI agent to use effectively.

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% (5 of 18 parameters have descriptions), and the tool description itself provides no additional parameter explanations. Many parameters remain undocumented, leaving the agent with insufficient semantic understanding to set 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 uses specific verb+resource ('Find operators we FIRST OBSERVED selling recently') and clearly distinguishes from the sibling tool top_expanding_operators by stating it's for newly-observed sellers, not existing operators adding 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?

Explicitly provides example queries ('new sellers this month', 'who just started selling', 'newly seen operators') and explains the key difference from top_expanding_operators, giving clear guidance on when to use this tool.

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

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

Annotations indicate readOnlyHint=false (not read-only). The description describes a live price check, which is a read operation, but no destructive behavior is mentioned. It adds transparency about the source (Webotee's Amazon buy-box anchor) and output details (price, class, spread, durability, fulfillment info). 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 a single paragraph of about six sentences, front-loaded with the main purpose. It is reasonably concise with no redundant information, though it could be more structured (e.g., bullet points for modes). Every 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?

Given the tool's complexity (17 parameters, no output schema, many siblings), the description covers the essential aspects: purpose, input requirements, modes, and output components (price, class, spread, durability, Amazon anchor). It does not fully describe all parameters or edge cases, but it is sufficient for the primary use case.

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 65% (11 of 17 params described). The description adds meaning beyond the schema by explaining identifier options (asin, upc, gtin, title+brand) and mode functionality. It highlights key parameters but does not cover all 17; however, it provides enough context for the main usage.

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: 'Find where one product sits across the open web — a live cross-retailer price check'. It specifies the action (find), resource (product across web), and scope (one product per call). This distinguishes it from sibling tools that focus on brands, operators, categories, etc.

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

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

The description explains required inputs ('Give ONE identifier and a mode') and the four modes (price_compare, cheaper, dropship, supplier) with brief definitions. It implies when to use each mode but does not explicitly state when not to use this tool or list alternatives among siblings. Overall clear 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. The description adds context that results are either gated/exclusive or operator-acquired brands, which provides insight into the nature of the output beyond the read-only flag.

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

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

Two sentences: first defines the core function, second gives usage examples. Every sentence is essential and no waste. Front-loaded with the most important 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?

No output schema exists, so the description should hint at return format. It does not. With 13 parameters and complex filtering, the description is minimal but adequate given schema and annotations. Lacks clarity on output 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 coverage is 62%, so baseline is 3. The description does not add any parameter-level information beyond the schema. It does not compensate for the undocumented parameters like limit, brand_contains, or min_control_score.

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

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

The description clearly states the tool finds brands with a single operator controlling 100% buybox days, and gives example user queries. However, it does not explicitly differentiate from sibling tools like brand_buybox_trajectory or brand_under_attack.

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 specific example user queries ('brands with one seller', 'exclusive brands', etc.) and states when to use it. It lacks explicit exclusions or alternative tool suggestions, but the guidance is clear.

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

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

Annotations provide readOnlyHint=true, which is consistent with the description. The description adds behavioral detail about the output (viability qualifier, risks, validation steps) and states it provides 'honest' sourcing advice, not get-rich-quick promises. This goes beyond the annotation by describing the nature and tone of the results.

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 paragraph that front-loads the core purpose and then details the output. It is reasonably concise for the amount of information conveyed, though it could be slightly tighter. Every sentence adds value, with no wasted words.

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

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

Given the tool's complexity (diagnosing business model, returning a detailed assessment) and no output schema, the description covers the key aspects: input, process, and output format (viability qualifier, risks, etc.). It lacks specifics on data freshness or exact JSON structure but is sufficient for an agent to understand what the tool does and what it returns.

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% for both parameters (asin and marketplace_id). The description mentions 'Given an Amazon ASIN' but does not add significant new meaning beyond what the schema provides. Baseline of 3 is appropriate as the description does not compensate for missing schema details.

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

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

The description clearly states the tool's purpose: given an ASIN, diagnose business model, find supplier matches, and return a sourcing read with viability qualifier, differentiation, economics, risks, and validation steps. It distinguishes itself from siblings like 'evaluate_asin_sourcing' or 'alibaba_supplier_search' by emphasizing an honest, comprehensive lead generation output.

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 usage when an ASIN is available and a detailed sourcing analysis is needed, but it does not explicitly state when to use this tool versus alternatives (e.g., 'evaluate_asin_sourcing' or 'search_products'). No guidance on when not to use or prerequisites.

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 is consistent with the readOnlyHint annotation, stating it is a discovery tool. It adds important behavioral context such as being the flagship tool, detailing the default seller window, seed_brand constraint, and include_catchall filter, which goes beyond the annotation's scope.

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, using a single paragraph that front-loads the core purpose, then provides example queries and seed_brand usage. Every sentence adds value 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?

Given 18 parameters and no output schema, the description covers the main use case and seed_brand but does not describe the return format or results. It omits guidance on many parameters, which may leave the agent uncertain about the output. Slightly 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?

The input schema descriptions for parameters like min_sellers and max_sellers are already detailed and provide semantic meaning. The tool description adds value by explaining the purpose and context, though it does not elaborate on most parameters individually. With 56% schema coverage, the description supplements rather than repeats.

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 with low seller competition but real sales presence, and is identified as the flagship sourcing discovery tool. It distinguishes from siblings by providing specific user query examples and positioning as the primary sourcing tool.

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

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

The description explicitly lists when to use the tool with example queries and gives guidance on using seed_brand. It does not explicitly state when not to use or mention alternatives, but the provided examples sufficiently guide appropriate usage.

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 read-only nature is known. The description adds behavioral context: returns categories/subcategories only, never brands, ranked by private-label winnability using 2-year marketplace data. It does not contradict annotations. However, it lacks details on rate limits, pagination, or data freshness beyond what is implied.

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: starts with a bold key phrase, then explains purpose, followed by usage guidance and sibling exclusion. It is not excessively long and each sentence adds value. Minor improvement could be more brevity in listing example queries.

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 21 parameters, no output schema, and minimal annotations, the description covers purpose and usage well but does not describe the output format or how to interpret results (e.g., ranking criteria, data fields returned). For a tool of this complexity, more detail on return values would enhance 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 coverage is only 43%, meaning many parameters lack descriptions in the schema. The description adds context for a few parameters (e.g., default price range 20-70, unhappy_shoppers bias) but does not elaborate on the majority of the 21 parameters. For a tool with low schema coverage, the description should compensate more.

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 finds underserved niches (real subcategories) with genuine demand and room to compete, ranked by private-label winnability from 2-year marketplace data. It distinguishes from sibling tools that return brands, making the purpose 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 explicitly states 'This is the RIGHT tool for ANY niche-discovery question' and lists example queries. It also provides clear when-not-to-use guidance by naming sibling tools category_undercompeted_brands and find_undercompeted_brands that return brands instead. Additionally, it explains how to handle user-provided department names.

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

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

Annotations already set readOnlyHint=true, so no destructive behavior is expected. The description does not contradict and adds context on output (product details and metrics). It does not elaborate on other behavioral aspects like rate limits or data freshness, but with annotations covering safety, 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, front-loaded with the main action, and packs all essential information: output type, metrics, product details, and use cases. No redundant words; each 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?

Without an output schema, the description adequately explains return fields (metrics, product brand/title/price/fulfillment). It lacks details on error handling or behavior when marketplace_id is omitted, but the default and description cover the common case. Overall sufficient for a recommendation 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%; only marketplace_id has a description in the schema. The tool description does not add any detail for the asin parameter, nor does it expand on marketplace_id beyond what the schema provides. It misses an opportunity to clarify parameter usage, especially for asin.

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 recommends ungate/arbitrage/avoid for an ASIN, with a 3-bullet rationale citing specific metrics. It differentiates from siblings like evaluate_asin_sourcing by focusing on gating and pricing advice, and includes explicit use cases ('should I try to ungate this?' / 'how should I price this?').

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 for the tool, indicating when to use it. However, it does not mention alternatives or when not to use it, nor does it compare to sibling tools. The context is clear but lacks exclusions.

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

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

Annotations already declare readOnlyHint=true, so the description correctly implies a read-only operation. However, the description does not add further behavioral context such as what 'active' means, data freshness, pagination, or limits. With annotations covering safety, this is adequate but not enriched.

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 two sentences, front-loading the core action and following with usage cues. It avoids fluff, though a more structured breakdown (e.g., separating purpose from examples) could improve clarity for agents.

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 no description of return format or behavior, the description is insufficient. It does not explain what 'active' means, whether results are aggregated or per-product, or how violations are calculated. The tool is complex, but the description offers minimal 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?

The input schema has 18 parameters with only 39% description coverage, yet the tool description adds zero information about any parameter. This is a critical gap; the description must compensate for low schema coverage but fails entirely, leaving agents blind to parameter meaning beyond schema labels.

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' with a specific verb ('Show') and resource. It also provides example user queries, making purpose unmistakable and distinct from the long list of sibling tools, none of which focus on MAP violations.

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 queries that trigger this tool ('MAP violations', 'who is selling below MAP', etc.), offering clear context for when to use it. However, it does not mention when not to use it or suggest alternative tools, which would strengthen 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, indicating safe read-only operation. The description adds context that the tool returns brands ranked by competition level. It does not disclose potential rate limits, error handling, or authentication needs, but given the annotation, the description adds sufficient behavioral clarity.

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, well-structured sentence followed by example queries. It is front-loaded with the core purpose and avoids unnecessary words, making it easy to scan.

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 14 parameters and no output schema, the description lacks important details: no explanation of the return format (e.g., fields in results), no error handling or edge case guidance, and insufficient differentiation from sibling tools like 'brands_gaining_sellers' or 'find_undercompeted_brands'.

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%, meaning many parameters lack descriptions. The tool description does not explain individual parameters beyond the general purpose. It does not compensate for the low coverage, leaving many filter parameters (e.g., brand_contains, min_competitor_count) unexplained.

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 action: given operator names, return brands ranked by competition. It includes specific example queries, which cover the tool's scope and distinguish 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 provides clear when-to-use examples (e.g., 'which brands sold by these operators have the least competition'). It does not explicitly state when not to use or suggest alternatives, but the examples offer strong guidance for appropriate usage.

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 rich behavioral details: output structure with fields like situation, suggested_action, totals, pagination note, and sorting options. It does not contradict annotations, though it could mention authorization requirements.

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 concise despite its length. It is front-loaded with the core purpose, then details output, usage examples, and sorting/filtering without redundancy. Every 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?

Given 10 parameters, no output schema, and no nested objects, the description thoroughly covers all aspects: required parameters, optional filters, output fields, and sort options. It leaves no ambiguity for an agent to understand input and expected output.

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

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

Schema coverage is 100%, and the description adds contextual meaning beyond schemas, e.g., explaining max_buybox_share_pct's default as 'not dominating' and how situation_in is a comma-separated list. This enhances usability.

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 ASINs where a specific seller is losing the buy-box, ranked by revenue at risk. It includes specific verbs ('find', 'returns') and distinguishes from siblings like 'asin_buybox_history' by focusing on a single operator's losses with actionable suggestions.

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 example queries ('where is seller X losing the buy-box', etc.), giving clear guidance on when to use the tool. However, it does not explicitly state when not to use it or mention alternative 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 already declare readOnlyHint=true. The description adds that results are ranked by brand count and buybox days, which is helpful. No additional behavioral traits (e.g., rate limits, data freshness) are disclosed. 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 with two sentences plus query examples. It front-loads the core purpose. However, it could be slightly more structured (e.g., bullet points for parameters).

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

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

No output schema is provided, but the description explains the return structure (categories ranked by metrics). With 11 parameters, low schema coverage, and no output schema, the description is moderately complete but not fully comprehensive.

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 at 27%. The description mentions key metrics but does not explain the meaning of many parameters (e.g., limit, category_name_contains, min/max fields). It adds minimal value beyond the parameter names and brief schema descriptions.

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

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

The description clearly states the tool shows categories dominated by an operator, ranked by brand count and buybox days. Example queries are provided. However, it does not explicitly differentiate from similar sibling tools like 'operator_top_brands' or 'operator_brands_by_competition'.

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 examples and query patterns, but lacks guidance on when not to use this tool or mentions of alternative tools for related questions.

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 that the label is heuristic, not legal, and explains input signals (cross-brand data). This provides useful behavioral context beyond the annotation.

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

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

The description is concise (three sentences) with a clear front-loaded purpose, usage examples, and a caveat. Every sentence adds value.

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