amazon-product-research-mcp

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

Beyond the readOnlyHint annotation, the description clearly states the result is TEXT ONLY and explicitly warns that price and photo are not available, with a note that the user sees them after clicking the Alibaba link. It also names the exact return fields, which is valuable behavioral context.

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

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

Two sentences with no wasted words. The main action and source are front-loaded, followed by a compact list of return fields and a clear limitation note. Every sentence adds value.

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

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

The tool has one parameter, no output schema, and read-only annotations. The description sufficiently covers what the tool returns, what it does not return, and the source. An agent has enough information to call it correctly and set user expectations.

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 query parameter already includes a helpful description about being brand-free for private label. The tool description adds no extra parameter meaning beyond that, so the baseline score applies.

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 uses a specific verb ('Find') with a concrete resource ('Alibaba supplier / manufacturer listings') and a scoped mechanism ('via Serper site:alibaba.com'). It clearly distinguishes itself from generic search tools by focusing on Alibaba supplier results and listing exactly what is returned.

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 its usage context: finding Alibaba supplier listings for a product/OEM query. However, it does not explicitly state when to use this tool over alternatives like web_search, search_products, or shopping_search, nor does it give a when-not-to-use condition.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds important behavior beyond the annotation: it is a real-time fetch with ~10-40 seconds latency, restricted to 'Amazon marketplaces only,' and capped at 'up to 3 pages per call.' These constraints are not available anywhere else and manage agent expectations.

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

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

The description is front-loaded with the core action, then gives example triggers, alternatives, and constraints in a logical order. Every sentence adds a distinct fact—returned fields, latency, alternative tools, marketplace restriction—so nothing feels redundant or wasted.

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

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

For a tool with no output schema and six parameters, the description covers the return contents, when to use it, latency, pagination cap, and marketplace scope. An agent has all the information needed to select the tool and invoke it correctly without additional lookups.

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 each of the six parameters is already individually documented in the schema. The description doesn't need to restate them but adds value by imposing a usage limit on the page parameter ('up to 3 pages per call') and reinforcing marketplace scoping, which goes beyond the schema's default-value notes.

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

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

The description opens with a specific verb and resource: 'Fetch a LIVE Amazon search-results page (SERP)' and lists the exact data returned (position, ASIN, title, price, rating, badges). It also names the sibling tools it is not (search_products, shopping_search), so an agent can distinguish the tool immediately without opening other definitions.

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

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

It explicitly states when to use the tool: 'Use when the user wants CURRENT ranking/visibility' and gives three concrete example queries. It also provides clear exclusions: 'for warehouse keyword search use search_products; for buying advice use shopping_search.' This is direct, actionable routing guidance.

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

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

Annotations already cover the read-only and non-destructive nature, so the description only needs to add behavioral context. It does so by disclosing that the result is an observed series over time with observation dates and current product attributes, plus marketplace and single-ASIN limits. It stops short of detailing the exact history window or data granularity, but annotations lower the burden.

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

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

The description is front-loaded with the core definition, followed by trigger examples, sibling routing, and constraints. Every sentence earns its place and there is no fluff or repetition. Despite being longer than average, all content contributes directly to correct tool selection and invocation.

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

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

For a read-only single-resource tool with no output schema, the description covers the main return contents, usage scenarios, sibling alternatives, and invocation constraints. Minor details like the length of history or number of data points are omitted, but an agent has enough information to select and call the tool correctly in most situations.

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

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

Schema description coverage is 100%, so the schema already documents asin and marketplace_id fully. The description reinforces 'one ASIN per call' and 'Amazon marketplaces only' but does not add meaningful parameter-level semantics beyond what the schema provides. A baseline of 3 is appropriate.

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

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

The description opens with a precise statement of what the tool does: returns the BSR history time series for one Amazon ASIN, including first/last observation dates and product identity fields. It is clearly differentiated from the closest sibling tools by name and behavior, so an agent can select it correctly without checking other schemas.

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

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

The description explicitly states when to use the tool: when the user asks how an ASIN's rank/demand has moved, with concrete example queries. It also names the alternatives for related but different needs, asin_buybox_history and collect_asin_now, and adds constraints like Amazon marketplaces only and one ASIN per call.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description adds meaningful behavioral context: the per-week breakdown, trailing ~6-month monthly seller count series, and the stable/rising/falling seller_trend label. It also explains how to interpret the trend label in terms of seller piling-on vs consolidation. 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 long but well-structured: it front-loads the core purpose, then details the return data, then gives concrete trigger phrases. The example query list is somewhat repetitive but genuinely useful for an agent matching user intent. Every section serves a purpose.

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

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

For the primary use case, the description is fairly complete: it clearly explains what data is returned, what the trend label means, and which user queries should trigger the tool. However, given the high parameter count, low schema coverage, and lack of an output schema, the description leaves advanced filtering behavior undocumented. It is adequate for the main path but has clear gaps.

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

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

Only about 30% of the 27 parameters have schema descriptions, and the tool description does not mention any of the optional filter parameters, such as max_price, seller_name_contains, min_observed_buybox_days, or fulfillment_in. The description focuses entirely on outputs and use cases, leaving the many optional filtering parameters unexplained. With low schema coverage, the description does not compensate for this 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 states a specific verb and resource: it shows buybox winners for a given ASIN over time and the monthly change in the competing-seller pool. It is clear and detailed, but it does not explicitly distinguish itself from sibling tools like brand_buybox_trajectory, so it stops short of full differentiation.

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

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

The description includes an explicit 'Use when the user asks' section with many natural-language phrasings covering buybox history, seller rotation, and seller-pool stability. This is strong contextual guidance, but there is no when-not-to-use guidance or description of alternatives, so it does not fully earn 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 and destructiveHint=false, and the description adds useful behavioral context by specifying what each returned comparable includes (brand, title, price/price range, fulfillment with FBA/FBM/AMZ and percentage splits). 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?

Three tight sentences: purpose, usage triggers, and output contents. Every sentence earns its place, and the main purpose is front-loaded.

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

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

With 19 parameters, low schema coverage, and no output schema, the description is too thin to be fully actionable. It describes the output shape at a high level but leaves out marketplace semantics, default limits, filtering behavior, and return structure, so an agent would still face significant ambiguity when invoking 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 32%, leaving many parameters undocumented. The description names broad filter dimensions (brand, price band, seller count) that map to some parameters, but it does not explain key parameters like limit, marketplace_id, min/max_days_observed, fulfillment percentages, or the various 'contains' filters, so it does not sufficiently compensate for the schema 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 opens with a specific verb and resource: 'Find ASINs similar to a given ASIN', and further specifies the similarity dimensions (brand, price band, seller count). It also clarifies this is an ASIN-level lookalike tool, distinguishing it from brand-level siblings like brand_similar.

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

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

The description provides explicit user-phrase triggers ('ASINs like this one', 'similar products', 'comparable ASINs') and one concrete example. It clearly states when to use the tool, though it does not explicitly mention when not to use it or name alternative 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 declare readOnlyHint=true and destructiveHint=false. The description adds that the tool consumes buybox/FBA/referral data and returns brand, title, price/price range, and fulfillment details. This is coherent with the read-only hint and provides useful context beyond 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?

Two compact sentences. The first front-loads purpose and usage triggers; the second lists additional return fields, which is justified because there is no output schema. No fluff or repetition.

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

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

The tool is simple and the schema covers all parameters. The description also reveals return contents (brand, title, price/price range, fulfillment with percentages), which compensates for the missing output schema. It could be more explicit about the exact shape of the profit-estimate result, but this is 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?

