Tool Reference

This page describes what each tool is for — its purpose, when an agent should reach for it, and any side effects. It deliberately does not enumerate every parameter: your MCP client receives the full, authoritative parameter schema from the server automatically, and that schema is the source of truth. Only the inputs that matter for understanding a tool are called out here. Ids are prefixed (see Vocabulary).

Read tools

find_entity

Fuzzy (case-insensitive substring) search across SKUs, products, suppliers, locations, categories, and collections. The right first step to turn a name the user typed into an id you can pass to other tools. Optionally restrict to specific entity types.

list_entities

Enumerate the full set of a small entity type — suppliers, locations, categories, collections — when you need everything rather than a fuzzy match.

get_entity

Point lookup of a single entity by id. The id prefix encodes the type, so the type usually doesn’t need to be specified separately. A tr_… id returns the transfer with its lines — each carrying the line_id that update_transfer takes — and a po_… id returns the PO with its lines.

search_inventory

Current stock state and derived metrics, at a configurable grain (sku, product, or sku_location). Supports structured filters and sorts over fields like current_stock, days_left_min and stock_health. Use it to answer “what’s low / overstocked / out of stock”.

search_purchase_orders

List purchase orders with rich filters (status, supplier, creation-date window, tags, type). Pass expand=["lines"] to include line detail — that’s how you get the line_ids needed to edit or receive against a PO. Deleted POs are never returned.

Note

Omitting order_types hides production orders: it defaults to [finished_good, raw_material]. Ask for production explicitly to see them.

search_transfers

List stock transfers between locations with filters for status, source / destination location, name and date windows. Rows are headers only — pass a tr_… id to get_entity for the lines. A name_contains search needs at least 3 characters; a shorter one is rejected rather than answered with every transfer. Date and timestamp filters are UTC — give updated_after an offset and it is converted, give it none and it is read as UTC. Transfers outside your location permissions are never returned.

search_forecasts

Forecasted demand for the next 12 months, bucketed by month, grouped by sku by default. Use it to read the demand plan; update_forecast_plan changes it.

get_insights

Pre-computed insight cards — stock-out risk, late POs, excess inventory, best sellers stock, and similar. The fastest way to surface “what needs attention” without assembling it from raw search results.

get_change_history

Audit trail: who changed what, when, with old → new values. Works scoped to a single entity — purchase orders, stock arrivals, SKUs, suppliers, locations, products, location transfers, stock takes, shipments, forecasts and tags — or as a tenant-wide feed.

export_purchase_order

Generate a downloadable PDF / XLSX export of a single PO and return a public URL.

Note

Read-only with respect to your data — it does not modify the PO. Its only side effect is writing the export file to Prediko’s public export bucket and returning a link.

Write tools

Write semantics

All write tools — the purchase-order, SKU-settings, forecast and transfer tools — share one response envelope and a few behaviours worth understanding. Exact response fields come from the live tool results; these are the concepts.

• Preview, then apply. Every write tool accepts dry_run. With dry_run=true it runs full validation and returns a preview of the projected effect without writing anything. The recommended pattern is always to preview, show the user, then re-issue the same call with dry_run=false.
• Partial outcomes. Writes are best-effort, not transactional. A batch can have some items succeed and others fail — the result tells you which. If a problem is caught before anything is written, nothing changes and you can retry the whole batch; if some items already committed, only re-try the failed ones (re-sending the successes would duplicate them).
• Lost answers. A write whose answer never arrives is not reported as “nothing written”. The transfer tools re-read the record to see what landed; anything that still cannot be settled comes back with retryable: false and an unknown affected_count, so read the record before sending it again.
• Reversibility. receive_po_units and receive_transfer_units are reversible via received_quantity — quantities are deltas, so a negative quantity backs out a previous receipt. mark_as_received and is_closed are not deltas and are not undone by a negative quantity. Reverting a placed PO to an earlier status is destructive (it resets received units) and surfaces a destructive: warning first. The same applies to reverting an ordered transfer. update_forecast_plan is not reversible — see its caution below.
• Renamed parameters. update_purchase_order, receive_po_units and export_purchase_order take purchase_order_id; the former po_id is deprecated and still accepted until the next release. Sending both is rejected. receive_units is receive_po_units’s deprecated former name — the tool itself is unchanged, only the name; use receive_po_units in new integrations.
• Auditing. Every write is recorded in Prediko’s audit log and attributed to you, the real caller (see Actor attribution). Each result carries an audit_id — quote it when reporting an issue.

create_purchase_order

Create a new purchase order from a supplier, a destination location, and a set of lines (each a SKU + ordered_units).

Note

The PO is created in draft status. There is no external side effect — the supplier is not contacted on creation.

update_purchase_order

Apply header and/or line changes to an existing PO. Line edits use an action model — update, add, or remove — keyed by line_id (from search_purchase_orders with expand=["lines"]). Delivery dates are per-line, so they are set on an update line rather than on the PO header.

Caution

