market

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

Annotations already indicate readOnlyHint=true and destructiveHint=false, but the description adds meaningful behavioral context: country adjectives are parsed server-side, similarity seeds must resolve to an active catalog brand, unknown/ambiguous seeds return no brands, and shipping-origin signals are best-effort and separate from product availability. These details go well beyond the annotations and help prevent false 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 four sentences, front-loaded with the core purpose, and every sentence adds useful information: examples, an alternative, server-side parsing behavior, and a caveat about best-effort signals. There is no redundancy or filler, striking an ideal balance between detail and brevity.

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 8-parameter tool with no required parameters and an output schema, the description covers selection criteria, invocation modes, parameter interplay, and edge cases (unknown seeds, optional queries). The output schema handles return-value documentation, so nothing essential is missing. It is complete for an agent to select and invoke the tool correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by clarifying the relationship between query and structured filters, noting query optionality, and explaining the best-effort nature of shipping filters. While much of this repeats schema descriptions, the description consolidates it into a cohesive usage narrative, earning slightly above baseline.

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 statement: 'Find fashion brands using natural language, structured filters, or both.' It clearly differentiates from siblings by explicitly directing plain 'brands like X' queries to find_similar_brands, and the brand-vs-product distinction is obvious from the sibling names. This is unambiguous and useful.

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 rich examples ('Italian streetwear brands', 'Scandinavian minimalist brands') and names an alternative: 'For a plain "brands like X" request, use find_similar_brands.' It also clarifies when query is optional and how to combine it with structured filters, giving the agent clear decision criteria.

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

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

Beyond the readOnlyHint annotation, the description discloses behavioral nuances: semantic ranking vs recency ranking, pagination, output format (compact product cards), multi-currency handling, and the zero-result risk from over-specifying filters. It also explains nested variant price differences, adding meaningful context not available in 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 with clear sections, examples, and a logical flow from purpose to usage to output. Every paragraph adds operational detail without filler. Given the tool's 25-parameter complexity, the length is justified, though it is more verbose than strictly necessary in places.

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 discovery modes, price parsing, currency conversion, output card content, and the explicit handoff to get_product for deeper data. With an output schema already present, it still adds context on return semantics and edge cases, making it complete for the tool's complexity.

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

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

Input schema has 100% coverage, so baseline is 3. The description adds substantial value: concrete query-construction tips ('noun-led with up to one or two modifiers works best'), example mappings from natural language to sparse filter populations, and explicit warnings that soft descriptors are the most common cause of zero-result calls. It clarifies category shortcuts, store domain normalization, and currency conversion—all beyond the schema's per-parameter descriptions.

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

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

The description opens with a clear verb+resource ('Find fashion products') and explains the three operation modes (semantic query, structured browse, hybrid). It also positions itself against get_product, the deep-dive sibling, making its role as a discovery endpoint 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?

Explicitly tells when to use semantic query vs structured filters vs both, and explicitly directs users to get_product for deep product details: 'For merchant description, store info, SKU-level variants, exact variant prices, and all product images, call get_product...' It also warns against over-specifying soft descriptors, providing actionable when-not 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?

The description adds meaningful behavioral context beyond the readOnlyHint and destructiveHint annotations: it reveals the vector-based mechanism, the requirement for active/merged aliases, the 'returns no brands' edge case for unknown/ambiguous inputs, and a hard limit of 20 results. This gives the agent a clear model of what will happen.

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 dense sentences, front-loaded with the core purpose, and every word provides useful information without redundancy. It efficiently covers the input constraint, mechanism, edge case, and output limit.

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 combination of description, annotations, and output schema fully covers the tool's behavior. The description handles the key business logic (seed requirements, no results, cap), while the output schema presumably documents return structure, so no further explanation is needed.

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

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

The schema already describes 'brand' and 'country' explicitly, and the description adds extra semantics for 'brand' (must be active or merged alias) and 'limit' (implied by 'Returns up to 20'). The description does not discuss 'country' beyond the schema, but the schema already covers it, so the marginal value is still positive.

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

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

The description clearly states the verb 'find' and the resource 'similar brands', and specifies the method ('using brand-profile vectors generated during product indexing'). It also distinguishes from siblings like discover_brands and find_similar_products by focusing on brand similarity based on a seed brand.

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

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

The description provides clear context: the seed must be an 'active catalog brand name or merged alias', and unknown seeds return nothing. However, it does not explicitly name alternative tools or state when not to use this tool, such as 'for browsing all brands use discover_brands'.

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

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

