Tools & errors

list_locations

Start here. Lists the merchant's locations with address, hours, fulfillment modes (pickup, delivery, dine_in, catering), and whether each is open right now. Pass near (lat/lng) to sort by distance, and/or postal_code to learn whether each location delivers there (delivers_to_you: yes | no | unknown). With fulfillment="delivery", locations that definitely do not deliver to you are dropped. Returns location ids. Next: call search_menu with a location_id.

Read-only.

search_menu

Find items at one location, with live availability. Use after list_locations. Filters: free-text query (matches name, description, category), dietary tags (all must match; vegan counts as vegetarian and dairy_free), exclude_allergens (drops items that contain or may contain them; items where the merchant has not stated the allergen are kept but carry allergen_warning, never treat those as safe), max_price in minor units, category. By default only items orderable now (or at desired_time) are returned; set include_unavailable to see sold-out items too. Each result includes price (minor units), allergens, lead_time_minutes, serves, modifier groups (ids needed for quote_order), and availability with as_of/ttl_seconds. Next: get_item for full detail, or quote_order.

Read-only.

get_item

Full detail for one item: description, price, every modifier group with option ids and min/max, dietary tags, and the complete allergen map (contains | may_contain | unknown for each major allergen; unknown means the merchant has not said, so never treat it as safe), lead time, serves, plus availability at each location that sells it. Use before quoting anything with modifiers or when a customer has allergies. Next: quote_order.

Read-only.

check_availability

Check whether specific items can be ordered at a location for a given time. Honors stock (in_stock | low | sold_out | unknown, with quantity when tracked), item lead times (e.g. cakes need 48h), opening hours, and fulfillment mode. Returns per-item orderable, earliest_time, a reason when not orderable, and stale=true if the merchant's stock data has outlived its ttl. Use before quote_order for pre-orders, catering, or anything with a future desired_time. Next: quote_order, or search_menu for substitutes.

Read-only.

plan_group_order

Propose a cart that feeds a group: team lunch, catering, an offsite. Deterministic, no LLM inside. Give headcount, budget_per_person (minor units, ALL-IN: tax and fees included), dietary_requirements as counts (e.g. {"vegetarian": 3, "gluten_free": 1}; each count is treated as different people), and desired_time. It covers each dietary group with individual portions first, fills the rest with up to three mains for variety, then adds drinks (and dessert if asked) only if the budget allows. Returns lines ready to pass to quote_order unchanged, a per-line breakdown of who each item covers, an estimate with per-person cost, a coverage report, any unmet constraints, and warnings (e.g. shared-kitchen gluten risk). Next: show the plan to the customer, then quote_order with the same lines.

Read-only.

quote_order

Price a cart and lock it for 10 minutes. Required before place_order: there is no way to order without a quote. Validates everything an order can fail on: opening hours (CLOSED), delivery zone (OUTSIDE_DELIVERY_ZONE), stock (ITEM_SOLD_OUT), lead times (LEAD_TIME_NOT_MET), modifiers (INVALID_MODIFIERS), delivery minimum (MINIMUM_NOT_MET). Errors include suggested_next_tool and details such as earliest_time. Returns quote_id, itemized lines, subtotal, fees, tax, total (minor units), eta, expires_at, and a policy check. If policy.allowed is false, place_order will refuse; tell the customer why. Next: confirm the total with the customer, then place_order.

Changes state.

place_order

Turn a quote into a real order. Only call after the customer has seen the quote total and said yes. Requires an unexpired quote_id, a unique idempotency_key you generate (e.g. a UUID), customer contact (name plus email or phone), and confirm: true. Retrying with the same idempotency_key and quote returns the original order (idempotent_replay: true), never a duplicate. Safe to retry on timeouts. Fails with QUOTE_EXPIRED, QUOTE_ALREADY_USED, PRICE_CHANGED or ITEM_SOLD_OUT (re-quote), or POLICY_BLOCKED (spending policy; do not work around it). No card data is ever taken here: payment is at pickup, on invoice, or via a merchant-hosted link in order.payment. If order.dry_run is true, the order was recorded but NOT sent to the merchant; say so. Next: get_order_status.

Changes state. Safe to retry.

get_order_status

Track an order. Returns the current status (received, accepted, preparing, ready, out_for_delivery, delivered, picked_up, cancelled), a timestamped timeline, eta, and until when it can be cancelled. ttl_seconds says how long before checking again is useful. DRY_RUN orders stay "received" because they were never sent.

Read-only.

cancel_order

Cancel an order within the merchant's cancellation window (see cancellable_until on the order, or orderable://policies). Fails with CANCELLATION_WINDOW_CLOSED once the window has passed or the order is ready/out for delivery; details include the store phone number so a human can call. Cancelling an already-cancelled order succeeds again (idempotent). Only cancel when the customer asked to.

Changes state (destructive). Safe to retry.

Errors

Errors come back as an MCP tool error whose text content is JSON:

{
  "error": {
    "code": "LEAD_TIME_NOT_MET",
    "message": "Chocolate Celebration Cake (8 in) needs 48h notice. Earliest: 2026-10-09T13:00:00.000Z",
    "suggested_next_tool": "check_availability",
    "details": { "problems": [{ "item_id": "crumb-chocolate-cake", "earliest_time": "2026-10-09T13:00:00.000Z" }] }
  }
}

Resources

• orderable://menu/{location_id}: the full menu with modifiers, allergens and availability.
• orderable://policies: cancellation, refund, payment and delivery fees, plus the agent spending policy and ordering rules.