Filters & attributes

How to narrow product search by attribute — brand, price, sticker, vendor code — when your agent queries your catalog. This applies to the in-product sales agent (which builds filters for you automatically) and to any external agent you wire up over the Product (commerce) MCP. Read this when you need to constrain results by attribute, or when a filter "silently returns nothing."

In the app

You don't hand-write filters for the in-product agent — it applies them for you while it searches. You build filters by hand only when you connect your own agent to the catalog over the Product MCP. Either way, the catalog itself is connected and managed under Knowledge Base → your product integration (https://app.mychatbot.app/knowledge-base).

Cheat sheet

Which filters each search tool honors

Not every search tool filters the same way. The big one to remember: whole-catalog semantic search only honors exact (eq) and is-one-of (in) filters. Ranges and comparisons only work in the category tools.

Search tool	What it does	Filters it honors
semantic_product_search	Free-text semantic search across your whole catalog	eq, in only
filter_category_products	Lists products in one category, with filters	eq, in, and ranges (gt, gte, lt, lte)
get_available_filters	Shows which attributes/values you can filter on within a category	eq, in, gt, gte, lt, lte
get_category_attributes, get_category_attribute_values	Discover the exact attribute names and their real values	discovery only — no filters
get_product_details, get_product_variants, find_similar_products, get_products_by_ids, get_all_categories	Detail / lookup / browse	no filters

Only eq / in filter on whole-catalog search

On semantic_product_search, comparison and text operators — ne, gt, gte, lt, lte, startswith, endswith — are accepted but silently ignored. Only equals (eq) and is-one-of (in) actually narrow the results. For anything with a range (price >= 20) or a comparison, use filter_category_products, which runs inside a single category and honors the full set.

Why the difference? Whole-catalog semantic search matches against a compact, searchable copy of each product's attributes that's built for fast exact/is-one-of lookups across everything at once. The category tools work inside a single category, where every attribute keeps its original type (numbers stay numbers), so they can do ranges and comparisons.

What a filter looks like

A filter is a small object:

{ "attribute": "brand", "operator": "eq", "value": "Numbuzin" }

• attribute — the attribute name exactly as it appears in your feed (case- and underscore-sensitive; MyChatBot does no rewriting).
• operator — one of eq, ne, gt, gte, lt, lte, in, startswith, endswith (remember: on whole-catalog search only eq/in take effect).
• value — a single value, or a list when operator is in.

Multiple filters are AND-ed together:

{
  "query": "hydrating serum",
  "filters": [
    { "attribute": "brand",     "operator": "eq", "value": "Numbuzin" },
    { "attribute": "skin_type", "operator": "in", "value": ["dry", "normal"] }
  ]
}

Range filter — route it through the category tool so the numeric type is preserved:

{
  "category_id": "skincare_serums",
  "filters": [
    { "attribute": "price", "operator": "gte", "value": 20 },
    { "attribute": "price", "operator": "lte", "value": 60 }
  ]
}

Look up the real attribute names first

Because attribute must match your feed exactly, discover the available attributes and their real values with get_category_attributes and get_category_attribute_values before you build a filter. In the app you can see the same attributes on your product integration's page (Knowledge Base → your product integration →https://app.mychatbot.app/knowledge-base).

Stickers & other multi-value attributes

stickers is a multi-value attribute — one product can carry several — and filters match it element-wise. An eq on a single sticker matches any product whose stickers list contains that value, no matter what else is tagged on it; in matches any of several:

{
  "query": "gift sets",
  "filters": [ { "attribute": "stickers", "operator": "eq", "value": "Подарунок" } ]
}

This returns every product whose stickers include Подарунок, regardless of its other tags.

Want another attribute matched element-wise?

Today only stickers is treated as a native multi-value list. By default any other attribute is stored as one joined string, so element-wise filtering won't work on it. If you need another attribute matched per-value, contact MyChatBot support.

Filtering by SKU or product code

Identifier attributes are not filterable on whole-catalog semantic search — they're deliberately kept out of the searchable-attributes copy and handled by exact-match ranking instead. An attribute is treated as an identifier when its name contains any of these as a whole word:

