amazon-product-research-mcp

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

Annotations declare readOnlyHint=true, and the description adds behavioral context: it uses Serper, scrapes site:alibaba.com, and clarifies that price/photo are unavailable. 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 (two sentences), front-loads the main action and return fields, and adds a necessary limitation note. Every sentence is valuable.

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

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

Despite no output schema, the description adequately describes the return fields and limitations. For a single-parameter search tool, it covers all necessary 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% with a clear description of the 'query' parameter. The tool description does not add further parameter 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 the verb 'Find', the resource 'Alibaba supplier / manufacturer listings', and specifies the return fields (title, rating, snippet, link). It distinguishes itself from sibling tools by focusing on Alibaba via Serper.

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 tells when to use (for a query) and what limitations exist (text only), but does not explicitly state when not to use or compare to alternative tools like shopping_search or find_product_across_web.

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 beyond that: it details the output (per-week breakdown, monthly distinct-seller-count, seller_trend label, product brand/title/price/fulfillment). 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 lengthy (5+ sentences) and includes many example queries and output details. While it front-loads the main purpose, some sentences are repetitive (e.g., the 'Use when' clause restates earlier examples). It could be more concise without losing clarity.

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

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

Given the high parameter count and no output schema, the description provides a good overview of the return values and use cases but omits explanation of the many filter parameters. It assumes the agent will interpret the schema alone, which is incomplete due to low coverage.

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 (30%), meaning many of the 27 parameters lack schema descriptions. The tool description does not compensate by explaining any parameters beyond the required ASIN. It only mentions price and fulfillment in the context of output, not as filters. This leaves the agent without guidance for most parameters.

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

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

The description states a specific verb ('Show') and resource ('which sellers have been winning the buybox for an ASIN over time'), and distinguishes from siblings like brand_buybox_trajectory by focusing on a single ASIN with historical breakdown and seller pool changes.

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 six example user queries that trigger this tool, such as 'who has been winning buybox on this ASIN' and 'is the seller pool stable or volatile'. It does not explicitly state when not to use it or mention alternatives, but the context signals and sibling list make it relatively 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 declare readOnlyHint=true, so the agent knows it's a safe read operation. The description adds value by specifying the output format (product brand, title, price, fulfillment), which goes beyond annotations. 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?

Two well-structured sentences: first states the core function with filters, second provides usage examples and output details. Every sentence is necessary and front-loaded with the most critical information.

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

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

Given the tool has 19 parameters and no output schema, the description covers the core functionality, typical usage, and key output fields. It does not explain default behaviors (e.g., limit, ordering) or less common parameters, but it is sufficient for common use cases.

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 32%, so the description partially compensates by mentioning key filtering dimensions (brand, price band, seller count). However, many parameters (e.g., max_days_observed, buybox_seller_contains) remain undocumented in both schema and description, limiting the agent's ability to use 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 clearly states the tool finds ASINs similar to a given ASIN, with specific filtering criteria. It distinguishes itself from siblings (e.g., brand_similar) by focusing on ASIN-level lookalikes. The verb 'Find' and resource 'ASINs similar' are precise and not tautological.

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 query patterns that trigger this tool: 'ASINs like this one', 'similar products', 'comparable ASINs', etc. This guides the agent on when to select this tool over alternatives, though it would benefit from mentioning when not to use it (e.g., for brand-level similarity).

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 no mutations. It adds detail on what the tool computes (profit margin) and returns (brand, title, price, fulfillment), enhancing transparency 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 two sentences: first covers purpose and inputs, second lists additional outputs and example queries. No redundant information; every sentence serves a purpose.

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

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

Given no output schema, the description adequately describes returns (brand, title, price range, fulfillment) and the primary scenario. Could be slightly more detailed on output structure, but sufficient for agent invocation.

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

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

Schema coverage is 100%, but the description adds value by explaining the 'cogs' parameter's default behavior (estimates breakeven if omitted). This provides practical insight not in the schema.

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

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

The description clearly states the tool estimates profit margin for a given ASIN, specifying inputs and outputs. It distinguishes from sibling tools like 'asin_buybox_history' and '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 provides explicit usage scenarios ('can I make money on this ASIN', 'profit calculator') and lists example queries. It lacks explicit when-not-to-use guidance, but the context is clear given the sibling tools.

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

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

Annotations already provide readOnlyHint=true. The description adds that it 'list[s]' and provides example queries, but does not elaborate on return format, pagination, or other behavioral details. With the annotation, the behavioral profile is clear, 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 very concise: two sentences. The first states the purpose, the second gives usage examples. 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?

For a simple list tool with readOnlyHint and no output schema, the description is sufficient. It clearly explains what the tool does and when to use it. The only minor gap is no mention of the return format, but it's not critical.

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

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

Schema coverage is 100%, so the schema already documents all parameters. The description adds no additional parameter details beyond the schema. Baseline 3 is correct.

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 'List' and resource 'authorized sellers for a brand'. It provides example user queries, making the purpose unmistakable. It is clearly distinct from sibling tool 'authorized_seller_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 gives explicit use cases: 'when the user asks who are my authorized sellers...' This helps an agent know when to invoke. It does not mention when not to use, but the context is clear enough for a read-only 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?

Discloses write operation (consistent with readOnlyHint=false), brand tracking prerequisite, and precision requirement for seller names. Does not address whether previous list is overwritten or appended, leaving minor ambiguity.

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 explains purpose and benefit, second provides usage examples and critical instruction. Every sentence earns its place, 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?

