market

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

Beyond the annotations, it discloses server-side parsing of country adjectives and warns that brand country and shipping signals are best-effort and distinct from product availability. These are useful processing and data-quality caveats, though the description does not add further operational context such as result freshness or ranking 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 purpose is front-loaded, followed by routing, parsing, optionality, and data-quality guidance in a logical order. It is dense and mostly purposeful, but the long example list and repetition of schema guidance make it somewhat longer than necessary.

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 eight-parameter discovery tool, the description covers supported search modes, sibling selection, country-language handling, optional inputs, and an important limitation of shipping-origin signals. The fully documented input schema and presence of an output schema fill the remaining structural and return-value 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 structured fields already provide the baseline parameter documentation. The description adds useful cross-parameter semantics by explaining that query and filters can be combined and that country adjectives require no ISO-code translation, although some of this guidance duplicates the query schema.

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

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

The opening clearly states the verb and resource: finding fashion brands through natural language, structured filters, or both. Concrete queries establish the intended scope, and the explicit distinction from find_similar_brands separates it from its closest sibling.

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

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

It explains when this tool is best suited, including qualified similarity requests, and explicitly routes plain "brands like X" requests to find_similar_brands. It also clarifies that callers may supply a query, structured filters, or both.

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?

Goes well past the annotations by disclosing ranking semantics (semantic for query, recency for filter-only), pagination behavior, multi-currency conversion for price filters, and that results are compact cards with nested variant price differences. It even discloses a side effect not visible in annotations — the `country` value is recorded for analytics — which is consistent with readOnlyHint=false rather than contradicting it.

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

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

Front-loaded with the core purpose and mode selection, then examples, then return shape, then the escalation path to get_product — a logical progression with no filler sentences. It is on the long side for a tool description, but the length is driven by genuinely decision-relevant content rather than 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?

For a 25-parameter discovery tool this covers everything an agent needs: mode selection, query phrasing guidance, filter sparsity warnings, currency handling, result shape, and where to go for deeper product data. An output schema exists, yet the description still usefully summarizes the compact card contents and the nested variant pricing, which is the non-obvious part.

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 earns above that by teaching the non-obvious population strategy — keep descriptive attributes in `query` and populate structured filters sparsely — and by giving four worked natural-language-to-parameter mappings. It does not walk through the 25 individual fields, but the schema already does that adequately.

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

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

States a specific verb and resource ("Find fashion products") and immediately distinguishes the three modes of operation: semantic query, pure structured browse, and combined filtered semantic search. It also separates itself from the sibling get_product by naming it as the tool for merchant descriptions, SKU-level variants, and full image sets.

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 when to use query (open-ended discovery), when to use filters only (pure browse, recency-ranked), when to combine both, and the hard precondition that at least one of query or a filter must be supplied. It also routes detail-seeking agents to get_product with a product ID, which is exactly the sibling-disambiguation an agent needs.

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?

Adds real context beyond the annotations: similarity is vector-based, seeds must be active or merged aliases, failed seeds return an empty set, and output is capped. But the annotations declare readOnlyHint=false for what is plainly a read-only lookup, and the description does nothing to clarify that no state is changed (unlike the country parameter, which the schema admits is recorded for analytics). That leaves a genuine ambiguity an agent cannot resolve from either source.

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 short sentences, front-loaded with the verb and mechanism, then the edge case, then the result size. No filler or repetition, though 'Returns up to 20 brands' partially duplicates the schema's limit maximum of 20.

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?

An output schema exists so return structure needn't be explained, and the description covers seed validity, empty-result behavior, and result volume. The one omission for a lookup tool of this shape is whether results are similarity-ranked, which determines how an agent should present them.

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 67%, so the schema already documents brand and country. The description adds meaning for the brand parameter (must be an active catalog brand or merged alias) and echoes the 20-result cap that bounds limit. It says nothing about how limit interacts with the default of 12 or about ranking/ordering of results.

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

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

States a specific verb and resource ('find similar brands') plus the mechanism ('brand-profile vectors generated during product indexing'), which cleanly separates it from find_similar_products and discover_brands by resource. It also constrains the seed to an 'active catalog brand name or merged alias'. Sibling tools are not named explicitly, so it falls just 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?

Gives an implicit usage rule that unknown or ambiguous seeds return no brands, which helps an agent predict failure. However, it never says when to prefer this over discover_brands (broad discovery) or find_similar_products (item-level similarity), so the alternative selection is left to inference.

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 supply the safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=false), so the description doesn't need to. It does disclose the result shape (compact cards, not full variant detail) and pagination bounds, but the 20-per-page and 3-page limits simply restate the schema's maximums for limit and page, and it says nothing about ordering, matching logic, or what happens with an unknown product_id.

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

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

