How to build product search for an AI shopping assistant

Most shopping assistants fail in the same order. The demo works because someone typed a product name. Then a real user says “something like this but under sixty quid”, the retrieval layer returns three unrelated items, and the model writes a persuasive recommendation for a product nobody wants. The fix is almost never a better prompt. It is a better pipeline underneath.

1. Define the request and the market

Before retrieval, resolve two things: what the shopper is actually asking for, and which market the answer applies to.

Intent decomposition is worth doing explicitly. A request like “a quiet dishwasher for an open-plan flat, under £500” contains a product type, a soft constraint that maps onto a specification, a context that explains the soft constraint, and a hard numeric bound. Hard bounds should become filters. Soft constraints should stay in the semantic query, where they can influence ranking without excluding good candidates on a technicality.

Market is not optional and should not be guessed. simlir requires the shopper country on every search — gl on the REST search and lookup endpoints, market on image search and the MCP tools — and never infers it server-side. The response echoes the market back. Compare the two in your client and treat a mismatch as a bug rather than a curiosity.

2. Retrieve candidates from text or an image

Give your assistant all three entry points. Shoppers do not arrive with uniform certainty.

For an image request, send a hosted HTTPS URL rather than raw bytes. That keeps the tool call text-only, which matters in an agent workflow: the model does not need to inspect the image itself before deciding to call the tool.

When your workflow already holds an identifier — from a merchant feed, an ERP row, a checkout export or a retailer page — skip semantic ranking entirely and use exact lookup. It costs 1 credit rather than 2, and it does not introduce ranking ambiguity where none is needed. Use type=auto to try GTIN, then MPN, then SKU. GTIN is the strongest cross-retailer key; a retailer SKU is contextual and should be paired with a retailer filter.

3. Return a record your application can actually use

This is the stage that decides how good the rest of the assistant can be. If retrieval hands you a title and a link, every downstream feature — sorting, filtering, comparison tables, explanations, follow-up questions — has to be reconstructed with a model, expensively and unreliably.

Four things in that record do disproportionate work:

• id is a stable UUID that never changes. Cache it. Later you can re-fetch that exact product through /v1/product for 1 credit instead of repeating a 2-credit search — which is what you want when a user clicks a result or you refresh a saved comparison.
• spec is what makes two candidates comparable. Marketing prose is not.
• review_score paired with review_count is the honest form. A 5.0 from three people is not better than a 4.6 from nine hundred, and your ranking should know that.
• links.retailer is the destination. It may be null when there is no verified retailer product URL for that row, so handle the null rather than rendering a dead button. links.buy is a compatibility alias that resolves to the same URL.

4. Preserve provenance and checked time

A price is not a timeless fact. In the simlir contract it arrives as an object with an amount, a currency, the retailer where it was observed, and as_of — the date it was last seen.

Carry all four through your system. The moment your assistant flattens price to a single number, it loses the ability to say “£29.99 at Holland & Barrett, seen 7 April” and is left saying “£29.99” as though it were a quote. The first sentence survives contact with a shopper who clicks through to a different number. The second does not.

Use snapshots for ranking, sorting and rough display. Send shoppers to links.retailer for the current offer. This is covered in more depth in why product prices need a source and checked time.

5. Compare candidates on criteria you can name

An assistant earns trust by being explicit about why one product beat another. That requires comparison logic that lives in your code, not implicitly inside a model’s output.

A workable pattern:

1. Retrieve a candidate set larger than you intend to show.
2. Apply hard constraints as filters — price bounds, brand, category.
3. Score the remainder on named criteria: how well the specification meets the soft constraint, review score weighted by review count, price position within the set, and completeness of the record.
4. Drop candidates whose critical fields are missing rather than presenting them with silent gaps.
5. Pass the shortlist and the reasons to the model, and ask it to explain the ranking — not to invent it.

The division of labour matters. Retrieval and scoring are deterministic and testable. Language generation is where the model should be, because that is what it is good at. Teams that let the model do the ranking end up unable to answer the simplest support question: why did we recommend this?

6. Expose the capability through MCP or REST

Choose based on who decides when to search.

Both routes share authentication, credits, market scope and response shape, so this is an integration decision rather than a data decision. Many production assistants use both: MCP inside the conversational loop, REST for the pages and jobs around it. The full comparison is here.

7. Test the failure cases before your users find them

Shopping data is uneven. Some rows have no verified retailer URL. Some have no visual enrichment. Some categories have thin review coverage. An assistant that only works on complete records is an assistant that works in the demo.

Log meta on every call. Count, market, response time and credits used are four numbers that will tell you what is wrong with your assistant long before a user complains.

Architecture checklist

• Market is explicit on every requestSent as gl or market, echoed in the response, compared client-side.
• Hard constraints are filters, soft constraints are query textNumeric bounds go to min_price and max_price; qualitative needs stay semantic.
• All three retrieval modes are wiredSemantic search, image search, and exact lookup for known identifiers.
• Product UUIDs are cachedRe-fetch with /v1/product at 1 credit instead of repeating a search.
• Price stays an objectAmount, currency, retailer and as_of travel together through your whole stack.
• Ranking is deterministic and inspectableWritten in your code, testable, explainable to a support agent.
• Every null has a renderingNull retailer link, null visual, thin spec, no reviews.
• Empty results are a designed stateNot an exception, and never filled in by the model.
• Response metadata is loggedCount, market, latency and credits per call.
• Error codes are handled individually402, 429, 502 and 503 need different behaviour.

Frequently asked questions