Instagrocer

Add 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_basket

Add 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.

add_to_shopping_list

Add 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_list_to_basket

Remove 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.

clear_basket

Create or fetch the shopper's shopping list for a store (planning list). DATA tool. To display the list, call get_shopping_list.

create_shopping_list

Find 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.

find_nearby_stores

Full detail for one product by UPC: pricing, ingredients, nutrition. Relative image paths are also surfaced absolute as `images_url_absolute`.

get_item_details

The 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.

list_addresses

Remove 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.

remove_from_basket

Search 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.

search_products