Fashion & apparel MCP: visual outfit search, stock verification, and 1-click checkout.
Scored across 10 tools
Most tools have distinct purposes across search, curation, product details, and vision, but several pairs overlap: looks.curation.by_occasion and looks.curation.recommend both return occasion-based outfits, and products.items.check_stock overlaps heavily with products.items.get_by_handle. Image search is also split into upload and URL variants that could cause selection confusion.
Names follow a consistent module.submodule.action convention such as checkout.links.*, looks.curation.*, products.items.*, products.search.*, and vision.outfit.*, making navigation predictable. The final segments are slightly inconsistent—some are actions, some are nouns, and 'recommend' lacks an explicit object—but the namespace pattern mitigates this.
Ten tools is a reasonable size for a fashion-commerce assistant covering search, product details, curation, vision, and checkout linking. The count is slightly generous because image search is split into upload and URL variants and curation has overlapping occasion/recommend tools, but no tool feels trivial.
The set covers the key discovery-to-purchase flow: search, alternatives, stock checks, curated looks, outfit detection, and direct checkout links. It lacks broader browsing/category listing and cart/order management, but those appear outside the server's stated scope, so the gaps are minor.
Delete a saved delivery address by ID from ~/.polopan/region.json.
| Name | Required | Description | Default |
|---|---|---|---|
| address_id | Yes | ID of the saved address to delete |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and readOnlyHint=false, so irreversibility is covered. The description adds real value by naming the side-effect target (~/.polopan/region.json), but omits what happens if the ID is unknown or if the address is currently the default.
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?
One sentence, front-loaded with the verb and resource, with no filler. Every element 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 single-param destructive tool with full annotation coverage, a complete schema, and no output schema, the description supplies what the structured fields do not: the persistence location. Only missing edge-case behavior keeps it from a 5.
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 the single address_id parameter is documented in the schema, so baseline 3 applies. The description adds no format, source, or lookup detail beyond 'by ID'.
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 (Delete), a specific resource (a saved delivery address), the selector (by ID), and the storage target. It is clearly distinguishable from address.save, address.set_default, and address.list_saved without opening any 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?
Use case is implied by the intent — remove a saved address — but there is no explicit when-to-use guidance, no exclusion conditions, and no pointer to alternatives such as address.set_default for merely changing the default rather than deleting.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the default delivery/shipping address saved for the currently active region from local configuration (~/.polopan/region.json).
WHEN TO USE (CRITICAL ANTI-SHORTCIRCUIT RULE):
ALWAYS call this BEFORE generating 1-click checkout links to check if the user already has a saved delivery address for their destination country.
If 'has_address' is false, DO NOT emit a naked checkout link. Prompt the user naturally for their shipping address (First Name, Street Address, City, Postal Code, Phone & Email) and save it using 'address.save'.
If 'has_address' is true, inform the user you are prefilling their saved address and proceed with checkout.
| Name | Required | Description | Default |
|---|---|---|---|
| country | No | Optional country code (e.g. 'US', 'AE', 'GB', 'IN') to inspect addresses for. Defaults to active region country. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare this a safe read (readOnlyHint=true, destructiveHint=false), so the bar is lower. The description nonetheless adds real context: the data source is local config at ~/.polopan/region.json, and — importantly with no output schema present — it discloses the 'has_address' result flag that callers must branch on. It does not cover failure modes (missing/corrupt config file, no active region), which is a minor gap.
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 core purpose in one sentence, then uses a labeled block for the critical usage rule; every sentence carries actionable content. The uppercase 'CRITICAL ANTI-SHORTCIRCUIT RULE' framing is slightly dramatic but defensible given the downstream branching requirement.
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 returns and does disclose the key 'has_address' flag plus the prefill-vs-prompt behavior. It stops short of describing the remaining address fields or the error path when no region/config is available, so it 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 100%, so the single optional 'country' parameter (with code examples and default-to-active-region behavior) is already fully documented in the schema. The description's mention of the 'currently active region' restates rather than extends that semantics, so baseline 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+resource (get the default delivery/shipping address) and scopes it to the active region's local configuration. It is immediately distinguishable from siblings like address.list_saved or address.delete, which operate on address collections rather than the single active-region default.
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 directive ('ALWAYS call this BEFORE generating 1-click checkout links') plus branch-specific follow-ups depending on the result, and routes to a named alternative ('address.save') when no address exists. It even states the anti-pattern to avoid (emitting a naked checkout link) and what to ask the user for instead.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all saved customer delivery addresses stored in ~/.polopan/region.json, optionally filtered by country.
| Name | Required | Description | Default |
|---|---|---|---|
| country | No | Optional country filter (ISO-2 code or natural country name) |
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 by structured data. The description adds useful context by disclosing the backing store (~/.polopan/region.json), but says nothing about ordering, pagination, auth requirements, or behavior when the file is missing/empty — so it adds only modest value beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
One sentence, front-loaded with the verb and resource, followed by scope and the optional filter. No filler or redundancy; every clause carries information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter read-only list tool with full schema coverage, the description is nearly sufficient. Since there is no output schema, it could have stated what a returned address entry looks like (fields, ordering), which is the one remaining 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 100%, so the single 'country' parameter (ISO-2 or natural name, optional) is already fully documented in the schema. The description merely restates the filter without adding syntax, matching rules, or fallback behavior, so baseline 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?
States a specific verb+resource (list saved customer delivery addresses) and even names the storage location (~/.polopan/region.json), so the agent knows exactly what collection is being read. It is clearly distinct from write siblings like address.save/address.delete, but it does not explicitly differentiate itself from address.get_current, leaving a small routing ambiguity.
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 phrase 'optionally filtered by country' implies the intended usage (enumerate all saved addresses, narrow by country), but it is framed as a parameter note rather than guidance. There is no statement of when to prefer this over address.get_current or what happens when no filter is supplied, so usage is only implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Save a customer delivery shipping address mapped to the active region in ~/.polopan/region.json.
Matches Flutter app (newapp) address schema: firstName, lastName, address1, address2, city, province, zip, country, phone, email, type.
| Name | Required | Description | Default |
|---|---|---|---|
| id | No | Optional existing address ID to update | |
| zip | Yes | Postal code / Zip code / PIN code | |
| city | Yes | City / Town | |
| type | No | Address label/type: 'Home', 'Work', or 'Other' | Home |
| No | Customer delivery notification email address | ||
| phone | No | Recipient contact phone number with country dialing code | |
| country | No | Destination country code or natural name. Defaults to active region country. | |
| address1 | Yes | Street address, house/flat/building name | |
| address2 | No | Apartment, suite, unit, landmark, or area | |
| lastName | No | Recipient last name | |
| province | No | State, Province, or Governorate | |
| firstName | Yes | Recipient first name | |
| is_default | No | Set this address as default for the country (default true) | |
| storage_mode | No | Storage destination: 'local' (writes to ~/.polopan/region.json) or 'stateless' (returns for chat context without disk write). Defaults to 'stateless' in cloud-hosted environments. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations establish it is a non-destructive write; the description adds real value by disclosing the persistence target (~/.polopan/region.json), the region-mapping behavior, and schema parity with the Flutter app. It stops short of explaining update-vs-create conflict semantics or what happens to pre-existing addresses.
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 in one sentence, followed by a short schema-parity note. The second sentence is somewhat redundant with the schema's field list, but overall it is tight and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 14-parameter mutation tool with no output schema, the essential behavior (where it writes, region binding) is covered and safety is carried by annotations. It does not address return values, the outcome of an update to an existing id, or failure modes, leaving modest 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 100%, so the schema already carries all 14 parameter meanings (enums, defaults, id semantics, storage_mode). The description only re-lists field names that the schema already documents, adding no syntax or format detail beyond it, so baseline 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?
States a specific verb+resource (save/update a customer delivery shipping address) and clarifies its dual create-or-update role. It does not, however, name or contrast with address siblings like set_default or delete, leaving the agent to infer which address tool to reach for.
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?
There is no explicit when-to-use vs when-not guidance and no reference to alternatives such as address.set_default (relevant since is_default is a parameter) or address.delete. Usage is only implied from the tool name and the 'id' parameter.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Set an existing address as the default shipping address for its country in ~/.polopan/region.json.
| Name | Required | Description | Default |
|---|---|---|---|
| address_id | Yes | ID of the saved address to set as default |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false and destructiveHint=false, so the mutation/safety profile is covered. The description usefully adds that the change is persisted to ~/.polopan/region.json and scoped per-country, but it does not say whether an existing default for that country is overwritten or what happens if the address belongs to a different country.
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 front-loaded sentence with the verb first and zero wasted words. The persistence path is appended without diluting the core action.
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 one-parameter mutation with no output schema and safety annotations already present, the description covers what changes and where it is stored. It stops short of describing replacement semantics for an existing default or error conditions, but nothing critical for invocation 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% for the single address_id parameter, so the baseline is 3. The description only reinforces that the address must be 'existing' and implies its country drives the scope; it adds no format or validation detail 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 (set as default), the resource (an existing saved address), and the scope (default shipping address for its country). This clearly separates it from address.save (create), address.delete, and region.set_current (region-wide default).
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 word 'existing' implies a precondition that the address must already be saved, which implicitly routes creation to address.save, but no sibling is named and there is no explicit when-to-use/when-not guidance. Usage is inferable rather than stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Generate the direct 1-click checkout purchase URL for a specific product handle and size variant index (https://s.polopan.com/p/{handle}/{size_index}).
PURPOSE & DISAMBIGUATION:
Produces the final, verified 1-click buy link configured with the user's selected size index, unit quantity, and pre-applied coupon code.
Distinct from browsing links: General browsing uses base link (https://s.polopan.com/p/{handle}); this tool generates size-specific purchase permalinks (https://s.polopan.com/p/{handle}/{size_index}).
WHEN TO USE:
ONLY after the user has explicitly selected and confirmed their size (e.g. 'I want size M' or 'size 40').
WHEN NOT TO USE:
Do NOT provide direct checkout URLs with /{size_index} during initial product browsing, shortlisting, or if size is ambiguous (use base link https://s.polopan.com/p/{handle}).
BEHAVIOR & SAFETY:
Read-only link generator with no persistent state modifications or charges.
Automatically resolves variant index if a size string (e.g. 'M', 'L') is provided without size_index.
Encodes optional coupon parameters and quantity parameters into the final URL.
PARAMETERS & CONSTRAINTS:
'handle' (string, required): Unique product handle identifier.
'size' (string, optional): Size label confirmed by user (e.g. 'M', 'L', 'XL', '42').
'size_index' (integer >= 0, optional): Zero-based index of the chosen size variant.
'quantity' (integer 1-10, default 1): Number of units to purchase.
'coupon' (string, optional): Optional discount coupon code to pre-apply (e.g. 'SAVE15').
'address_id' (string, optional): ID of specific saved address to prefill.
'address' (object, optional): Delivery address object to prefill directly.
| Name | Required | Description | Default |
|---|---|---|---|
| size | No | Size label confirmed by the user (e.g. 'M', 'L', 'XL', '40') | |
| coupon | No | Optional discount coupon code to pre-apply in the checkout session | |
| handle | Yes | Unique product handle identifier (e.g. 'solid-linen-shirt', 'shopify_11206') | |
| address | No | Optional ad-hoc address object to prefill | |
| country | No | Country name, city, currency, or 2-letter ISO code (e.g. 'US', 'United States', 'UK', 'Dubai', 'CA', 'IN'). Defaults to active saved region. | |
| quantity | No | Number of units to purchase (1 to 10, default 1) | |
| address_id | No | Optional saved address ID to prefill | |
| size_index | No | Zero-based index of the chosen size variant |
Discover complete curated fashion looks styled for specific occasions (e.g., 'Wedding & Reception', 'Party', 'Casual', 'Cocktail', 'Date Night', 'Club Night', 'Brunch', 'Vacation', 'Formal'). All returned looks are verified 100% in-stock (any look with an out-of-stock item is automatically excluded). Automatically localized to active country / 240+ destination regions.
PURPOSE & DISAMBIGUATION:
Curates multi-item aesthetic outfits tailored to specific social events, vibes, and demographics.
Distinct from 'products.search.text': Use this tool to retrieve complete harmonized outfits, NOT individual standalone products.
Distinct from 'looks.curation.recommend': Use this tool to discover outfits by occasion/event theme without a seed product, whereas 'looks.curation.recommend' builds outfits around a specific product handle.
WHEN TO USE:
When a user seeks outfit inspiration or complete looks for events (e.g. 'What to wear to a summer cocktail party?', 'Brunch outfit for men', 'Date night dresses').
WHEN NOT TO USE:
Do NOT use when searching for a single product category (use 'products.search.text').
Do NOT use when coordinating around a specific item the user already picked (use 'looks.curation.recommend').
BEHAVIOR & SAFETY:
Read-only and idempotent with no persistent state modifications.
Strictly filters out any look containing an out-of-stock item (guarantees 100% purchaseable outfits).
Enriches all included products with verified PoloPan purchase links (https://s.polopan.com/p/{handle}) and policy data.
PARAMETERS & CONSTRAINTS:
'occasion' (string, optional): Target occasion or theme ('Wedding & Reception', 'Party', 'Casual', 'Cocktail', 'Date Night', 'Club Night', 'Brunch', 'Vacation', 'Formal').
'gender' (enum, default 'women'): Target gender filter ('women', 'men', 'female', 'male').
'country' (string, optional): Target country name, city, currency, or ISO-2 code (e.g. 'US', 'United States', 'UK', 'Dubai', 'CA', 'IN'). Defaults to active saved region.
'mode' (enum, optional): Catalog mode: 'global' (ships to country) or 'local' (domestic only).
'age' (integer 16-99, default 25): Target demographic age.
'page' (integer >= 1, default 1): Pagination page number.
'page_size' (integer 1-100, default 10): Number of looks per page.
'vendor' (array of strings, optional): Optional brand filter array.
MANDATORY AGENT INSTRUCTIONS:
Always inform the user of available in-stock sizes, fast shipping SLA, and return policy for each item (Negative return days = 'Exchange only |X| days').
When shortlisting a look, render the product specifications table (Fabric, Pattern, Collar, Sleeves, Fit, Care).
Provide the clean base link (https://s.polopan.com/p/{handle}) during browsing. Provide direct 1-click checkout link (https://s.polopan.com/p/{handle}/{size_index}) ONLY after the user's size is finalized.
| Name | Required | Description | Default |
|---|---|---|---|
| age | No | Target demographic age (16 to 99, default 25) | |
| mode | No | Catalog mode: 'global' (ships to country) or 'local' (domestic only). Defaults to active saved region. | |
| page | No | Page number for looks pagination (1-indexed) | |
| gender | No | Target gender filter: 'women' or 'men' (default: 'women') | women |
| vendor | No | Optional brand or vendor name filter array | |
| country | No | Country name, city, currency, or 2-letter ISO code (e.g. 'US', 'United States', 'UK', 'Dubai', 'CA', 'IN'). Defaults to active saved region. | |
| occasion | No | Target occasion or vibe: 'Wedding & Reception', 'Party', 'Casual', 'Cocktail', 'Date Night', 'Club Night', 'Brunch', 'Vacation', 'Formal' | |
| page_size | No | Number of looks returned per page (1 to 100, default 10) |
Get complete recommended outfits. Pass a product 'handle' to find complementary items styled with it, OR pass an 'occasion' (e.g. 'Wedding & Reception', 'Party', 'Cocktail', 'Date Night', 'Formal') and 'gender' to discover full occasion looks. All returned looks are verified 100% in-stock (any look with an out-of-stock item is excluded). Automatically localized to active country / 240+ destination regions.
PURPOSE & DISAMBIGUATION:
Generates harmonized outfits coordinated around a seed product handle or occasion theme.
Distinct from 'products.search.alternatives': Use 'looks.curation.recommend' to build coordinating outfits with different garment pieces (e.g. pairing pants and shoes with a shirt); use 'products.search.alternatives' to find visual replacements for the exact same garment.
Distinct from 'looks.curation.by_occasion': 'looks.curation.recommend' supports building outfits around a specific chosen product handle as well as occasion themes.
WHEN TO USE:
When a user has selected a product and asks 'How do I style this?' or 'Show me outfits with this shirt'.
When discovering coordinated outfit recommendations for an occasion.
WHEN NOT TO USE:
Do NOT use to find substitute alternatives of the same garment (use 'products.search.alternatives').
Do NOT use for basic keyword search (use 'products.search.text').
BEHAVIOR & SAFETY:
Read-only and idempotent with no persistent state modifications.
Filters out any outfit containing out-of-stock items (guarantees 100% purchaseable looks).
Enriches all included items with verified purchase permalinks and policy strings.
PARAMETERS & CONSTRAINTS:
'handle' (string, optional): Product handle identifier to build coordinating outfits around (e.g. 'solid-linen-shirt').
'occasion' (string, optional): Target occasion or theme (e.g. 'Wedding & Reception', 'Party', 'Cocktail', 'Date Night', 'Formal').
'gender' (enum, default 'women'): Target gender filter ('women', 'men', 'female', 'male').
'country' (string, optional): Target country name, city, currency, or ISO-2 code (e.g. 'US', 'United States', 'UK', 'Dubai', 'CA', 'IN'). Defaults to active saved region.
'mode' (enum, optional): Catalog mode: 'global' (ships to country) or 'local' (domestic only).
'page' (integer >= 1, default 1): Pagination page number.
'page_size' (integer 1-100, default 20): Number of outfit sets per page.
MANDATORY AGENT INSTRUCTIONS:
Always inform the user of available in-stock sizes, fast shipping SLA, and return policy for each item (Negative return days = 'Exchange only |X| days').
When shortlisting a look, render the product specifications table (Fabric, Pattern, Collar, Sleeves, Fit, Care).
Provide the base link (https://s.polopan.com/p/{handle}) during shortlisting. Provide direct 1-click checkout link (https://s.polopan.com/p/{handle}/{size_index}) ONLY after the user's size is finalized.
| Name | Required | Description | Default |
|---|---|---|---|
| mode | No | Catalog mode: 'global' (ships to country) or 'local' (domestic only). Defaults to active saved region. | |
| page | No | Page number for pagination (1-indexed) | |
| gender | No | Target gender filter: 'women' or 'men' (default: 'women') | women |
| handle | No | Product handle identifier to build coordinating outfits around (e.g. 'solid-linen-shirt') | |
| country | No | Country name, city, currency, or 2-letter ISO code (e.g. 'US', 'United States', 'UK', 'Dubai', 'CA', 'IN'). Defaults to active saved region. | |
| occasion | No | Target occasion or aesthetic theme (e.g. 'Wedding & Reception', 'Party', 'Cocktail', 'Date Night', 'Formal') | |
| page_size | No | Number of outfit sets to return per page (1 to 100, default 20) |
Verify real-time live stock availability, discounted pricing, product specifications table (Fabric, Pattern, Collar, Sleeves, Fit, Care Instructions), shipping/return policies, and available size variants for a specific fashion product handle.
PURPOSE & DISAMBIGUATION:
Real-time inventory and metadata inspection tool for a single product.
Computes the full size-availability matrix, active pricing, discount percentage, specifications dictionary, and resolves the 1-click checkout permalink for a chosen size.
Distinct from 'products.items.get_by_handle': Use this tool to check live stock, available sizes, formatted policies, and get size-specific checkout links; use 'products.items.get_by_handle' for raw catalog document retrieval.
Distinct from 'checkout.links.get_direct_url': Use this tool to verify stock and sizing options; use 'checkout.links.get_direct_url' to generate a final permalink once a size is confirmed.
WHEN TO USE:
Before presenting or confirming a product to the user, to verify whether their desired size is in-stock.
When generating the mandatory product specifications table (Fabric, Pattern, Collar, Sleeves, Fit, Care).
When checking return/exchange eligibility and shipping dispatch timelines.
WHEN NOT TO USE:
Do NOT use to search across multiple catalog products (use 'products.search.text' or 'products.search.image_url').
BEHAVIOR & SAFETY:
Read-only and idempotent with no persistent state modifications.
Automatically maps numeric and Indian/UK/EU shoe and apparel sizes (e.g. '6' -> EU 39, 'M' -> Medium).
Formats negative return days cleanly as 'Exchange only |X| days' (e.g. -7 -> 'Exchange only 7 days').
Returns structured JSON with 'is_in_stock', 'available_sizes', 'out_of_stock_sizes', 'product_details', 'shipping_policy_text', and 'return_policy_text'.
PARAMETERS & CONSTRAINTS:
'handle' (string, required): Unique product handle identifier (e.g. 'solid-linen-shirt', 'shopify_11206').
'desired_size' (string, optional): Size label to verify against the variant inventory (e.g. 'M', 'L', 'XL', '32', '40').
'size_index' (integer >= 0, optional): Zero-based index of the size variant.
MANDATORY AGENT INSTRUCTIONS:
Always inform the user of available in-stock sizes, fast dispatch SLA, and return policy (Negative return days = 'Exchange only |X| days').
Display the product specifications table (Fabric, Pattern, Collar, Sleeves, Fit, Care).
Return the base link (https://s.polopan.com/p/{handle}) during browsing. Provide direct checkout link (https://s.polopan.com/p/{handle}/{size_index}) ONLY after the user's size is finalized.
| Name | Required | Description | Default |
|---|---|---|---|
| handle | Yes | Unique product handle identifier (e.g. 'solid-linen-shirt', 'shopify_11206') | |
| country | No | Country name, city, currency, or 2-letter ISO code (e.g. 'US', 'United States', 'UK', 'Dubai', 'CA', 'IN'). Defaults to active saved region. | |
| size_index | No | Zero-based index of the specific size variant to inspect | |
| desired_size | No | Optional size query to verify against variant inventory (e.g. 'M', 'L', 'XL', '32', '40') |
Fetch the raw product document and metadata for a single item by unique product handle identifier. Returns catalog metadata, variant details, available in-stock sizes, price details, and verified purchase link (https://s.polopan.com/p/{handle}).
PURPOSE & DISAMBIGUATION:
Retrieves the full catalog record for a specific product handle.
Distinct from 'products.items.check_stock': Use 'products.items.get_by_handle' to fetch general catalog metadata; use 'products.items.check_stock' to get live variant inventory availability, computed sizing, specifications table, and 1-click checkout permalinks.
Distinct from 'products.search.text': Use this tool when you already have an exact product handle.
WHEN TO USE:
When you need the raw product metadata, image list, description, or variant array for a known product handle.
WHEN NOT TO USE:
Do NOT use to check real-time variant stock or obtain 1-click checkout URLs (use 'products.items.check_stock').
Do NOT use for general keyword product searches (use 'products.search.text').
BEHAVIOR & SAFETY:
Read-only and idempotent with no persistent state modifications.
Returns HTTP 404 error if handle does not exist.
Enriches returned document with verified purchase URLs.
PARAMETERS & CONSTRAINTS:
'handle' (string, required): Unique product handle identifier (e.g. 'solid-linen-shirt', 'shopify_11206').
| Name | Required | Description | Default |
|---|---|---|---|
| handle | Yes | Unique product handle identifier (e.g. 'solid-linen-shirt', 'shopify_11206') | |
| country | No | Country name, city, currency, or 2-letter ISO code (e.g. 'US', 'United States', 'UK', 'Dubai', 'CA', 'IN'). Defaults to active saved region. |
Retrieve the complete size guide chart, body measurement matrix (Chest/Bust, Waist, Hip, Length, Shoulders), unit switcher (inches/cm), how-to-measure guidelines, and automatic best-fit size recommendations for a specific product handle.
PURPOSE & DISAMBIGUATION:
Dedicated size guide and fit consultancy tool for apparel and footwear.
Computes dimensional measurements across sizes, supports metric (cm) <-> imperial (in) unit conversions, and maps international/brand scales.
If user body measurements are provided (e.g. chest: 40 in, waist: 32 in), computes the best matching size variant with fit confidence and relaxed vs snug fit advice.
Distinct from 'products.items.check_stock': Use 'products.items.get_size_guide' when the user asks sizing/fit questions (e.g. 'What size fits a 40 chest?' or 'Show me the size chart'); use 'products.items.check_stock' for inventory checking.
WHEN TO USE:
When a user asks about sizing, fit, measurements, or how a garment fits (e.g., 'Is M true to size?', 'What are the chest measurements for this shirt in cm?').
When helping a customer choose between two sizes based on their body dimensions.
When rendering a full size chart matrix.
WHEN NOT TO USE:
Do NOT use for products without size variants (e.g., standard accessories, bags).
BEHAVIOR & SAFETY:
Read-only and idempotent.
Supports 'in' (inches) and 'cm' (centimeters) with automated dynamic range conversion.
Connects each recommended size to its direct 1-click checkout permalink (https://s.polopan.com/p/{handle}/{size_index}).
PARAMETERS & CONSTRAINTS:
'handle' (string, required): Unique product handle identifier.
'unit' (enum 'in' | 'cm', default 'in'): Preferred measurement unit system.
'desired_size' (string, optional): Specific size variant to inspect (e.g. 'M', 'L', '32', '40').
'user_chest' (number, optional): User's chest / bust body measurement.
'user_waist' (number, optional): User's waist body measurement.
'user_hip' (number, optional): User's hip body measurement.
'user_unit' (enum 'in' | 'cm', default 'in'): Unit of the user's provided body measurements.
| Name | Required | Description | Default |
|---|---|---|---|
| unit | No | Measurement unit system for the size chart ('in' for inches, 'cm' for centimeters) | in |
| handle | Yes | Unique product handle identifier (e.g. 'solid-linen-shirt', 'shopify_11206') | |
| user_hip | No | Optional user body hip measurement for automated fit recommendation | |
| user_unit | No | Unit for the user's input measurements ('in' or 'cm') | in |
| user_chest | No | Optional user body chest/bust measurement for automated fit recommendation | |
| user_waist | No | Optional user body waist measurement for automated fit recommendation | |
| desired_size | No | Optional specific size label to highlight or verify (e.g. 'M', 'L', 'XL', '32') |
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 and the restated 'Read-only and idempotent' adds little. The description does add genuine behavioral context beyond annotations: dynamic in/cm conversion, fit-confidence with relaxed vs snug advice when body measurements are supplied, and a per-size 1-click checkout permalink. It stops short of describing output format or edge-case handling (e.g., product lacking a size chart).
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 and the sectioned layout (purpose, disambiguation, when/when-not, behavior, parameters) is easy to scan. It is somewhat long and has mild redundancy, notably restating the read-only/idempotent facts already in annotations and repeating example sizing questions across the purpose and WHEN TO USE sections.
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 correctly carries the return-value burden and does so concretely, enumerating the chart, measurement matrix, unit switcher, how-to-measure guidelines, and fit recommendation plus permalink. Combined with full parameter coverage, an agent has everything needed to invoke and interpret this 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 description coverage is 100%, so the baseline is 3. The description goes modestly beyond the schema by clarifying the semantic split between 'unit' (chart unit) and 'user_unit' (unit of the user's own measurements), which the schema leaves ambiguous since both default to 'in', and by explaining that user_chest/waist/hip jointly drive best-fit computation. It adds clarifying value but no new syntax 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 opening sentence states a specific verb (Retrieve) and enumerates the exact resource returned (size guide chart, body measurement matrix, unit switcher, fit recommendations) scoped to a product handle. It explicitly distinguishes itself from sibling 'products.items.check_stock' by mapping sizing/fit questions to this tool and inventory questions to the other, so an agent can route without opening either 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?
The definition provides explicit WHEN TO USE bullets (sizing, fit, measurements, rendering a chart), an explicit WHEN NOT TO USE exclusion (products without size variants such as accessories/bags), and names the alternative sibling plus the condition that selects it. Nothing 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.
Find visual substitute products within a designated price bracket for a given fashion item handle using visual image similarity. Automatically localized to active country / 240+ destination regions.
PURPOSE & DISAMBIGUATION:
Retrieves catalog items visually similar to an existing product (e.g. finding similar shirts or jackets) constrained to a target budget tier.
Distinct from 'products.search.text': Use this tool when substituting a specific known item by handle, NOT for free-text search queries.
Distinct from 'products.search.image_url' / 'products.search.image_upload': Use this tool when referencing an existing catalog item handle, NOT for user-uploaded or external images.
Distinct from 'looks.curation.recommend': Use this tool to find replacement substitutes for the same garment category, NOT for pairing complementary outfit pieces.
WHEN TO USE:
When a shopper likes a product but requests cheaper alternatives, higher-end alternatives, or similar styles in a specific price bracket (e.g., 'show cheaper alternatives for this shirt under 1500').
WHEN NOT TO USE:
Do NOT use for general keyword discovery without a source product handle (use 'products.search.text').
Do NOT use to assemble a full outfit / lookbook (use 'looks.curation.recommend' or 'looks.curation.by_occasion').
BEHAVIOR & SAFETY:
Read-only and idempotent with no persistent side effects.
Automatically fetches the source product's primary image embedding and queries the catalog for visual matches within the requested price range.
Excludes the source product handle from returned alternatives.
Returns clean PoloPan purchase permalinks (https://s.polopan.com/p/{handle}).
PARAMETERS & CONSTRAINTS:
'handle' (string, required): The unique identifier of the source product to find alternatives for.
'budget_range' (enum, default '1501-3000'): Price tier bracket ('0-1500', '1501-3000', '3001-5000', '5000+').
'country' (string, optional): Target country name, city, currency, or ISO-2 code (e.g. 'US', 'United States', 'UK', 'Dubai', 'CA', 'IN'). Defaults to active saved region.
'mode' (enum, optional): Catalog mode: 'global' (ships to country) or 'local' (domestic only).
'limit' (integer 1-100, default 6): Maximum number of alternative products returned in the final list.
'page' (integer >= 1, default 1): Pagination page number for the search pool.
'page_size' (integer 1-100, default 8): Number of candidate items fetched per page before limit filtering.
'sort_by' (enum, default 'relevance'): Ranking attribute ('relevance', 'price', 'title').
'sort_order' (enum, default 'desc'): Sort order direction ('asc' or 'desc').
'personalize' (boolean, default false): Whether to apply personalization weights.
| Name | Required | Description | Default |
|---|---|---|---|
| mode | No | Catalog mode: 'global' (ships to country) or 'local' (domestic only). Defaults to active saved region. | |
| page | No | Pagination page number (1-indexed) | |
| limit | No | Maximum number of filtered alternative products to return in the result (1-100) | |
| handle | Yes | The unique product handle identifier to find visual alternatives for (e.g. 'solid-cotton-shirt') | |
| country | No | Country name, city, currency, or 2-letter ISO code (e.g. 'US', 'United States', 'UK', 'Dubai', 'CA', 'IN'). Defaults to active saved region. | |
| sort_by | No | Sorting attribute for the visual matches: 'relevance', 'price', or 'title' | relevance |
| page_size | No | Number of candidate items to fetch per backend page (1-100) | |
| sort_order | No | Sort direction: 'asc' for ascending, 'desc' for descending | desc |
| personalize | No | Whether to apply personalized user ranking to the results | |
| budget_range | No | Target price bracket filter in local currency: '0-1500', '1501-3000', '3001-5000', or '5000+' | 1501-3000 |
Upload a local image file (or base64 string) and search PoloPan catalog products using visual image similarity. Returns matching products with available in-stock sizes, pricing, and verified purchase URLs (https://s.polopan.com/p/{handle}). Automatically localized to active country / 240+ destination regions.
PURPOSE & DISAMBIGUATION:
Performs reverse visual search by uploading a local or base64-encoded image to secure temporary storage, then querying visual embeddings.
Distinct from 'products.search.image_url': Use this tool when the image file is local on the user's machine or in base64 format, NOT already on a public URL.
Distinct from 'vision.outfit.detect_pieces': Use this tool to search for products matching a single garment, NOT for decomposing full multi-piece outfits into bounding boxes.
WHEN TO USE:
When a user uploads a local photo/screenshot or supplies base64 image data to find matching fashion products in the catalog.
WHEN NOT TO USE:
Do NOT use when the image is already accessible via a public web URL (use 'products.search.image_url').
Do NOT use for text-only searches (use 'products.search.text').
BEHAVIOR & SAFETY:
Read-only catalog query with temporary image upload artifact (automatically expires after 'expiry_hours', default 24h).
Resolves MIME types automatically if not explicitly provided.
Enriches all returned items with verified PoloPan purchase links and stock metadata.
PARAMETERS & CONSTRAINTS:
'image_path' (string, optional): Local file system path to the image file (one of image_path or image_base64 is required).
'image_base64' (string, optional): Base64-encoded image data string.
'country' (string, optional): Target country name, city, currency, or ISO-2 code (e.g. 'US', 'United States', 'UK', 'Dubai', 'CA', 'IN'). Defaults to active saved region.
'mode' (enum, optional): Catalog mode: 'global' (ships to country) or 'local' (domestic only).
'content_type' (string, default 'image/jpeg'): MIME type of the uploaded image (e.g. 'image/jpeg', 'image/png', 'image/webp').
'expiry_hours' (integer 1-168, default 24): Temporary upload lifetime in hours before expiration.
'page' (integer >= 1, default 1): Pagination page number.
'page_size' (integer 1-100, default 20): Number of items per page.
'sort_by' (enum, default 'relevance'): Sorting attribute ('relevance', 'price', 'title').
'sort_order' (enum, default 'desc'): Sort direction ('asc' or 'desc').
'gender' (string, optional): Target gender filter ('men', 'women', or 'unisex').
'size' (array of strings, optional): Size filter array.
'price_min' (number, optional): Minimum price threshold.
'price_max' (number, optional): Maximum price threshold.
'vendor' (array of strings, optional): Brand filter array.
'personalize' (boolean, default false): Whether to personalize search ranking.
| Name | Required | Description | Default |
|---|---|---|---|
| mode | No | Catalog mode: 'global' (ships to country) or 'local' (domestic only). Defaults to active saved region. | |
| page | No | Pagination page number (1-indexed) | |
| size | No | Array of sizes to filter by | |
| gender | No | Target gender filter: 'men', 'women', or 'unisex' | |
| vendor | No | List of brand names to filter by | |
| country | No | Country name, city, currency, or 2-letter ISO code (e.g. 'US', 'United States', 'UK', 'Dubai', 'CA', 'IN'). Defaults to active saved region. | |
| sort_by | No | Sorting criteria: 'relevance', 'price', or 'title' | relevance |
| page_size | No | Number of items to return per page (1 to 100, default 20) | |
| price_max | No | Maximum price in local currency | |
| price_min | No | Minimum price in local currency | |
| image_path | No | Local file system path to the image file (e.g. '/path/to/dress.jpg') | |
| sort_order | No | Sort order: 'asc' or 'desc' | desc |
| personalize | No | Whether to apply personalized ranking weights | |
| content_type | No | MIME type of the image, e.g. 'image/jpeg', 'image/png', 'image/webp' | image/jpeg |
| expiry_hours | No | Temporary upload URL lifetime in hours before expiration (1 to 168, default 24) | |
| image_base64 | No | Base64-encoded image data string (alternative to image_path) |
Search PoloPan catalog products using visual image similarity from a publicly accessible image URL with optional multi-attribute filters. Returns visually similar products with available sizes, pricing, and verified purchase URLs (https://s.polopan.com/p/{handle}). Automatically localized to active country / 240+ destination regions.
PURPOSE & DISAMBIGUATION:
Performs reverse visual search using computer-vision embeddings for a remote image URL.
Distinct from 'products.search.text': Use this tool when you have an image URL, NOT for textual keyword queries.
Distinct from 'products.search.image_upload': Use this tool for publicly hosted HTTP(S) image URLs, NOT for local file paths or base64 data.
Distinct from 'vision.outfit.detect_pieces': Use this tool to search catalog items matching an entire single-garment image, NOT for segmenting multi-garment influencer photos into bounding boxes.
WHEN TO USE:
When the user shares a web link to an image (e.g. Pinterest, Instagram, blog post) and wants to find visually matching products in the PoloPan catalog.
WHEN NOT TO USE:
Do NOT use when the image is stored on local disk or as base64 data (use 'products.search.image_upload').
Do NOT use when searching by text descriptions (use 'products.search.text').
Do NOT use when you need to crop/isolate individual outfit pieces from a full-body model photo (use 'vision.outfit.detect_pieces').
BEHAVIOR & SAFETY:
Read-only and idempotent with no persistent state modifications.
Downloads the image, generates visual embeddings, and retrieves ranked catalog matches.
Enriches all returned items with verified PoloPan purchase links and stock metadata.
PARAMETERS & CONSTRAINTS:
'image_url' (string, required): Publicly accessible HTTP(S) URL of the image to search for visual matches.
'country' (string, optional): Target country name, city, currency, or ISO-2 code (e.g. 'US', 'United States', 'UK', 'Dubai', 'CA', 'IN'). Defaults to active saved region.
'mode' (enum, optional): Catalog mode: 'global' (ships to country) or 'local' (domestic only).
'page' (integer >= 1, default 1): Pagination page number.
'page_size' (integer 1-100, default 20): Number of candidate items returned per page.
'sort_by' (enum, default 'relevance'): Ranking attribute ('relevance', 'price', 'title').
'sort_order' (enum, default 'desc'): Sort order ('asc' or 'desc').
'gender' (string, optional): Target gender filter ('men', 'women', or 'unisex').
'size' (array of strings, optional): Filter by available size labels.
'price_min' (number, optional): Minimum price threshold.
'price_max' (number, optional): Maximum price threshold.
'vendor' (array of strings, optional): Brand filter array.
'personalize' (boolean, default false): Whether to apply personalized ranking weights.
| Name | Required | Description | Default |
|---|---|---|---|
| mode | No | Catalog mode: 'global' (ships to country) or 'local' (domestic only). Defaults to active saved region. | |
| page | No | Page number for pagination (1-indexed) | |
| size | No | Array of sizes to filter by (e.g. ['S', 'M', 'L']) | |
| gender | No | Target gender filter: 'men', 'women', or 'unisex' | |
| vendor | No | List of brand names to filter by | |
| country | No | Country name, city, currency, or 2-letter ISO code (e.g. 'US', 'United States', 'UK', 'Dubai', 'CA', 'IN'). Defaults to active saved region. | |
| sort_by | No | Sorting criteria for search results: 'relevance', 'price', or 'title' | relevance |
| image_url | Yes | Publicly accessible HTTP(S) URL of the fashion image to search for visual matches | |
| page_size | No | Number of items to return per page (1 to 100, default 20) | |
| price_max | No | Maximum price in local currency | |
| price_min | No | Minimum price in local currency | |
| sort_order | No | Sort order: 'asc' for ascending, 'desc' for descending | desc |
| personalize | No | Whether to apply personalized ranking based on user style profile |
Search PoloPan catalog products using a text keyword query with optional multi-attribute filters. Returns matching fashion items with available in-stock sizes, product specifications, shipping/return policies, discounted pricing, and verified purchase URLs (https://s.polopan.com/p/{handle}). Automatically localized to active country / 240+ destination regions.
PURPOSE & DISAMBIGUATION:
Primary text-based catalog search tool for fashion discovery across apparel, footwear, and accessories.
Distinct from 'products.search.image_url' / 'products.search.image_upload': Use this tool for textual queries and keyword filters, NOT for visual image search.
Distinct from 'products.search.alternatives': Use this tool for open discovery queries, NOT for finding direct visual substitutes of a known product handle.
Distinct from 'looks.curation.by_occasion': Use this tool to search individual products, NOT complete multi-piece outfit looks.
WHEN TO USE:
When a user searches for clothing or fashion styles using keywords, brand names, colors, or categories (e.g. 'black leather jacket', 'floral summer midi dress', 'men linen shirts').
When refining catalog searches with structured filters like price ranges, gender, sizes, country regions, or vendor brands.
WHEN NOT TO USE:
Do NOT use when the user provides an image URL or image file (use 'products.search.image_url' or 'products.search.image_upload').
Do NOT use when searching for cheaper/higher-end substitutes of a specific known product (use 'products.search.alternatives').
Do NOT use to find curated complete occasion outfits (use 'looks.curation.by_occasion').
BEHAVIOR & SAFETY:
Read-only and idempotent with no persistent state modifications.
Automatically sanitizes and enriches product records with verified PoloPan short permalinks (https://s.polopan.com/p/{handle}), computed in-stock size lists, and human-readable shipping and return policy strings.
Handles pagination and multi-attribute filtering deterministically.
PARAMETERS & CONSTRAINTS:
'query' (string, required): Free-text search query or style keyword (e.g. 'black linen shirt', 'oversized hoodie').
'country' (string, optional): Target country name, city, currency, or ISO-2 code (e.g. 'US', 'United States', 'UK', 'Dubai', 'CA', 'IN'). Defaults to active saved region.
'mode' (enum, optional): Catalog mode: 'global' (ships to country) or 'local' (domestic only).
'page' (integer >= 1, default 1): Pagination page number.
'page_size' (integer 1-100, default 20): Number of products returned per page.
'sort_by' (enum, default 'relevance'): Ranking criterion ('relevance', 'price', 'title').
'sort_order' (enum, default 'desc'): Sort direction ('asc' for ascending, 'desc' for descending).
'gender' (string, optional): Target demographic filter ('men', 'women', or 'unisex').
'size' (array of strings, optional): Size filter array (e.g. ['S', 'M', 'L', 'XL', '32', '40']).
'price_min' (number, optional): Minimum price threshold in local currency.
'price_max' (number, optional): Maximum price threshold in local currency.
'vendor' (array of strings, optional): List of brand or vendor names to filter by.
MANDATORY AGENT INSTRUCTIONS:
Always communicate available in-stock sizes, fast dispatch SLA, and return policy for each product (Negative return days = 'Exchange only |X| days').
When presenting or shortlisting products, display the product specifications table (Fabric, Pattern, Collar, Sleeves, Fit, Care).
Return the clean base link (https://s.polopan.com/p/{handle}) during browsing. Provide direct checkout link (https://s.polopan.com/p/{handle}/{size_index}) ONLY after the user's size is finalized.
| Name | Required | Description | Default |
|---|---|---|---|
| mode | No | Catalog mode: 'global' (ships to country) or 'local' (domestic only). Defaults to active saved region. | |
| page | No | Pagination page number (1-indexed, starts at 1) | |
| size | No | Array of size labels to filter by (e.g. ['S', 'M', 'L', 'XL', '32']) | |
| query | Yes | The search query or style keyword to find fashion items (e.g. 'black leather jacket', 'floral summer midi dress') | |
| gender | No | Target gender filter: 'men', 'women', or 'unisex' | |
| vendor | No | List of brand or vendor names to filter by (e.g. ['Zara', 'H&M', 'Tandul']) | |
| country | No | Country name, city, currency, or 2-letter ISO code (e.g. 'US', 'United States', 'UK', 'Dubai', 'CA', 'IN'). Defaults to active saved region. | |
| sort_by | No | Sorting criteria for search results: 'relevance', 'price', or 'title' | relevance |
| page_size | No | Number of items to return per page (1 to 100, default 20) | |
| price_max | No | Maximum price in local currency | |
| price_min | No | Minimum price in local currency | |
| sort_order | No | Sort order: 'asc' for ascending, 'desc' for descending | desc |
Get the currently active shopping destination country, currency code, symbol, phone code, and catalog scope mode from persistent local configuration (~/.polopan/region.json).
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
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 genuinely useful context by disclosing the data source (persistent local configuration at ~/.polopan/region.json), implying no network call and locally persisted state.
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 front-loaded sentence enumerating the returned fields with zero filler; every clause carries 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?
With no output schema and no parameters, the description appropriately enumerates the returned values (country, currency code, symbol, phone code, catalog scope mode) and the source of truth. It stops short of describing behavior when no region is configured, which is the only real 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?
The tool takes zero parameters, so the schema has nothing to document and the baseline is 4. All semantic weight falls on the described return content, which the schema does not cover.
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 (Get) plus the exact resource and the fields returned (destination country, currency code, symbol, phone code, catalog scope mode). It is clearly distinguishable from region.set_current and region.list_supported by verb alone.
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?
Usage is only implied by the verb 'Get' and the sibling pair region.set_current / region.list_supported; there is no explicit statement of when to call this versus those alternatives or whether the state can be absent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search the 240+ supported destination countries with localized currency codes, symbols, flags, phone codes, and price groups from live platform settings.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max number of countries to return (default: 20) | |
| query | No | Optional search filter by country name, ISO code, currency, or phone dialing code (e.g. 'Emirates', 'dollar', 'CAD', 'Europe') |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true / destructiveHint=false, so the safety profile is covered. Beyond that, the description adds real context: the size of the dataset (240+), the fields attached to each entry (currency codes, symbols, flags, phone codes, price groups) and the fact they come from 'live platform settings' (i.e., data may change). It is silent on pagination behavior despite the limit parameter.
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 front-loaded sentence with the verb first and no filler; the trailing field list is doing work by previewing the payload. Nothing could be removed without losing information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple, read-only, two-optional-parameter tool, the description covers purpose and the shape of the returned records, which matters because there is no output schema. Only pagination/limit interaction and any search-matching caveats remain unaddressed, and those are minor for this complexity level.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, including the query field's accepted search axes and an example, so the schema already carries the parameter burden. The description echoes the search concept but adds no syntax, matching rules, or default/limit behavior beyond what the schema states. 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 pairs a specific verb ('Search') with a specific resource ('240+ supported destination countries') and enumerates the data carried on each result, so the agent knows this is a catalog/read tool rather than a lookup of the user's own region. It does not explicitly contrast itself with region.get_current / region.set_current, but the scope is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is only implied: calling it a search over 'supported destination countries' hints at discovery/validation use cases, but there is no statement of when to prefer this over region.get_current or the address.* tools, and no prerequisites or exclusions are given. Minimum viable guidance, nothing more.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Set the active shopping country/region using any natural country name, city (e.g. 'Dubai', 'London', 'California', 'Paris'), 2-letter ISO code ('US', 'GB', 'IN', 'AE', 'CA'), or currency ('USD', 'AED', 'GBP', 'EUR'). Saves to persistent local JSON (~/.polopan/region.json) so the user never needs to be asked again across turns and sessions.
| Name | Required | Description | Default |
|---|---|---|---|
| mode | No | Catalog mode: 'global' (ships to country) or 'local' (domestic store only). Defaults to 'global'. | |
| country | Yes | Target country name, alias, city, currency, or ISO-2 code (e.g. 'United States', 'US', 'UK', 'London', 'Dubai', 'UAE', 'Canada', 'India', 'Germany', 'AED', 'EUR') |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only declare readOnlyHint=false and destructiveHint=false; the description adds the genuinely useful behavioral fact that the value is written to a persistent local JSON file (~/.polopan/region.json) and survives across turns and sessions. It does not say what happens on an unrecognized region or whether validation failures are possible, which keeps it 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, both front-loaded: the first covers accepted inputs, the second covers the persistence side effect. No filler and no repetition of the title.
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, and the description covers the action, the input flexibility, and the side effect, which is nearly everything an agent needs to call a 2-parameter setter. It omits error/validation behavior for invalid regions and whether the call requires prior authentication.
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, but the description adds real semantic value by enumerating the accepted input variants (natural name, city, ISO-2, currency) and giving concrete examples that clarify the loosely typed 'country' string. It does not explain the interaction between the 'country' and 'mode' 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?
States a specific verb (Set) and resource (active shopping country/region) and implicitly distinguishes itself from region.get_current and region.list_supported by describing the write action and what it accepts. An agent can tell exactly what this tool mutates 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?
The description gives a rich and explicit set of accepted input forms (country name, city, ISO-2 code, currency) and explains the persistence rationale. It stops short of naming sibling alternatives (e.g., region.list_supported to discover valid values, region.get_current to read the current value), so routing is implied rather than stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Deconstruct an outfit image or influencer photo into individual fashion pieces (e.g. Upper-body garment, Lower-body garment, Dress, Footwear, Bag, Headwear) with normalized bounding box coordinates and detection confidence scores.
PURPOSE & DISAMBIGUATION:
Computer-vision object detection tool designed to analyze multi-item outfit photographs and isolate individual garments with their spatial coordinates.
Distinct from 'products.search.image_url' / 'products.search.image_upload': Use this tool to segment a full outfit into pieces before querying, NOT to directly retrieve catalog search results.
Distinct from 'looks.curation.recommend': Use this tool for image-based piece decomposition, NOT text-based styling suggestions.
WHEN TO USE:
When the user provides a full-body model photo, street style snapshot, or celebrity outfit and wants to identify each individual clothing piece (jacket, top, pants, shoes, bag) to find matching products for each piece.
WHEN NOT TO USE:
Do NOT use when the image contains only a single standalone garment (use 'products.search.image_url' or 'products.search.image_upload' directly).
Do NOT use for text-only searches (use 'products.search.text').
BEHAVIOR & SAFETY:
Read-only and idempotent with no persistent state modifications.
Supports input via local file path ('image_path'), base64 string ('image_base64'), or public URL ('image_url'). Exactly one source must be provided.
Returns an array of detected piece objects with 'label', 'confidence' (0.0 to 1.0), and normalized 'box' coordinates [ymin, xmin, ymax, xmax].
PARAMETERS & CONSTRAINTS:
'image_path' (string, optional): Local file system path to the outfit image (e.g. '/tmp/outfit.jpg').
'image_base64' (string, optional): Base64-encoded image data string.
'image_url' (string, optional): Public HTTP(S) URL of the image.
'threshold' (number 0.05-0.95, default 0.22): Detection confidence threshold for bounding box filtering.
| Name | Required | Description | Default |
|---|---|---|---|
| image_url | No | Public HTTP(S) URL of the fashion image to deconstruct | |
| threshold | No | Confidence threshold for object detection bounding boxes (0.05 to 0.95, default 0.22) | |
| image_path | No | Local file system path to the outfit image file to deconstruct | |
| image_base64 | No | Base64-encoded image data string for outfit piece detection |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
While annotations already declare readOnlyHint and destructiveHint, the description goes further by stating the tool is 'read-only and idempotent' and specifies the input methods (image_path, image_base64, image_url) with the constraint that exactly one must be provided. It also discloses the output structure (label, confidence, box) and the threshold's range, adding valuable 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?
The description is well-organized with clear sections (PURPOSE, WHEN, BEHAVIOR, PARAMETERS) and avoids redundancy. It is longer than minimal but each sentence serves a purpose, such as disambiguation and usage rules. Slight redundancy exists in the parameter explanations (schema already contains similar), but it remains focused.
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 moderate complexity (4 params, no output schema), the description is exceptionally complete. It covers purpose, disambiguation, usage rules, behavioral details, input constraints, and return format. An agent has everything needed to correctly invoke the tool without additional research.
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 covers all parameters (100% coverage), but the description adds practical context for each, such as example paths, the meaning of threshold, and the exact-one-source constraint. It also clarifies the output format, which is not in the schema, providing extra value for parameter usage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: deconstructing outfit images into individual fashion pieces with bounding boxes and confidence scores. It lists the piece types (e.g., Upper-body garment, Dress, Footwear) and explicitly distinguishes it from sibling tools like products.search.image_url, making its unique role unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit WHEN TO USE and WHEN NOT TO USE sections, detailing scenarios for multi-piece outfit images versus single garments, and contrasts it with text-based search. This directly guides the agent on when to select this tool over alternatives like products.search.image_url or looks.curation.recommend.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
address.deleteaddress.get_currentaddress.list_savedaddress.saveaddress.set_defaultcheckout.links.get_direct_url9 fields changedInput schema / properties / address / descriptionPrevious value: -"Delivery address object to prefill directly into checkout link"New value: +"Optional ad-hoc address object to prefill"Input schema / properties / address / properties / zip / minLengthAdded value: +1Input schema / properties / address / requiredPrevious value: -[
- "firstName",
- "address1",
- "city"
-]New value: +[
+ "firstName",
+ "address1",
+ "city",
+ "zip"
+]Input schema / properties / address_idAdded value: +{
+ "description": "Optional saved address ID to prefill",
+ "type": "string"
+}Input schema / properties / countryAdded value: +{
+ "description": "Country name, city, currency, or 2-letter ISO code (e.g. 'US', 'United States', 'UK', 'Dubai', 'CA', 'IN'). Defaults to active saved region.",
+ "type": "string"
+}Input schema / properties / coupon / descriptionPrevious value: -"Optional discount coupon code to pre-apply"New value: +"Optional discount coupon code to pre-apply in the checkout session"Input schema / properties / handle / descriptionPrevious value: -"Unique product handle identifier"New value: +"Unique product handle identifier (e.g. 'solid-linen-shirt', 'shopify_11206')"Input schema / properties / quantity / descriptionPrevious value: -"Number of units to purchase (1-10)"New value: +"Number of units to purchase (1 to 10, default 1)"Input schema / properties / size / descriptionPrevious value: -"Size label confirmed by the user (e.g. 'M', 'L', 'XL')"New value: +"Size label confirmed by the user (e.g. 'M', 'L', 'XL', '40')"looks.curation.by_occasion7 fields changedInput schema / properties / age / descriptionPrevious value: -"Target demographic age"New value: +"Target demographic age (16 to 99, default 25)"Input schema / properties / countryAdded value: +{
+ "description": "Country name, city, currency, or 2-letter ISO code (e.g. 'US', 'United States', 'UK', 'Dubai', 'CA', 'IN'). Defaults to active saved region.",
+ "type": "string"
+}Input schema / properties / gender / descriptionPrevious value: -"Target gender filter: 'women' or 'men'"New value: +"Target gender filter: 'women' or 'men' (default: 'women')"Input schema / properties / modeAdded value: +{
+ "description": "Catalog mode: 'global' (ships to country) or 'local' (domestic only). Defaults to active saved region.",
+ "enum": [
+ "global",
+ "local"
+ ],
+ "type": "string"
+}Input schema / properties / page / descriptionPrevious value: -"Page number for looks pagination"New value: +"Page number for looks pagination (1-indexed)"Input schema / properties / page_size / descriptionPrevious value: -"Number of looks per page"New value: +"Number of looks returned per page (1 to 100, default 10)"Input schema / properties / vendor / descriptionPrevious value: -"Optional brand filter"New value: +"Optional brand or vendor name filter array"looks.curation.recommend7 fields changedInput schema / properties / countryAdded value: +{
+ "description": "Country name, city, currency, or 2-letter ISO code (e.g. 'US', 'United States', 'UK', 'Dubai', 'CA', 'IN'). Defaults to active saved region.",
+ "type": "string"
+}Input schema / properties / gender / descriptionPrevious value: -"Target gender filter: 'women' or 'men'"New value: +"Target gender filter: 'women' or 'men' (default: 'women')"Input schema / properties / handle / descriptionPrevious value: -"Product handle to build coordinating outfits around"New value: +"Product handle identifier to build coordinating outfits around (e.g. 'solid-linen-shirt')"Input schema / properties / modeAdded value: +{
+ "description": "Catalog mode: 'global' (ships to country) or 'local' (domestic only). Defaults to active saved region.",
+ "enum": [
+ "global",
+ "local"
+ ],
+ "type": "string"
+}Input schema / properties / occasion / descriptionPrevious value: -"Target occasion or aesthetic theme (e.g. 'Wedding', 'Party', 'Cocktail', 'Date Night')"New value: +"Target occasion or aesthetic theme (e.g. 'Wedding & Reception', 'Party', 'Cocktail', 'Date Night', 'Formal')"Input schema / properties / page / descriptionPrevious value: -"Page number for pagination"New value: +"Page number for pagination (1-indexed)"Input schema / properties / page_size / descriptionPrevious value: -"Number of outfits per page"New value: +"Number of outfit sets to return per page (1 to 100, default 20)"products.items.check_stock4 fields changedInput schema / properties / countryAdded value: +{
+ "description": "Country name, city, currency, or 2-letter ISO code (e.g. 'US', 'United States', 'UK', 'Dubai', 'CA', 'IN'). Defaults to active saved region.",
+ "type": "string"
+}Input schema / properties / desired_size / descriptionPrevious value: -"Optional size query to verify (e.g. 'M', 'L', 'XL', '32', '40')"New value: +"Optional size query to verify against variant inventory (e.g. 'M', 'L', 'XL', '32', '40')"Input schema / properties / handle / descriptionPrevious value: -"Unique product handle identifier"New value: +"Unique product handle identifier (e.g. 'solid-linen-shirt', 'shopify_11206')"Input schema / properties / size_index / descriptionPrevious value: -"Zero-based index of the size variant"New value: +"Zero-based index of the specific size variant to inspect"products.items.get_by_handle2 fields changedInput schema / properties / countryAdded value: +{
+ "description": "Country name, city, currency, or 2-letter ISO code (e.g. 'US', 'United States', 'UK', 'Dubai', 'CA', 'IN'). Defaults to active saved region.",
+ "type": "string"
+}Input schema / properties / handle / descriptionPrevious value: -"Unique product handle identifier (e.g. 'solid-linen-shirt')"New value: +"Unique product handle identifier (e.g. 'solid-linen-shirt', 'shopify_11206')"products.items.get_size_guideproducts.search.alternatives10 fields changedInput schema / properties / budget_range / descriptionPrevious value: -"Target price bracket in local currency"New value: +"Target price bracket filter in local currency: '0-1500', '1501-3000', '3001-5000', or '5000+'"Input schema / properties / countryAdded value: +{
+ "description": "Country name, city, currency, or 2-letter ISO code (e.g. 'US', 'United States', 'UK', 'Dubai', 'CA', 'IN'). Defaults to active saved region.",
+ "type": "string"
+}Input schema / properties / handle / descriptionPrevious value: -"Base product handle to find alternatives for"New value: +"The unique product handle identifier to find visual alternatives for (e.g. 'solid-cotton-shirt')"Input schema / properties / limit / descriptionPrevious value: -"Maximum number of filtered alternatives to return"New value: +"Maximum number of filtered alternative products to return in the result (1-100)"Input schema / properties / modeAdded value: +{
+ "description": "Catalog mode: 'global' (ships to country) or 'local' (domestic only). Defaults to active saved region.",
+ "enum": [
+ "global",
+ "local"
+ ],
+ "type": "string"
+}Input schema / properties / page / descriptionPrevious value: -"Page number for pagination"New value: +"Pagination page number (1-indexed)"Input schema / properties / page_size / descriptionPrevious value: -"Number of items to fetch per page"New value: +"Number of candidate items to fetch per backend page (1-100)"Input schema / properties / personalize / descriptionPrevious value: -"Whether to apply personalized ranking"New value: +"Whether to apply personalized user ranking to the results"Input schema / properties / sort_by / descriptionPrevious value: -"Sorting criteria"New value: +"Sorting attribute for the visual matches: 'relevance', 'price', or 'title'"Input schema / properties / sort_order / descriptionPrevious value: -"Sort order: 'asc' or 'desc'"New value: +"Sort direction: 'asc' for ascending, 'desc' for descending"products.search.image_upload16 fields changedInput schema / properties / content_type / descriptionPrevious value: -"MIME type of the image, e.g. 'image/jpeg', 'image/png'"New value: +"MIME type of the image, e.g. 'image/jpeg', 'image/png', 'image/webp'"Input schema / properties / countryAdded value: +{
+ "description": "Country name, city, currency, or 2-letter ISO code (e.g. 'US', 'United States', 'UK', 'Dubai', 'CA', 'IN'). Defaults to active saved region.",
+ "type": "string"
+}Input schema / properties / expiry_hours / descriptionPrevious value: -"Temporary upload URL lifetime in hours"New value: +"Temporary upload URL lifetime in hours before expiration (1 to 168, default 24)"Input schema / properties / gender / descriptionPrevious value: -"Target gender filter"New value: +"Target gender filter: 'men', 'women', or 'unisex'"Input schema / properties / image_base64 / descriptionPrevious value: -"Base64-encoded image data string"New value: +"Base64-encoded image data string (alternative to image_path)"Input schema / properties / image_path / descriptionPrevious value: -"Local file system path to the image file"New value: +"Local file system path to the image file (e.g. '/path/to/dress.jpg')"Input schema / properties / modeAdded value: +{
+ "description": "Catalog mode: 'global' (ships to country) or 'local' (domestic only). Defaults to active saved region.",
+ "enum": [
+ "global",
+ "local"
+ ],
+ "type": "string"
+}Input schema / properties / page / descriptionPrevious value: -"Page number for pagination"New value: +"Pagination page number (1-indexed)"Input schema / properties / page_size / descriptionPrevious value: -"Number of items to return per page"New value: +"Number of items to return per page (1 to 100, default 20)"Input schema / properties / personalize / descriptionPrevious value: -"Whether to personalize search ranking"New value: +"Whether to apply personalized ranking weights"Input schema / properties / price_max / descriptionPrevious value: -"Maximum price"New value: +"Maximum price in local currency"Input schema / properties / price_max / minimumAdded value: +0Input schema / properties / price_min / descriptionPrevious value: -"Minimum price"New value: +"Minimum price in local currency"Input schema / properties / price_min / minimumAdded value: +0Input schema / properties / sort_by / descriptionPrevious value: -"Sorting criteria"New value: +"Sorting criteria: 'relevance', 'price', or 'title'"Input schema / properties / vendor / descriptionPrevious value: -"List of brand names"New value: +"List of brand names to filter by"products.search.image_url11 fields changedInput schema / properties / countryAdded value: +{
+ "description": "Country name, city, currency, or 2-letter ISO code (e.g. 'US', 'United States', 'UK', 'Dubai', 'CA', 'IN'). Defaults to active saved region.",
+ "type": "string"
+}Input schema / properties / image_url / descriptionPrevious value: -"Publicly accessible URL of the fashion image to search for visual matches"New value: +"Publicly accessible HTTP(S) URL of the fashion image to search for visual matches"Input schema / properties / modeAdded value: +{
+ "description": "Catalog mode: 'global' (ships to country) or 'local' (domestic only). Defaults to active saved region.",
+ "enum": [
+ "global",
+ "local"
+ ],
+ "type": "string"
+}Input schema / properties / page / descriptionPrevious value: -"Page number for pagination"New value: +"Page number for pagination (1-indexed)"Input schema / properties / page_size / descriptionPrevious value: -"Number of items to return per page"New value: +"Number of items to return per page (1 to 100, default 20)"Input schema / properties / personalize / descriptionPrevious value: -"Whether to apply personalized ranking"New value: +"Whether to apply personalized ranking based on user style profile"Input schema / properties / price_max / minimumAdded value: +0Input schema / properties / price_min / minimumAdded value: +0Input schema / properties / size / descriptionPrevious value: -"Array of sizes to filter by"New value: +"Array of sizes to filter by (e.g. ['S', 'M', 'L'])"Input schema / properties / sort_by / descriptionPrevious value: -"Sorting criteria for search results"New value: +"Sorting criteria for search results: 'relevance', 'price', or 'title'"Input schema / properties / sort_order / descriptionPrevious value: -"Sort order: 'asc' or 'desc'"New value: +"Sort order: 'asc' for ascending, 'desc' for descending"products.search.text9 fields changedInput schema / properties / countryAdded value: +{
+ "description": "Country name, city, currency, or 2-letter ISO code (e.g. 'US', 'United States', 'UK', 'Dubai', 'CA', 'IN'). Defaults to active saved region.",
+ "type": "string"
+}Input schema / properties / modeAdded value: +{
+ "description": "Catalog mode: 'global' (ships to country) or 'local' (domestic only). Defaults to active saved region.",
+ "enum": [
+ "global",
+ "local"
+ ],
+ "type": "string"
+}Input schema / properties / page / descriptionPrevious value: -"Page number for pagination (starts at 1)"New value: +"Pagination page number (1-indexed, starts at 1)"Input schema / properties / page_size / descriptionPrevious value: -"Number of items to return per page (max 100)"New value: +"Number of items to return per page (1 to 100, default 20)"Input schema / properties / price_max / minimumAdded value: +0Input schema / properties / price_min / minimumAdded value: +0Input schema / properties / size / descriptionPrevious value: -"Array of sizes to filter by, e.g. ['S', 'M', 'L', 'XL']"New value: +"Array of size labels to filter by (e.g. ['S', 'M', 'L', 'XL', '32'])"Input schema / properties / sort_by / descriptionPrevious value: -"Sorting criteria for the search results"New value: +"Sorting criteria for search results: 'relevance', 'price', or 'title'"Input schema / properties / vendor / descriptionPrevious value: -"List of brand or vendor names to filter by"New value: +"List of brand or vendor names to filter by (e.g. ['Zara', 'H&M', 'Tandul'])"region.get_currentregion.list_supportedregion.set_currentvision.outfit.detect_pieces3 fields changedInput schema / properties / image_base64 / descriptionPrevious value: -"Base64-encoded image string for outfit piece detection"New value: +"Base64-encoded image data string for outfit piece detection"Input schema / properties / image_path / descriptionPrevious value: -"Local path to the outfit image file to deconstruct"New value: +"Local file system path to the outfit image file to deconstruct"Input schema / properties / threshold / descriptionPrevious value: -"Confidence threshold for object detection bounding boxes (0.05 to 0.95)"New value: +"Confidence threshold for object detection bounding boxes (0.05 to 0.95, default 0.22)"checkout.links.get_direct_url2 fields changedInput schema / properties / addressAdded value: +{
+ "description": "Delivery address object to prefill directly into checkout link",
+ "properties": {
+ "address1": {
+ "minLength": 1,
+ "type": "string"
+ },
+ "address2": {
+ "type": "string"
+ },
+ "city": {
+ "minLength": 1,
+ "type": "string"
+ },
+ "country": {
+ "type": "string"
+ },
+ "email": {
+ "type": "string"
+ },
+ "firstName": {
+ "minLength": 1,
+ "type": "string"
+ },
+ "lastName": {
+ "type": "string"
+ },
+ "phone": {
+ "type": "string"
+ },
+ "province": {
+ "type": "string"
+ },
+ "zip": {
+ "type": "string"
+ }
+ },
+ "required": [
+ "firstName",
+ "address1",
+ "city"
+ ],
+ "type": "object"
+}Output schema / (root)Previous value: -{
- "$schema": "http://json-schema.org/draft-07/schema#",
- "additionalProperties": false,
- "properties": {
- "checkout_url": {
- "description": "Direct 1-click purchase permalink (https://s.polopan.com/p/{handle}/{size_index})",
- "type": "string"
- },
- "handle": {
- "description": "Product handle",
- "type": "string"
- },
- "size": {
- "description": "Selected size",
- "type": "string"
- },
- "size_index": {
- "description": "Selected size index",
- "type": "number"
- }
- },
- "required": [
- "handle",
- "size_index",
- "checkout_url"
- ],
- "type": "object"
-}New value: +nulllooks.curation.by_occasion1 field changedOutput schema / (root)Previous value: -{
- "$schema": "http://json-schema.org/draft-07/schema#",
- "additionalProperties": false,
- "properties": {
- "looks": {
- "description": "List of verified in-stock occasion looks",
- "items": {
- "additionalProperties": false,
- "properties": {
- "id": {
- "description": "Unique look ID",
- "type": "string"
- },
- "image_url": {
- "description": "Main styled look image",
- "type": "string"
- },
- "occasion": {
- "description": "Occasion tag",
- "type": "string"
- },
- "products": {
- "description": "100% in-stock items in this outfit",
- "items": {
- "additionalProperties": false,
- "properties": {
- "handle": {
- "description": "Product handle",
- "type": "string"
- },
- "price": {
- "description": "Price",
- "type": "number"
- },
- "title": {
- "description": "Product title",
- "type": "string"
- },
- "url": {
- "description": "Purchase link",
- "type": "string"
- }
- },
- "required": [
- "handle",
- "title",
- "price",
- "url"
- ],
- "type": "object"
- },
- "type": "array"
- },
- "title": {
- "description": "Look title",
- "type": "string"
- }
- },
- "type": "object"
- },
- "type": "array"
- }
- },
- "required": [
- "looks"
- ],
- "type": "object"
-}New value: +nulllooks.curation.recommend1 field changedOutput schema / (root)Previous value: -{
- "$schema": "http://json-schema.org/draft-07/schema#",
- "additionalProperties": false,
- "properties": {
- "handle": {
- "description": "Base product handle",
- "type": "string"
- },
- "looks": {
- "description": "List of recommended outfits",
- "items": {
- "additionalProperties": false,
- "properties": {
- "image_url": {
- "description": "Look image URL",
- "type": "string"
- },
- "title": {
- "description": "Outfit title",
- "type": "string"
- }
- },
- "type": "object"
- },
- "type": "array"
- }
- },
- "type": "object"
-}New value: +nullproducts.items.check_stock1 field changedOutput schema / (root)Previous value: -{
- "$schema": "http://json-schema.org/draft-07/schema#",
- "additionalProperties": false,
- "properties": {
- "available_sizes": {
- "description": "List of currently available in-stock sizes",
- "items": {
- "type": "string"
- },
- "type": "array"
- },
- "direct_checkout_url": {
- "description": "Verified 1-click checkout permalink",
- "type": "string"
- },
- "handle": {
- "description": "Product handle",
- "type": "string"
- },
- "is_in_stock": {
- "description": "Overall stock status",
- "type": "boolean"
- },
- "out_of_stock_sizes": {
- "description": "List of out-of-stock sizes",
- "items": {
- "type": "string"
- },
- "type": "array"
- },
- "title": {
- "description": "Product title",
- "type": "string"
- }
- },
- "required": [
- "handle",
- "title",
- "is_in_stock",
- "available_sizes",
- "out_of_stock_sizes",
- "direct_checkout_url"
- ],
- "type": "object"
-}New value: +nullproducts.items.get_by_handle1 field changedOutput schema / (root)Previous value: -{
- "$schema": "http://json-schema.org/draft-07/schema#",
- "additionalProperties": false,
- "properties": {
- "handle": {
- "description": "Product handle identifier",
- "type": "string"
- },
- "price": {
- "description": "Price",
- "type": "number"
- },
- "title": {
- "description": "Product title",
- "type": "string"
- },
- "url": {
- "description": "Verified purchase link",
- "type": "string"
- },
- "variants": {
- "description": "Variant size list",
- "items": {
- "additionalProperties": false,
- "properties": {
- "in_stock": {
- "description": "Stock availability",
- "type": "boolean"
- },
- "size": {
- "description": "Size label",
- "type": "string"
- }
- },
- "required": [
- "size",
- "in_stock"
- ],
- "type": "object"
- },
- "type": "array"
- }
- },
- "required": [
- "handle",
- "title",
- "price",
- "url"
- ],
- "type": "object"
-}New value: +nullproducts.search.alternatives1 field changedOutput schema / (root)Previous value: -{
- "$schema": "http://json-schema.org/draft-07/schema#",
- "additionalProperties": false,
- "properties": {
- "budget_range": {
- "description": "Applied budget bracket",
- "type": "string"
- },
- "products": {
- "description": "List of visual alternatives within budget",
- "items": {
- "additionalProperties": false,
- "properties": {
- "handle": {
- "description": "Alternative product handle",
- "type": "string"
- },
- "price": {
- "description": "Alternative product price",
- "type": "number"
- },
- "title": {
- "description": "Alternative product title",
- "type": "string"
- },
- "url": {
- "description": "Purchase link",
- "type": "string"
- }
- },
- "required": [
- "handle",
- "title",
- "price",
- "url"
- ],
- "type": "object"
- },
- "type": "array"
- },
- "source_handle": {
- "description": "Source product handle",
- "type": "string"
- }
- },
- "required": [
- "budget_range",
- "source_handle",
- "products"
- ],
- "type": "object"
-}New value: +nullproducts.search.image_upload1 field changedOutput schema / (root)Previous value: -{
- "$schema": "http://json-schema.org/draft-07/schema#",
- "additionalProperties": false,
- "properties": {
- "products": {
- "description": "Matching products",
- "items": {
- "additionalProperties": false,
- "properties": {
- "handle": {
- "description": "Product handle",
- "type": "string"
- },
- "price": {
- "description": "Price",
- "type": "number"
- },
- "title": {
- "description": "Product title",
- "type": "string"
- },
- "url": {
- "description": "Purchase link",
- "type": "string"
- }
- },
- "required": [
- "handle",
- "title",
- "price",
- "url"
- ],
- "type": "object"
- },
- "type": "array"
- },
- "uploaded_image_url": {
- "description": "Temporary URL of the uploaded image",
- "type": "string"
- }
- },
- "required": [
- "uploaded_image_url",
- "products"
- ],
- "type": "object"
-}New value: +nullproducts.search.image_url1 field changedOutput schema / (root)Previous value: -{
- "$schema": "http://json-schema.org/draft-07/schema#",
- "additionalProperties": false,
- "properties": {
- "products": {
- "description": "List of matching fashion products",
- "items": {
- "additionalProperties": false,
- "properties": {
- "handle": {
- "description": "Unique product handle identifier",
- "type": "string"
- },
- "price": {
- "description": "Current selling price",
- "type": "number"
- },
- "title": {
- "description": "Product name and title",
- "type": "string"
- },
- "url": {
- "description": "Verified purchase link",
- "type": "string"
- }
- },
- "required": [
- "handle",
- "title",
- "price",
- "url"
- ],
- "type": "object"
- },
- "type": "array"
- }
- },
- "required": [
- "products"
- ],
- "type": "object"
-}New value: +nullproducts.search.text1 field changedOutput schema / (root)Previous value: -{
- "$schema": "http://json-schema.org/draft-07/schema#",
- "additionalProperties": false,
- "properties": {
- "pagination": {
- "additionalProperties": false,
- "description": "Pagination metadata",
- "properties": {
- "page": {
- "description": "Current page number",
- "type": "number"
- },
- "page_size": {
- "description": "Number of items per page",
- "type": "number"
- },
- "total": {
- "description": "Total number of matching products",
- "type": "number"
- }
- },
- "required": [
- "page",
- "page_size"
- ],
- "type": "object"
- },
- "products": {
- "description": "List of matching fashion products",
- "items": {
- "additionalProperties": false,
- "properties": {
- "brand": {
- "description": "Brand or vendor name",
- "type": "string"
- },
- "discount_percent": {
- "description": "Discount percentage",
- "type": "number"
- },
- "handle": {
- "description": "Unique product handle identifier",
- "type": "string"
- },
- "mrp": {
- "description": "Original maximum retail price",
- "type": "number"
- },
- "price": {
- "description": "Current selling price",
- "type": "number"
- },
- "sizes": {
- "description": "List of available in-stock sizes",
- "items": {
- "type": "string"
- },
- "type": "array"
- },
- "title": {
- "description": "Product name and title",
- "type": "string"
- },
- "url": {
- "description": "Verified purchase link",
- "type": "string"
- }
- },
- "required": [
- "handle",
- "title",
- "price",
- "url"
- ],
- "type": "object"
- },
- "type": "array"
- }
- },
- "required": [
- "products"
- ],
- "type": "object"
-}New value: +nullvision.outfit.detect_pieces1 field changedOutput schema / (root)Previous value: -{
- "$schema": "http://json-schema.org/draft-07/schema#",
- "additionalProperties": false,
- "properties": {
- "pieces": {
- "description": "List of detected fashion pieces",
- "items": {
- "additionalProperties": false,
- "properties": {
- "box": {
- "description": "Normalized bounding box coordinates [ymin, xmin, ymax, xmax]",
- "items": {
- "type": "number"
- },
- "type": "array"
- },
- "confidence": {
- "description": "Confidence score between 0.0 and 1.0",
- "type": "number"
- },
- "label": {
- "description": "Detected clothing category (e.g. Upper-body garment, Lower-body garment, Footwear, Bag)",
- "type": "string"
- }
- },
- "required": [
- "label",
- "confidence",
- "box"
- ],
- "type": "object"
- },
- "type": "array"
- }
- },
- "required": [
- "pieces"
- ],
- "type": "object"
-}New value: +nullcheckout.links.get_direct_urllooks.curation.by_occasionlooks.curation.recommendproducts.items.check_stockproducts.items.get_by_handleproducts.search.alternativesproducts.search.image_uploadproducts.search.image_urlproducts.search.textvision.outfit.detect_piecesFashion & apparel MCP: visual outfit search, stock verification, and 1-click checkout.
Search and get fashion products recommendations across multiple e-ecom stores
Fashion product discovery and virtual try-on via the Glance catalog
Virtual try-on and on-model AI fashion photography: catalog search, try-on grids, HD delivery.
Add one secure layer between your agents and this server.
