Search Products By Text
products.search.textSearch fashion products by text keyword and filter by size, gender, price, or vendor. Get in-stock items with specs, pricing, and purchase links.
Instructions
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}).
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, 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').
'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.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| 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']) | |
| 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 |