Discovery Tool

search_products

Search the product catalog using natural language. Returns products with pricing, variants, and commission metadata.

Parameters

Parameter	Type	Default	Description
`query`	string	—	Natural language description of products to find. Examples: "comfortable running shoes", "gift for coffee lover".
`limit`	integer	`5`	Number of products to return. Range: 1-50.
`agent_id`	string	—	Your agent ID for attribution tracking. Get one via register_agent.

Response

Returns an array of product objects. Each product includes its public ID, name, description, price, image URLs, and variation attributes. When agent_id is provided and the store has commission configured, products include a _meta block with commission rates and attribution data.

Response

[
  {
    "public_id": "prod_8kx2m",
    "name": "Pro Burr Coffee Grinder",
    "description": "Professional-grade burr grinder with 40 grind settings...",
    "price": {
      "amount_in_cents": 14999,
      "currency": "USD"
    },
    "image_urls": [
      "https://cdn.shopify.com/s/files/1/example/grinder-front.jpg",
      "https://cdn.shopify.com/s/files/1/example/grinder-side.jpg"
    ],
    "variation_attributes": [
      {
        "name": "Color",
        "values": ["Matte Black", "Stainless Steel"]
      }
    ],
    "has_variations": true,
    "_meta": {
      "commission": {
        "default_rate": 0.08,
        "effective_rate": 0.13,
        "rate_breakdown": {
          "base": 0.08,
          "campaign_bonus": 0.05,
          "campaign_name": "Spring Sale",
          "campaign_ends": "2026-03-31T23:59:59+00:00"
        }
      },
      "attribution": {
        "agent_ref": "agent_abc123def456"
      }
    }
  },
  {
    "public_id": "prod_3nv7q",
    "name": "Manual Ceramic Hand Grinder",
    "description": "Portable hand grinder with ceramic burrs...",
    "price": {
      "amount_in_cents": 4999,
      "currency": "USD"
    },
    "image_urls": [
      "https://cdn.shopify.com/s/files/1/example/hand-grinder.jpg"
    ],
    "variation_attributes": null,
    "has_variations": false
  }
]

Commission metadata

The _meta.commission block only appears when the store has commission rates configured. The _meta.attribution block only appears when agent_id is provided.

Example

Example Call

// Tool call
{
  "name": "search_products",
  "arguments": {
    "query": "coffee grinder",
    "limit": 5,
    "agent_id": "agent_abc123def456"
  }
}

Response Fields

Field	Type	Description
`public_id`	string	Unique product identifier. Use with `get_product_details` and `get_faqs`.
`name`	string	Product name.
`description`	string \| null	Product description. May be null for products without descriptions.
`price`	object	Price object with `amount_in_cents` (integer) and `currency` (string, e.g. "USD").
`image_urls`	string[]	Up to 4 product image URLs.
`variation_attributes`	array \| null	Variant options (e.g. Size, Color) with their possible values.
`has_variations`	boolean	Whether the product has multiple variants.
`_meta`	object \| undefined	Commission and attribution metadata. Present only when applicable.

Notes

Results are ranked by semantic similarity to the query using vector search.
Internally, the search queries up to limit * 10 vector results (capped at 500) and deduplicates by product, so even small limits produce high-quality results.
An empty array is returned if no products match the query or if the store has no indexed products.