No output schema, and description omits response behavior (e.g., success confirmation, error messages). For a simple save operation, this is adequate but lacks detail on side effects like overwriting behavior.

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%, but description adds value by emphasizing seller names must match Amazon exactly and reinforcing brand tracking. This supplemental guidance aids correct parameter 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 explicitly states the tool saves authorized sellers for a brand, enabling unauthorized seller detection. It uses specific verb 'save' and resource 'authorized sellers for a brand', clearly distinguishing from sibling 'authorized_seller_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 when-to-use examples (e.g., 'these are my authorized sellers for X') and prerequisite (brand must be tracked). Does not explicitly mention when not to use, but context with sibling tools implies listing is for reading.

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

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

Annotations declare readOnlyHint=true, so the description is not required to state safety. It adds context about returning weekly seller counts and observed buybox days for a trailing window. However, it does not disclose behavior for edge cases (e.g., no data) or permission requirements, which is acceptable given the read-only annotation.

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

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

The description is extremely concise: two sentences and a usage line. It is front-loaded with the core purpose and example queries, with no extraneous 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?

Despite having 16 parameters and no output schema, the description provides minimal overview of what the tool returns (weekly seller counts and observed buybox days) but does not explain key parameters or output structure. This is insufficient for a tool with such complexity.

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

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

Schema description coverage is only 38% (6 of 16 parameters have descriptions). The tool description adds no parameter explanations beyond what is in the schema, failing to compensate for the low coverage. For example, the 'trend_in' parameter is described in schema but the description does not clarify its role.

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 'Show' and resource 'brand's buybox concentration trajectory' with specific example queries. However, it does not explicitly differentiate from sibling tools like 'operator_concentration' or 'find_deconcentrating_brands' that also analyze competition over time.

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 ('is this brand getting more competitive', 'concentration trend for Nike') that indicate when to use the tool. It does not specify when not to use it or mention alternatives, but the guidance is clear enough.

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 confirms read-only behavior. It adds detail about returned data fields (brand, title, price, fulfillment). No side effects or restrictions mentioned, but adequate given annotations.

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

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

Two sentences: first states purpose, second provides usage examples and return info. Very concise and front-loaded with essential information.

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

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

Given the tool's complexity (26 params, many siblings), the description covers core use case and output fields. However, it lacks explanation of parameter meanings and doesn't fully compensate for missing output schema.

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

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

Schema coverage is only 31%, and the description does not explain any parameters. For a tool with 26 parameters, description should provide guidance on key filters like since_days, limit, etc. It fails 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 it shows ASINs that recently appeared for a brand and gives example queries. It distinguishes itself from sibling tools by focusing on new additions for a specific 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?

The description provides example user queries to indicate when to use the tool. It does not explicitly state when not to use or list alternatives, but the context is clear.

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

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

Warns that signal is based on observation, not confirmed market entry, due to sparse re-sampling. Adds value beyond readOnlyHint annotation. Could mention data freshness or limitations more explicitly.

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 focused sentences plus usage examples. Front-loaded with main purpose, then caveat, then usage. No extraneous 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 use case and warning about signal reliability, but with 17 parameters and no output schema, lacks details on many parameters and return format. Adequate but not comprehensive for complexity level.

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?

Description covers only key parameters (category filter, window_days default/max) and brand match. With only 35% schema coverage, many parameters (e.g., min_new_sellers, control scores) remain unexplained. Some compensation but insufficient for a 17-param tool.

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

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

Description clearly states it finds brands gaining newly-OBSERVED sellers, distinguishes from confirmed market entry, and provides specific user query examples. Differentiates from sibling tools like find_brands_with_high_seller_churn.

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 intents (e.g., 'brands gaining sellers in [category]', 'brands under hijacker pressure') and notes it's for category-scoped signals without naming a brand. Lacks explicit when-not-to-use or alternative tool references, but context provides 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, indicating safe read behavior. The description adds context about selection criteria (category, price tier, competition level) but does not disclose data freshness, computation method, or limitations. With annotations covering safety, this is adequate but not rich.

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

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

The description is three sentences, with the core purpose in the first sentence and usage guidance in the second. It is front-loaded and concise with no superfluous information.

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

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

Given 14 parameters and no output schema, the description is insufficient. It does not explain what the tool returns, how similarity is computed, or provide guidance on parameter combinations. A more complete description would include example parameter usage or note that results are sorted by similarity.

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 (29%), and the description does not explain individual parameters beyond vague references to 'category, price tier, and competition level'. Many parameters like min_asin_count, max_control_score, and limit are left entirely unexplained. The description fails to 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 uses a specific verb+resource ('Find brands similar') and includes explicit example queries ('brands like Nike', 'similar brands to source'), clearly distinguishing it from many sibling tools focused on operators, categories, or individual ASINs.

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

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

The description provides concrete when-to-use scenarios with example user queries. However, it does not mention situations where this tool is not appropriate or recommend alternative tools for deeper analysis, which would be helpful given the large number of sibling tools.

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

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

The annotations already declare readOnlyHint=true, so the description's job is to add context. It does so by explaining the output order ('ranked by how many operators they share') and the underlying concept ('reveals the operator graph'). No contradictions with annotations. The description adds value beyond the annotation by clarifying what 'read-only' means in this 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 extremely concise: two sentences plus a list of example queries. It front-loads the purpose and then provides immediate usage guidance with examples. Every sentence earns its place without fluff or repetition.

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

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