Best-effort atomicity: the header is patched separately from lines, so one can succeed while the other fails (you’ll get a partial result). Reverting a placed PO (ordered+) to a pre-placement status is destructive and returns a destructive: warning.

receive_po_units

Note

receive_units is this tool’s deprecated former name — same behaviour, kept for backward compatibility. Use receive_po_units going forward.

Record received quantities against PO lines when stock arrives. Each line sets one or more of received_quantity, mark_as_received, is_closed — except received_quantity and mark_as_received together, which are mutually exclusive on the same line.

Caution

received_quantity is a delta, not an absolute: positive = units arrived, negative = reverse a previous receipt, zero is rejected. This is what makes receipts reversible. mark_as_received (receive the full confirmed quantity in one shot) and is_closed (close the line without moving its received quantity, e.g. a short-close) are independent of received_quantity and are not deltas — they cannot be reversed by sending the opposite value. received_quantity and mark_as_received cannot be set on the same line — pick a delta or a full receive, not both — but is_closed can be combined with either.

update_sku_settings

Batch-update SKU planning attributes: reorder_status (whether the SKU is included in re-order planning), lead_time_days, moq, and the coverage alert window.

Caution

The coverage window — safety_stock_days / days_of_cover — is expressed in days of stock, not units. A patch where the buffer exceeds the ceiling is rejected as a contradictory alert config.

Caution

reorder_status is not an instant flag flip. Setting it to false takes the SKU out of re-order planning: its stock health is dismissed and its demand forecast decays away asynchronously. Setting it back to true puts it back. Either way the numbers settle only once the recompute finishes.

Bundle SKUs are always excluded from re-order planning by Prediko, so reorder_status: true on a bundle is rejected rather than reported as applied — set it on the bundle’s component SKUs instead.

update_forecast_plan

Apply manual overrides to demand-plan cells — one value per (item, period), or per (item, location or store, period) when the plan is split — when a human judgement (a promotion, a delisting, a known one-off) should replace the forecast for specific periods. The split defaults to overall (the item across every location); pass split_type: "location" or "store" with a matching split_id to override one split instead. Read the plan with search_forecasts first. All cells in one call must share the same item level and split; each cell must cover exactly one calendar month, quarter or week (start on the period’s first day, end on its last day), and every cell in the call must resolve to the same one of those three. A week ending on the first day of a month spans two months and is not supported yet — use a monthly cell for that period. Send a coordinate once: two values for the same item, split and period are rejected rather than applied in an arbitrary order.

Caution

Destructive and not reversible: each cell overwrites any manual adjustment already on the same coordinates. Always preview with dry_run=true — the preview returns, for every cell, the current plan value, the proposed value and the delta (current is null when no plan value could be read for the cell, and a warning names it). dry_run validates the payload and previews values but does not prove the write will be permitted. A cell Prediko refuses — an item with no plan data for the period, such as an archived one — comes back under failed with status: "partial" rather than being reported as applied, and each entry echoes the cell in the shape you sent it so it can be resubmitted once the cause is fixed. If the error does not say which cell it refers to, the entry carries cell_incomplete: true and only the fields that could be mapped back. Applying the change queues a stock-health and reorder recompute that settles within about 30 seconds.

create_transfer

Create a stock transfer from a source location; each line names its SKU, ordered_units and destination location, so one transfer can feed several locations. It lands in draft; nothing moves until you place it with update_transfer(patch: {status: "ordered"}). Units are capped at the stock available at the source — capped lines are reported in warnings. The source and every destination must be within your location permissions — an out-of-scope location is refused, never silently dropped. Prediko does not report which end was out of scope, so the error names both.

Caution

Not transactional: the header is created before the lines. A partial result names the created transfer_id when the creation itself was confirmed — add the lines with update_transfer instead of creating it again. If the answer to the creation itself is lost instead, you also get partial, but with affected_count null and no transfer_id: the transfer may exist all the same, the result is not retryable, and Prediko assigns its own reference on creation while any name you gave is applied afterwards — so search for a draft transfer from the same source location created in the last few minutes before retrying.

update_transfer

Header, status and line edits to a transfer: name, notes, tracking number, due date, status, and update / add / remove lines keyed by line_id (from get_entity). New lines must name their destination_location_id and whole-number ordered_units, and can only be added while the transfer is still draft, sent_for_approval or approved — once it is placed, create a new transfer for the extra units. A newly added line’s ordered_units is capped at the stock available at the source and capped lines are reported in warnings; changing an existing line’s ordered_units is stored exactly as sent. A patch-level confirmed_delivery_date covers every line including ones added in the same call, and a per-line confirmed_delivery_date overrides it.

patch.status moves the transfer between draft, sent_for_approval, approved and ordered, and is applied after the header and line changes in the same call — so one call can add a line and place the transfer. ordered places it: its units count as in transit and, for transfers managed in Prediko, are reserved at the source location.

Caution

