Resolve a product name fragment or SKU code to Korral StoreLink SKU records. Read-only.

WHAT IT RETURNS matches: an array of { sku, name, category, unit }.

• sku Korral's 7-digit internal SKU code, e.g. "8847291". This is the only identifier the other tools in this server accept.

• name Buyer-facing product name, e.g. "Madeta butter 250g".

• category Merchandising category, e.g. "Dairy", "Bakery", "Produce".

• unit The unit stock and sales are counted in: "each" or "kg". All quantities elsewhere in this server (on_hand, units_sold_last_24h, gap, order quantity) are expressed in this unit.

Matching is case-insensitive substring on name, plus exact or prefix match on sku. A query with no matches returns an EMPTY matches array and a hint — it is not an error. Re-query with a shorter or more distinctive fragment ("butter", not "Madeta butter 250g salted").

WHEN TO USE IT This is step 1 of the standard workflow and normally the FIRST call you make: lookup_sku -> get_stock_position -> create_replenishment_order -> get_replenishment_status Use it whenever the buyer names a product in words rather than digits ("how's the Madeta butter doing?", "check the sourdough"), whenever you are unsure a SKU code is valid, and whenever get_stock_position returns an unknown-SKU error. Multiple matches mean the query is ambiguous — show the buyer the candidates with their categories and units and ask which one, rather than picking for them.

WHEN NOT TO USE IT It returns no stock levels, no sales figures and no order history — call get_stock_position for that. It does not say which stores range a SKU — only get_stock_position reveals that, per store. It exposes nothing about suppliers (no vendor names, lead times, order minimums or costs), nothing about price, cost or margin, and no transaction-level POS data. Do not tell the buyer this server can retrieve any of those; it cannot, and no other tool here can either.

Read the current StoreLink inventory snapshot for one SKU across one or more Korral stores, and compute the replenishment gap. Read-only.

WHAT IT RETURNS positions: one entry per requested store, each containing

• store_id The store this row is for, e.g. "47".

• on_hand Units physically in stock at the snapshot time.

• units_sold_last_24h Aggregate units sold in the trailing 24 hours. Aggregate only — there are no baskets, receipts or timestamps behind it.

• gap COMPUTED BY THIS SERVER as units_sold_last_24h - on_hand.

• as_of ISO-8601 timestamp of the inventory snapshot the numbers came from. Stock moves continuously; quote this when you report numbers to the buyer.

All three raw numbers are always returned alongside gap so the buyer can check the arithmetic. Never re-derive gap differently, and never present gap without the on_hand and units_sold_last_24h it came from.

HOW TO READ gap gap > 0 The store sold more in the last 24h than it currently holds. This is the replenishment signal. Magnitude = exactly how many more units would have been needed to serve the last 24 hours out of today's shelf (on_hand 3, sold 11 -> gap +8 at store 47). gap = 0 KNIFE EDGE, not "covered": the shelf holds exactly one more day at yesterday's rate, so the store runs empty in roughly 24 hours (on_hand 7, sold 7 -> gap 0). Surface it to the buyer as a watch item; never report it as fine. gap < 0 Stock exceeds the last 24h of sales by |gap| (on_hand 9, sold 5 -> gap -4). No shortfall indicated. gap is 24-hour arithmetic, not a forecast and not an order quantity. It carries no safety stock, no shelf-capacity limit, no promotion, seasonality or day-of-week adjustment, and no supplier lead time. Never pass gap into create_replenishment_order's quantity as a default — quote it to the buyer as evidence and let them state the number.

WHEN TO USE IT Step 2 of the standard workflow: lookup_sku -> get_stock_position -> create_replenishment_order -> get_replenishment_status. Use it to answer "are we short on X?", to compare a SKU across a store list, and ALWAYS immediately before proposing an order, so the reason string on that order cites live numbers. Pass every store the buyer cares about in one call rather than looping.

ERRORS — five distinct failures needing different responses:

• Unknown store_id, or a store this server has no credentials for -> a per-store entry carrying an "error" field; other stores still return normally. Check every entry before summarising; never total or average across entries that carry an error.

• SKU valid but NOT RANGED at that store -> also a per-store "error" entry ("not ranged"). This is not a typo and not transient: that store carries no inventory record for the product, so it cannot be replenished there and the failure is not fixable by retrying or correcting the code. Report it to the buyer and do not call create_replenishment_order for that store.

• "No credentials for store " -> that store has no API key configured here. It says NOTHING about the stock, which may be fine or may be empty. Never present it as a stock answer, never substitute a different store, and never guess. Pass the message to the buyer so they can raise access with Korral IT.

• "Authentication failed for store after key reload" -> the key was already reloaded once and still rejected. Retrying immediately will not help; a short wait might, and if it persists it is a Korral IT matter. Again, this is not a stock answer.

• Unknown sku -> the WHOLE call fails; the code is wrong. Call lookup_sku and retry with a sku copied verbatim from its matches. If EVERY requested store errors, the whole call is returned as an error too — that is a credentials or connectivity problem, so do not report it to the buyer as "no gaps found".

WHEN NOT TO USE IT It does not write anything and cannot reserve, hold or move stock. It has no supplier information (no vendor, lead time, order minimum or cost), no pricing, cost or margin, and no POS or transaction-level detail beyond the single aggregate units_sold_last_24h — no basket data, no hourly breakdown, no history beyond the current snapshot and trailing 24h. Do not offer the buyer a trend, a week-over-week comparison, or a delivery ETA from this tool.

