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"]`
`materials`	`string[]`	No	—	Filter by materials, e.g. `["cotton", "silk", "leather"]`
`gender`	`string`	No	—	`women`, `men`, `unisex`, or `kids`
`occasion`	`string`	No	—	`casual`, `formal`, `athletic`, `evening`, `business`, `outdoor`, `wedding`, `loungewear`, or `streetwear`
`season`	`string`	No	—	`spring`, `summer`, `fall`, `winter`, or `all-season`
`style`	`string`	No	—	Style filter (e.g. `minimalist`, `streetwear`, `bohemian`, `classic`)
`silhouette`	`string`	No	—	Silhouette/fit filter (e.g. `fitted`, `oversized`, `relaxed`, `tailored`)
`brand`	`string`	No	—	Filter by brand name
`min_price`	`number`	No	—	Minimum price
`max_price`	`number`	No	—	Maximum price
`in_stock_only`	`boolean`	No	`true`	Only show in-stock products
`store_id`	`string`	No	—	Filter by store
`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",
    "style": "bohemian",
    "silhouette": "relaxed",
    "inStock": true,
    "images": ["https://..."],
    "productUrl": "https://store.com/coastal-breeze",
    "brand": "Reformation",
    "relevanceScore": 0.92
  }
]

Response fields

Field	Description
`relevanceScore`	Semantic similarity score (0–1) — how closely the product matches the query
`colors` / `materials`	AI-classified product attributes
`gender` / `occasion` / `season`	AI-classified taxonomy fields
`style` / `silhouette`	AI-classified style and fit attributes
`inStock`	Current availability

Examples

Descriptive natural language query with filters:

{
  "name": "discover_products",
  "arguments": {
    "query": "breathable linen dress for a beach wedding under $200",
    "occasion": "wedding",
    "max_price": 200
  }
}

Style-based search:

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

Color and season filtering:

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

How it works

Your query is embedded into a vector using Voyage AI's multimodal embedding model
The vector is compared against pre-computed embeddings for every product in the catalog
Qdrant returns the nearest neighbors, filtered by any structured parameters you provide
Results are ranked by cosine similarity (the relevanceScore field)

When to use

Use discover_products for all product search. It handles both natural language ("something elegant for a cocktail party") and filter-driven requests ("sneakers under $150") — the semantic model understands intent either way.