All four parameters already have schema descriptions (100% coverage), so the description is not required to add parameter-level detail. It does contextualize the calculation (buybox price, FBA fees, referral fee), but it does not add semantics beyond what the schema already provides for cogs, marketplace_id, or target_margin_pct.

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

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

The description opens with a specific verb+resource: 'Estimate whether an ASIN can hit a target profit margin' and lists the inputs used (buybox price, FBA fees, referral fee). The trigger-phrase list further disambiguates it from other ASIN-level tools such as asin_buybox_history or asin_comparables.

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

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

It provides explicit user-phrase triggers ('can I make money on this ASIN', 'profit calculator', 'margin estimate for B08N5WRWNW', 'is this ASIN profitable to sell') and generalizes to 'any margin/profit question'. It does not, however, name alternative tools or state when not to use it, so it stops short of a full 5.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds the useful scoping notion of 'saved' sellers, but it does not disclose return shape, ordering, pagination, or any other behavior beyond what annotations and schema already imply.

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 tight sentences: the first states the action and resource, and the second provides realistic user phrasing. There is no filler or redundant restatement of the schema.

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 read-only list tool with only three scalar parameters, full schema coverage, and read-only annotations, the description is largely sufficient. A mention of what the returned list contains could push it higher, but the examples and schema make the expected behavior clear enough.

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

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

Schema description coverage is 100%, so the schema already documents brand, marketplace_id, and seller_contains. The description does not add further parameter-level meaning beyond framing the brand as the main lookup key.

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

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

The description opens with a specific verb and resource: 'List the saved authorized sellers for a brand.' This clearly distinguishes it from sibling authorized_seller_set (which modifies the list) and unauthorized_sellers (which addresses a different concept).

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 natural-language trigger examples: 'who are my authorized sellers for X', 'show my approved resellers', and 'what's my whitelist for this brand.' It clearly indicates when to use the tool, though it does not explicitly mention when not to use it or point to the setter alternative.

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 mark this as destructive (destructiveHint=true), and the description does not contradict that. However, the description never discloses whether calling the tool replaces the entire existing whitelist or merges with it. Given the 'add Y' example, this ambiguity could lead an agent to pass only the new seller and accidentally wipe the authorized list.

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-loaded with the core purpose, and every sentence earns its place: purpose, precondition, trigger examples, and exact-name guidance. No filler or redundant restatement.

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

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

The description covers purpose, preconditions, trigger phrasing, and exact seller-name handling. However, it omits the overwrite-versus-merge behavior, which is a critical piece of context for a destructive set operation and for correctly handling 'add Y' requests.

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 one useful operational detail—seller names must be passed exactly as they appear on Amazon—but provides little else beyond what the schema already states.

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 action ('Save') with a clear resource ('the authorized sellers for a brand') and explains the business purpose: the whitelist that makes unauthorized-seller detection possible. It also distinguishes naturally from the sibling authorized_seller_list by framing this as a write operation.

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 trigger phrases ('these are my authorized sellers for X', 'add Y to my authorized list') and states a precondition: the brand must already be tracked in the workspace. It does not explicitly name the alternative read tool, but the save-vs-list distinction is strongly implied.

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

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

Annotations already declare readOnlyHint and destructiveHint, so the safety profile is covered. The description adds useful context about returning weekly seller counts and observed buybox days over a trailing window, but it does not disclose empty-result behavior, data limits, or other edge-case traits.

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

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

The description is front-loaded with the core purpose, followed by a concise summary of output and specific query examples. Every sentence earns its place, with no redundant or filler content.

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

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

With 16 parameters and no output schema, the description is undercomplete for safe and correct invocation. It gives a high-level sense of the result but does not explain parameter interplay, defaults, filtering semantics, or what the returned timeline looks like.

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

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

Schema description coverage is low at 38%, and many filter parameters are undocumented. The description only obliquely references seller counts and observed buybox days; it does not explain trend_in labels, since_weeks bounds, or the numerous min/max filter semantics that would help an agent set parameters correctly.

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

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