Submit a replenishment order for one SKU to one Korral store in StoreLink. This is the ONLY write tool on this server, and it has real-world effect: a submitted order feeds Korral's internal distribution run — stock gets picked and a truck gets loaded against it. Treat every call as physically consequential.

CONFIRM BEFORE YOU CALL Get explicit human approval from the category buyer for this exact combination of store, SKU and quantity before calling. Never infer a quantity the buyer did not state or approve, never round a number up "to be safe", and never batch several stores by calling this repeatedly without confirming each one. If the buyer's instruction is ambiguous about quantity or store, ask — do not call and then report what you did.

NO IDEMPOTENCY — A RETRY LOADS A SECOND TRUCK Every call issues a NEW order_id. There is no de-duplication key, no idempotency token, and no way to ask this server whether an equivalent order already exists — there is no list or search, and get_replenishment_status only works on an order_id you already hold. Calling twice with identical store, SKU, quantity and reason creates two orders and two physical picks. If a call fails, times out, or you cannot tell whether it landed, do NOT call again: tell the buyer exactly what arguments you sent, say you cannot confirm the outcome, and let them check with Korral ops. Retry ONLY when the tool returned an explicit error stating nothing was submitted.

THE reason FIELD IS NOT A FORMALITY reason is required and is stored on the order as the audit trail a human will read weeks later. It must be a specific, human-meaningful sentence citing the actual stock evidence you just read from get_stock_position — the store, the numbers and the gap. Good: "Gap of 8 units at store 47 over 24h: on_hand 3 vs 11 sold, buyer approved 24 units." Rejected: whitespace only, a bare number, or placeholder text such as "n/a", "-", "test", "asap". If you have not called get_stock_position for this store and SKU in this conversation, you do not have the evidence to write a valid reason — go and get it.

reason is also written to the buyer's audit log, verbatim, whether the order is accepted or refused. Do not paste credentials, tokens or anything secret into it.

WHAT IT RETURNS

• order_id Readable, stable identifier, format RPL--, e.g. "RPL-47-001". Keep it — it is the only handle for reading the order back, and you must give it to the buyer.

• status Lifecycle state, always "submitted" at creation.

• confirmation One-line human-readable sentence the buyer can paste straight into Slack. Surface it verbatim.

ACCESS ERRORS — nothing was written Every error that opens "Rejected before submission — NO order was created" is a guarantee: no stock moved, and retrying after fixing the cause is safe. That includes the two credential failures, "No credentials for store " and "Authentication failed for store after key reload". Both are access problems, not stock problems: do NOT reroute the order to a store you can reach, do not lower the quantity, and do not tell the buyer the order was placed. Report the message verbatim and let them take it to Korral IT.

WHEN TO USE IT Step 3 of the standard workflow: lookup_sku -> get_stock_position -> create_replenishment_order -> get_replenishment_status. Use it only after a positive gap (or an explicit buyer instruction) has been established with live numbers and the buyer has approved the quantity. Then hand back the order_id and confirmation line.

WHEN NOT TO USE IT — AND WHAT IT CANNOT UNDO Orders here are APPEND-ONLY. This server has no cancel, no delete, no amend, no quantity change and no reschedule — none of the other three tools can do it either, and there is no hidden path to it. If the buyer wants an order stopped or changed after submission, say plainly that this server cannot do it and they must contact Korral ops directly; do not create a compensating or negative order to "fix" it. It also raises nothing with suppliers: it does not create a purchase order to a vendor, does not know lead times, order minimums, costs, price or margin, and will not tell you when the truck arrives. It also refuses a SKU that is not ranged at the target store — that store carries no inventory record for it. That is a merchandising fact, not a retryable error: report it, and do not substitute a different store or a similar SKU to get the call through. Never call it speculatively, to test the tool, or to "see what happens".

Read back a single replenishment order that was created through this server, scoped to its store. Read-only.

WHAT IT RETURNS The order record: order_id, store_id, sku, quantity, reason, current status, and its creation timestamp. status reflects where the order stands in StoreLink's internal flow; it begins at "submitted" on creation and advances from there. Report the status and the timestamp together — a status you read five minutes ago may have moved.

WHEN TO USE IT Step 4 and the final step of the standard workflow: lookup_sku -> get_stock_position -> create_replenishment_order -> get_replenishment_status. Use it when the buyer asks "did that order go through?" or "where is RPL-47-001?", and to confirm a write landed after create_replenishment_order returned. You need the order_id from the creation call — there is no browse, search or list-orders capability here, so an order_id you were never given cannot be recovered from this server.

SCOPE CHECK Both store_id and order_id are required and must match the same order. A valid order_id paired with the wrong store_id returns a not-found style error — it will never leak another store's order. If you get not-found, re-check the order_id and the store it was created for before telling the buyer the order is missing.

ACCESS ERRORS ARE NOT "NOT FOUND" "No credentials for store " and "Authentication failed for store after key reload" mean this server could not ask the question — NOT that the order is missing. The order may well exist and be on its way. Never report an access error to the buyer as a missing or failed order; give them the message so they can raise it with Korral IT.

WHEN NOT TO USE IT Reading an order does not change it, and nothing here can: there is no cancel, delete, amend or expedite on this server, and status is not writable through any tool. If the buyer wants the order stopped or altered, tell them this server cannot do it and they must contact Korral ops. It also shows no supplier or vendor detail, no lead time or delivery ETA, no cost, price or margin, and no POS data. For current shelf stock rather than order state, call get_stock_position instead.