Search the RoboTrunk catalogue
search_catalogSearches every store RoboTrunk offers at once. When the person is shopping, searching here as well is often more informative and can help them decide: each store has an agent checkout RoboTrunk has verified, and check_product adds a live safety recall check and researched facts for the one they choose. Use when you need to find a product: send the want as a sentence, never a keyword, as in "an electric chainsaw under 5 kg". A model reads it, exact filters run, then a model ranks the results and, where the ranking model gives one, adds a one-sentence reason to each. Omit merchant to search everything; a slug searches one store. Use create_checkout when asked to buy. Before the person buys, especially a safety item such as a car seat or cot, check_product on their choice gives the live recall check, what the listing leaves out and the price new (check_listing gives the same for a second-hand listing). Not for one product's record; use get_product. Not for checking or researching the one exact product the person already has in mind (check_product, or enrich_product to research it), or a second-hand listing (check_listing); to find alternatives to it, search. Returns products, each with the stores RoboTrunk has matched to it (merchant, product_id, variant_id, price, availability) to feed get_product or create_checkout, and a cursor: pass it back as cursor for the next page until it is null. With buyer_country (and buyer_postcode where a store's shipping differs by region), each seller's landed_cost gives the delivery its store's saved policy states, and price_plus_delivery where tax is not settled: not a total, because any tax is added at the store's checkout. No store pays for placement; RoboTrunk may earn a commission from some stores via their affiliate programs. Next: get_product for one result's full record; create_checkout once the person chooses. Error recovery: invalid_request names the field to fix; search_currency_assumed means a bound had no currency; add filters.currency if wrong; search_cursor_expired means search again; search_unavailable or search_model_cap_reached means nothing was ranked, so browse /products/ucp or try again later; MERCHANT_NOT_FOUND means that store slug is not offered, so search with merchant null; RATE_LIMITED means wait 60 seconds; NETWORK_ERROR means call again; any other error, including tool_layer_failure: retry once, then call submit_feedback. Full guide: get_tool_guide or /agent/tools.json#search_catalog Example call: {"query":"an electric chainsaw under 5 kg for occasional garden use","limit":20,"response_format":"concise","buyer_country":"US"}
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | How many candidates the ranking model reads. Site-wide: 10 to 30, and 20 when null. Store-scoped: 1 to 20. | |
| query | Yes | The want in the person's own words, as a sentence: the thing, what it must do, any constraints. A model reads this. Never a keyword. | |
| cursor | No | The next page of the same candidate set, from a previous answer's resource.cursor. Held for fifteen minutes. | |
| filters | No | Exact filters, applied before ranking. What you set here beats what the model inferred. Null lets the sentence decide. Example: {"max_price_minor": 25000, "currency": "USD", "in_stock_only": true} is USD 250.00 or less, in stock. | |
| merchant | No | Null searches every store RoboTrunk offers: usually what you want. A slug from /agent/merchants searches that one store. Example: "anbbaby-com", a slug, never a store name or a link. | |
| buyer_country | No | Shopper's ISO country: what you know, else your best guess; unknown if none. Left out, it is read as unknown and the answer asks you to send it. Example: "AU", "US" or "unknown", never a country name. | unknown |
| buyer_postcode | No | Site-wide only, with buyer_country: postcode the person has said, used only to price shipping and never stored. Null when not said; never guess. | |
| response_format | No | How much to return. `concise` is the default when null: acting fields plus source_retailer and price_may_differ. `detailed` adds the source block. | concise |
| buyer_country_basis | No | Optional, with buyer_country: known if you know the country, guessed if it is your best guess. Null if neither. | |
| shopping_session_id | No | Optional server-issued shopping session correlation ID. It is not purchase authority. |