The description uses a specific verb and resource ('Show how a brand's buybox concentration has changed over time') and clarifies the returned data. It is clear, but it does not explicitly distinguish itself from closely related sibling tools like asin_buybox_history or find_deconcentrating_brands.

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

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

The description provides direct user-query examples for when to use the tool, such as 'concentration trend for Nike' and 'buybox trajectory'. It does not mention when not to use it or name alternatives, so it stops short of full exclusion 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, openWorldHint=false, and destructiveHint=false, so the safety profile is covered. The description adds value beyond that by disclosing what each returned ASIN carries (brand, title, price/price range, fulfillment breakdown with amz/fba pct), which is useful since no output schema exists. It does not contradict 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?

Three sentences with no filler: the core purpose is front-loaded, usage triggers come second, and the output-contents disclosure third. Every sentence earns its place, especially the last one given the missing output schema.

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 adequately covers the tool's purpose, trigger phrases, and result contents, which is enough to select and invoke it for the core 'brand' parameter. However, given the tool's high complexity (26 parameters, 31% schema coverage, no output schema), it leaves the agent without guidance on the many filter parameters, the effect of limit, or the interplay of since_days with first_seen_from.

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

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

Schema description coverage is only 31% across 26 parameters, so the description needed to compensate, but it documents no parameters directly. It only hints at price and fulfillment filtering through the output-content sentence. Most parameters (asin_contains, first_seen_from, max_seller_count, latest_buybox_seller, fulfillment pct filters, etc.) remain unexplained in both schema and description.

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

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

The description opens with a specific verb+resource+scope: 'Show ASINs that recently appeared for a brand.' The example user queries ('new products for Nike', 'recently added ASINs') reinforce the intent and help distinguish it from sibling tools focused on categories or operators (e.g., category_new_entrants, operator_new_brands).

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

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

The description gives explicit when-to-use guidance with concrete user-query examples and a catch-all ('or any question about a brand's recent catalog additions'). However, it does not state when not to use it or name alternative sibling tools, so it stops short of full exclusion 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 mark readOnlyHint=true and destructiveHint=false, but the description adds crucial behavioral context beyond the annotations: this is an observation signal, NOT confirmed market entry, because sparse re-sampling can resurface long-present sellers as 'new.' This caveat is exactly what an agent needs to avoid over-interpreting results.

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

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

Three sentences with no wasted words: the core definition and critical caveat are front-loaded, followed by a brief filter note and explicit usage triggers. Every sentence earns its place and the description is appropriately sized for the tool's 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?

The description adequately defines the primary metric and gives clear usage guidance. However, with 17 parameters, only 35% schema coverage, and no output schema, an agent still lacks enough context about the return format and the semantics of most filter parameters. It is a minimum-viable description with clear gaps.

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

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

Schema description coverage is only 35% (6 of 17 parameters have descriptions). The description does clarify the core 'newly-OBSERVED sellers' concept, which maps to min_new_sellers and window_days, but it fails to compensate for the many undocumented min/max filters (control scores, churn, total sellers, catalog churn) or brand_contains, limit, and category beyond a passing mention of 'optional category filter.'

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

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

The description states a specific verb and resource ('Find brands that recently gained the most newly-OBSERVED sellers') and precisely defines the metric as first-seen date within the window. It also distinguishes the tool from brand-specific queries by the phrase 'without naming a specific brand,' making its purpose unmistakable.

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

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

The description gives explicit usage triggers: 'Use when the user asks...' with multiple concrete phrasings, and includes exclusions: it is an observation signal, not confirmed market entry, and is for category-scoped signals without naming a specific brand. However, it does not name alternative sibling tools, so it stops short of full alternative routing.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds the matching criteria (category, price tier, competition level) but does not disclose output behavior, ordering, filtering semantics, or data 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?

Two sentences with no filler: the first states what the tool does, and the second provides immediately useful example queries. The description is front-loaded and every sentence earns its place.

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

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

With 14 parameters, sparse schema descriptions, and no output schema, the tool needs richer guidance than this. The description covers the common 'brand like X' case well but leaves advanced filtering and expected results largely unexplained.

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

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

Schema description coverage is only 29%, and the description does not compensate by explaining the many optional filter parameters. It mentions price tier and competition level generally, but does not map those to min/max_avg_price, min/max_control_score, min/max_asin_count, or other available filters.

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

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

The description clearly states the tool finds brands similar to a given brand by category, price tier, and competition level, and backs it with concrete user phrasings like 'brands like Nike'. This distinguishes it from sibling tools such as evaluate_brand or competitive_landscape.

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 trigger phrases and question patterns ('Use when the user asks...'), giving clear context for when to invoke the tool. It does not mention exclusions or contrast with alternatives, so it falls just short of a 5.

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

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

With readOnlyHint=true and destructiveHint=false already covering safety, the description adds meaningful behavior: results are ranked by shared operator count and represent an operator graph through shared distribution channels. This helps the agent set expectations about output ordering without contradicting 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 filler: definition, return behavior, and concrete usage triggers are front-loaded, followed by a one-line conceptual summary. Every sentence earns its place.

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

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

For a 12-parameter tool with no output schema, the description gives enough to select it and make a basic brand call, but it does not clarify the many optional numeric filters or what the returned brand objects contain. The low parameter coverage leaves real gaps.

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

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

Schema description coverage is only 33%, and the description compensates only for the core concept of 'shared operators' and ranking. It does not explain domain-specific filters such as control_score, observed_buybox_days, or the seller_count ranges, leaving much of the parameter space underspecified.

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

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

The description opens with a specific verb and resource: it finds brands that share operators/sellers with a target brand and returns them ranked by number of shared operators. Example queries ('brands in X's network', 'brand family') and the phrase 'operator graph' differentiate it from lookalike siblings such as brand_similar or operator_top_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?

It states explicit trigger phrasing: 'Use when the user asks...' with five concrete natural-language examples. It does not name excluded cases or compare itself to alternatives, so it stops short of a 5.

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

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

The description discloses important methodology: it uses brand-level first-seen rather than per-ASIN counts and is stable under scraper-coverage growth. This adds meaningful context beyond the readOnlyHint and destructiveHint annotations, though it does not describe the output shape or edge-case behavior.

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

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

The description is dense but every sentence earns its place: definition, methodology caveat, and usage signals. The key concept is front-loaded, and the user-trigger list is compactly placed at the end.

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

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

This is a detection tool with no output schema, yet the description does not explain what the return value looks like (e.g., boolean, threat level, or signal details). It covers the why-and-when well, but an agent may not know how to interpret the tool's result.

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

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

Schema coverage is 100%, so the schema already documents all five parameters, including defaults and allowed values. The description adds no extra parameter-specific semantics beyond the algorithmic context, so the baseline score of 3 is appropriate.

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

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

The description clearly states what the tool does: 'Detect whether a brand is under competitive attack' and precisely defines the detection via elevated new-entrant rate combined with buy-box churn. It also distinguishes its methodology from the inflated per-ASIN count, which separates it from related seller-count tools.

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

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

The description provides explicit when-to-use guidance with concrete user phrasings like 'is my brand being targeted' and 'new sellers flooding my listings.' It does not, however, mention alternatives or when not to use this tool, so it stops short of a full 5.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral detail by disclosing that results are per-marketplace and include seller count, ASIN count, observed buybox days, and control score. This goes beyond what annotations provide, though it does not explain how 'control score' is defined.

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

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

The description is three sentences with no filler. The core purpose and output metrics are front-loaded, followed by concrete example queries. Every sentence adds value, and the structure makes it easy for an agent to quickly understand when and how to use the 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?

The tool has 10 parameters, low schema coverage, and no output schema. The description provides a clear high-level purpose, example usage, and a general list of returned metrics, which is sufficient for selecting the tool and calling it with just the required brand parameter. However, it leaves the optional filter semantics and the full output structure undefined, so it is only minimally complete for more advanced invocations.

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

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

Schema description coverage is only 20%, and the description does little to compensate. The brand parameter and marketplace_id_in are documented in the schema, but the eight numeric filter parameters (min/max seller count, ASIN count, control score, observed buybox days) are undocumented in both schema and description. The description mentions the output metrics but not how the filters behave or whether they apply per-marketplace.

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 ('Check whether'), a specific resource ('a brand'), and the exact marketplaces covered (Amazon US, Amazon UK, Walmart). It also names the output metrics, making the tool's function unmistakable and distinguishing it from sibling tools like keyword_cross_marketplace 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?

The description gives concrete user-query examples ('does this brand sell on Walmart', 'is this brand on Amazon UK') and says to use it for 'any multi-marketplace brand question.' This provides clear when-to-use context, though it does not explicitly discuss when not to use it or name alternative tools.

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

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

Annotations already mark the tool as read-only and non-destructive. The description adds useful behavioral context: results are ranked by estimated revenue at stake, each flagged ASIN includes brand/title/price/fulfillment, and without an authorized list it flags any third-party buy-box holder. No contradiction with annotations.

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

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

The description is front-loaded with the main purpose and ranking rationale, then adds the prerequisite and output shape in a compact way. Each sentence contributes, though it is slightly dense for a tool with 26 parameters.

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

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

The core call path, prerequisite, and basic result shape are covered, making it minimally viable. However, with 26 parameters, no output schema, and very low schema coverage, the lack of detail on filters and marketplace parameter semantics is a clear gap.

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% across 26 parameters, so the description must compensate. It clarifies the brand and authorized_sellers behavior, but most filter parameters such as price, fulfillment, buybox holder, marketplace, and revenue-at-stake remain unexplained in both the schema and the description.

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

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

The description uses a specific verb and resource: find ASINs where a brand you own has lost the buy box to an unauthorized seller, ranked by estimated revenue at stake. It clearly distinguishes this from sibling tools like operator_buybox_losses and brand_buybox_trajectory by focusing on brand ownership and authorized-seller scope.

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

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

The description gives explicit usage triggers such as 'where am I losing the buy box on <brand>' and states a key prerequisite: save your authorized list first for precise flagging, with fallback behavior if not saved. It does not explicitly name alternative sibling tools or state when not to use them.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, lowering the bar. The description adds genuinely useful behavioral context beyond those annotations: the 90-day lookback window, the exact filter threshold (amazon_expansion_net_90d < 0), and the sort behavior. It does not conflict with the annotations. Minor gap: no mention of the limit cap of 10 or default result size.

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 dense sentences, both load-bearing. The definition is front-loaded with the metric and ordering before the usage examples, and the parenthetical '(amazon_expansion_net_90d < 0)' is a compact shorthand. Zero filler, no repetition of the title or annotations.

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

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

The description conveys the core concept, the trigger phrases, and the ordering in under 40 words, and annotations carry the read-only safety profile. Since no output schema exists, a brief note on result fields would add value, and the marketplace_id enumeration lives only in the schema. These are minor gaps; the essential call intent is 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 only 27% — 11 of 15 parameters (min/max_asin_count, min/max_brand_count, pct_amazon_pl filters, retal dominance filters, etc.) are entirely undocumented. The description names the central metric (amazon_expansion_net_90d) and its default threshold, which illuminates the min/max variants of that filter, but it does not compensate for the large coverage gap. The agent is left guessing what most filter parameters mean.

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-object pair ('Find categories where Amazon is retreating') and anchors it to a verifiable operational definition ('net brand exits exceed entries over 90 days (amazon_expansion_net_90d < 0)'). It also discloses the output ordering ('ordered by retreat magnitude'), which clearly separates it from growth-oriented siblings like category_top_growers and top_expanding_operators.

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

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

The description gives three concrete trigger phrasings ('where is Amazon pulling back?', 'which categories is Amazon leaving?', 'Amazon retreat opportunities') that make routing unambiguous. However, it names no sibling alternatives or exclusion conditions (e.g., 'for expansion use X instead'), so the agent must infer the contrast with expansion tools.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds meaningful behavioral context beyond that: it discloses the breadth of the returned metric set, the 'ONE category' scope, and the ability to query at any depth. It doesn't cover error or fallback behavior when no category identifier is provided, but that's a minor gap given the annotation coverage.

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

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

Three tightly structured sentences: core purpose, detailed metric inventory, and concrete example user queries. Every sentence earns its place, and there is no redundant or filler content.

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

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

With no output schema, the metric enumeration in the description compensates well by telling the agent what kinds of data will come back. The main gap is that no parameters are required in the schema, but the tool logically needs category_id or category_name; the description implies this but doesn't state it explicitly.

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 no additional parameter-level meaning beyond what the schema already provides; it restates the one-category scope and metric families, but doesn't clarify whether category_id and category_name can be used together or whether at least one is required.

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 and resource: 'Return the full metric set for ONE category at any depth.' It clearly distinguishes itself from sibling category tools by emphasizing that it returns the full metric bundle for a single category, including demand, competition, and Amazon presence 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 explicitly lists trigger phrasings like 'show me the metrics/stats for category X' and 'how big is the X category,' which gives clear usage context. It does not explicitly contrast with related sibling tools such as evaluate_category_for_private_label or category_top_growers, so exclusion guidance is only implicit rather than direct.

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

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

Beyond the readOnlyHint/destructiveHint annotations, the description discloses a nontrivial behavioral trait: the tool reports first observation, not confirmed first entry, and explains that sparse re-sampling can resurface long-present brands as 'new'. This prevents an agent from over-interpreting results.

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

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

Three sentences, each carrying weight: core definition, critical caveat, and usage examples. The most important semantic warning is front-loaded, and there is no filler or repetition of the schema.

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 is complete for high-level selection and basic calls through category_name/category_id and since_days, but with 17 parameters and no output schema, there is no coverage of return shape or most filter semantics. It is a viable baseline, not a fully self-sufficient definition.

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

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

Schema description coverage is only 35%, and the description does not compensate by explaining the many undocumented filter parameters (limit, price/asins/seller/buybox filters, first_observed_to, etc.). It adds context about the observation window, but the agent is left without guidance for most of the 17 parameters.

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

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

The description uses a specific verb (Find) with a clearly scoped resource: brands newly observed in a category, defined by the first daily-sampling observation date. The observation-signal caveat distinguishes it from true-entry concepts and separates it from sibling tools like brand_new_asins or operator_new_brands, even without naming them.

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

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

It explicitly lists natural-language triggers ('new brands in Electronics', 'what brands just entered this category', 'category new entrants'), so an agent knows when to select it. It lacks an explicit when-not-to-use clause or a named alternative tool, but the inclusion examples provide clear context.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, covering the safety profile. The description adds that growth is measured by seller count and observations, which is useful metric context. It does not disclose return format, ordering, or the default comparison window, but with annotations this is acceptable.

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

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

Two sentences with no filler: the first states function and the second gives usage triggers. The most important information is front-loaded.

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

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

Given 19 parameters, no output schema, and no required parameters, the description is too thin. It does not explain how to specify a category by id vs name, how filters interact, or what the default result set is when no parameters are supplied.

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%, leaving 14 parameters undocumented, and the description does not compensate by explaining any filter parameters. It only implies the relevance of seller-count and observation metrics. The generic phrase adds little meaning beyond what parameter names already suggest.

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

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

The description opens with a specific action and resource: 'Find brands in a category with the biggest recent growth in seller count and observations.' It is clear and not tautological. It doesn't explicitly differentiate from similar growth-focused siblings like brands_gaining_sellers, but the category-scoped wording narrows it.

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 user-phrase triggers ('fastest growing brands in Toys', 'top growers in this category') and generalizes to 'any category-scoped growth question.' This gives clear context, though it does not name alternatives or state when not to use the tool.

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

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

Annotations already indicate readOnlyHint=true and destructiveHint=false. The description adds non-obvious behavior: the min-seller floor intentionally drops single-seller/brand-owner-only listings so results represent proven multi-seller demand. It also clarifies the result granularity (brands, not subcategories), which is behaviorally relevant.

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 the core behavior first, followed by return-type clarification and usage examples. It is slightly repetitive about the niche distinction, but every sentence adds decision-relevant 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 a 17-parameter tool with no output schema, the description covers selection, intended category context, result type, and the most important filtering behavior. It does not describe output format or the many optional filters, but the schema and self-explanatory names fill most gaps.

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

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

Schema description coverage is only 53%, so the description partially compensates by explaining the min_sellers semantics and category scoping. However, 8 parameters lack schema descriptions and the description does not clarify them (e.g., min/max_asin_count, velocity/control-score bounds), leaving agents to infer from names.

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

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

The description opens with a specific verb and resource: 'Find specific BRANDS within a category' and adds a precise qualifier -- proven multi-seller demand but still under-competed. It also explicitly states the output is BRANDS, not niches or sub-categories, which separates it from the sibling find_underserved_niches. The only minor ambiguity with find_undercompeted_brands is largely resolved by the 'within a category' scope in the name and first sentence.

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 concrete query-phrase examples for when to use it and explicit 'Do NOT use' examples with a named alternative (find_underserved_niches). This is about as clear routing guidance as an agent could ask for.

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

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

Annotations already mark the tool as non-read-only, non-destructive, and open-world; the description adds that it is live/on-demand and scoped to one ASIN per call. It does not disclose other behavioral traits such as latency, invalid-ASIN handling, or any side effects, but given the annotation coverage, the bar is lower and the description adds reasonable 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 well-structured: it front-loads the core capability and return values, then provides usage guidance and examples, then closes with scope and cardinality. Every sentence earns its place, and the examples are concrete without bloating the text.

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

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

The tool has no output schema, so the description compensates by summarizing the return payload: current price, offers, sellers, brand, title, price range, and fulfillment. It also covers marketplace support and the one-ASIN-per-call constraint. It stops short of specifying exact response shape or edge-case behavior, but for a two-parameter live-lookup tool the coverage is strong.

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

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

Schema description coverage is 100%, so both 'asin' and 'marketplace_id' are already documented in the input schema. The description restates that one ASIN is used and that all marketplaces are supported, but it does not add meaningfully new parameter-level details beyond the schema. Baseline 3 is appropriate.

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

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

The description uses a specific verb-resource pair ('Pull a LIVE, on-demand snapshot of a single Amazon ASIN') and enumerates what is returned: current title, price, live offers, and sellers. It also distinguishes itself from the 'pre-collected dataset,' making it clear this is the real-time alternative to other data-lookup tools.

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

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

The description explicitly states when to use the tool: 'Use when the user gives a specific ASIN and wants its CURRENT/today's data rather than the pre-collected dataset,' with concrete example queries. It does not name an alternative sibling tool, but the contrast with pre-collected data supplies a clear selection rule, so it stops just short of full alternative-name 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 establish readOnlyHint=true and destructiveHint=false. On top of that, the description adds meaningful behavioral detail about what the tool returns: top 10 sellers, top 10 brands, and week-over-week deltas. This is useful beyond the annotations, though it does not disclose edge cases or filtering behavior.

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

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

Two sentences with no filler. The core purpose is front-loaded, the output is summarized concretely, and the usage trigger is placed at the end in natural language. Every sentence earns its place.

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

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

For a tool with 30 parameters and no output schema, the description is too thin. It gives a high-level sense of the output but does not explain how the many filter parameters affect results, whether they are optional, how they interact, or what the returned data structure looks like. The high complexity demands more guidance than this.

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

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

Schema description coverage is only 10%, so the description carries a heavy burden for explaining parameters. It does not. It only hints at 'brand or category root' as entry points, but gives no guidance on the 30 parameters, their meanings, or how to combine them. The three schema-described params (seller_name, marketplace_id, dominant_category_velocity_tier_in) carry the only real semantic weight.

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 ('Map') with a clear resource ('competitive landscape for a brand or category root') and states concrete outputs: top 10 sellers by observed buybox days held, top 10 brands by winner-diversity HHI, and week-over-week deltas. It also directly ties to user intents like 'who's winning this category?' which distinguishes it from nearby 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 says when to use the tool: when the user asks 'who's winning this category?' or 'who controls the buybox here?'. It provides clear context for selection, though it does not name alternatives or state when not to use it.

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

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

Annotations already mark the tool as read-only and non-destructive. The description adds meaningful behavior beyond that by explaining interpretive nuances: the data_coverage flag distinguishes a null demand reading as a coverage gap rather than zero sales, and the rating_coverage flag is called out. This helps the agent reason about results more accurately. No contradiction with annotations exists.

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

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

The description is long but densely informative, and it front-loads the core purpose before enumerating outputs and usage triggers. Every major clause adds useful detail about return values or interpretation. It is somewhat verbose, but for a tool with no output schema this level of detail is justified.

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

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

With no output schema, the description carries the burden of explaining return values, and it does so thoroughly: composite score, dimension breakdown, demand estimate with confidence, data coverage flag, rating/review data, brand dominance, red flags, product identity, price, and fulfillment mix. This is sufficient for an agent to select and invoke the tool correctly, though it does not cover error or edge-case 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 description coverage is 100%, and all three parameters already have descriptions in the schema. The tool description adds context about the ASIN being a single item and mentions qty for ROI sizing indirectly, but it does not substantially enrich parameter semantics beyond the schema. Baseline 3 is appropriate.

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

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

The description opens with a specific verb and resource: 'Evaluate a single ASIN for FBA sourcing.' It clearly differentiates from sibling tools like evaluate_brand and evaluate_category_for_private_label by focusing on a single ASIN, and it names the type of output (sourcing score, demand estimate, red flags). An agent can tell exactly what this tool does without guessing.

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

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

The description includes explicit usage triggers: 'Use when the user asks "should I buy this?", "how fast does this sell?", or shares an ASIN and wants a sourcing recommendation.' This is clear contextual guidance, though it does not explicitly name alternatives or state when not to use it, so it falls just short of a 5.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds substantive behavioral context by enumerating exactly what the call returns, which is important because there is no output schema. It does not reveal any hidden side effects or edge-case behavior, but for a read-only evaluation tool this is strong transparency.

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

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

The description is two sentences with no wasted words. The first sentence packs the core purpose and a dense but necessary output list (no output schema exists to carry that burden), and the second sentence provides crisp usage triggers. Every clause earns its place.

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

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

For a 27-parameter tool with 22% schema coverage and no output schema, the description gives a solid picture of the primary output and when to call it, but it leaves the many optional filters unexplained. It is adequate for a simple 'evaluate this brand' call but incomplete for understanding filtering behavior, marketplace defaults, or how top-ASIN selection reacts to constraints.

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%, with 21 of 27 parameters undocumented. The description does not compensate: it only mentions 'composite sourcing score' as the ordering criterion and never explains the min/max filters, distribution_verdict_in behavior, or product_title_contains semantics. An agent would have to guess at the meaning of most optional 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 opens with a specific verb and resource: 'Evaluate a brand for portfolio inclusion,' which clearly distinguishes this tool from sibling tools like evaluate_asin_sourcing and evaluate_category_for_private_label. The detailed return-value list reinforces that it is a brand-level evaluation, not an ASIN- or category-level one.

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 trigger phrases: 'Use when the user names a brand and asks ...' with four concrete example queries. This tells an agent when to invoke the tool, but it does not explicitly state when not to use it or point to alternatives, so it stops short of a 5.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds meaningful behavioral detail beyond that: it accepts ANY depth, targets new private-label entrants, and returns a per-signal pass/fail breakdown plus a Strong/Moderate/Weak verdict based on footprint, fragmentation, demand, and price band.

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

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

Two sentences with no wasted words. The core purpose is front-loaded, the trigger phrases are packed into the first sentence, and the return format appears immediately after. Every clause contributes information an agent needs.

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

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

With no output schema, the description carries the burden of explaining the return value, and it does so clearly: per-signal pass/fail breakdown and a three-level verdict. It also explains the evaluation axes and the ANY-depth scope, while the input schema fully documents the four parameters. Nothing critical is missing.

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

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

Schema description coverage is 100%, which earns a baseline of 3. The description adds value by clarifying that category_name accepts any depth with fuzzy matching (e.g. 'Terrariums') and by naming the four evaluation signals, complementing the schema's structural definitions rather than repeating them.

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

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

The description opens with a specific verb and resource: 'Assess whether a category or niche is winnable for a NEW private-label brand.' It distinguishes itself from sibling tools like evaluate_brand and evaluate_asin_sourcing by targeting categories/niches rather than brands or ASINs, and it explicitly states the output verdict types.

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

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

The description provides explicit trigger-phrase examples ('is X winnable for private label', 'should I private-label X'), making it clear when to invoke the tool. It does not, however, name alternatives or explain when not to use it, so it stops short of full exclusion 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 provide readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds meaningful behavioral context: the exact FBA share formula, percentage scale, sortable fields, and the intended screening semantics, going beyond what annotations alone convey.

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 dense, front-loaded sentences. The core purpose appears first, followed by useful interpretation examples, sort options, and sibling-tool routing. No sentence is wasted.

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 18 parameters and no output schema, the description supports the core threshold-filtering use case well but omits details about default limits, pagination, result fields, and the behavior of several optional filters. It is adequate but not fully complete for a complex screening 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 33%, so the description must compensate. It does clarify the threshold formula and percentage range, and gives helpful examples for fba_share_value. However, many optional min/max filters and the difference between brand and brand_contains are not explained, leaving some parameters underspecified.

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 ('Return brands') and clear resource ('brands whose FBA buybox share is below or above a threshold'). It also distinguishes this tool from evaluate_brand by noting it is for screening lists, making its purpose unmistakable.

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

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

Provides explicit guidance: use fba_share < 40 for FBM-heavy brands and fba_share > 80 for FBA-dominated brands. It also names evaluate_brand as the better first call for a single named brand, giving a clear when-to-use vs. when-not-to-use 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?

Annotations already mark the tool read-only and non-destructive. The description adds useful behavioral context beyond that: the 0-100 percentage meaning, the screening-list scope, and how threshold values map to operator types. It does not add details like default limit or sort, but these are not critical for a safe read-only screening call.

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

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

Four sentences, no filler. The core behavior is front-loaded, and the alternative-tool guidance and interpretation examples are compact and useful.

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 primary use case, thresholds, and main optional brand filter are well covered. Yet the tool accepts 20 parameters with no output schema, and the description omits details on limit, sorting, and the many rating/revenue/buybox-day filters, leaving an agent under-informed about the full range of 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?

The description adds real meaning for the core parameters (fba_share_value, fba_share_op, brand) and even gives interpretation guidance. However, schema coverage is only 30%, and the description does not mention many optional filter parameters (min/max_avg_rating, min_sold_30d_revenue, min/max_observed_buybox_days, etc.), so it only partially compensates 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?

Description states a specific operation: return operators filtered by FBA buybox share threshold. It distinguishes itself from the operator-profile tools (operator_classifier / operator_top_brands) by framing this as list screening, and the name/semantics differentiate it from filter_brands_by_fba_share.

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

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

Explicitly says this is for screening lists rather than profiling a single named seller, points to operator_classifier/operator_top_brands as alternatives, and gives concrete threshold examples (fba_share < 50 for FBM-leaning, > 80 for FBA-heavy). That is actionable selection guidance.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so no side-effect warning is needed. The description adds useful behavioral detail by specifying the comparison baseline ('relative to their category'), the default threshold (5pp), and optional category filtering.

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

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

The description is three sentences with no filler. It front-loads the core purpose, then states the selection formula, and ends with practical query triggers. Every sentence earns its place.

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

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

For a read-only filtering tool with no required parameters and no output schema, the description covers the primary use case, the key metric, and example user intents. It could also mention common filtering dimensions like marketplace or scope, but the parameter names and schema descriptions cover those adequately.

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

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

Schema description coverage is 62%, so the description is not the main carrier of parameter meaning, and the core threshold/default is already present in min_delta_pp's schema description. The description reinforces the central delta-vs-category concept but does not add semantic value for the 5 undocumented parameters, though their names are fairly self-explanatory.

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 action ('Find brands') on a specific resource, defines the exact selection criterion (seller_churn_30d_delta_vs_cat_pp >= threshold), and gives concrete user-phrase triggers. This clearly distinguishes it from sibling tools like brands_gaining_sellers by framing it as high 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?

The description explicitly says when to use the tool: when the user asks about 'brands losing sellers', 'high churn brands', or 'seller instability'. It does not name specific alternatives or exclusions, but the trigger phrases provide enough routing clarity for an 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 declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral framing: it searches for buybox concentration dropping over a quarter and explains the competitive meaning. It does not disclose filtering behavior tied to params like control_score, seller counts, or ASIN count thresholds.

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 with no filler. The core purpose is front-loaded, and the usage triggers are placed in a compact second sentence.

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 16 optional parameters, low schema coverage, and no output schema, the description is too thin to let an agent invoke it confidently. It gives the high-level idea and usage context but leaves most parameter semantics and output expectations unaddressed.

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%, and the description does almost nothing to compensate. It never explains control_score, new_seller_count, old_seller_count, seller_growth_pct, asin counts, brand_contains, or limit. The phrase 'more sellers are entering' hints at seller-growth semantics but does not define the actual parameters or their ranges.

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

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

The description clearly states a specific verb and resource: 'Find brands where buybox concentration dropped over the last quarter' and ties it to concrete user phrasings like 'brands losing control' and 'brands becoming less monopolized.' It does not explicitly differentiate this from siblings such as brands_gaining_sellers or brand_buybox_trajectory, so it stops short of full sibling differentiation.

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

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

The description gives explicit 'Use when' guidance with multiple indicative user queries, which tells an agent when to select this tool. However, it lacks any 'do not use when' guidance or references to alternative tools that might overlap, such as brands_gaining_sellers.

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

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

The description discloses a crucial behavioral caveat beyond the read-only annotations: the result is an observation signal, NOT confirmed market entry, and sparse sampling can surface long-present sellers. This prevents an agent from over-interpreting results as true new entrants — exactly the kind of semantic-trap context that annotations cannot convey.

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

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

Four sentences, roughly 85 words, with zero wasted content: definition, central caveat, sibling distinction, and usage triggers. The most decision-critical information (what 'new' means and its caveat) is front-loaded, and usage guidance comes last. Every sentence earns its place.

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

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

For an 18-parameter tool with no output schema, the description covers the highest-value semantic ground: the meaning of 'new', the false-positive risk, and routing against the primary sibling. It does not describe return values or pagination, and the 13 undocumented parameters remain a gap, but the conceptual load an agent must grasp before calling is fully 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 only 28%, leaving 13 of 18 parameters undocumented. The description supplies the core semantic frame — 'earliest observation in our data falls in the window' — which gives meaning to since_days and earliest_seen_from/to, but it does not compensate for the undocumented filter dimensions (ratings, ASIN counts, FBA share, buybox days). Concept is clarified; parameter-level meaning is mostly still missing.

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

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

The description names a specific verb ('Find'), a precise resource ('operators we FIRST OBSERVED selling recently'), and pins down exactly what 'new' means: earliest observation in our data falls in the window. It also explicitly distinguishes itself from top_expanding_operators, so an agent can tell them apart without opening the schema.

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

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

It names the closest alternative (top_expanding_operators) and states the condition that selects between them: newly observed sellers vs existing operators adding brands. It then gives concrete trigger phrases ('new sellers this month', 'who just started selling', 'newly seen operators') that map natural-language requests directly to this tool.

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

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

The description discloses meaningful behavioral detail beyond the annotations: the Amazon buy-box anchoring methodology, what the modes do, the 16-month durability history, and the one-product-per-call constraint. It does not contradict readOnlyHint=false because this is an open-world web lookup with possible external side effects, though rate limits and external-data costs are not mentioned.

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

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

The description is dense but every sentence contributes. It front-loads the tool's purpose, then moves into identifier and mode usage, then return characteristics. There is no filler or redundant restating of the tool name or annotations.

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

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

With no output schema, the description reasonably explains the return payload: source price, class, spread vs the buy-box, durability read, and the Amazon anchor's product and fulfillment fields. It is complete enough for core invocation, but an agent navigating all 17 optional filter parameters or ambiguous identifier cases would still need more guidance.

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 strong semantics for the core parameters: only one identifier should be used, and each mode's meaning and default are explained. However, with schema coverage at only 65%, several numeric filter parameters such as max_price, source_contains, spread thresholds, and dropship margin thresholds remain unexplained in both schema and 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 names a specific action and resource: finding where one product sits across the open web as a live cross-retailer price check anchored to the Amazon buy-box. It also defines the modes concretely. It does not explicitly differentiate itself from likely sibling tools such as xmkt_pricing_compare or search_products, so it stops short of a 5.

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

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

It clearly tells the agent when to use the tool: for a live cross-retailer price check on a single product, and it explains the identifier requirement and mode selection. It does not name alternatives or provide when-not-to-use guidance like 'prefer asin_buybox_history for historical buy-box data,' so it lacks explicit routing.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so no contradiction exists. The description adds useful interpretation of results (gated/exclusive or operator-acquired) and the '100 percent of observed buybox days' condition, but it does not disclose operational details such as observation window, default limits, or what the returned records contain. 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 three sentences with no filler: the core definition is front-loaded, the interpretation is brief, and the usage triggers are compactly listed. Every sentence earns its place and helps an agent decide when to invoke the tool.

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

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

For a 13-parameter tool with no output schema, the description covers the core concept and invocation conditions well, but it does not explain expected return shape, key default behaviors, or how optional filters relate to the single-operator condition. The annotations and partial schema descriptions provide some context, so it is adequate but not complete.

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

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

The input schema describes 62% of the 13 parameters, and the description adds one central semantic idea—single-operator control over buybox days—that overlaps with the control-score filters. However, several parameters remain undocumented in both schema and description (limit, brand_contains, max_control_score, min_control_score, dominant_seller_contains), and the description does not compensate for that 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 names a specific verb and resource ('Find brands') and adds a precise, measurable condition: a single operator controls 100% of observed buybox days. It also interprets what such brands mean ('gated/exclusive or operator-acquired'), which clearly separates this tool from more general brand competition tools. The trigger phrases reinforce the intended semantic scope.

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

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

The description explicitly lists user phrasings that should route to this tool: 'brands with one seller', 'exclusive brands', 'single-seller brands', 'monopoly brands', and 'no competition'. It does not provide when-not-to-use guidance or name alternative sibling tools, so it falls just short of a 5.

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

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

Annotations already indicate read-only, open-world, non-destructive behavior. The description adds a detailed output contract: viability qualifier, specific move, economics, named risks, and validation steps, plus an expectation-setting note ('credible lead generator, not get-rich advice'). This goes beyond the annotations without contradicting them.

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

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

The description is front-loaded with the core behavior and then efficiently enumerates the output components. It is dense but every clause adds value; the 'Scout+' tag is minor branding but not harmful.

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

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

With no output schema, the description compensates well by enumerating return contents and risk categories. Combined with the input schema, an agent has enough to invoke the tool correctly and interpret results. It stops short of covering edge cases or failure behavior, but the essential contract 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 the baseline is 3. The description reinforces that the ASIN is the core input but adds no additional parameter semantics beyond what the schema already provides.

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

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

The description precisely states what the tool does: given an Amazon ASIN, it diagnoses the business model, finds supplier/wholesale/arbitrage matches, and returns a sourcing viability assessment. This is a specific verb-resource pairing that clearly distinguishes it from generic search or evaluation tools.

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

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

The description clearly implies when to use it: when you have an Amazon ASIN and want a sourcing opportunity read. It does not explicitly name alternative tools or state when not to use it, but the context is strong enough for an agent to route 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?

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds useful behavioral context: seed_brand constrains results to the same root category and results must show 'real sales presence'. However, it does not disclose how competition is measured, data recency, or whether results are marketplace-scoped, so the added behavioral detail is moderate.

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 dense, well-ordered sentences: what it does, its flagship status, and when/how to use it with seed_brand. There is no filler, and the most important selection guidance is front-loaded.

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

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

For an 18-parameter tool with no output schema, the description covers the main selection triggers and the critical seed_brand behavior, while defaults and filter semantics live in the schema. It is complete enough for an agent to select the tool and make a reasonable first invocation, though it does not describe the result record shape or explicitly route away from similar siblings.

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

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

Schema description coverage is 56%, leaving several parameters like limit, brand_contains, velocity filters, and control-score filters undocumented. The description adds practical meaning for seed_brand with concrete user-phrase examples, and the trigger 'undercompeted brands under $50' hints at price filtering. It does not compensate for all undocumented parameters, but it adds value beyond the schema for the key sourcing intent.

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

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

The description states a specific verb and resource: 'Find brands with low seller competition but real sales presence' and reinforces it as 'the flagship sourcing discovery tool.' It does not explicitly differentiate from closely related siblings like find_sourcing_opportunities or category_undercompeted_brands, so it stops short of 5, but the intent is unmistakable.

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

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

The description provides explicit trigger examples: 'find brands with few sellers', 'low competition brands', 'undercompeted brands under $50', and 'find me something to sell'. It also explains when to use seed_brand with concrete examples like 'brands like Ninja' and 'low competition in the same category as OXO'. It lacks an explicit when-not-to-use statement or named alternatives, so it is not a 5.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context beyond annotations: the tool reports subcategories rather than brands, ranks by private-label winnability, uses 2-year marketplace data, and can bias toward 'unhappy_shoppers' as a PL opening. This gives the agent a good sense of what the tool computes and returns.

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

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

The description is dense but every sentence earns its place: it defines the output type, provides query-phrase examples, gives the category_name mapping, and names the sibling tools to avoid. The structure is front-loaded with the core definition and then progressively adds routing and exclusion guidance, with no filler.

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

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

Given the tool's complexity — 21 parameters, no output schema — the description covers the essential usage context: what the tool returns, how to scope by category_name, and which sibling tools to avoid. It does not specify the exact return structure or how multiple filters interact, but the main niche-discovery flow is thoroughly explained. For an unannotated output schema, this is strong but not exhaustive.

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 43%, so the description bears added weight for parameter semantics. It does provide valuable extra guidance: 'When the user names a department or category ... pass it as category_name to scope the niches to that area.' However, it does not compensate for the many undocumented numeric filter parameters (e.g., max_competing_brands, min_seller_diversity, min_monthly_demand_usd), leaving much interpretation to their self-explanatory names.

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

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

The description states a specific verb and resource: 'Find UNDER-SERVED NICHES' and explicitly defines the output as subcategories ranked by private-label winnability. It draws a clear line against sibling tools by stating 'Returns CATEGORIES / sub-categories ... NEVER brands', so an agent can immediately distinguish it from brand-returning 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 explicit when-to-use guidance: 'This is the RIGHT tool for ANY niche-discovery question' followed by concrete utterance examples. It also names exclusions: 'Do NOT use category_undercompeted_brands or find_undercompeted_brands for niche questions — those return BRANDS', leaving no ambiguity about routing.

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

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

Annotations already establish readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral detail beyond annotations: the decision categories, the 3-bullet rationale structure, named metrics, and the returned product/fulfillment fields. This gives the agent a clear expectation of what the tool will produce.

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 tight sentences, front-loaded with the core recommendation decision. Each sentence contributes something distinct: the recommendation and rationale, the additional returned data, and the user-intent triggers. There is no filler or redundant wording.

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

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

There is no output schema, so the description carries the burden of return-value disclosure, and it does so well: recommendation type, bullet format, metric names, product fields, and fulfillment status. It does not discuss metric interpretation or edge cases, but for a read-only advisory tool the core invocation contract is clear enough.

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

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

The schema fully describes marketplace_id with its value mappings, and the description clarifies that 'asin' is the target ASIN. With 50% schema description coverage and no description-side parameter detail, the description does not substantially add meaning beyond the schema, but the parameters are simple enough that this is minimally adequate.

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 action ('Recommend ungate / arbitrage / avoid') on a concrete resource ('an ASIN') and details the output form: a 3-bullet rationale citing named metrics, plus product and fulfillment data. The 'should I try to ungate this?' framing clearly separates it from the many search and analytics 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 gives explicit user-intent triggers: 'should I try to ungate this?' and 'how should I price this?' This provides clear context for when to call the tool. However, it does not mention exclusions or name alternative tools, so it stops short of full routing guidance.

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

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

Annotations already mark this as read-only and non-destructive, and the description adds meaningful behavioral detail beyond that: it reveals the data source is Amazon's autocomplete suggestions, the match is exact, and it returns per-marketplace observed dates and an example suggestion-list position. It also scopes the data to Amazon marketplaces only.

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

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

The description is front-loaded with the core function in the first sentence, followed by usage guidance and constraints. Every sentence serves a purpose: what, when, and what-not.

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 no output schema, the description adequately sets expectations by mentioning observed marketplaces, first/last observed dates, and an example current suggestion-list position. It covers selection context, limitations, and sibling relationships, making it complete 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?

The schema already fully documents the single 'keyword' parameter, so the baseline is 3. The description adds value by clarifying the exact-match behavior and giving concrete usage context, though it doesn't need to add much since coverage is 100%.

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

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

States a specific verb and resource: 'Check which of the 11 Amazon marketplaces a keyword was observed in Amazon's own autocomplete suggestions.' It also clearly distinguishes from sibling tools by specifying exact-keyword matching and explicitly excluding volumes and rankings.

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 scenarios: a seller asking if a keyword is typed on a specific marketplace, cross-country keyword presence comparison, and marketplace expansion planning. It names related sibling tools (brand_xmarket / operator_xmarket_presence) and states exclusions: exact match only, not volumes/rankings.

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

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

Annotations already mark the tool as read-only; the description adds value by disclosing the exact data scope: suggestion lists for the seed's prefix, positions 1-10, related vocabulary, and observed marketplaces. It also clarifies output limitations, which is useful beyond the annotation hints. 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 dense but every clause adds information: data returned, use cases, and exclusions. It is slightly run-on and could be broken into clearer sentences, but nothing is wasted.

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?

Since there is no output schema, the description compensates by describing the return contents: suggestion lists with positions, related vocabulary, and marketplaces. It is missing minor details such as empty-result behavior or exact response shape, but for a simple two-parameter read-only read the coverage is adequate.

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

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

Schema coverage is 100%, so the schema already documents both parameters. The description reinforces the meaning of seed ('seed term') and marketplace ('per marketplace', 'Amazon marketplaces only') but does not add substantial new per-parameter detail.

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 precisely defines what the tool returns: Amazon autocomplete keyword suggestions for a seed term, with list positions and per-marketplace observation. It also distinguishes itself from volume- or ranking-based keyword tools by explicitly stating those are excluded.

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

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

It gives explicit use cases ('listing/backend keyword language', 'what do buyers type for X', seeding research) and explicit when-not-to-use boundaries (no volume figures, no organic-ranking data, Amazon only). It does not name an alternative sibling tool, so it stops short of a full 5.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description goes beyond annotations by disclosing behavioral traits: it returns 'best match first', it prefers priced and recently observed rows, it returns specific fields (ASIN, brand, title, price, rating, image), and it restricts one barcode per call. It doesn't describe edge cases like no-match behavior, but the disclosure of ranking logic is valuable.

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

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

Three sentences, all information-dense: purpose, formats, usage conditions, return behavior, ranking, fields, and constraint. The most important information is front-loaded ('Look up products by retail barcode'), and no sentence is wasted.

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 lookup with two fully documented parameters and no output schema, this description is complete enough for an agent to select and invoke the tool correctly. It covers input formats, use cases, return fields, ranking, and the one-barcode constraint. No critical operational guidance is missing.

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

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

Schema coverage is 100%, so the input schema already explains both parameters in detail. The description reinforces that the barcode is numeric and gives accepted formats, which slightly adds context, but it doesn't add meaning beyond the schema for marketplace_id. Baseline 3 is appropriate because the description adds minor value but the schema carries the heavy lifting.

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

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

The description states a specific verb ('look up'), a precise resource ('products by retail barcode'), and enumerates the barcode formats (UPC-12, EAN-13, GTIN-14). It also gives concrete example queries and distinguishes the tool's function by clarifying it maps barcodes to Amazon or Walmart listings. Siblings like search_products and find_product_across_web are distinct enough in name, but this description also explicitly explains the barcode-to-listing 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?

The description explicitly states when to use the tool: when the user supplies a numeric retail barcode from a shelf tag, invoice, supplier price list, or wholesale catalog and wants to know the Amazon/Walmart listing. It also provides example user phrasings and notes 'One barcode per call', an implicit boundary. It does not name a specific sibling alternative, but the use-case conditions are clear enough that an agent can decide without comparing schemas.

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, openWorldHint=false, and destructiveHint=false, so the safety profile is covered. The description adds the 'active' and workspace-scope context, but leaves important behavior vague: what 'active' means, whether 'today' is a hard time window, and what the result looks like. This is acceptable 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 two sentences: the first states purpose, the second gives concrete user-phrase triggers. It is front-loaded and generally efficient, though the list of example queries is slightly redundant with the closing 'any MAP-enforcement question.'

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 18 optional filters, no output schema, and sparse parameter descriptions, this description is incomplete for confident invocation. It covers purpose and routing, but not result contents, filter combination, date formats, pagination, or the exact semantics of 'active' and 'today.'

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

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

The tool has 18 optional parameters but only 39% schema description coverage. The description provides no parameter-level guidance at all—no mention of filtering by brand, retailer, date, price, violation percentage, or product title. It does not compensate for the large undocumented filter surface.

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 operation ('Show'), the resource ('active MAP violations'), expands the acronym, and scopes it to 'products in the workspace.' It is specific and easy to distinguish from unrelated sibling tools, though it does not explicitly name a contrasting sibling.

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

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

The description provides explicit trigger phrases ('MAP violations', 'who is selling below MAP', 'price violations today', 'are there any MAP breaches') and generalizes to 'any MAP-enforcement question,' giving clear routing guidance. However, it does not mention when not to use the tool or name an alternative, so it stops short of a 5.

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

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

Annotations already mark this as read-only and non-destructive. The description adds useful behavioral context beyond that: it requires a connected store/plan tier, reports own buy-box and undercut status, and changes behavior based on whether ASIN is provided. 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 information-dense but not bloated: it front-loads the core purpose, then covers parameter-dependent behavior, requirements, and typical user intents. Every sentence contributes useful guidance, and the formatting makes the two modes easy to distinguish.

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 no output schema and two optional parameters, the description is complete: it explains input modes, output fields, prerequisites, and use cases. An agent can determine when to invoke it and what to expect without needing additional schema or annotation details.

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

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

Schema coverage is 100%, so the schema already documents both parameters. The description adds meaning beyond the schema by explaining that the optional ASIN must come from the seller's catalog and that omitting it switches the tool to a 'most-contested products' mode, which is essential for correct 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 identifies the tool's function: showing competitors on the seller's own products, with a specific verb-like framing in 'Who's competing'. It also distinguishes scope by emphasizing 'OWN products' and details the output fields (buy-box winner, FBA/FBM, price, tenure), which separates it from generic competition 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 explicit usage scenarios: pass an ASIN for a listing-level competitor list, omit it for the most-contested products, and provides concrete example queries like 'am I losing the buy-box'. It also states a prerequisite (connected store, Starter+), though it does not name alternative sibling tools for comparison.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds meaningful behavioral context: it sources from the seller's OWN connected catalog, excludes existing brands, and requires a connected store (Starter+). This goes beyond the annotations and informs the agent about data dependency and prerequisites.

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

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

The description is reasonably concise at three sentences and front-loads the core purpose. The phrase 'Seeds Webotee's undercompeted-brand and underserved-niche engines' is jargon-heavy, but it is compact and quickly conveys the mechanism.

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 suggestion tool with one optional parameter and no output schema, the description covers the main questions: what it does, its data source, prerequisite, and when to use it. It could be slightly clearer about the type of results returned, but nothing essential is missing for invoking it correctly.

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