Given the high parameter count (12), low schema coverage (33%), and lack of output schema, the description is somewhat incomplete. It explains the main output concept (ranked brands by shared operators) but does not describe the output structure, default limit, or how filters interact. A typical usage example would enhance completeness. For a complex tool, more detail is needed to guide 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?

Schema description coverage is only 33% (4 of 12 parameters have descriptions). The tool description mentions only the 'brand' parameter implicitly and the concept of 'shared operators', but does not explain the numerous filter parameters (min/max seller_count, control_score, etc.). A tool with so many parameters requires the description to compensate for low schema coverage, which it fails to do.

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/sellers with a target brand, with ranking by shared operators. This specific verb+resource combination distinguishes it from siblings like 'brand_similar' or 'operator_brands_by_competition', which focus on different aspects of brand relationships.

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 ('what brands are in X's network?', 'brands related to Ninja', etc.) that signal when to use this tool. It explains the concept of 'operator graph' and shared distribution channels, giving clear context. While it doesn't mention when not to use or provide alternatives, the examples make the use case obvious.

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 behavioral context (brand-level first-seen stability). No contradiction. However, it lacks details on response format or error handling, which would be beneficial given no output schema.

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 relatively concise with two sentences, front-loading the purpose. The second sentence is slightly dense but informative. 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 (5 params, no output schema), the description covers detection logic, metric distinction, and usage cues. It does not address return format or edge cases, but for a detection tool it is reasonably complete.

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

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

Schema description coverage is 100%, so parameters are well-documented in the schema. The description adds conceptual context (e.g., signals_in values) but does not significantly enhance parameter semantics beyond schema.

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

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

The description clearly states the tool's purpose: 'Detect whether a brand is under competitive attack' with specific criteria (elevated new-entrant rate + buy-box churn). It distinguishes itself by emphasizing brand-level first-seen vs per-ASIN count, and its focus on attack detection is unique among siblings.

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

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

The description provides explicit use cases: 'Use when the user asks...' with example queries. It does not mention when not to use or list alternatives, but the context is clear and directed.

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, so description's mention of returns adds moderate context. No contradiction, but no further behavioral details like rate limits or auth needs.

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 efficient sentences: first states purpose and outputs, second gives usage examples. No wasted words, front-loaded with key info.

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 clear purpose, 10 parameters with low schema coverage and no output schema make the description incomplete. Missing details on filtering and 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?

With only 20% schema coverage, description fails to explain 8 undocumented parameters (e.g., min/max counts, marketplace_id_in). No parameter guidance beyond brand.

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, listing specific return fields. It distinguishes from sibling tools like operator_xmarket_presence by focusing on 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 user queries ('does this brand sell on Walmart', etc.), guiding when to use. Missing explicit when-not-to-use or alternatives, but usage 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?

Description reveals read-only behavior (consistent with annotations), output fields (brand, title, price, fulfillment), and fallback behavior without saved list (flags all third-party buy box holders). 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?

Concise and front-loaded: first sentence covers main purpose, second adds output details, third gives prerequisite, fourth provides example queries. No redundant sentences.

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

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

Adequate for basic understanding: covers purpose, output, and prerequisite. But lacks details on the many filter parameters (price, fulfillment, etc.) and output schema, leaving gaps for complex queries.

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

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

Schema coverage is only 27% with 26 parameters. Description does not explain any filter parameters beyond mentioning output fields. Fails to compensate for missing schema descriptions, making parameter usage unclear.

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

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

Clearly states verb 'find' and specific resource 'ASINs where brand lost buy box to unauthorized seller'. Includes ranking by estimated revenue at stake. Distinguishes from siblings like operator_buybox_losses and brand_buybox_trajectory.

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 prerequisite: use authorized_seller_set first. Offers example queries indicating when to use. Does not explicitly mention when not to use, but context is clear. No comparison to alternatives, but sibling differentiation is implied.

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

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

Annotations declare readOnlyHint=true, so the tool is a read operation. The description adds behavioral context: it uses the metric amazon_expansion_net_90d < 0, returns categories ordered by retreat magnitude, and is over a 90-day window. 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 three sentences, front-loaded with the main purpose, then ordering, then usage examples. Every sentence adds value with no redundancy or filler.

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

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

Given the complexity of 15 parameters and no output schema, the description adequately covers purpose and usage but lacks parameter details and return value structure. It is sufficient for an experienced user but not fully self-contained.

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

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

Schema description coverage is only 27%, with 15 parameters but no parameter explanations in the description. The description does not add meaning beyond the parameter names and types provided in the schema. This fails to 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 the tool finds categories where Amazon is retreating, defined by net brand exits exceeding entries over 90 days. It uses specific verbs ('Find') and resources ('categories'), and distinguishes from sibling tools by focusing on retreating categories.

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 ('where is Amazon pulling back?', 'which categories is Amazon leaving?', 'Amazon retreat opportunities'), guiding when to use the tool. It lacks explicit 'when not to use' but the examples cover typical 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, so the description does not need to reiterate safety. It adds value by listing the comprehensive set of metrics returned (demand, competition, Amazon presence, price, etc.), giving the agent a clear picture of the tool's output. 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, front-loaded with the core purpose. The first sentence establishes scope and the second lists metrics. Every word earns its place; no redundancy or filler.

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

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

Despite lacking an output schema, the description fully explains what the tool returns by listing all metric groups. The three parameters are well-described in the schema, and the description complements them with usage context. Given the complexity (many metrics), this is complete enough for an agent to invoke correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds minor value by noting that category_name supports fuzzy matching and that marketplace defaults to US (2). It does not delve into parameter formatting or constraints beyond what the schema provides.

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

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

The description starts with 'Return the full metric set for ONE category at any depth', clearly stating the action and resource. It distinguishes from sibling tools by specifying 'ONE category' and enumerates the exact metrics covered, leaving no ambiguity about what the tool does.

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 ('show me the metrics/stats for category X', 'how big is the X category') that tell when to use this tool. It does not explicitly state when not to use it, but the context is clear enough to avoid misuse.

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

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

The annotations already mark the tool as read-only (readOnlyHint=true). The description adds key behavioral nuance: it's an observation signal, not a true first-entry parser due to sampling sparsity. This warns the agent about potential inaccuracies. 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 extremely concise: two sentences plus a list of example queries. Every sentence adds value, and the most important information (purpose and caveat) appears first. 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 has 17 parameters, no output schema, and only 35% schema coverage, the description should provide more context. It lacks details on output format, parameter interactions, or result interpretation. The description only covers high-level purpose and one caveat, leaving the agent underinformed.

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

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

Schema description coverage is low (35%), so the description should compensate by explaining key parameters. However, the description does not elaborate on any parameter meanings; it only describes the tool's overall function. Thus, it adds little value beyond the sparse schema.

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

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

The description clearly states the tool's goal: finding brands newly observed in a category within a date window. It uses specific verb 'Find' and resource 'brands newly OBSERVED in a category', and distinguishes from a common misinterpretation (confirmed first-ever entry). This sets it apart from siblings like brand_new_asins and category_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?

The description provides explicit usage scenarios: 'when the user asks 'new brands in Electronics', etc. It also clarifies what the tool is not (confirmed first-ever entry). However, it does not mention when not to use or list alternative tools among the many 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 no destructive behavior. The description adds that it compares recent period to earlier period, which is useful context, but does not disclose other behavioral traits like pagination or sorting.

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, consisting of two sentences that efficiently convey purpose and usage examples without extraneous information.

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

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

Given no output schema and many sibling tools, the description does not explain the return format or how parameters interact, making it incomplete for an agent to effectively 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 description coverage is only 26%, and the description provides no additional details about the 19 parameters, leaving the agent with insufficient guidance on parameter 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 finds brands with biggest recent growth in seller count and observations within a category, and provides specific example queries that distinguish it from sibling tools.

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

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

The description explicitly lists example user queries to trigger this tool, but does not mention when not to use it or suggest alternative tools for different 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?

The description explains the filtering logic of 'min-seller floor drops single-seller / brand-owner-only listings' and clarifies that results are BRANDS, not niches. Annotations show readOnlyHint=true, and the description adds behavioral context without contradiction.

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

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

The description is moderately concise, front-loaded with purpose, and each sentence serves a purpose. A slight reduction in length could improve conciseness, but it remains efficient.

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

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

Given 17 parameters, no output schema, and annotations providing readOnlyHint, the description explains the core purpose and key filtering logic. It could more thoroughly cover expected return format, but overall adequately sets context for a read-only brand query 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 53%, so many parameters are not described. The description adds context for min_sellers ('drops single-seller / brand-owner-only PL junk'), but overall does not significantly compensate for the missing parameter 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 finds 'specific BRANDS within a category that have proven multi-seller demand but are still under-competed', using specific verbs and resource. It explicitly distinguishes from sibling tools like find_underserved_niches for subcategory questions.

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

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

The description provides explicit when-to-use examples ('undercompeted brands in <category>', 'low competition brands in Toys') and when-not-to-use examples ('under-served niches', 'niches in <category>'), including the alternative tool name (find_underserved_niches).

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 only readOnlyHint=false (not read-only). Description adds context: it's a 'LIVE, on-demand snapshot' implying real-time fetching, which is a behavioral trait. However, it doesn't disclose potential side effects (e.g., cost, caching) that might be relevant given readOnlyHint=false. Still, adds value beyond sparse 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?

Single, dense paragraph with clear front-loading: verb, resource, and key qualifiers. Every sentence adds value—purpose, usage hints, constraints. No redundancy or 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?

For a tool with 2 params and no output schema, the description fully covers what the tool does, what it returns (current data plus historical intelligence), and its constraints. An agent has enough to invoke correctly.

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

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

Schema coverage is 100%, so both parameters have descriptions. Tool's description reinforces the US-only constraint and one-ASIN limit but doesn't add significant new parameter-level meaning. 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 verb 'Pull', resource 'single Amazon ASIN', and specific data returned (title, price, offers, sellers, historical intelligence). It distinguishes from pre-collected dataset and sibling tools by emphasizing 'LIVE, on-demand snapshot' and specifying 'Amazon US only; one ASIN per call'.

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

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

Explicitly states when to use: 'when the user gives a specific ASIN and wants its CURRENT/today's data rather than the pre-collected dataset'. Provides example phrases ('check ASIN B0... right now'). Also specifies constraints (Amazon US only, one ASIN per call), implicitly guiding against misuse.

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

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

Annotations already provide readOnlyHint: true, so the description is not required to re-state safety. The description adds that it returns specific metrics and week-over-week deltas, which is useful but not deep behavioral context. No discussion of data freshness or limitations.

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

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

The description is two sentences long, front-loading purpose and outputs, then adding usage cues. It is concise and well-structured, though could be slightly more organized with bullet points.

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 30 parameters, low schema coverage, no output schema, and many sibling tools, the description is insufficient for an agent to use effectively. It lacks parameter guidance and does not help differentiate from similar tools like 'brand_buybox_trajectory' or 'category_metrics'.

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%, leaving 90% of parameters undocumented. The description does not compensate by explaining any parameters; it mentions 'brand or category root' but does not specify which parameters to use (e.g., 'brand' or 'category_root_id'). This is a major gap for an agent.

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, listing specific outputs (top 10 sellers, top 10 brands, deltas). It distinguishes from many sibling tools by focusing on landscape mapping, but does not explicitly differentiate from tools like 'category_metrics' or 'brand_buybox_trajectory'.

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 cues are given: 'Use when the user asks who's winning this category? or who controls the buybox here?' This provides clear context for when to invoke, but no when-not-to-use instructions or alternative tool mentions.

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

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

Annotations only indicate readOnlyHint=true. The description adds extensive behavioral context: it explains how null demand indicates a coverage gap, describes data_coverage_flag, rating_coverage_flag, and red flag list. It also details the return structure beyond what annotations provide, with no contradiction.

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

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

The description is long but packed with valuable information. It front-loads the main purpose and then details outputs and usage. Every sentence contributes, though it could be slightly more concise. Still, it is well-structured 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?

Given the complexity (no output schema, many return values), the description thoroughly explains all outputs: scores, demand estimates with flags, ratings, brand dominance, red flags, fulfillment info. It covers all necessary context for an agent to understand what the tool returns and how to interpret edge cases like null demand.

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 significant new meaning beyond the schema; it only mentions the marketplace_id default in passing. Since schema already documents the parameters, the description adds minimal value here.

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 explicitly states the tool evaluates a single ASIN for FBA sourcing, listing specific outputs (composite score, 5-dimension breakdown, demand estimates, etc.) and use cases. It clearly distinguishes from sibling tools like asin_profit_calc or asin_comparables by focusing on sourcing evaluation.

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 guidance on when to use the tool: 'when the user asks 'should I buy this?', 'how fast does this sell?', or shares an ASIN and wants a sourcing recommendation.' This directly tells the agent the appropriate contexts.

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 read-only nature is clear. The description adds value by detailing all return fields (e.g., control posture, HHI, churn rate, top ASINs), giving the agent a good understanding of what to expect.

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, front-loaded with the main action, then lists outputs and usage examples. 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?

For the primary use case (just a brand name), the description is complete. However, given the 27 optional filtering parameters and no output schema, the description could better explain how to use filters like distribution_verdict_in or price ranges.

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% (6 of 27 parameters described). The tool description does not explain any parameters beyond the implicit brand. It relies on schema descriptions, which are sparse. The description should bridge the gap but fails to do so.

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 evaluates a brand for portfolio inclusion, lists specific outputs, and provides example user queries. It is distinct from sibling tools like evaluate_asin_sourcing (ASIN-level) and evaluate_category_for_private_label (category-level).

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

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

Description explicitly says 'Use when the user names a brand and asks...' which is clear guidance. While it does not explicitly state when not to use, the context of sibling tools suggests alternatives are available.

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 and adds value by detailing the output (per-signal breakdown and verdict). No behavioral 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?

The description is front-loaded with purpose, concise (three sentences), and contains no unnecessary 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?

The description explains the return value well, given no output schema. It covers inputs implicitly but could mention parameter optionality.

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 only adds minimal value (e.g., 'ANY depth'). The output description does not enhance parameter understanding.

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 assesses whether a category is winnable for a new private-label brand and provides example queries. However, it does not explicitly distinguish this tool from sibling category 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 gives example queries that imply usage, but lacks explicit guidance on when to use this tool versus 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 indicate readOnlyHint=true, so no contradiction. The description adds the computation formula and interpretation of thresholds, which is beneficial 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 extremely concise: three sentences front-loading the purpose, formula, and 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 the complexity (18 params, no output schema), the description covers the core functionality well. It could mention output format or pagination, but the main use cases are adequately addressed.

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

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

Schema coverage is low (33%), and the description only elaborates on key parameters (fba_share_op, fba_share_value, sort_by). Many parameters (min/max scores) lack explanation in both schema and description, leaving gaps.

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

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

The description clearly states it returns brands filtered by FBA buybox share threshold, with the formula provided. It distinguishes from siblings like filter_operators_by_fba_share by focusing on brands and providing use-case 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 gives explicit use cases (FBM-heavy vs FBA-dominated) and mentions sorting options. It lacks explicit comparison to sibling tools but provides enough context for 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 read-only nature is covered. The description adds context about the 0-100 percentage range and brand filtering. However, it does not mention pagination, default sorting, or any behavior for missing optional parameters. With annotations present, the description is adequate but not comprehensive.

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-load the main purpose and usage examples. Every sentence adds value with no redundancy. Efficient and well-structured.

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

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

Despite the complexity of 20 parameters and no output schema, the description only covers 3 parameters. Many optional filters (e.g., min_avg_rating, max_brands_touched, sort_by) are not mentioned, leaving agents unaware of their existence. Significant gap in completeness for a parameter-heavy 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 30%, meaning many parameters are undocumented in the schema. The description explains key parameters (fba_share_op, fba_share_value, brand) but does not add meaning for the remaining 17 parameters like min_avg_rating, max_asins_touched, etc. It compensates partially for the low coverage but not fully.

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 operators filtered by FBA buybox share threshold, specifying the resource (operators) and action (filter by percentage). It distinguishes from sibling 'filter_brands_by_fba_share' by targeting operators instead of 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?

Provides explicit guidance with examples: 'Use fba_share < 50 to find FBM-leaning operators...' and includes the optional brand filter to narrow results. Clearly indicates when to use each comparison operator and threshold.

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

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

Annotations already mark readOnlyHint=true. Description adds behavioral context: specifies the exact metric (seller_churn_30d_delta_vs_cat_pp), default threshold (5pp), and optional category filter. 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?

Extremely concise: two sentences, front-loaded with the verb 'Find', no redundancy, each sentence adds essential 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?

For a read-only tool with 13 parameters and no output schema, the description covers the core logic and usage triggers. Could mention return format or empty results handling, but not critical.

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

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

Schema description coverage is 62%, placing baseline around 3. The description adds value for the primary parameter (min_delta_pp) with default and threshold explanation, but does not cover other parameters like brand_contains, max_delta_pp, or velocity tiers.

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

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

Clearly states it finds brands with high seller churn relative to category, specifies the metric and default threshold. Does not explicitly differentiate from sibling tools like 'brands_gaining_sellers', but the description implies uniqueness by focusing on churn relative to category.

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

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

Provides explicit usage triggers: 'Use when the user asks about brands losing sellers, high churn brands, or seller instability.' Lacks explicit when-not-to-use or alternative tools, 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 already declare readOnlyHint=true. The description adds business context ('more sellers entering, creating opportunity for new entrants') but does not disclose data freshness, pagination, or result limits 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?

The description is a single sentence plus a list of example queries. It is front-loaded with purpose and efficient, though the list could be slightly more compact.

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 16 optional parameters and no output schema, the description omits important context like return format, how filters interact, or result sorting. Incomplete for a tool of this complexity.

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

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

Schema description coverage is only 25%, but the description adds no parameter-specific details. It fails to compensate for the low coverage, leaving 12 parameters undocumented in either schema or description.

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

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

The description states a specific verb ('find') and resource ('brands where buybox concentration dropped over the last quarter'), clearly distinguishing this tool from siblings like 'brands_gaining_sellers' or 'find_undercompeted_brands'.

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

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

The description provides explicit query examples ('brands losing control', 'gentrification opportunities'), offering clear usage context. However, it does not specify when not to use this tool 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, so the description adds value by explaining that the tool reports observations, not confirmed market entries, and that sparse sampling can cause false positives. This is 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, front-loading the core purpose, then providing the caveat and usage guidance in a clear, efficient manner. 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?

Despite having many parameters and no output schema, the description does not explain what data is returned or how to interpret results beyond the observation caveat. For a complex tool, this leaves significant gaps in understanding 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?

Schema description coverage is only 28%, and the description does not elaborate on any parameter semantics. With 18 parameters, many lacking descriptions, the tool definition fails to help the agent understand parameter usage beyond what little is in the schema.

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

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

The description uses a specific verb-resource combination 'Find operators we FIRST OBSERVED selling recently' and clearly distinguishes from sibling tool 'top_expanding_operators' by noting the difference in what they track (newly observed vs. expanding).

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

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

Provides explicit guidance on when to use this tool (e.g., 'new sellers this month', 'who just started selling') and contrasts with 'top_expanding_operators.' It also includes a caveat about the observational nature of the signal.

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 describes a read-only query operation ('Find where one product sits'), but annotations set readOnlyHint=false, implying mutation. This contradiction undermines transparency. No mention of side effects or permissions.

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?

Single paragraph front-loaded with purpose and key inputs. Every sentence serves a purpose—no fluff. Efficiently covers all critical aspects in a compact form.

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 17 parameters and no output schema, the description explains return values and key filters. Minor gaps in filter parameters but overall sufficiently complete 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?

Adds significant meaning beyond the input schema by explaining identifier groups, modes, and return fields. With 65% schema coverage, the description compensates well, though some parameters (e.g., source_contains) lack elaboration.

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 a product across retailers with a live price check anchored to Amazon buy-box. It specifies identifier options and modes, distinguishing it from sibling tools like 'shopping_search' or 'xmkt_pricing_compare'.

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 clear input instructions: give one identifier and a mode. Lists all modes and their meanings. However, does not explicitly state when to avoid this tool or mention alternatives, though context is sufficient for typical 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?

The annotations already declare readOnlyHint=true. The description adds context that 'single operator controls 100 percent of observed buybox days' and explains these are gated/exclusive or operator-acquired brands, but does not discuss data freshness, rate limits, or other behavioral traits 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?

The description is two focused sentences plus a usage note, front-loaded with purpose and examples. 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?

With no output schema, the description should explain what results look like (e.g., list of brands, with metrics), but it only describes the core logic. Additionally, 5 parameters lack schema descriptions and the tool has 13 parameters, making it incomplete for an agent to understand filtering and output without further context.

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

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

Schema coverage is 62% with descriptions for 8 of 13 parameters. The description does not add any parameter-level information beyond the schema, and the missing parameters (limit, brand_contains, control scores, etc.) remain undocumented. The description does not compensate for the uncovered 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 with a single operator controlling 100% of buybox days, gives examples of gated/exclusive brands, and provides user query examples. This clearly distinguishes 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?

The description explicitly tells when to use the tool with example queries ('brands with one seller', 'exclusive brands', etc.), but does not mention when not to use it or offer alternative tools for related queries.

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, consistent with the description's diagnostic and research nature. The description adds context by detailing the output's honesty and risk factors, going beyond annotations. No contradiction.

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

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

The description is front-loaded with the main purpose and provides detailed output structure. While slightly verbose, each sentence adds value without redundancy. It is appropriately sized for the complexity.

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

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

Given no output schema, the description comprehensively describes the return value (viability qualifier, move, economics, risks, validation). It covers all necessary context for a research tool, making it 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 both parameters ('asin', 'marketplace_id') adequately described. The description does not add additional semantic meaning beyond the schema, achieving the baseline of 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?

The description clearly states the tool's function: diagnose business model from an ASIN, find supplier/wholesale/arbitrage matches, and return a viability assessment with specific components (qualifier, move, economics, risks, validation). It distinguishes from sibling tools like 'evaluate_asin_sourcing' by emphasizing its comprehensive, honest sourcing read.

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

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

The description implies usage for sourcing research given an ASIN, but does not explicitly state when not to use or compare to alternatives like 'evaluate_asin_sourcing' or 'find_product_across_web'. Guidance 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 declare readOnlyHint=true, and the description aligns as a discovery tool. It adds behavioral context like 'flagship sourcing discovery tool', explains seed_brand scopes to root category, and clarifies min_sellers default drops single-seller brands. 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?

The description is three sentences, front-loaded with purpose, and every sentence adds value without redundancy. Extremely concise and well-structured.

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

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

Given the 18 parameters and lack of output schema, the description adequately covers the tool's purpose and key behaviors. It could mention return format, but it's sufficient for selection among 70+ sibling tools.

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 56% schema coverage, the description adds meaningful context for key parameters like seed_brand and min_sellers (explaining the default 10-20 window for under-competed but real demand). It compensates for the coverage gap on important 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 with low seller competition but real sales presence' and calls it 'the flagship sourcing discovery tool', which is a specific verb+resource and distinguishes it from sibling tools like 'category_undercompeted_brands' or 'find_sourcing_opportunities'.

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

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

The description provides explicit when-to-use examples: 'Use when the user asks...' and explains how seed_brand is used for reference brands. It doesn't explicitly exclude alternatives but gives clear usage context.

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

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

The description adds useful behavioral context beyond the readOnlyHint annotation: returns subcategories (never brands), uses 2-year marketplace data, ranks by private-label winnability. It does not contradict annotations (readOnlyHint aligns with a search/analysis tool). Minor omission: no mention of caching or real-time data.

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 summary, then provides usage examples and explicit do-not instructions. It is reasonably concise for the amount of information conveyed, though slightly verbose in listing query 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?

While the description covers purpose and usage well, it lacks details about the output format (e.g., what fields are returned for each niche). Given the absence of an output schema, this is a notable gap. The extensive filter parameters are also not explained beyond the schema descriptions, leaving some ambiguity for an agent.

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

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

The description adds meaningful guidance for the category_name parameter ('pass it as category_name to scope'). However, with 21 parameters and only 43% schema description coverage, the description does not compensate for the gaps. Many filter parameters remain unexplained, and the description adds no extra semantics beyond the schema for most.

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

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

The description clearly defines the tool's purpose: finding under-served niches (subcategories) ranked by private-label winnability. It explicitly distinguishes from sibling tools that return brands, and provides concrete examples of subcategories, making the purpose unambiguous.

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

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

Excellent usage guidance: explicitly lists the types of questions this tool should handle, provides a usage tip for passing category_name, and warns against using sibling tools for niche questions. This leaves no ambiguity about when to use this tool vs 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, and the description explains the output (rationale with named metrics, product details). It adds context beyond annotations, though does not disclose limitations or data freshness.

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

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

The description is two sentences, front-loading the primary action and listing key return elements. It is efficient without 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?

Given no output schema, the description adequately explains the return values (rationale with metrics, product details). The tool is simple with two parameters, and the description covers the main purpose and 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?

The description mentions ASIN and implicitly the market context, but does not provide detailed semantic meaning for each parameter beyond what the input schema offers. Schema coverage is 50%; the description adds modest extra value.

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

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

The description clearly states it recommends ungate/arbitrage/avoid for an ASIN, with specific metrics. It is a specific verb+resource combination, but does not explicitly distinguish from sibling tools like evaluate_asin_sourcing which may overlap.

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 ('should I try to ungate this?', 'how should I price this?'), but does not mention when not to use the tool or list alternative sibling tools for similar tasks.

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

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

Annotations already declare readOnlyHint=true, and the description aligns by stating 'Show'. No additional behavioral traits (e.g., rate limits, data freshness) are disclosed. The description adds minimal context beyond the annotation, so a 3 is appropriate.

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

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

Two sentences: first clearly states purpose, second provides usage examples. No unnecessary words or repetition. Front-loaded with action and scope.

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 18 parameters and no output schema, but the description fails to explain return data, pagination, or default parameter behavior. For a complex filtering tool, this leaves significant gaps in what an agent needs to properly invoke and interpret results.

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

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

Schema description coverage is only 39%, yet the description provides no additional meaning for any parameters. It does not elaborate on filters like brand, limit, date ranges, or price thresholds, leaving the agent to rely solely on sparse 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 active MAP violations for workspace products, with specific verb 'Show' and resource 'active MAP violations'. It distinguishes from siblings by being the only MAP-specific tool, and provides example queries that reinforce its purpose.

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

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

Explicitly instructs to use when user asks about MAP violations, selling below MAP, price violations today, or any MAP enforcement question. This provides clear context and triggers, making it easy for an agent to select this tool appropriately.

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

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

The description goes beyond readOnlyHint annotations by detailing what information is returned (buy-box status, FBA/FBM, observed price, time on listing) and prerequisites (connected store required). 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 succinct, starting with a clear statement of purpose, then detailing usage and output. Every sentence adds value without redundancy. Ideal length for an MCP tool.

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

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

Despite no output schema, the description fully explains what the tool returns (competitor details, own buy-box status) for both modes. Prerequisites (connected store) are mentioned. All needed context for an AI agent is present.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining the optional ASIN parameter's effect (full list vs. contested products) and providing context for marketplace_id values (1=UK, 2=US). This justifies a score of 4.

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 explicitly states the tool's purpose: listing competitors on the seller's own products. It specifies two modes: with an ASIN to see full competitor details for that listing, and without to see most-contested products. This clearly distinguishes it from sibling tools like 'competitive_landscape' 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 clear use cases ('who am I competing with', 'am I losing the buy-box', etc.) and explains the two invocation patterns. However, it does not explicitly state when NOT to use this tool in favor of alternatives, though the context is sufficient for an AI agent.

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 context: the tool requires a connected store and excludes already-carried brands. No contradictions. Adds useful behavioral constraints 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?

Three sentences with no wasted words. Core purpose is in the first sentence, followed by examples and a prerequisite. Efficient and well-structured.

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

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

Given the simple schema and no output schema, the description covers purpose, usage, prerequisites, and behavior. Missing output format details, but not critical for tool selection. Adequate for the task.

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

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

The input schema fully describes the only parameter (marketplace_id) with enum values and default. The description does not reference this parameter, so it adds no additional semantic value. Schema coverage is 100%, 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 defines the tool as providing sourcing opportunities adjacent to the seller's existing catalog, using specific engines. It distinguishes from many sibling tools by focusing on the seller's own opportunities and gives example queries.

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

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

The description explicitly lists use cases like 'what should I source next' and specifies a prerequisite (connected store, Starter+). However, it does not directly contrast with sibling alternatives, leaving some ambiguity about 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 declare readOnlyHint: true, and the description does not contradict that. It adds important behavioral context: 'Requires a connected store (Starter+)', and describes the data fusion (account data vs. market data). No destructive actions 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 a single paragraph, concise and front-loaded with the core purpose. It lists data fields efficiently without excessive detail, though it could be slightly more structured.

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

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

Given no output schema, the description adequately explains what the tool returns: exact account data alongside market data and a price_vs_market read. It also covers the requirement (connected store). Comprehensive enough for a read-only catalog 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 clear descriptions for all three parameters (sort, brand, marketplace_id). The description does not add significant meaning beyond the schema; it only mentions the data fields in a general sense but does not elaborate on parameter usage or constraints.

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 the seller's own connected Amazon catalog fused with market intelligence. It lists specific data fields (your price, inventory, FBA/FBM, etc.) and market data (sourcing score, buy-box price, etc.), distinguishing it from sibling tools like my_competitors or my_store.

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

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

Explicitly states when to use: 'Use when the seller asks about their own products, 'how am I priced vs the market', 'which of my products are under pressure', or 'show my catalog'.' Provides clear context and implies alternatives are for other purposes.

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 does not need to re-state safety. The description adds some behavioral context by listing the output fields and the requirement of a connected store, but no details on rate limits, auth beyond 'Starter+', or non-obvious side effects. With annotations covering the safety profile, a 3 is appropriate.

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

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

The description is a single sentence that is dense but well-structured: it starts with the core purpose ('Store-level summary'), lists specific metrics, and ends with use cases. Every part adds value; 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 is simple (1 optional parameter, read-only, no output schema) and the description explains what the summary includes. It does not describe the return format or pagination, but given the read-only nature and the explicit list of metrics, the description is largely complete for an agent to understand what to expect. It loses a point for not specifying that the result is a JSON object or similar.

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 for the single parameter (marketplace_id with description including defaults). The tool description does not add any additional parameter semantics beyond the schema, so baseline 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 clearly states it provides a store-level summary with specific metrics (products, brands, FBA/FBM split, inventory, etc.). The verb is implied but the resource and scope are explicitly defined, distinguishing it from sibling tools like 'my_competitors' or 'my_products'.

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

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

The description explicitly says when to use it: 'Use for 'how is my store doing', 'summarise my catalog', or a dashboard overview.' It also notes the prerequisite of a connected store (Starter+). However, it does not mention when not to use it or compare to alternatives, which would make it 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 already declare readOnlyHint=true, indicating safe read operation. The description adds minor context about ranking and chaining but does not elaborate on any other behavioral traits like pagination, rate limits, or return format. It is adequate given the 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 at three sentences, front-loading the core purpose and example queries. It could benefit from more structured formatting like bullet points, but it remains efficient and readable.

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

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

The description covers core intent but leaves many gaps: no output schema, no explanation of return format, no mention of sorting or filtering details. Given the tool's complexity (14 parameters), the description is incomplete and would not fully inform an AI 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?

Despite having 14 parameters and only 29% schema description coverage, the description provides no explanation for any parameters beyond mentioning operator names in passing. It fails to add meaning beyond the schema, which is a significant gap.

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

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

The description clearly states the tool's function: given operator names, return brands ranked by seller competition level. It uses specific verb+resource and provides example queries that distinguish it from sibling tools like 'brands_gaining_sellers' or 'find_undercompeted_brands'.

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

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

The description explicitly lists example queries for which the tool should be used, such as 'which brands sold by these operators have the least competition'. It also mentions follow-ups that chain operator names to brand-level metrics. However, it does not explicitly state when not to use the tool or mention alternatives.

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