Best-effort atomicity: each change is a separate write and a failure part way through yields a partial result. validation_failed with affected_count 0 means Prediko refused every change outright — nothing was written and the whole patch is safe to retry. A lost answer is settled by re-reading the transfer instead; a change that cannot be settled comes back as outcome: unresolved with retryable: false and a null affected_count. remove is a bulk delete.

Caution

partially_received (any line with units received or rejected) and closed (every line closed or fully accounted for — received plus rejected) follow from receipts and cannot be set, and a transfer already in one of them cannot be moved out here — that would discard its received units. Reverting an ordered transfer stops its units counting as in transit, releases any source reservation, and returns a destructive: warning first.

receive_transfer_units

Record received quantities against stock-transfer lines when units arrive at the destination. Each line sets one or more of received_quantity, mark_as_received, is_closed — the same three fields receive_po_units takes, applied to a transfer’s lines (line_id from get_entity) instead of a PO’s — with the same restriction that received_quantity and mark_as_received are mutually exclusive on a line.

Caution

The transfer must already be placed: receipts against a draft, sent_for_approval or approved transfer are rejected (in dry-run too) — place it first with update_transfer(patch: {status: "ordered"}). Unlike receive_po_units, there is no over-receive ceiling or allow_overreceive flag — only a negative received_quantity delta that would take a line below 0 received is rejected.

Common workflows

How the tools compose into real tasks. Each step is a tool call; arguments come from the live schemas.

• Restock a low SKU. find_entity to resolve the SKU → search_inventory to check stock (low days_left, no incoming_units = reorder) → find_entity / list_entities for the supplier and location → create_purchase_order. The PO lands in draft — the supplier is not contacted automatically.
• Receive a delivery. search_purchase_orders with expand=["lines"] to get each line_id → receive_po_units. Quantities are deltas — send a negative quantity to reverse a mistaken receipt.
• Receive a transfer. get_entity on the transfer to get each line_id → receive_transfer_units.
• Audit and fix re-order status. search_inventory with a reorder_status = false filter to list everything currently excluded from re-order planning → update_sku_settings with patch: {reorder_status: true} to put the ones that should be replenished back. Preview with dry_run: true first — the write triggers a stock-health and forecast recompute.
• Tune restock thresholds in bulk. One update_sku_settings call with an array of per-SKU patches. If one patch is invalid (e.g. safety_stock_days > days_of_cover) the whole batch reports validation_failed and nothing is written — fix it and retry.
• Move stock between locations. list_entities for the two locations → search_inventory at sku_location grain to pick the SKUs and quantities → create_transfer (lands in draft) → update_transfer with patch: {status: "ordered"} to place it. get_entity on the tr_… id shows the lines and what has arrived.

Vocabulary

The same concept uses the same name across every tool:

Term	Meaning
current_stock	On-hand units. Can be negative after returns / voided orders — treat negatives as data, not errors.
days_left	How long current stock lasts at the current sales rate. Returned as {min, max} at sku/product grain, scalar at sku_location grain. Sort/filter use days_left_min / days_left_max.
safety_stock_days / days_of_cover	The coverage targets days_left is judged against. Written with update_sku_settings.
stock_health	Stock status today: NO_STOCK, BELOW_SAFETY_STOCK, OVER_SAFETY_STOCK, OVER_DAYS_OF_COVER. Filtering it at sku/product grain matches a row when any of its locations has that status, even though the row shows the worst status across locations — use granularity: "sku_location" to match a location’s exact status.
stock_health_projected	The risk over the forecast horizon: STOCKOUT_LIKELY, AT_RISK, NO_RISK, OVERSTOCK_RISK. Same grain caveat as stock_health: a sku/product-grain filter matches on any location, while the row shows the worst status.
incoming_units	Units on open purchase orders headed for the location.
ordered_units / received_units	Units on a purchase order or stock transfer line, and how many of them have arrived.
line_id	The handle for one line of an order. oprt_… on a purchase order, tprt_… on a stock transfer. Purchase-order tools also still accept the former name order_part_id until the next release.
is_late	Whether an order is overdue: its earliest expected delivery has passed and it is still expecting stock. On purchase orders and stock transfers alike.
confirmed_delivery_date	When a PO line’s units are due to arrive. Stored per line. create_purchase_order accepts one date and applies it to every line; update_purchase_order sets it per line.
unit_cost	The last purchase cost per unit — not a landed cost. bom_cost is the sum of component costs for bundles/assemblies.
reorder_status	Whether the SKU is included in re-order planning. Boolean at sku/sku_location grain, a {yes, no} SKU counter at product grain. Read with search_inventory / get_entity, write with update_sku_settings.

ID prefixes

Every id carries a type prefix, so the type is always visible at a glance:

Prefix	Entity
sku_…	SKU
prod_…	Product
sup_…	Supplier
loc_…	Location (the app’s Locations)
po_…	Purchase order
oprt_…	Purchase order line (the line_id write tools take)
tr_…	Stock transfer between locations
tprt_…	Transfer line (the line_id write tools take)
cat_…	Category
coll_…	Collection
audit_…	Change-history entry