Search & Discovery

Search and discovery tools let an agent retrieve products from a merchant’s catalog — by natural-language query, by image, or by relation to a product the shopper is already looking at. They answer under any authenticated credential, including the site’s read-only token.

Tools

Tool	Description
text_search	Searches the catalog by natural-language query.
visual_search	Searches the catalog by an image, optionally cropped to one region, with object detection on by default.
similar_products	Recommends products similar to an anchor product — substitutes for the product the shopper is viewing.
cross_selling	Recommends products that go well with an anchor product — complements rather than substitutes.

Each tool wraps the service of the same name; for what the underlying service does and how a merchant configures it in Panel, see Text Search, Visual Search, Similar Products, and Cross-Selling.

Shared request fields

All four tools accept the same set of optional fields alongside their own:

• columns — catalog columns to materialize into every result’s attributes. Leave unset for the default preset. Use list_relevant_columns to learn which columns a catalog offers.
• limit — upper bound on the number of results. The merchant’s campaign limit still applies, so the effective limit is the smaller of the two.
• additional_filter — a free-form boolean filter tree (McpStaticFilter) applied in addition to the campaign’s own static filters. It shrinks the candidate set before ranking, so it suits hard constraints.
• dynamic_filters — facet selections (McpDynamicFilterSelection) echoed back from a previous response’s dynamic_filters. Unlike additional_filter, these refine within the same ranking instead of shrinking the candidate set ahead of it, which keeps rankings comparable across rounds.
• group_variants — whether variants of one product collapse into a single result. Leave unset for the merchant’s configured default.
• session_id — a UUID the agent generates; no response returns one. Pass a stable value across calls that refine the same query, image, or anchor, and a fresh one when the shopper moves on. For visual_search it does more than tie calls together: it pins the image, so later calls under the same session omit the image entirely.

Filtering: which channel to use

additional_filter and dynamic_filters solve different problems:

• Reach for additional_filter when a constraint must hold for every result — “only in-stock”, “only this brand”. It removes candidates before ranking.
• Reach for dynamic_filters when refining within results the shopper has already seen — especially numeric ranges like price. These refine within the same ranking rather than shrinking the candidate set ahead of it, so results stay comparable between rounds.

In normal use an agent does not set dynamic_filters on the first request. It reads the available facets off the first response’s dynamic_filters and echoes matching selections back on the next call.