optimize_delivery

io.github.nitaiaharoni1/super-mcp · Verify this server

Price a whole shopping list at every Israeli online supermarket that delivers to an address, and rank them on what the order actually costs: items + delivery fee + service fee. Call this ONCE with the full list — never price lines separately. This is SuperMCP's shopping-list tool for online supermarket delivery. ASK THE SHOPPER WHERE THEY LIVE BEFORE CALLING, whenever you can get it in the same breath. A city is enough. It is not a detail that sharpens the answer, it usually IS the answer: of the 531 towns whose coverage we hold, 386 are served by exactly one chain. It is also much the cheaper call, comparing the handful of storefronts that reach one town instead of every storefront in the country. Only when you cannot ask, or when showing the range now beats a round trip, call with no destination. It does not fail: it returns status=needs_destination, the same list priced at every storefront in the country, carrying only what an address does not decide — each storefront's shelf prices, its own delivery fee and its minimum order. NOT ONE of them was tested against a service area, so that reply names no cheapest, carries no handoffUrl and is not a recommendation. Quote it as a range, say we do not yet know who delivers to this shopper, ask for their city or street address, then send {continuation, city} to get the storefronts that actually reach them. THE HEADLINE FIGURE IS deliveredTotal, not the item subtotal: a ₪35.90 delivery fee outweighs most price differences between chains. But RANK on deliveredComparableTotal, never on deliveredTotal: totalScope is priced_lines_only, so a storefront that stocks four of your twelve items reports a small deliveredTotal precisely because it cannot fill the basket. Check pricedLines against requestedLines and say when the coverage is partial. A gap has two possible reasons and catalogVisibility says which. 'full_catalogue' means catalogSize is the retailer's complete published price file, so a line it did not price is a line it does not stock. 'partial_index' means WE cannot see the whole shop, because its prices are read off a website that cannot be paged, so the gap may be ours and the shop may well carry the missing items. Say which it is rather than telling a shopper a storefront does not stock something we simply never indexed. Both fields are null when the count has not loaded yet, which is not an empty shop. Read deliveryTerms.confidence before quoting: 'verified' was read from the retailer's own binding terms, 'reported' from a cited secondary source, 'unknown' means no fee is established and the ranking used an assumption (assumedDeliveryFee) that must not be repeated as a price. Anything other than verified or reported withholds the whole quotable tariff page, not just the fee: deliveryFee, freeDeliveryThreshold and nextFeeBreak all come back null together, because all three are read off the page we just declined to stand behind. Never fill one of them in from get_delivery_terms and quote it beside a fee this plan refused to give. minimumOrder is gated differently on purpose, lapsing only once the figure is past its 90-day recheck, so its presence is not evidence the fee beside it can be quoted. deliveryFeeIsFloor=true means the fee is a published lower bound, so quote it as 'from ₪X' and treat deliveredTotal as a minimum. meetsMinimum=false means the order cannot be placed as it stands; report amountToMinimum, the top-up needed. Those plans are still listed, after the orderable ones, so present them as options that need topping up rather than hiding them. Of several branches of one marketplace chain that all sit under their minimum, the one listed is the cheapest that is also nearest to its minimum, so the top-up you report is the smallest on offer there. Rank on cheapestDelivered only if the shopper will happily order twice: it prices missing lines at a market reference. bestSingleOrder is the fullest basket obtainable in one order. Both, and bestVerifiedTerms, carry totals only: find the storefront in plans by serviceSlug for its priced lines. When nextFeeBreak.worthTopUp is true, spending a little more makes the order cheaper overall — say so. A line carrying cheaperAlternative can be met for less AT THE SAME SHOP: it names the product, how many packs, what the line would cost instead, and the saving, promotions included. Every one is cheaper per 100g/ml/piece as well as per line, so it is a genuine saving rather than a smaller pack, and the saving can be quoted as it stands. Offer these unprompted when the shopper cares about price, and never silently swap them in — it is a different product and theirs to choose. Pin one by calling again with its productId. splitOrder, when it is not null, is the same list bought from two shops instead of one, with each leg's items, fees and its own handoffUrl. reason='cheaper' means it saves money after BOTH delivery fees; reason='more_of_the_list' means no one shop stocks everything and the second order fills the gap at extra cost, which `saving` reports as a negative. Volunteer it unprompted, and say which of the two it is. null means one order is the right answer here. If the shopper says a priced line is wrong, call suggest_similar_products with their Hebrew words and the rejected product_id, then call this tool again with that product_id on the line. Storefronts that cannot serve this basket come back in unavailableStores with a reason. By default only the actionable ones are listed: below_minimum_order, and price_feed_stale for a chain that delivers here but has published no prices for over a fortnight, which is therefore not in plans at all and must not be presented as an option. A plan flagged priceFeedStale is a milder case, over a week old: still worth comparing, but quote it as what the shop last published on priceFeedAsOf. If no storefront inside the fortnight can take the order, the abandoned ones come back in plans rather than leaving the shopper with nothing, and notes says so. unavailableStoresOmitted counts the rest, all ruled out on the address alone. A plan may carry venues: branches of one marketplace chain that priced this basket identically, collapsed into one row. Any slug in it works with get_delivery_terms. venuesOmitted counts further branches of that chain left out because each costs more and fills no line this row is missing. None of their figures are here and this row's are not theirs, so never quote a price for them; list_delivery_options names them all. By default only the recommended storefronts carry a `lines` breakdown; every other plan reports its totals and pricedLines with `lines: []`. That is not a gap — re-call with response_detail=standard only if you must compare the same item's price across chains. When the shopper settles on a storefront, give them that plan's handoffUrl: it opens the whole basket as one Hebrew page, every line with its price and its own product link. Hand over that one link rather than the per-line link fields, which leave the shopper opening a tab per item. Say that the page shows the prices this answer was built on.