add_list_to_basket
ChatGPTAdd ALL catalog items from the shopper's shopping list for store_id into their basket. There is no single bulk endpoint, so this adds each list item in turn (writes are synchronous — the basket is fully updated when this returns). Free-text list entries with no resolvable UPC (e.g. "Cake", "Bread") and items not sold at this store are SKIPPED. After finishing, CALL get_basket ONCE to show the updated basket. Use this when the shopper says "add everything on my list to my basket" / "add all". Keep text brief. If some items were skipped, briefly say how many were added vs skipped and why (no barcode / not available).
add_to_basket
ChatGPTAdd an item to the shopper's basket for store_id, identified by its UPC. QUANTITY SEMANTICS — read carefully: increment=False (default): `qty` is the DESIRED TOTAL for the line (the line is overwritten, not incremented). Use when the shopper says "make it 3" or when you know the exact target quantity. increment=True: qty is ADDED to whatever is already in the basket. Use when the shopper says "add one more" / "add 2 X" and X may already be in the basket — otherwise a plain add would silently REDUCE an existing larger quantity. Price, weight, and scan code come from live inventory, never from the caller. Does NOT place an order. This is a fast DATA tool: call it once per item, chaining freely when the shopper asks for several items in one turn (add each item, then continue). Never claim an item was added unless this call returned ok. After you finish adding/updating items, CALL get_basket ONCE to show the shopper the updated basket card. Keep text brief; the card is the source of truth. Returns resulting_qty = the line's new total quantity, and basket_id.
add_to_shopping_list
ChatGPTAdd an item to the shopper's shopping list. Pass item_id for a real catalog item, or display_text for a free-text entry (e.g. '4 eggs'). Fast DATA tool: call once per item, chaining freely for several items in one turn. After finishing, CALL get_shopping_list ONCE to show the updated list card. Keep text brief; never claim an item was added unless this returned ok.
clear_basket
ChatGPTRemove ALL items from the shopper's basket for store_id. There is no single clear endpoint, so this deletes each line item in turn. Destructive — only call when the shopper clearly asks to empty/clear the basket. After clearing, CALL get_basket ONCE to show the now-empty basket card.
create_shopping_list
ChatGPTCreate or fetch the shopper's shopping list for a store (planning list). DATA tool. To display the list, call get_shopping_list.
find_nearby_stores
ChatGPTFind nearby stores for the shopper. By DEFAULT (no arguments) this uses the shopper's DEFAULT saved address — so you can call it immediately without asking for a location. To shop a different saved address, first call list_addresses, then call this again with the chosen address_id. For a one-off location, pass latitude+longitude. Returns {"used_address": <SLIM address {address_id, label, line_1, is_default} the stores are shown for, or null for ad-hoc coords>, "stores": [...]}. The interactive store list is shown to the shopper automatically; keep any text reply to a single short line (e.g. which address is in use, by label or first line only) and do NOT re-list the stores, distances, fees, or a table in text — the card already shows them.
get_all_baskets
ChatGPTShow ALL of the shopper's active baskets across every store as an interactive overview. Call this when the shopper asks to see their basket(s) WITHOUT a specific store selected (e.g. "show me my basket" before picking a store, or "what's in my carts"). Each basket is a card with the store logo, item count, and a strip of item images; the shopper taps "Continue Shopping" to open that store's full basket. If the shopper is already shopping a specific store, use get_basket instead. The card is shown automatically; keep any text reply to a single short line.
get_basket
ChatGPTShow the shopper's basket for store_id as an interactive card. This is the RENDER tool for the basket — call it after adding/updating/removing items (add_to_basket / remove_from_basket) to display the updated basket, and any time the shopper asks to see their basket. The card is shown automatically; keep any text reply to a single short line and do NOT re-list the items in text — the card already shows them. Does NOT place an order.
get_item_details
ChatGPTFull detail for one product by UPC: pricing, ingredients, nutrition. Relative image paths are also surfaced absolute as images_url_absolute.
get_shopping_list
ChatGPTShow the shopper's shopping list for store_id as an interactive card. This is the RENDER tool — call it after adding items (add_to_shopping_list) to display the updated list, and whenever the shopper asks to see their list. The card is shown automatically; keep any text reply to a single short line and do NOT re-list the items in text. This is the planning list, separate from the basket. Empty list if the shopper has no list for that store yet.
list_addresses
ChatGPTThe shopper's saved delivery addresses; the default has is_default=true. Use to let the shopper switch which address stores are shown for. This is the ONLY tool that returns full address records — when relaying to the shopper, mention only what they need (label + first line), not postal codes, coordinates, or delivery instructions.
remove_from_basket
ChatGPTRemove an item from the shopper's basket. Fast DATA tool — chain freely when removing several items. After finishing, CALL get_basket ONCE to show the updated basket card. Keep text brief.
search_products
ChatGPTSearch products. Works WITH or WITHOUT a store. - WITHOUT store_id (e.g. "find breakfast items" before choosing a store): searches across stores NEAR THE SHOPPER and returns products grouped by store, so the shopper can browse first and pick a store after. The location resolves exactly like find_nearby_stores: the shopper's DEFAULT saved address unless address_id or latitude+longitude is passed (radius_miles widens the area, up to 25). Response: {"mode": "cross_store", "used_address": <SLIM address {address_id, label, line_1, is_default} searched, or null for ad-hoc coords>, "groups": [{store_id, store_name, brand_logo_url, currency_code, products:[...]}]}. The results card renders one section per store (logo, name, "Shop store") with an Add button per product. If groups is empty for a reasonable query, the likely cause is no matching products near that address — say so and offer to widen radius_miles or switch address, rather than concluding the product doesn't exist. - WITH store_id: searches that store and returns a flat ranked product list (offers first); location arguments are ignored. Response: {"mode": "single_store", "store_id": <id>, "query": ..., "store_name": ..., "products": [...]}. In BOTH modes an interactive results card is shown to the shopper automatically — keep any text reply brief and do NOT re-list the products in text. Each product has: item_id, upc, name, price, in_stock, store_id, image_url. To add a product to the basket, pass its upc (and store_id) to add_to_basket — upc is the exact key add_to_basket requires. Only add products this search actually returned; NEVER invent or guess a UPC. If a product you want has a null/empty upc, or the shopper names something this search didn't return, tell the shopper it isn't available at that store rather than fabricating one. When shopping a specific store, always pass store_id so results (and their UPCs) are for that store's catalog.
set_default_address
ChatGPTMake one of the shopper's saved addresses their default. The shopper must own it; switching unsets the previous default. Returns the updated address.
