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
Section titled “Read tools”find_entity
Section titled “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
Section titled “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
Section titled “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. A stk_… id returns a
stock take with its counted lines (see search_stock_takes).
search_inventory
Section titled “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”. At sku and sku_location
grain it also returns each SKU’s planning settings when you list them in
metrics: lead_time_days, moq, safety_stock_days, days_of_cover.
search_purchase_orders
Section titled “search_purchase_orders”List purchase orders with rich filters (status, supplier name or id,
creation-date window, tags, type), free-text search (e.g. a PO number) and
sort_by / sort_dir. 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.
search_transfers
Section titled “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_stock_takes
Section titled “search_stock_takes”List stock takes (counts of the stock at one location), with filters for
status, location, name and created / completed date windows. Statuses are
not_started, in_progress, completed and cancelled: ask for
in_progress to find counts that were started and never finished. Rows are
headers only: status, location, who created and completed it (when known),
created and completed dates, and the line and variance totals. Pass a stk_…
id to get_entity for the lines: each has the SKU, the counted quantity, the
expected_stock it was compared against, the variance, and a counted_at
that is null for a line nobody has counted yet. A take with more than 1000
lines returns the first 1000 and sets lines_truncated. Date filters are UTC.
Stock takes at locations outside your location permissions are never returned.
search_forecasts
Section titled “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
Section titled “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
Section titled “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. A stock take’s moves between not_started,
in_progress, completed and cancelled show up as updates to its status,
with who made them.
export_purchase_order
Section titled “export_purchase_order”Generate a downloadable PDF / XLSX export of a single PO and return a public URL.
Write tools
Section titled “Write tools”Write semantics
Section titled “Write semantics”All write tools (purchase-order, SKU-settings, forecast, transfer and stock-take) 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. Withdry_run=trueit 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 withdry_run=false.update_stock_take_statusis the exception to the default: it previews unless you passdry_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: falseand an unknownaffected_count, so read the record before sending it again. - Reversibility.
receive_po_unitsandreceive_transfer_unitsare reversible viareceived_quantity— quantities are deltas, so a negative quantity backs out a previous receipt.mark_as_receivedandis_closedare 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 adestructive:warning first. The same applies to reverting anorderedtransfer.update_forecast_planis not reversible — see its caution below. - Renamed parameters.
update_purchase_order,receive_po_unitsandexport_purchase_ordertakepurchase_order_id; the formerpo_idis deprecated and still accepted until the next release. Sending both is rejected.receive_unitsisreceive_po_units’s deprecated former name — the tool itself is unchanged, only the name; usereceive_po_unitsin 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
Section titled “create_purchase_order”Create a new purchase order from a supplier, a destination location, and a set
of lines (each a SKU + ordered_units).
update_purchase_order
Section titled “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.
receive_po_units
Section titled “receive_po_units”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.
update_sku_settings
Section titled “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. Read the current values back with get_entity on the SKU, or with
search_inventory listing the same field names in metrics; a write shows
there once the SKU’s planning data has refreshed. A lead_time_days or moq
of 0 is treated as unset: it is not applied, the row’s other fields still are,
and the response carries a warning for that row.
update_forecast_plan
Section titled “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.
create_transfer
Section titled “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.
update_transfer
Section titled “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.
receive_transfer_units
Section titled “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.
update_stock_take_status
Section titled “update_stock_take_status”Complete or cancel a stock take (status is completed or cancelled; get the
stock_take_id from search_stock_takes). Only a not_started or
in_progress stock take can be closed.
Unlike the other write tools, dry_run defaults to true: the first call
returns a preview and changes nothing. The preview shows the status change, the
number of lines, how many are still uncounted, and the variance currently shown. Call again
with dry_run=false to apply it. The preview confirms you can read the stock
take; applying can still be refused if your permissions do not allow closing it.
If Prediko does not confirm the change, the result is unresolved: read the
stock take with get_entity before sending it again. Cancelling closes the
stock take without changing any stock.
Feedback tool
Section titled “Feedback tool”send_feedback
Section titled “send_feedback”Tell Prediko about a gap in the MCP tools themselves: data or an action you
needed that is missing, a result that looked wrong, or a tool that was
confusing. Each call takes a category (missing_data, missing_action,
wrong_result, confusing or other) and a short message, and can name the
related_tool and the user’s goal. The Prediko team reads these to decide what
to build next.
Common workflows
Section titled “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_entityto resolve the SKU →search_inventoryto check stock (lowdays_left, noincoming_units= reorder) →find_entity/list_entitiesfor the supplier and location →create_purchase_order. The PO lands in draft — the supplier is not contacted automatically. - Receive a delivery.
search_purchase_orderswithexpand=["lines"]to get eachline_id→receive_po_units. Quantities are deltas — send a negative quantity to reverse a mistaken receipt. - Receive a transfer.
get_entityon the transfer to get eachline_id→receive_transfer_units. - Audit and fix re-order status.
search_inventorywith areorder_status = falsefilter to list everything currently excluded from re-order planning →update_sku_settingswithpatch: {reorder_status: true}to put the ones that should be replenished back. Preview withdry_run: truefirst — the write triggers a stock-health and forecast recompute. - Tune restock thresholds in bulk. One
update_sku_settingscall with an array of per-SKU patches. If one patch is invalid (e.g.safety_stock_days > days_of_cover) the whole batch reportsvalidation_failedand nothing is written — fix it and retry. - Move stock between locations.
list_entitiesfor the two locations →search_inventoryatsku_locationgrain to pick the SKUs and quantities →create_transfer(lands in draft) →update_transferwithpatch: {status: "ordered"}to place it.get_entityon thetr_…id shows the lines and what has arrived.
Vocabulary
Section titled “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, in days. 0 when never set. Read with search_inventory / get_entity, write with update_sku_settings. |
lead_time_days / moq |
The SKU’s lead time (days) and minimum order quantity (units). lead_time_days is the lead time planning uses: the SKU’s own, else its supplier’s default. moq is null or 0 when the SKU has none. Read with search_inventory / get_entity, write 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
Section titled “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 |
