Skip to main content

Before you build

This page is the pre-build companion to Troubleshooting. It isn't what the data is — see The data — or how to call it — see How to query. It's the short list of places where the data's shape or vocabulary behaves differently than a new builder reasonably expects, drawn from real use.

Two things make this cheaper than it looks:

  • It's learn-once. The facts underneath these gotchas are stable — the vertical tokens, the way a metric is computed, and the slug a given retailer resolves to don't shift under you. New retailers and verticals get added, but a slug is never quietly reassigned to a different retailer. So the cost is a single orientation, after which you cache what you resolved and reuse it across the session.
  • The answer is already in the tools. Everything below is verifiable with market_data_docs, market_data_entitlements, and the search_* resolution tools. These trip builders up not because the information is missing, but because it's reasonable — for a person or an agent — to shortcut past it. The fix each time is the same one move: check the tool that knows, then trust your cached answer.

An average may describe a subset, not the whole assortment​

What you'd expect. An "average" spans everything in scope — average price across the assortment, average discount across the range.

What actually happens. Some aggregates are computed over a conditional population — only the rows that meet a filter — rather than the full set. Average discount depth, for instance, is computed across only the products currently on discount, not the whole assortment. Read as a market-wide figure, it overstates. Nothing errors; the number is just answering a narrower question than you asked.

How to design around it. Before you surface an aggregate, confirm the population it's computed over — check the metric's definition in market_data_docs (the metrics topic) rather than assuming it spans everything. For any time-windowed or period-over-period figure, pair it with get_retailer_coverage first: a clean-looking aggregate can still be built on a range with data gaps, and it won't tell you that on its own.

EDITED's terms may not mean what the same word means in your system​

What you'd expect. Words like market, category, vertical, and brand carry the definitions they have in your own product or schema.

What actually happens. They're EDITED's terms, with specific meanings that often differ from a builder's:

  • Market is a country or region context, not a market segment or a total-addressable-market figure.
  • Vertical is a top-level segment of the data (apparel, beauty, home) — not your industry vertical — and the token a tool accepts isn't always the word you'd guess, so resolve it rather than typing it in.
  • Category is a resolved product-search concept (via search_product_searches), not a free-text taxonomy label you supply.

Mapping your word onto EDITED's without checking returns the wrong concept, not an error — the most expensive kind of mismatch to catch, because everything keeps working.

How to design around it. Map each EDITED term to your own vocabulary deliberately before you build on it, and confirm any definition you're unsure of in market_data_docs. Each term is defined in full on the page that owns it — verticals in The data, for instance — so this entry only has to flag that the words collide, with a single source to keep current.

A retailer identifier isn't portable — resolve it in context​

What you'd expect. Once you've got a retailer's slug, it's that retailer's ID everywhere — reuse it across markets and across domains.

What actually happens. Retailer identifiers are contextual:

  • Slugs aren't globally unique. The same retailer can slug differently by market — Zara in the UK may be zara, not zara-uk — so a name on its own can match the wrong regional storefront. Resolve the market first.
  • IDs don't cross domains. A slug from the market-data tools isn't a valid filter in the messaging & promotions tools; the two domains identify retailers differently.

Either one returns some other retailer's data, not an error — the same silent kind of wrong as the term collisions above.

How to design around it. Resolve the retailer in the context you're querying: market first for market data (search_markets, then search_retailers), and re-resolve with messagingmcp-list_retailers when you move to promotions. The full sequence is in How to query — this entry is just the heads-up that one slug won't carry everywhere.

How this page grows​

This page is the reported-friction surface: each friction that comes back from real use is one more entry in the same shape — what you'd expect, what actually happens, how to design around it. Each names a class of surprise and how to verify it, never the specific values — so adding a retailer or a vertical never dates the page, and a class that stops being true simply comes off. The goal is a page a builder can trust because it's short and current, not a comprehensive list of caveats.