search_catalog
Search product catalog
Search the AirShelf cross-vendor product catalog by natural-language query. The catalog covers industrial-automation, wiring-devices, digital-signage, business-display, mfp, barcode-printer, laser-printer, inkjet-printer, mechanical-keyboards, cybersecurity, threat-intelligence-platform. Industrial-automation and wiring-device rows are indexed by manufacturer part number, so a brand or part number in the query ("Pepperl+Fuchs retroreflective sensor", "IN5409") retrieves more reliably than a bare product type; those rows carry no normalized spec facets, so the `specs` filter does not apply to them. Returns ranked products with prices, specs, and per-row match accounting. Each row includes `unverified_specs`, the normalized spec names that lack claim-level receipts; never use those as decisive facts. Example queries: "tactile mechanical keyboard under $150", "Toshiba A3 colour multifunction device", "industrial barcode printer for a warehouse", "threat-intelligence platform with dark-web monitoring".
Result fields: • canonical_name — the exact catalog name of the product. • spec_absence_note — spec fields absent from this product's golden record (AirShelf's verified product record); null when nothing is missing. • constraint_match_score and matched_criteria — query constraints supported by claim-level receipts. unverified_criteria names matching catalog values that still need confirmation; missing_criteria names values that are absent or conflict. • parsed.price_availability — all_null = true means every returned price is null. For quote-gated B2B pricing, a null price with a quote path is expected rather than an error; query_had_budget reports whether the query carried one. • result.commercial_data — branch on actionable before using price or stock. Observations older than 24 hours are withheld from result.price/result.inStock and retained only as labelled last_observed history. • parsed.weak_match — the response contains an unresolved constraint, query match, or product-identity warning. parsed.unverified_identity_count counts returned names without an identity receipt. parsed.no_match — no product satisfies a hard constraint, and candidates violating it were excluded server-side.
On a miss or near-miss for a specific brand+model the response may also carry a `tier3` block, meaning a real-time lookup for the exact SKU asked about; it can appear alongside fuzzy-neighbour rows. • tier3.status = "resolved" — a single-source reading of the page at tier3.source_url. MPN-confirmed means the live lookup matched the manufacturer part number. Its verification is "live-unverified": confirmed on a live page during this run, but not yet matched to an AirShelf catalog record. A verified row is matched to the catalog record. tier3.cached = true means it came from a recent prior lookup, with fetched_at recording when the page was read. • tier3.status = "abstain" — the lookup could not confirm the product exists as asked, so no specs, price, or availability were established. tier3.guidance describes the quote-request path. • tier3.status = "declined" — an applicable lookup did not run; tier3.reason says why (disabled, rate_limited, daily_cap, negative_cache, error). No specs or availability were established, and none should be inferred. No tier3 block at all means a live lookup was not applicable to this query (no parseable brand+model identity).
Optional `market` (ISO 3166-1 alpha-2, e.g. "TH") excludes catalog rows whose country-specific URL conflicts with the buyer market and scopes tier3 lookup/cache. A remaining global URL is not local-availability proof: parsed.weak_match stays true and unsatisfied_constraints includes market_availability until every returned row has a matching country receipt. "Available in <market>" still does not guarantee stock.
Key parameters
| Name | Required | Type | Description |
|---|---|---|---|
| q | Yes | string | Natural-language query, at most 200 characters. Supports budget hints (e.g. "under $150"). |
| category | No | string | Optional category filter (industrial-automation, wiring-devices, digital-signage, business-display, mfp, barcode-printer, laser-printer, inkjet-printer, mechanical-keyboards, cybersecurity, threat-intelligence-platform) |
| limit | No | number | Max results |
| market | No | string | Buyer market as an assigned ISO 3166-1 alpha-2 country code (e.g. "TH", "AU"). Conflicting country receipts are excluded; global URLs remain market-unverified. |
| merchant | No | string | Optional merchant slug (e.g. "toshiba", "cyble") from list_merchants. Scopes the search to that merchant's own shelf, which is a SEPARATE substrate from the cross-vendor catalog: it is reached only when the cross-vendor catalog returns nothing, and its rows carry the merchant's own product data rather than datasheet-extracted golden records. Omit it for cross-vendor search, which is the default and the right choice for "what should I buy". |
| specs | No | object | Hard spec facets, e.g. {"form_factor":"desktop","print_speed_ppm":33}. Filters by exact/range spec match. |
Request example
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "search_catalog",
"arguments": {
"q": "industrial barcode printer"
}
}
}