Skip to main content
Glama
Sign In

PoloPan Fashion MCP Server

by io.github.rofoso-com
OverviewDiscussionsAdmin

Search Alternatives In Budget

products.search.alternatives
Read-only

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.

Input Schema

NameRequiredDescriptionDefault
modeNoCatalog mode: 'global' (ships to country) or 'local' (domestic only). Defaults to active saved region.
pageNoPagination page number (1-indexed)
limitNoMaximum number of filtered alternative products to return in the result (1-100)
handleYesThe unique product handle identifier to find visual alternatives for (e.g. 'solid-cotton-shirt')
countryNoCountry name, city, currency, or 2-letter ISO code (e.g. 'US', 'United States', 'UK', 'Dubai', 'CA', 'IN'). Defaults to active saved region.
sort_byNoSorting attribute for the visual matches: 'relevance', 'price', or 'title'relevance
page_sizeNoNumber of candidate items to fetch per backend page (1-100)
sort_orderNoSort direction: 'asc' for ascending, 'desc' for descendingdesc
personalizeNoWhether to apply personalized user ranking to the results
budget_rangeNoTarget price bracket filter in local currency: '0-1500', '1501-3000', '3001-5000', or '5000+'1501-3000

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed10 schema fields changed
    • changedInput schema / properties / budget_range / description
      Previous value: -"Target price bracket in local currency"New value: +"Target price bracket filter in local currency: '0-1500', '1501-3000', '3001-5000', or '5000+'"
    • addedInput schema / properties / country
      Added 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"
+}
    • changedInput schema / properties / handle / description
      Previous 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')"
    • changedInput schema / properties / limit / description
      Previous value: -"Maximum number of filtered alternatives to return"New value: +"Maximum number of filtered alternative products to return in the result (1-100)"
    • addedInput schema / properties / mode
      Added value: +{
+  "description": "Catalog mode: 'global' (ships to country) or 'local' (domestic only). Defaults to active saved region.",
+  "enum": [
+    "global",
+    "local"
+  ],
+  "type": "string"
+}
    • changedInput schema / properties / page / description
      Previous value: -"Page number for pagination"New value: +"Pagination page number (1-indexed)"
    • changedInput schema / properties / page_size / description
      Previous value: -"Number of items to fetch per page"New value: +"Number of candidate items to fetch per backend page (1-100)"
    • changedInput schema / properties / personalize / description
      Previous value: -"Whether to apply personalized ranking"New value: +"Whether to apply personalized user ranking to the results"
    • changedInput schema / properties / sort_by / description
      Previous value: -"Sorting criteria"New value: +"Sorting attribute for the visual matches: 'relevance', 'price', or 'title'"
    • changedInput schema / properties / sort_order / description
      Previous value: -"Sort order: 'asc' or 'desc'"New value: +"Sort direction: 'asc' for ascending, 'desc' for descending"
  2. Changed1 schema field changed
    • 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: +null
  3. First observed

TDQS

A4.6/5.0
Behavior5/5

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

Beyond the readOnly/destructive annotations, it discloses non-obvious behavior: it auto-fetches the source product's primary image embedding, excludes the source handle from results, and returns PoloPan purchase permalinks. This is meaningful context an agent could not derive from annotations or schema.

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

Conciseness4/5

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

The summary line is front-loaded and the sections are well organized, but the PARAMETERS & CONSTRAINTS block duplicates schema content verbatim, adding length without new information.

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

Completeness5/5

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

With no output schema, the description compensates by explaining the return format (clean permalinks), the exclusion of the source item, and the localization behavior. For a 10-parameter read tool, this is complete enough to call correctly.

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

Parameters3/5

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

Schema description coverage is 100%, so all ten parameters are already documented in the schema. The description's PARAMETERS & CONSTRAINTS section largely restates the schema (enums, defaults, ranges) rather than adding new meaning, so the baseline of 3 applies.

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

Purpose5/5

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

The description states a specific verb and resource ('find visual substitute products... for a given fashion item handle using visual image similarity') and immediately disambiguates against four named siblings. An agent can select it confidently 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.

Usage Guidelines5/5

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

Dedicated WHEN TO USE and WHEN NOT TO USE sections name the exact scenario (cheaper/higher-end substitutes for a known handle) and route the agent to alternatives ('products.search.text', 'looks.curation.recommend', 'looks.curation.by_occasion') with the condition that selects each. 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.

All PoloPan Fashion MCP Server toolsInspect
Try in Browser
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources