discover_products

Use discover_products for all product search. It works best with descriptive natural-language queries ("something elegant for a cocktail party", "breathable linen dress for a beach wedding under $200") and can be combined with structured filters like category, gender, min_price for precise results. AI-powered semantic search with vector embeddings handles intent, not just keywords. Price phrases like "under 200 zł" inside the query are parsed automatically.

Parameters

Core query

Parameter	Type	Required	Default	Description
`query`	`string`	Yes	—	Natural language search query — be descriptive for best results. Price phrases like `"under 200 zł"` are parsed automatically.

Filters

Parameter	Type	Required	Default	Description
`category`	`string`	No	—	Category slug from `get_filters`, e.g. `clothing`, `clothing/jackets`, `clothing/jackets/bomber-jackets`. Last-segment shortcuts are accepted when unambiguous (e.g. `loafers-and-slip-ons` resolves the same as `shoes/loafers-and-slip-ons`).
`colors`	`string[]`	No	—	Filter by colors, e.g. `["black", "navy", "sage green"]`
`exclude_colors`	`string[]`	No	—	Colors to exclude from results
`color_match`	`string`	No	`any`	`"any"` (default): product has at least one queried color. `"exact"`: at least one image is exclusively the queried colors — use for mono-color searches like "all black".
`materials`	`string[]`	No	—	Filter by materials, e.g. `["cotton", "silk", "leather"]`
`exclude_materials`	`string[]`	No	—	Materials to exclude from results
`gender`	`string`	No	—	Gender filter — call `get_filters` for current values
`occasion`	`string`	No	—	Occasion filter — call `get_filters` for current values
`season`	`string`	No	—	Season filter — call `get_filters` for current values
`style`	`string`	No	—	Single-style filter — call `get_filters` for current values
`styles`	`string[]`	No	—	Multi-style filter (OR). A product matches if any of its `styles` is in this list. Use to span a related set, e.g. `["basics","minimalist","preppy","sportswear"]` for a "Casual" bucket. Combined with `style` if both are provided.
`silhouette`	`string`	No	—	Silhouette/fit filter — call `get_filters` for current values
`pattern`	`string`	No	—	Pattern filter (e.g. `solid`, `stripe`, `checked`, `floral`)
`neckline`	`string`	No	—	Neckline filter (e.g. `crew`, `v-neck`, `turtleneck`)
`sleeves`	`string`	No	—	Sleeve-style filter (e.g. `short`, `long`, `sleeveless`)
`available_sizes`	`string[]`	No	—	Filter by available size labels, e.g. `["s", "m", "38"]`
`is_sustainable`	`boolean`	No	—	Only products with explicit sustainability claims
`brand`	`string`	No	—	Filter by brand name
`store_domain`	`string`	No	—	Filter by a single store domain (e.g. `"thereformation.com"`)

Pricing

Parameter	Type	Required	Default	Description
`min_price`	`number`	No	—	Minimum price (in `currency`, or USD if omitted). Positive float; extra decimals beyond two are floored silently (e.g. `19.999` → `19.99`).
`max_price`	`number`	No	—	Maximum price. Same rules as `min_price`. If set below `min_price`, results come back empty.
`currency`	`string`	No	`USD`	ISO 4217 code for `min_price`/`max_price` and returned prices (e.g. `"EUR"`, `"PLN"`).

Pagination

Parameter	Type	Required	Default	Description
`limit`	`number`	No	`10`	Page size (max `10`)
`page`	`number`	No	`1`	Page number.

Response

Returns products ranked by semantic relevance, the current page, and a hasNextPage flag:

{
  "page": 1,
  "hasNextPage": true,
  "results": [
    {
      "id": "665a1f...",
      "title": "Coastal Breeze Linen Dress",
      "summary": "A flowing linen midi in soft sage with subtle pleating.",
      "brand": "Reformation",
      "price": 178,
      "currency": "USD",
      "compareAtPrice": null,
      "category": "clothing/dresses",
      "colors": ["sage green"],
      "materials": ["linen"],
      "gender": "women",
      "silhouette": "relaxed",
      "neckline": "v-neck",
      "sleeves": "short",
      "closures": [],
      "tags": ["casual", "summer", "minimalist", "solid"],
      "isSustainable": true,
      "inStock": true,
      "images": ["https://..."],
      "productUrl": "https://api.vistoya.com/go/665a1f...?src=mcp",
      "availability": {
        "dimensions": ["color", "size"],
        "color": [
          {
            "colorKey": "sage-green",
            "color": "sage green",
            "label": "Sage Green",
            "imageUrls": ["https://..."],
            "availableSizes": [
              { "label": "xs", "inStock": true },
              { "label": "s",  "inStock": true },
              { "label": "m",  "inStock": false }
            ]
          }
        ],
        "sizes": [
          { "label": "xs", "inStock": true },
          { "label": "s",  "inStock": true },
          { "label": "m",  "inStock": false }
        ]
      },
      "relevanceScore": 0.92
    }
  ]
}

Fields

Field	Description
`page`	Current result page
`hasNextPage`	True when another page of results is available
`id`	Product identifier — pass to `get_product` for full details
`title`	Product title
`summary`	AI-generated shopping summary. Not merchant copy — call `get_product` for `merchantDescription`
`price`	Current price rendered in `currency`
`currency`	Price currency code
`compareAtPrice`	Original price before discount (nullable — present when on sale)
`category`	Most specific available category value, preferring subcategory over broad category
`colors`	Product colors
`materials`	Product materials
`gender`	Target gender
`silhouette`	Fit/silhouette
`neckline`	Neckline value
`sleeves`	Sleeve style
`closures`	Closure types (e.g. zipper, button)
`tags`	Merged public descriptive tags — derived from fit, function, details, aesthetic, style, and pattern. Use these to read off stylistic/occasion/season hints that aren't promoted to top-level fields.
`isSustainable`	Has explicit sustainability claims
`inStock`	Any variant is in stock
`images`	Product image URLs
`productUrl`	Click-tracked Vistoya redirect URL
`brand`	Brand name
`availability`	Compact color/size availability matrix. Full SKU-level variants come from `get_product`
`relevanceScore`	Semantic similarity score (0–1) — how closely the product matches the query

Examples

Natural language with price filter:

{
  "name": "discover_products",
  "arguments": {
    "query": "black leather jacket for going out",
    "max_price": 300
  }
}

Price in a non-USD currency:

{
  "name": "discover_products",
  "arguments": {
    "query": "white wool coat",
    "max_price": 1000,
    "currency": "PLN"
  }
}

Size + sustainability filter:

{
  "name": "discover_products",
  "arguments": {
    "query": "organic cotton t-shirt",
    "available_sizes": ["m", "l"],
    "is_sustainable": true
  }
}

Multi-style filter for a "Casual" bucket:

{
  "name": "discover_products",
  "arguments": {
    "query": "easy weekend layers",
    "styles": ["basics", "minimalist", "preppy", "sportswear"],
    "season": "fall"
  }
}

After a result, call get_product for the full merchant description, all images, and SKU-level variants. Use find_similar_products with a result's id for "more like this." When called from a UI-capable host (ChatGPT Apps SDK, Claude Desktop, Cursor, VS Code Copilot, Goose), the same response renders inline as a visual product grid via the embedded widget — no separate render call needed.

Call get_filters once at the start of a session to learn which category, colors, materials, style, and other enum values are valid in the current catalog.