The description adds meaningful behavioral context beyond the readOnlyHint=true annotation: it discloses pagination behavior ('Returns page and hasNextPage... up to 20 results per page, paginated (max 3 pages)') and output shape ('compact product cards, not full variant detail'). There is no contradiction with 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, front-loaded with purpose, then usage guidance, then pagination details. Every sentence earns its place, with no filler or redundant restatement of schema information.

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

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

Given the rich schema, output schema, and readOnly annotations, the description sufficiently covers what the tool returns, how pagination works, and which sibling to call for more detail (get_product). It provides enough context for correct selection and invocation without over-specifying.

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 description does not need to compensate for missing schema details. It adds no parameter-specific meaning beyond the schema: pagination caps are already in page/limit descriptions, and product_id is already described as 'from a previous search result.' The description contextualizes output and usage, not the parameters themselves.

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+resource ('find similar products across the entire catalog') and clearly states the input ('Given a product ID') and purpose ('more like this' recommendations or finding alternatives). It also distinguishes itself from get_product by contrasting compact product cards vs full variant detail, avoiding tautology and sibling confusion.

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

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

Explicitly states when to use the tool ('more like this' recommendations or finding alternatives) and provides an explicit alternative: 'call get_product for SKU-level variants, exact variant prices, merchant description, store info, and all images.' It also communicates scope ('across the entire catalog') and limitations ('not full variant detail'), satisfying when-not 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?

Beyond the readOnlyHint annotation, the description discloses significant behavioral details: the DFS-ordered categoryTree with hierarchy encoded in slugs, parents-before-descendants ordering, compatibility with discover_products.category, case-insensitive prefix matching for brand_search, and the analytics purpose of the country parameter. This goes well beyond the structured annotations.

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

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

The description is well-structured and front-loaded, opening with the core purpose before moving to defaults, then practical tips, then technical details. Every sentence contributes valuable information without redundancy; it 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?

Given the output schema and annotations, the description covers all essential aspects: what the tool returns, how to control it, underlying data structures, cross-tool usage, and parameter interactions. It leaves no critical gaps for an agent to select and invoke the tool correctly.

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

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

While the schema already documents each parameter, the description enriches understanding by explaining default values, how 'fields' controls the response, the structure of categoryTree, and the behavior of gender scoping and brand_search. It also notes that country absence preserves current behavior, adding nuance beyond the schema.

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

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

The description explicitly states 'Returns available filter values in the catalog', specifying the exact resource and action. It further distinguishes this tool from sibling discovery tools by describing its focus on filter dimensions and connecting categoryTree values to discover_products.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 provides actionable usage guidance: it explains the default behavior (all dimensions), suggests using 'fields' to request only specific dimensions for speed, and details 'brand_search' for prefix-based brand lookup. It also clarifies gender scoping and the behavior when omitted, giving clear when-to-use 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, so the safety profile is covered. The description adds valuable behavioral context by enumerating what the detailed response contains (merchant description, store info, images, SKU variants, pricing in requested currency, direct link), which helps the agent set expectations about the output. Nothing contradicts the annotations.

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

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

The description is a single, fairly long sentence that front-loads the core purpose and then lists use-case details. It is efficient in word count but slightly dense due to the enumeration of output fields. It earns points for being front-loaded and non-repetitive, but could be structured as multiple sentences for improved readability.

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

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

Given the tool's simplicity (3 params, one required) and the presence of an output schema, the description is complete: it defines the purpose, provides workflow context (after discovery tools), enumerates returned content, and mentions currency handling. No critical information is missing for effective tool selection and 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 description coverage is 100%, with all three parameters clearly explained in the input schema (e.g., product_id from a previous search, currency ISO code). The description only mentions "product ID" and "requested currency" without adding new semantic detail. Baseline 3 is appropriate because schema carries the parameter meaning.

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: "Get the detailed response for a specific product ID," which immediately conveys the tool's function. It further distinguishes itself from sibling tools by framing the tool as a post-discovery retrieval step, listing the specific data fields returned (merchant description, images, SKU matrix, prices) and making clear this is the tool for detailed product data.

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 this after discover_products or find_similar_products when you need..." This provides clear contextual guidance and names the preceding discovery tools. It does not explicitly articulate when not to use it, but the workflow implication is strong enough to guide an agent effectively.

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