vendorcode, productcode, sku, upc, ean, isbn, mpn, asin, barcode,
model, part, product_id, item_id, catalog, article, артикул

Matching is by whole word, not substring — product_id and item_id count, but ordinary words that merely contain one of these (e.g. departure contains "part", compartment) are not treated as identifiers.

Filtering by SKU on semantic search returns nothing

An eq/in filter on sku, vendorcode, barcode, etc. can't be satisfied by whole-catalog search. To match exact codes:

• Put the code straight in query. MyChatBot automatically boosts exact code/SKU matches and skips semantic ranking for code-like queries, so the exact item lands on top.
• Fetch by id with get_products_by_ids when you already know the product id.
• To filter on a code column directly, use filter_category_products inside that product's category (you may need a reindex first — see below).

The vendor-site URL attribute

URL-valued attributes (image links, a vendor site link) are excluded from filtering like other links. The Ukrainian vendor-site link attribute посилання на сайт (romanized posilannya-na-sayt; Посилання_на_сайт and посилання_на_сайт are also recognized) gets extra ranking weight so "find the product at this vendor URL" queries land on the exact item. MyChatBot tunes this behind the scenes.

When a filter returns nothing

An empty result isn't always a real "no results"

A catalog indexed before the current searchable-attributes copy existed can have a missing attribute blob, so exact filters can't match even when the value genuinely exists.

Tell-tale: semantic_product_search with a filter returns [], but get_category_attribute_values (or filter_category_products) shows the value is really there.

Fix — a from-scratch reindex. This isn't a self-serve toggle. Either delete and re-add the integration in Knowledge Base (https://app.mychatbot.app/knowledge-base), or contact MyChatBot support with the integration id and ask them to reindex it.

MyChatBot tunes search relevance for you

Result ordering blends semantic similarity, keyword matching, exact-code boosts, and the special URL weighting above. These weights aren't self-serve — MyChatBot tunes relevance for your catalog. If ranking or filtering doesn't fit your inventory, contact support.

Best practices

Do

• Use eq/in filters on semantic_product_search for categorical facets (brand, sticker, condition).
• Route numeric and comparison filters (price >= 20) through filter_category_products.
• Look up attribute names and values with get_category_attributes and get_category_attribute_values before building a filter, so attribute matches the feed exactly.
• Put SKUs/barcodes in query, not in a filter, and let exact-code boosting do the work.

Don't

• Don't send gt/lt/startswith/ne to semantic_product_search expecting them to filter — they're dropped on whole-catalog search.
• Don't filter by SKU/vendorcode on semantic search — those aren't filterable there.
• Don't assume a filter that returns [] is a real "no results" — on an older catalog it may be a stale index; fix it with a from-scratch reindex (delete & re-add, or ask support).

Test it (over the Product MCP)

// 1. Discover the exact attribute name + type
{ "tool": "get_category_attributes", "category_id": "skincare_serums" }

// 2. See the real values you can filter on
{ "tool": "get_category_attribute_values",
  "category_id": "skincare_serums", "attribute_name": "brand" }

// 3. Apply an eq filter on semantic search
{ "tool": "semantic_product_search",
  "query": "brightening serum",
  "filters": [ { "attribute": "brand", "operator": "eq", "value": "Numbuzin" } ] }

// 4. Confirm range filters via the category tool
{ "tool": "filter_category_products",
  "category_id": "skincare_serums",
  "filters": [ { "attribute": "price", "operator": "lte", "value": 40 } ] }

If step 3 returns [] but step 4 (or get_category_attribute_values) shows the value exists, the catalog's searchable-attributes copy is likely stale — fix it with a from-scratch reindex (delete & re-add the integration, or ask MyChatBot support).

See also

• Search tools reference — the full tool list, params, and return shapes.
• Getting inventory in — connecting a catalog and how attributes become filterable.
• How search works — the search pipeline these filters run through.
• Image search — image-based product matching.
• Troubleshooting & best practices — stale-index, name-pollution, and SKU-filtering gotchas in depth.
• Product (commerce) MCP — the MCP endpoint that exposes these search tools to your agent.