Front-loaded with purpose and use case, then result shape, then the alternative tool, then pagination, which is a sensible order. The sentence 'Returns page and hasNextPage' is redundant given an output schema exists and could be cut.

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 rich schema, existing annotations, and an output schema, the description covers purpose, use case, result granularity, and the alternative tool adequately. Only minor gaps remain, such as no guidance on invalid or missing product IDs.

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 every parameter including page, limit, country, and currency is already documented with examples and defaults. The description adds no new meaning about the parameters beyond repeating the pagination caps, so the baseline of 3 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?

Names a specific verb and resource ('find similar products across the entire catalog') and anchors it to a required input ('Given a product ID'). It also implicitly distinguishes itself from get_product by saying it returns compact cards rather than full variant detail.

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

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

Gives concrete use cases ('more like this' recommendations, finding alternatives) and explicitly routes the agent to get_product when SKU-level variants, exact prices, descriptions, or images are needed. It does not cover the sibling find_similar_brands or state when not to use this tool, which keeps it 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?

Adds substantial behavior beyond the thin annotations: the full default dimension set, the performance/size tradeoff of 'fields', the flat DFS ordering of categoryTree with hierarchy encoded in the value slug, and parent-before-descendant ordering. It does not address the notable readOnlyHint=false on what reads as a retrieval tool, though the schema's note that 'country' is 'recorded for analytics' plausibly explains the side effect; that explanation lives in the schema rather than the description.

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

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

Front-loads the default payload, then the narrowing options, then the structural detail about categoryTree — a sensible order for an agent deciding how to call it. It is dense but nearly every clause carries actionable information; the quoted 'categoryTree' repetition is the only mild redundancy.

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

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

An output schema exists, so return values need not be documented, yet the description still explains the shape of the trickiest field (categoryTree) and how its values are consumed downstream. For a zero-required-parameter catalog tool, an agent has everything needed to call it efficiently on the first try.

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

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

Schema coverage is 100%, so the baseline is 3, but the description goes further by explaining semantics the schema cannot: categoryTree is a flat DFS-ordered { value, label } list whose hierarchy is encoded in the slug, values pass directly to discover_products.category, and 'gender' scopes only categoryTree. 'brand_search' prefix behavior and pagination are left to the schema.

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

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

Opens with a specific verb and resource ('Returns available filter values in the catalog') and immediately enumerates the default payload, so an agent knows exactly what comes back without opening the schema. It also names the downstream consumer ('discover_products.category'), which distinguishes it from sibling tools like discover_brands and discover_products.

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

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

Gives concrete selection guidance: use 'fields' for a narrower, faster response, use 'brand_search' instead of listing all brands, and pass 'gender' to scope categoryTree or omit it for the merged union. It stops short of saying when to prefer this tool over the sibling discover_brands for brand lookups, so it is clear context without explicit sibling exclusions.

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

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

Annotations already declare destructiveHint=false and openWorldHint=false, and the description correctly frames the tool as a retrieval that follows a search. However, readOnlyHint=false sits awkwardly against a pure "get" framing, and the description does not explain the side effect the schema hints at (country is recorded for analytics) or what happens for an unknown product ID.

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 the core action front-loaded ahead of the usage condition. The second sentence is a long comma-separated inventory of returned fields, which is information-dense but slightly list-like and partly redundant given an output schema exists.

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 three-parameter read tool with a full output schema and safety annotations, the definition covers the essentials: what it returns, when to reach for it, and which siblings precede it. The minor gaps are failure behavior for invalid IDs and the non-read-only annotation signal, neither of which blocks correct invocation.

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

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

Schema coverage is 100%, so all three parameters are already documented, including the currency and country codes, which sets a baseline of 3. The description only adds the phrase "in the requested currency," which clarifies that prices render in the currency parameter, but it never mentions country or the analytics-recording behavior of that field.

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 ("Get the detailed response for a specific product ID") and then enumerates exactly what detail is returned: merchant description, store info, images, SKU-level variants, colorKey/size matrix, prices and purchase link. Naming discover_products and find_similar_products as the upstream producers makes it distinguishable from every sibling at a glance.

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

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

Gives an explicit precondition ("Use this after discover_products or find_similar_products") plus the condition that selects this tool over those: you need detail fields rather than a list. It stops short of stating when not to use it, e.g. whether to batch multiple IDs or avoid calling it for every result of a broad search.

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