> Documentation index: https://www.xekta.com/llms.txt

# product_search

> Search the catalogs of approved shops for products, dishes or whole menus.

The first tool in almost every conversation. It answers "what is near me", "who has this" and "show me this shop's menu", with live prices and stock.

| | |
| - | - |
| Type | Read: looks things up, changes nothing |
| Needs a cart the buyer approved | No |
| Moves money | No |

**Tool description (what the assistant sees)**

```text
Searches the catalogs of approved XEKTA shops (groceries and prepared food for pickup) by name, brand, category or attributes and returns ranked offers with price, stock state and shop details. Shops open now rank first; offers from shops outside their posted hours are included with shop_open_now: false and shop_opens_at, and an order to such a shop goes through only once it opens. With near (a city or neighborhood, a street address, a ZIP code or coordinates) nearby shops rank first and carry distance_miles; if no shop within the radius has a match, the nearest ones are returned instead. Without near the buyer's saved home address is used, or results come unsorted by distance — no location is needed to browse — and location_basis reports which location was used. A general query such as "markets", "grocery stores" or "restaurants" returns a few example items from each shop instead of matching item names. An order a shop does not answer within 10 minutes is cancelled automatically and nothing is charged. An offer with image_url has a photo: image_source "shop" is the shop's own photo, "stock" is a XEKTA stock photo of the dish that is only to be displayed together with its image_note label. Read-only. Results are built as a picture menu: show them as picture cards (image_url, name, price) by default, without waiting for the buyer to ask for pictures; on clients that render MCP Apps the cards come with the result. A query with a shop name and the word menu, such as "Borek-G menu", returns that shop's full menu in one call, ready-to-eat items first, 60 items per page (page: 2 for the next). When two or more restaurants or markets match, the result has mode "shops" with the shops listed (shops_total, more) and the ordinary results alongside; a single matching shop gives mode "shop_dishes" with that shop's header; the optional shop_id limits the search to one shop.
```

## Parameters

| Name | Type | Required | Description |
| - | - | - | - |
| `query` | `string` | Yes | What to look for, 1 to 200 characters. A product, a dish, a general word such as "restaurants", or a shop name plus the word menu. |
| `near` | `object` | No | Where the buyer is or wants to look. Exactly one of `place` (city, neighborhood or landmark), `address` (street address or cross streets with city), `zip` (5-digit US ZIP) or `lat` and `lng`. Only a location the buyer stated. Left out: the buyer's saved home address is used, or results are not sorted by distance. |
| `radius_miles` | `number` | No | Search radius, up to 50 miles. |
| `shop_id` | `uuid` | No | Limits the search to one shop. Set it when the buyer picked a shop from an earlier result's shops list. |
| `page` | `integer` | No | Page of a shop's full menu, 60 items per page. Left out: page 1. |
| `filters.merchant_kind` | `string` | No | Only shops of this kind: `market`, `restaurant` or `online_store` (shops that ship). Left out: all. |
| `filters.category` | `string` | No | Only this category. |
| `filters.max_price` | `number` | No | Only offers at or under this price. |
| `filters.retailer` | `string[]` | No | Only these shops, by name. |
| `filters.attributes` | `string[]` | No | Only offers with these attributes. |

## Notes

- `mode: "shops"` with `next_step: "buyer_chooses_shop"` means several shops match. Show the shops and ask the buyer which one before going further.
- `availability` is `in_stock`, `low_stock`, `out_of_stock` or `unknown`. `unknown` means the shop does not report stock for that item, not that it is missing.
- An offer marked `fulfillment: "shipping"` or `"pickup_or_shipping"` comes from a shop that ships. See [Shipping](https://www.xekta.com/docs/shipping.md).

## What to call next

[`cart_build`](https://www.xekta.com/docs/tools/cart-build.md) for a shopping list, or [`cart_create`](https://www.xekta.com/docs/tools/cart-create.md) then [`cart_add`](https://www.xekta.com/docs/tools/cart-add.md) for items the buyer picked one by one.