Conversations server tools

The Conversations server exposes a small set of tools that your AI assistant can call during a shopping conversation. The AI assistant decides which tool to use based on the shopper's question — you don't configure this manually.

All tools run against the Pacific Apparel sample catalog. The catalog is fixed and read-only.

search_products

Searches the catalog by attribute and returns ranked results.

Your AI assistant calls this tool when a shopper has specified what they want — a product type, color, size, price range, brand, or any combination.

Behavior

• Returns products that match the specified attributes, ranked by relevance.
• Automatically relaxes the least important filter when strict criteria return too few results, and reports the change so your AI assistant can communicate it to the shopper.
• Generates refinement suggestions based on the result set — real price brackets, available colors, and other attributes — not hardcoded text.

Request parameters

Available filter attributes

The Pacific Apparel catalog supports filtering on:

• data.gender — male, female
• data.color — common color values
• data.material — material types
• data.style — style descriptors
• data.season — seasonal tags
• data.special_offer — blackfriday, back2school, mothersday, christmas, valentine, easter
• data.price — numeric range (use gte, lte)
• data.brand — exact brand name

Response parameters

The tool returns an object with the following fields:

search_productCollections

Runs multiple independent product searches in a single call. Useful when a shopper expresses several distinct intents at once — for example, "a casual shirt for him and a midi skirt for her."

Your AI assistant calls this tool when a shopper's message includes orthogonal intents that wouldn't combine into a single search.

Behavior

• Runs each sub-search independently with its own query, filters, and limit.
• Supports up to 5 sub-searches in a single call.
• Returns sub-results in the same order they were requested.

When intents are correlated rather than independent — for example, "a top that goes with these jeans" — your AI assistant should call search_products sequentially instead. Correlated intents need reasoning between searches.

Request parameters

Each sub-search object has the following fields:

Response parameters

Returns an array of search results, one per sub-search, in the same order as the request. Each sub-result has the same shape as a search_products response.

get_product

Fetches the full details of a specific product by identifier.

Your AI assistant calls this tool when a shopper references a specific product, or when it needs to follow up on a result from an earlier search.

Behavior

• Accepts either a variant-level identifier (itemId) or a parent-level identifier (product_id).
• Returns the parent product plus all its variants.
• Returns an explicit "not found" response when the identifier doesn't match anything.

Request parameters

Response parameters

When the product is found:

Each variant has the following fields:

Example response when found:

{
  "found": true,
  "product_id": "ABC-123",
  "matched_field": "data.gtin",
  "matched_item_id": "ABC-123-S",
  "variants": [
    {"itemId": "ABC-123-S", "data": {"title": "...", "size": "S"}},
    {"itemId": "ABC-123-M", "data": {"title": "...", "size": "M"}}
  ]
}

When the product is not found:

Example response when not found:

{
  "found": false,
  "code": "ABC-999",
  "message": "No product found for code 'ABC-999'"
}

seeker_products

Guides a shopper through follow-up questions when they don't know exactly what they want, then transitions into a search once it has enough context.

Your AI assistant calls this tool when a shopper is browsing, looking for a gift, or has expressed only a vague intent.

Behavior

• Generates follow-up questions based on an overview of the catalog — categories, price ranges, and product types.
• Uses the shopper's responses to build context for a search.
• Transitions to search_products or search_productCollections automatically once enough context is gathered.

Request parameters

This tool takes no arguments. It returns catalog context that your AI assistant uses to guide the conversation.

Response parameters

The tool returns an object with the following fields:

Related pages

• Test the Conversations server: verification prompts for each tool.
• Best practices: tips on prompt design and prototype evaluation.