Search Alternatives In Budget
products.search.alternativesFind visually similar substitute products for a known fashion item within a target price bracket, using the item's handle to return alternative styles in the same category.
Instructions
Find visual substitute products within a designated price bracket for a given fashion item handle using visual image similarity.
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+').
'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
| Name | Required | Description | Default |
|---|---|---|---|
| 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') | |
| 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 |