text_search MCP Tool

The text_search tool searches the merchant’s product catalog by natural-language query. session_id may be omitted on the first call; on follow-up calls for the same query, pass a stable UUID, and issue a fresh one when the shopper starts a new search. This tool answers under any authenticated credential, including the site’s read-only token.

Request (TextSearchRequest)

Field	Type	Description
query	string	Required. Free-form natural-language query the shopper is searching for.
campaign	string or null	Campaign UUID to use instead of the merchant’s default text-search campaign. Leave unset to use the default.
columns	array of string, or null	Catalog columns to materialize into every result’s attributes. Leave unset to receive the default preset.
limit	number (uint32) or null	Upper bound on the number of results returned. When omitted the merchant’s campaign limit applies. When set, the effective limit is min(limit, campaign_limit).
additional_filter	McpStaticFilter or null	Free-form boolean filter tree applied in addition to the campaign’s static filters. Shrinks the underlying candidate set before ranking, so use it for hard constraints (e.g. “only in-stock”). For refinement within the same ranking use dynamic_filters instead.
dynamic_filters	array of McpDynamicFilterSelection, or null	Facet selections echoed back from a previous response’s dynamic_filters. Unlike additional_filter, dynamic-filter selections refine within the same ranking instead of shrinking the candidate set ahead of it — essential for range refinement on columns like price so the ranking stays comparable across rounds. Where a catalog groups product variants, a selection additionally decides which variant may represent its group, so a group can move to the rank of the variant the selection keeps.
group_variants	boolean or null	Whether variants of the same product — for example the same style in different colors or sizes — are collapsed into a single result. Leave unset to use the merchant’s configured default; set true to force grouping on (one representative per product) or false to force it off. Which fields distinguish one variant from another stays a merchant-level setting and is not controlled here.
session_id	string or null	Optional session identifier (UUID). Omit on the first call; on follow-up calls for the same query, pass a stable UUID. Issue a fresh UUID when the shopper starts a new query.

Response (TextSearchResponse)

Field	Type	Description
results	array of McpItem	The ranked products matching the query. Always present.
dynamic_filters	array of McpDynamicFilter	The facets available for refining this result set, each with its column and the options it offers. Always present. Echo selections back in the next request’s dynamic_filters.
stream	array of McpStreamItem, or null	Stream items for this search — for example a filter the query implied or a category prediction. Absent when the search produced none.
redirect_url	string or null	A URL the merchant mapped this query to, when one is configured. Absent otherwise.

Refining a search

A typical two-round exchange:

1. Call text_search with just a query. Read results for the products and dynamic_filters for the facets the catalog offers on this result set.
2. Call it again with the same query and a stable session_id, passing the shopper’s picks back in dynamic_filters. The ranked candidate set is unchanged, so the second round’s results stay comparable to the first.

For constraints that must hold for every result rather than refinements within a result set, use additional_filter instead — see Filtering: which channel to use.