mcp-fashion

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

Beyond the readOnlyHint and destructiveHint annotations, the description discloses the important conditional behavior around size confirmation and the exact URL variants to emit. It clearly communicates that the tool only constructs links and has no destructive or state-changing side effects.

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 compact and front-loaded with the core action and URL format, followed by a clearly labeled mandatory instruction. There is no filler or redundant restatement of schema details.

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 presence of an output schema, full parameter schema coverage, and annotations, the description covers the key decision rule and URL construction behavior completely. The agent has enough information to invoke the tool correctly and know what to return.

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

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

The input schema already covers all parameters with 100% description coverage, so the baseline is 3. The description adds value by mapping handle and size_index to URL path positions and by tying size_index to the user's explicitly confirmed size selection. Coupon and quantity semantics are left to the schema, which is acceptable.

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 immediately states the specific action: generating the direct 1-click checkout purchase URL for a product and size index, and includes the exact URL template. This clearly distinguishes the tool from unrelated siblings such as product search or stock-checking 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 mandatory instruction explicitly tells the agent when to include /{size_index} (only after the user confirms a size) and when to return the clean base link instead (if the user is still browsing or sizes are unclear). This provides clear when-to and when-not-to 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 and destructiveHint annotations, the description discloses a key behavioral guarantee: all returned looks are verified 100% in-stock and any look with an out-of-stock item is excluded. It also specifies mandatory output behaviors around sizes, shipping SLA, return policy, spec tables, and base vs. checkout links, providing rich context 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: the purpose is stated first, followed by the stock-guarantee rule, then compact mandatory instructions. Each sentence adds necessary operational detail without repeating schema 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?

Given the read-only annotations, full schema descriptions, and presence of an output schema, the description supplies the missing operational context: the in-stock exclusion rule, exact link formats, and formatting requirements for return policies. Nothing needed to invoke the tool correctly 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%, so the baseline is 3. The description repeats the occasion enum examples but adds no additional meaning for parameters like age, page, gender, vendor, or page_size 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 clearly states a specific verb ('Discover') and resource ('complete curated fashion looks') with a well-defined occasion filter, including example occasions. However, it does not explicitly distinguish itself from the sibling tool looks.curation.recommend, 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 occasion-specific language makes the primary use case clear: when a user wants curated looks for a named occasion or vibe. The stock-guarantee note and mandatory agent instructions add useful context, but the description does not explicitly state when not to use this tool or point to alternatives like looks.curation.recommend.

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 it read-only and non-destructive. The description adds meaningful behavior beyond that: results are guaranteed 100% in-stock, and the mandatory agent instructions define expected output content (sizes, shipping SLA, return policy, specs table, base vs. checkout links).

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 main description is compact and front-loaded, and the mandatory instructions are structured and purposeful. Every sentence contributes operational detail, from stock verification to link formatting.

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 an output schema exists and annotations cover safety, the description is complete: it defines both input modes, the in-stock guarantee, and the exact post-result obligations. No critical calling information 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 schema already documents each parameter. The description adds value by explaining the OR relationship between handle and occasion+gender and the semantic difference between complementary items and full occasion looks; page and page_size need no extra explanation.

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 clear operation ('Get complete recommended outfits') and specifies two input modes: product handle for complementary styling, or occasion+gender for full looks. It does not explicitly distinguish this from the sibling looks.curation.by_occasion, which appears to cover the same occasion mode.

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 clear when-to-use context by describing the two invocation patterns and giving example occasions. However, it never mentions alternatives or exclusions, so an agent is left to infer when to prefer looks.curation.by_occasion instead.

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 agent knows it's safe. The description adds substantial behavioral context: it specifies how to interpret return policies (negative days = 'Exchange only |X| days'), mandates display of specs table, and defines link-return behavior (base link during browsing, checkout link only after size finalization). This goes beyond the annotations and enriches agent 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 front-loaded with the core purpose in one sentence, followed by a clearly labeled 'MANDATORY AGENT INSTRUCTIONS' section with three concise bullet points. While it is longer than minimal, the content is relevant and structured. Each instruction earns its place, though it could be tightened slightly.

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 is covered elsewhere. The description fills in presentation rules, link formats, and policy interpretation, which the schema does not convey. It covers what data to expect and how to handle it, leaving few gaps for an agent to call this tool correctly. Missing edge cases (e.g., out-of-stock handling) are likely in the output schema.

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

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

