discover_products

Find products using natural language. This tool uses AI-powered semantic search with vector embeddings to understand intent, not just keywords. A query like "something elegant for a night out" will match cocktail dresses, statement jewelry, and heeled sandals — even if those words don't appear in the product descriptions.

Parameters

Parameter	Type	Required	Default	Description
`query`	`string`	Yes	—	Natural language search query — be descriptive for best results
`category`	`string`	No	—	Product category
`subcategory`	`string`	No	—	Lowercase subcategory, e.g. `dresses`, `sneakers`, `crossbody bags`
`colors`	`string[]`	No	—	Filter by colors, e.g. `["black", "navy", "sage green"]`
`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"]`
`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	—	Style filter — call `get_filters` for current values
`silhouette`	`string`	No	—	Silhouette/fit filter — call `get_filters` for current values
`brand`	`string`	No	—	Filter by brand name
`min_price`	`number`	No	—	Minimum price
`max_price`	`number`	No	—	Maximum price
`store_domain`	`string`	No	—	Filter by store domain (use `list_stores` to get domains)
`limit`	`number`	No	`10`	Max results to return

Response

Returns products ranked by semantic relevance:

[
  {
    "id": "665a1f...",
    "title": "Coastal Breeze Linen Dress",
    "summary": "A flowing linen midi in soft sage with subtle pleating...",
    "price": 178,
    "currency": "USD",
    "category": "apparel",
    "subcategory": "dresses",
    "colors": ["sage green"],
    "materials": ["linen"],
    "gender": "women",
    "occasion": "casual",
    "season": "summer",
    "silhouette": "relaxed",
    "inStock": true,
    "images": ["https://..."],
    "productUrl": "https://api.vistoya.com/go/665a1f...?src=mcp",
    "brand": "Reformation",
    "relevanceScore": 0.92
  }
]

Response fields

Field	Description
`id`	Product identifier
`title`	Product title
`summary`	AI-generated product summary
`price`	Current price
`currency`	Price currency code
`category`	Product category
`subcategory`	Product subcategory
`colors`	Product colors
`materials`	Product materials
`gender`	Target gender
`occasion`	Suitable occasion
`season`	Suitable season
`style`	Product style (when available)
`silhouette`	Fit/silhouette
`inStock`	Current availability
`images`	Product image URLs
`productUrl`	Link to product page
`brand`	Brand name
`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
  }
}

Category and material filter:

{
  "name": "discover_products",
  "arguments": {
    "query": "minimalist jewelry for everyday wear",
    "category": "jewelry",
    "materials": ["silver"]
  }
}

Color and season filtering:

{
  "name": "discover_products",
  "arguments": {
    "query": "cozy oversized sweater for fall",
    "colors": ["cream", "camel", "burgundy"],
    "season": "fall"
  }
}

When to use

Use discover_products for all product search. It works best with descriptive natural language queries ("something elegant for a cocktail party") and can be combined with structured filters like category, gender, min_price, etc. for precise results.