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, warehouses, 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, warehouses, 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.

search_inventory

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

search_purchase_orders

List purchase orders with rich filters (status, supplier, date windows, tags, type). Pass expand=["lines"] to include line detail — that’s how you get the order_part_ids needed to edit or receive against a PO.

search_forecasts

Forecasted demand for the next 12 months, bucketed by month, grouped by SKU by default. Use it to read the demand plan; forecast writes are not exposed (see below).

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 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 four write tools — create_purchase_order, update_purchase_order, receive_units, update_sku_settings — 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).
• Reversibility. receive_units is reversible — quantities are deltas, so a negative quantity backs out a previous receipt. Reverting a placed PO to an earlier status is destructive (it resets received units) and surfaces a destructive: warning first.
• 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 warehouse, and a set of lines (each a SKU + quantity).

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 order_part_id (from search_purchase_orders with expand=["lines"]).

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_units

Record received quantities against PO lines when stock arrives.

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.

update_sku_settings

Batch-update SKU planning attributes: lead time, MOQ, lifecycle status (active / discontinued), and the coverage alert window.

Caution

The coverage window — min_days_on_hand / max_days_on_hand — is expressed in days of stock, not units. A patch where min > max is rejected as a contradictory alert config.

Not exposed

update_forecast_plan (demand-plan overrides) is not available in this version: there is no audited, reversible path for plan overrides yet. Use search_forecasts to read the plan.

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_of_stock, no incoming_units = reorder) → find_entity / list_entities for the supplier and warehouse → 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 order_part_id → receive_units. Quantities are deltas — send a negative quantity to reverse a mistaken receipt.
• Tune restock thresholds in bulk. One update_sku_settings call with an array of per-SKU patches. If one patch is invalid (e.g. min_days_on_hand > max_days_on_hand) the whole batch reports validation_failed and nothing is written — fix it and retry.

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_of_stock	Days of stock remaining at current sales velocity. Returned as {min, max} at sku/product grain, scalar at sku_warehouse grain. Sort/filter use days_of_stock_min / days_of_stock_max.
incoming_units	Units on open purchase orders headed for the warehouse.
unit_cost	Landed cost per unit. bom_cost is the sum of component costs for bundles/assemblies.

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
wh_…	Warehouse
po_…	Purchase order
cat_…	Category
coll_…	Collection