Schema description coverage is 100%, so all three parameters (handle, size_index, desired_size) are documented in the schema. The description mentions size_index in the link format but does not add new semantic meaning beyond the schema. Baseline 3 is appropriate when the schema fully covers 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 'Verify' and enumerates the exact resources (stock availability, live pricing, product specs, shipping/return policies, available sizes). It clearly distinguishes from siblings like products.items.get_by_handle by emphasizing 'live' data and sizing, which other tools likely lack. The purpose is unambiguous and scoped.

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 real-time checking but never explicitly states when to choose this over alternatives, nor does it mention sibling tools or exclusion conditions. It gives 'MANDATORY AGENT INSTRUCTIONS' about how to present results, but not when to invoke this tool vs. get_by_handle or search tools. The guidance is inferred rather than stated.

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 value by detailing the return content (including the purchase link format), which gives the agent a concrete expectation of what comes back. No contradiction; no extra caveats needed for a simple read.

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?

A single, well-structured sentence that leads with the action and then lists the key return fields. Zero filler, front-loaded with the core 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?

The tool has a single parameter, an output schema exists (so return structure need not be spelled out), and annotations cover safety. The description covers all essential invocation details, including the expected data fields and the link format, making it complete for an agent to call 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% – the handle parameter has a description and an example. The description reinforces that the handle is used in the link template but doesn't add new semantic information beyond what the schema provides. 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 ('Fetch'), a clear resource ('single product document'), and the identifier ('by product handle'). It also enumerates the returned data (metadata, variants, in-stock sizes, price, purchase link), which sharply distinguishes it from siblings like products.items.check_stock or the search 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?

It clearly states the use case: fetch a product by handle. It doesn't explicitly mention alternatives or when not to use it, but the context is unambiguous given the sibling list. Lacks explicit exclusions, so a 4 rather than 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. The description adds valuable context: result URLs must be the PoloPan short purchase link from GET /products/link/{handle}, never the raw catalog URL. It also clarifies the underlying similarity mechanism, going beyond what annotations provide.

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

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

Two sentences with no waste: the first states the core use case, the second pins a non-obvious URL rule that prevents calling errors. Both earn their 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 8 parameters, enums, an output schema, and read-only annotations, the description covers the essential purpose and a critical output convention. The only gap is the somewhat opaque 'same logic as extension' reference, which an agent without product-specific knowledge may not fully unpack.

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 all 8 parameters. The description only reasserts the budget_range and handle concepts at a high level and does not add constraints, formats, or interactions 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?

States a specific verb+resource ('Find product alternatives') and a precise scope ('within a selected budget range using product image similarity'). Differentiates implicitly from siblings like products.search.text and products.search.image_upload by focusing on alternatives via image similarity.

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

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

Provides clear contextual triggers: budget range + image similarity. The 'same logic as extension' reference hints at reuse, but the description does not explicitly name sibling tools or state when not to use this tool over products.search.text or image-based search.

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 that it uploads an image and uses a temporary URL, which is useful context, but does not disclose further behavioral details (e.g., statelessness, external calls). Given the annotations, a 3 is appropriate as the description adds some value but not a rich behavioral layer.

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, front-loaded sentence with no extraneous information. It states the core action and expected return in a compact, efficient manner.

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 the essential function, input requirements (local image or base64), and output contents (products with sizes, pricing, URLs). With an output schema present and high schema coverage, no critical information is missing for an agent to call 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?

The schema provides descriptions for all 14 parameters (100% coverage), so the baseline is 3. The description only reiterates the image input options (local file or base64) which are already in the schema, adding minimal value 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 states a specific action: upload a local image file (or base64) and search PoloPan products, clearly distinguishing it from text or URL-based search siblings. It also specifies what is returned (in-stock sizes, pricing, verified purchase URLs), leaving no ambiguity about the tool's core function.

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 usage when you have a local image (file path or base64) and want to search by image. It does not explicitly mention when not to use it or contrast with siblings like image_url, but the context of uploading a local file is clear and sufficient for most agents to select the right 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 declare readOnlyHint=true and destructiveHint=false, so no side-effect warning is needed. The description adds useful behavioral context beyond annotations by stating that returned products include available in-stock sizes, pricing, and verified purchase URLs with a concrete URL format. This helps the agent set expectations about the result set without contradicting 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, dense sentence that front-loads the core operation ('Search PoloPan products using image_url') and then adds the most important output expectations. No words are wasted, and it avoids repeating schema details that are already available.

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

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

