discover_products

Use discover_products for all product search. It works best with concrete, noun-led natural-language queries - one or two modifiers - like "oversized wool coat", "black leather jacket", "summer linen shirt", or "linen shirt for a beach wedding under $200". Combine with structured filters like category, gender, min_price for precision. AI-powered semantic search with vector embeddings handles intent, not just keywords. Price phrases like "under 200 zł" inside the query are parsed automatically.

Avoid stacking many descriptive qualifiers ("breathable", "perfect for") with multiple filter axes (season + price + material) in the same query - over-constrained queries can return empty. Push the axes you care about into structured filters (max_price, materials) instead of layering them into the query string.

Soft descriptors (occasion, season, styles, silhouette, pattern, neckline, sleeves) are already captured by the query field via semantic ranking. Set them ONLY when the user explicitly named that exact attribute - populating them otherwise is the most common cause of zero-result calls.

Parameters

Core query

Filters

Pricing

Pagination

Location

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://vistoya.com/p/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

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"
  }
}

Related tools

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.