Given the tool has 11 parameters, 100% schema coverage, an output schema, and read-only annotations, the description supplies enough context to invoke it with confidence. It names the required input, indicates optional filters, and summarizes return value characteristics. It could be slightly stronger by explicitly naming when to prefer this over image_upload or text search, but that gap is partially addressed by the tool name and sibling list.

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 every parameter already has a meaningful description, so the baseline is 3. The tool description only says 'optional filters' without enumerating them, but that is acceptable because the schema fully documents each filter. It does not reveal additional parameter semantics 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 states a specific verb and resource: 'Search PoloPan products using image_url'. It also distinguishes itself from siblings like products.search.text and products.search.image_upload by explicitly tying the search method to an image URL. The mention of returned data (in-stock sizes, pricing, purchase URLs) makes the purpose concrete.

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 this tool is for searching when an image_url is available, and optional filters can refine results. It does not explicitly contrast with products.search.image_upload or products.search.text, so it stops short of giving explicit when-not/alternative guidance. Still, the context is clear enough for an agent to select it among the image-related search siblings.

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

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

The description goes well beyond the readOnly/destructive annotations by disclosing what the response contains: in-stock sizes, specifications tables, shipping/return policies, pricing, and purchase URLs. The mandatory agent instructions further clarify behavior around displaying policies, specification tables, and link handling, including the 'Exchange only |X| days' interpretation. 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 well-structured: the main purpose is stated first, followed by a clearly separated list of mandatory agent instructions. Every sentence adds operational value, and the numbered format makes the required behaviors easy for an agent to follow. There is no redundant or filler 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 description is complete for an agent to call the tool correctly: it specifies the query-based behavior, the content of results, the required user-facing disclosures, and the link policy (base link until size is finalized, then checkout link). The output schema covers return structure, and the input schema covers parameters, so no critical calling context 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?

The input schema already provides 100% parameter description coverage, so the baseline is 3. The description does not add meaningful parameter-level semantics beyond calling them 'optional filters' and mentioning the text query. Since the schema fully documents all parameters like page, size, gender, vendor, sort_by, price_min, price_max, and sort_order, the description does not need to compensate.

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

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

The description clearly states the verb ('Search'), the resource ('PoloPan products'), and the method ('using a text query and optional filters'). It also enumerates exactly what is returned, making the tool's purpose unambiguous. The phrase 'text query' distinguishes it from image-based sibling tools such as products.search.image_upload and products.search.image_url.

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 establishes when to use the tool: whenever an agent needs to search products by a text query. It also gives operational guidance on how to present results and when to switch from base links to checkout links. However, it does not explicitly name alternative tools or state when not to use this tool in favor of a sibling.

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 behavioral context beyond that by enumerating the detectable fashion categories and stating that output includes bounding box coordinates and confidence scores, which helps an agent judge whether the model fits the query. Operational details like image limits or multi-person handling are absent, keeping this below a 5.

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 front-loads the verb and purpose, the second adds the usage scenario. The parenthetical category list is somewhat long but earns its place by communicating the detection taxonomy 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 an output schema present and 100% parameter coverage, the description's main job is usage context, which it largely delivers. The notable gap is input selection: all three image-source parameters are individually optional, and nothing states that exactly one image source must be provided, which an agent could misinterpret as allowing zero or multiple inputs.

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 each of the four parameters (image_url, threshold, image_path, image_base64) bearing its own description, so the description need not repeat parameter syntax. It adds a slight conceptual frame ('outfit image or photo', confidence) but no parameter-level guidance beyond what the schema already provides, matching the baseline of 3.

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

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

The description opens with a specific verb and resource ('Deconstruct an outfit image or photo into individual fashion pieces') and names concrete output categories (Upper-body garment, Lower-body garment, Dress, Footwear, Bag, Headwear) plus bounding boxes and confidence scores. It clearly communicates a detection/decomposition operation that differs from the sibling search and curation tools, though it never names a sibling explicitly.

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 second sentence gives an explicit use case: 'Use this to break down full-body look photos and search for matching catalog items for each piece individually.' This provides clear context for when the tool applies, but it states no exclusions and names no alternatives, leaving the boundary with products.search.image_url and products.search.image_upload implicit.

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