StockIQ MCP Tool Reference

Returns the bill of material around one item-site: its components (what it is made of), its parents (what consumes it), or both. Use for 'what goes into X', 'what is X used in', 'show me the BoM for X', 'which assemblies use this part', 'what do I need to build X'. This is the same data as the BoM and BoM Viz tabs of Inventory Snapshot. Each row is ONE link: ParentItemCode consumes QuantityPer of ComponentItemCode, plus the stock position of the item-site that row adds. depth IS explicit: levels=1 (the default) returns only the directly-attached links - do not answer a multi-level question from it. Pass levels=0 for the full explosion, or a specific number of levels. Transfer (HubSpoke) links are excluded by default because a quantity-per across a warehouse transfer is meaningless; pass includeTransferLinks=true to see them. This returns structure, not requirements: it does not multiply anything by a build quantity and does not say what to order. For the component requirement that planned builds generate use GetDependentDemand; for what to order use GetOrderSuggestions.

Returns items that are currently in excess or overstocked. Shows excess quantities, dollar values, days of excess, and inventory thresholds. Use when the user asks about excess inventory, overstocked items, or where they have too much stock relative to demand.

Returns dead stock items — inventory with no recent demand. Results can be filtered by site, supplier, buyer, and ABC class. Use sortBy to rank results (e.g., 'OnHandBalance' for highest value dead stock). Returns a grid showing item details, costs, on-hand quantities, and last sale dates.

Returns the time-phased dependent demand that planned and firm builds place on components — how much of a component is needed, on what date, and which parent assembly is driving it. Use for 'what components do I need to order for the assemblies I'm building', 'why does this component need ordering', 'what is driving demand on this part', 'what will building X consume and when'. role='Component' (default) anchors on a component and lists the parents that need it. role='Assembly' anchors on an assembly and lists what it drives onto its own components. This is StockIQ's actual plan, not a what-if: it reflects the builds already planned and firm, so it is the right answer to 'what do I need to order in preparation'. It is NOT a simulation of a build quantity you name. Pair it with GetBillOfMaterials for the structure behind these numbers, and with GetOrderSuggestions for what to actually order. negative quantities are components recovered by unbuilding an assembly - they are supply, not demand, and are excluded from the totals.

Performs root cause analysis on excess inventory for one or more items at a site. Runs 9 diagnostic checks: Large Min/Max, Canceled Demand, Buyer Over-Purchased, Lead Time Mismatch, Safety Stock Drop, Over-Forecasted, On-Hand Changes, Forecast Reduction, and Order Policy Mismatch. Each check returns a severity (Ok, Info, Warning, Error) and an explanation. Use when the user asks why an item is overstocked, what caused excess, or wants root cause analysis for overstock. Accepts itemSiteIds from grid results for batch analysis.

Returns holding cost per item-site, and the margin left after it. important: carrying cost AND holding cost ARE THE same figure IN StockIQ — a user who asks about carrying cost, cost of carry, cost to hold or inventory carrying charges is asking for this tool. There is no separate carrying-cost number anywhere in the product. Reports CurrentHoldingCost (what today's on-hand costs to hold), AverageHoldingCost, TargetHoldingCost (what the target stock level would cost) and the gap between current and target, alongside Revenue, Cogs, Margin, AdjustedCurrentMargin (margin NET of holding cost), Gmroi and the on-hand value. Use it for 'what is my carrying cost for SKU X', 'which SKUs cost the most to hold', 'where is carrying cost eating the margin', 'am I holding more than target', and — with usagePatterns — 'dead or slow items with a high carrying cost'. important — AdjustedCurrentMargin goes negative exactly when holding cost exceeds margin, so 'which items cost more to hold than they earn' is sortBy=AdjustedCurrentMargin, which ranks the most negative first. The summary states how many rows are negative. important — holding cost is NOT a flat percentage of value. It is value x the annual holding-cost rate x how long the stock is expected to sit, so a fast-moving item's holding cost is a small fraction of its value. When an item has NO usage StockIQ treats it as held forever and holding cost becomes the full on-hand value (capped at 5x). So a dead item's holding cost is its whole inventory value, not a carrying charge — say that rather than presenting it as a percentage-based cost. HoldingCostPercentOfOnHand shows which case a row is in; at or near 100% the item is not moving. These are the Stratification Detail / Class Analysis figures, refreshed by the nightly classing run, so they describe the position as of the last calculate rather than live. For the holding cost of a proposed order line rather than of stock on hand, use ExplainPlannedSupplyOrder. This tool does not project forward: it cannot say on what date carrying cost will overtake margin, only whether it already has.

Returns receipt-level inventory aging detail for a specific item-site, showing individual receipts/shipments, their dates, remaining quantities, and remaining dollar values. Use when the user wants to drill into a specific item's aging breakdown, asks 'why is this item aged', or wants to see receipt-by-receipt aging detail.

Returns an inventory aging report showing the dollar value of on-hand inventory distributed into age buckets (e.g. 0-30 days, 31-60 days). Use when asked about inventory age, aging analysis, how old inventory is, stale/slow-moving inventory value by age range, or aging buckets.

Returns historical daily snapshots for an item-site. Each record captures the item's on-hand quantity, order policy, safety stock levels, cost, ABC/XYZ class, and other planning parameters as of that date. Useful for root cause analysis, understanding how inventory levels and planning parameters changed over time, and investigating cost or policy changes. You can look up by item code + site code, a single ItemSiteId, or a list of ItemSiteIds.

Returns historical daily snapshots for an item-site-supplier relationship. Each record captures the supplier cost, lead times (calculated and active admin/manufacturing/shipping/putaway), safety stock lead time, order cycle, and suggested release quantities as of that date. Useful for understanding lead time changes over time, cost trends, and root cause analysis of supply issues. You can look up by item code + site code (+ optional supplier code), a single ItemSiteSupplierId, or a list of ItemSiteSupplierIds.

Returns projected lost sales grouped by a category dimension, showing top categories and top SKUs within each. Use when the user asks about lost sales by category, top product families/lines/groups at risk, or revenue impact of stockouts by grouping. First call GetCategoryMetadata to determine which categoryNumber (1-8) matches the user's term (e.g. 'Product Family' = ItemSiteCategory1 = categoryNumber 1).

Returns new item details — recently created items being monitored for initial demand traction. Use noSalesWithinDays to find items with no sales within N days (e.g., 30, 60, 90). Results include item age, first/last sale dates, customer counts, and inventory balances.

Returns items with order policy details and analysis. Use calculation AllOrderPolices (the enum's own spelling) to browse order policies by category, site, supplier, buyer, or ABC/XYZ class. Use WithOrderPolicyMismatch for ERP vs StockIQ mismatches, RecommendedForStock for items recommended for stock, RecommendedForDeStock for items recommended for de-stock. Also use this tool when the user asks about order policies by category — pass the appropriate itemSiteCategory filter with calculation AllOrderPolices.

Returns the order policy summary for a specific item-site. Shows the active order policy, ERP order policy, fixed quantities, min/max targets, kanban settings, safety stock, target stock, max stock, a human-readable settings description, and what StockIQ recommends. Use when the user asks about how an item is ordered, its replenishment policy, kanban settings, or whether StockIQ's recommendation differs from the active policy.

Returns items projected to be in excess. Shows SKUs whose on-hand + on-order position will exceed their excess threshold, with projected excess-start dates, excess quantity and dollar value, daily usage, and on-order info. Use when the user asks about overstock risk, write-down candidates, or de-expedite opportunities.

Returns the projected inventory position for one or more item-sites AT A future point IN time — by default the date an order placed today would actually arrive. USE this for 'what will my position be at lead time', 'do I need to order these', 'months of supply at lead time', 'projected on hand at <date>'. It resolves the lead time and the receiving bucket for you — do NOT ask the user for the lead time or the arrival date, and do NOT pull GetOrderScheduleDetail and hunt through its buckets for them. DO NOT USE this for 'how many days of supply will I have when this order arrives'. GetMetricDefinition explains either number if the user asks what they mean. By default it reports the lead-time position: the bucket StockIQ plans an order released now to arrive in. Pass asOfDate to report a specific date instead. Figures are read from a bucket, weekly unless you pass interval, and not from an exact date. Every row also carries the current position alongside, because 'now' versus 'when it lands' is the comparison that actually drives the order decision — never present the current figures as the lead-time ones. supply IS reported IN workdays, which is StockIQ's native unit. MonthsOfSupply is derived from it using the site's configured workdays per month, and both the divisor (AverageWorkdaysPerMonth) and the daily usage behind it are returned, so state the basis rather than converting yourself. Where an item has no meaningful demand the supply figures are null — say 'no demand', do not report an enormous number. ONE item across many sites: pass ONE itemCodes entry plus siteCodes to get one row per site. USE this for splitting or allocating a PO or shipment across warehouses, balancing stock age or cover between sites, and comparing one item's position site by site. Pass asOfDate = the order's arrival date to see each site's position when it lands. Do NOT call GetOrderScheduleDetail with several itemSiteSupplierIds for this: it returns their SUM, not a row per site. For the full time-phased schedule use GetOrderScheduleDetail; this tool deliberately returns one row per item-site instead.

Returns items projected to stock out. Shows SKUs at risk of running out of inventory, with projected stockout dates, on-hand quantities, daily usage, and on-order information. Use when the user asks about stockout risk, items running low, or inventory shortages. horizon — when the user scopes by time ('at risk in the next 4-6 weeks', 'going out of stock in the next month', 'by the end of the quarter') you must pass the horizon parameters. Without them the tool returns the top `limit` rows across every projected stockout date, which answers a different period than the one asked about, and the rows cannot be re-filtered afterwards. Use horizonDays for 'within the next N days'; add horizonStartDays for a window ('between 4 and 6 weeks out' is horizonStartDays=28, horizonDays=42). The window filters on the projected stockout date, and a row with no projected stockout date is excluded whenever a window is applied — the summary says how many that removed. Read the horizon assumption in the result and state that period, not the one requested, since an out-of-range input is corrected rather than obeyed.

Returns safety stock detail for one or more item-sites. Shows active and statistical safety stock levels, the chosen statistical method (Standard / Large Regular Pull / Sporadic / Retrospective), each method's value, usage source (Independent / Dependent / Both), target stock, reorder points, service levels, usage data, order policy, lead times, and any active alert status. When called with a single itemSiteId, the result additionally carries an `Explanation` block with StockIQ-grounded driver factors (model error rate used as the variability factor, lead-time choice, TOQ, lead-time cap, capacity constraint) and — when the chosen method is Large Regular Pull — LRP-specific summary stats. Use this enriched single-item form to explain how a safety stock value was calculated. Use when the user asks about safety stock settings, safety stock levels, target service levels, why safety stock is high/low, or safety stock alerts. Supports lookup by: a single itemSiteId, a hierarchyNodeId (covering multiple items), a siteCode (all items at a site), or filter parameters (siteIds, supplier, buyer, ABC/XYZ class, category, etc.).

Returns slow-moving inventory items. Shows SKUs with low or stagnant sales/usage relative to their on-hand position, with last-used/last-sold dates and the dollar value sitting in slow-moving stock. Use when the user asks about slow movers, stagnant inventory, items that aren't selling, or dead-stock risk before items become officially dead.

Ranks item-sites by the stockouts they suffered over a past window — how many times each ran out, how many days it was out, and the sales that were lost while it was out. Use for "which top 10 SKUs had the most stockouts in the last 90 days", "what did our stockouts cost us last quarter", "which items keep running out", and any question about stockout history, repeat offenders or past service failures. important — this is the tool for stockouts in the past. GetStockOuts returns only items that are out right NOW, so an item that stocked out five times last quarter and is in stock today does not appear there at all. important — the question "most stockouts" is ambiguous and the ranking must match what the user meant: EpisodeCount is how often it ran out (a flapper), TotalDaysOut is how long it was out in total (a sustained outage), LostRevenue is what it cost. A cheap item that flapped nine times and an A-item dead for 60 days are different answers; pass the sortBy that matches the question. Set detail=true to list the individual outages instead of the per-item-site ranking — one row per episode with its start date, end date and the sales lost during it, the same view as the Item-Site Stock Out History screen. Use that for "when exactly did this run out", "show me each outage", or as the drill-down after a ranked answer; pair it with itemIds or siteIds, because unfiltered it returns every outage in the window. Lost sales are measured, not estimated. An empty lost-revenue column means no lost-sales data exists for that item-site — it does NOT mean the stockout was free.

Performs root cause analysis on a stock out for one or more items at a site. Runs 8 diagnostic checks: Underforecasted, Unusual Sale, Late Supply Order, Missed Supply Order, Supply Order Date Change, Supply Order Quantity Change, Low Service Level, and Non-Stock Item. Each check returns a severity (Ok, Info, Warning, Error) and an explanation. Use when the user asks why an item ran out of stock, what caused a stockout, or wants root cause analysis. Accepts itemSiteIds from grid results for batch analysis.

Returns item-sites that are currently out of stock. Shows stock-out details including how long they've been out, projected in-stock dates, next supply info, and lost revenue. Use when the user asks about current stock outs, what's out of stock, or when items will be back in stock. each ROW IS AN item-site (one item at one site), so one item out at five sites is five rows. The result reports both counts; when you state how many are out, say item-sites, or quote the distinct item count, never call the item-site count 'items'. lifecycle: itemStatuses is StockIQ's own Active/Discontinued status. Many customers track their lifecycle (Active, Retired, Disabled, Bridge ...) in an item-site category instead; when the user says 'exclude retired' or 'only active', find which category holds those values with ResolveItemSiteCategory and pass the ids of the values to keep as that category's itemSiteCategoryNIds.

Finds inventory transfer opportunities between warehouses: which item can move from which site (that holds excess) to which other site (that needs it), how much, and what it is worth. Use for inventory balancing, 'can we transfer instead of buying', 'what can we ship out of this warehouse', 'why is this DC pulling so much from the hub', and rebalancing overstock across locations. Returns one row per source-site to destination-site pair, so the same answer reads from either end.

Adjusts the forecasts of many nodes under a group node at once - Forecast Manager's Edit Child Forecasts: name the group (hierarchyNodeId), the level below it to edit at (hierarchyLevel, from GetHierarchyLayout; defaults to the bottom level), and optionally which nodes at that level (dimensionValue matches a name or code such as a customer or category, or hierarchyNodeIds lists them from FindHierarchyNodes). each selected child is saved individually and gets its OWN forecast settings override. Use this for cross-cutting changes: 'raise Walmart by 10% across Headphones', 'lift every customer under Lifts & Transfer 5%'. When the number is FOR the node the user named - 'set Headphones to 300 a month' - use SaveForecast instead, which changes the group once and cascades top-down. Arithmetic, and say this in every preview: Percent applies to each child; UnitDelta, SetValue and PeriodValues are totals across the selected children, split between them by fair share (300 means 300 in total, not 300 each). Two-step confirmation: call with userConfirmed=false first - nothing is written; you get the group's trend chart with the change applied, the children selected, the arithmetic in words, and what happens to each child's settings in this instance's manual mode. Show ALL of it and stop. Call again with userConfirmed=true and the same arguments only after the user approves.

Compares forecast accuracy across multiple forecast series at a hierarchy node. Returns current-period (no-lag) error and lead-time-ago lag error for every series available at the node, plus the synthetic Statistical and Naive/Benchmark baselines. Use this when the user asks to compare series (e.g. 'compare Operational vs Sales forecast accuracy'). For a deep single-series breakdown use GetForecastErrors instead. Resolve the hierarchyNodeId first via ResolveHierarchyNodes. Supports per-lag focus (lag=0 = current period; lag=N = N periods ago), a useLeadTimeLag convenience flag, a seriesNames filter (case-insensitive series-name match; reserved tokens 'Statistical'/'Stat' and 'Naive'/'Benchmark'), and recentSnapshotCount for trend analysis over recent lagging snapshots.

Returns the forecast for one or more hierarchy nodes as the Forecast Manager trend chart (actuals and forecast over time), which renders as an interactive chart in the UI. By default it also returns the effective forecast / seasonality / algorithm / lost-sales / current-period-projection settings driving it, current-period info (including whether the current period is partial), and the hierarchy level path — use those to explain why a forecast looks the way it does. Set includeExplanation=false when the user only wants to see the forecast or its trend. Accepts the same arguments the Forecast Manager screen sends to /api/TrendChartDetail/FetchByHierarchyNodeIds.

Returns sales actuals aggregated at a specific hierarchy level (e.g., level 2 = Product Group). Requires itemHierarchyId and hierarchyLevel number. Four shapes, chosen with groupBy. groupBy="node" returns ONE ROW PER node, summed across every period in the window. Use this for any 'margin by product group', 'top N product lines' or 'which groups are down' question — otherwise the top rows are the highest single periods, not the highest nodes, and the same node appears once per period. groupBy="site" returns one row per site, and groupBy="node+site" the cross-tab: one row per node per site. Use node+site for 'by branch' / 'by warehouse' questions — 'which product groups are down, and at which branch'. The site is a dimension of the rows here, not a level of the hierarchy, so do not look for a deeper hierarchyLevel to get it; in many hierarchies the site sits below the item and no level is the cross-tab. Omitting groupBy (the default) returns one row per node per period, for trend and period-by-period questions. SummaryText carries accurate totals across all rows even when the grid is truncated, and states the period the result actually covers. That covered period can be wider than the dates requested, because actuals are stored in whole periods and the date filter selects whole periods rather than clipping them — describe the result using the covered dates it reports, never the dates you asked for.

Returns sales actuals for specific hierarchy node IDs. Use when the user has already identified specific product groups or categories by their node IDs. Also requires itemHierarchyId and hierarchyLevel. SummaryText includes accurate totals across all rows.

Returns sales actuals by customer. Two shapes, chosen with groupBy. groupBy="customer" returns ONE ROW PER customer, summed across every period in the window. Use this for any 'top N customers' or 'largest buyer' question — otherwise the top rows are the highest single months, not the highest customers, and the same customer appears several times. Omitting groupBy (the default) returns one row per customer per period, for trend and period-by-period questions. To answer 'which customers are down for this product line', resolve the group by name with FindHierarchyNodes and pass its id as hierarchyNodeIds - the node expands to its item-sites server-side, so do not ask for the item list first. SummaryText carries accurate totals across all rows even when the grid is truncated, and states the period the result actually covers. That covered period can be wider than the dates requested, because actuals are stored in whole periods and the date filter selects whole periods rather than clipping them — describe the result using the covered dates it reports, never the dates you asked for. A shorter interval snaps the window more closely. For 'which customers are down the most since last year', pass comparisonPeriod="priorYear" with rankDirection=Ascending. The tool queries both windows and returns the change already computed and ranked — never call it twice and subtract in your answer.

Returns sales actuals by customer ship-to location. Two shapes, chosen with groupBy. groupBy="shipTo" returns ONE ROW PER ship-TO, summed across every period in the window. Use this for any 'which locations buy the most' or 'top N ship-tos' question — otherwise the top rows are the highest single periods, not the highest locations, and the same ship-to appears several times. Omitting groupBy (the default) returns one row per ship-to per period, for trend questions. SummaryText carries accurate totals across all rows even when the grid is truncated, and states the period the result actually covers. That covered period can be wider than the dates requested, because actuals are stored in whole periods and the date filter selects whole periods rather than clipping them — describe the result using the covered dates it reports, never the dates you asked for.

Returns forecast error metrics for a hierarchy node. Shows backward-looking error, lead-time-ago vs current error, and lag period (out-of-sample) error. Compares the operational forecast against naive and statistical benchmarks. Also returns hierarchy-level context, a glossary of StockIQ-specific error terms, and recent snapshot history so the model can comment on whether accuracy is improving or degrading. Use this to answer 'is my forecast good or bad?' for a specific item/site or aggregate level. Resolve the hierarchyNodeId first using ResolveHierarchyNodes.

Ranks hierarchy nodes by forecast error or bias in ONE call - the children of one grouping, or a whole level. Use this for 'rank the buy categories under lowes US by bias %', 'which items under this forecast group have the worst forecast error', 'top 10 items with over 60% error'. never call GetForecastErrors node by node and rank the results yourself, and never ask the user for item codes to discover the nodes. Resolve the grouping with FindHierarchyNodes and pass it as parentNodeId; with hierarchyLevel omitted the direct children are ranked, and passing a deeper hierarchyLevel ranks every node at that level anywhere beneath the parent (e.g. all items under a forecast group, across all its buy categories). measure picks which error: Current (the configured error sample, default), LeadTimeAgo (the forecast as of the lead-time-ago snapshot, measured against the actuals now known), or LagPeriod (out-of-sample periods only). This is error and bias, not variance to forecast - for 'beating forecast this month' use GetForecastVarianceByLevel. For a custom date range ('change the timeframe to Feb-Aug 2026') pass startDate and endDate: each closed period in the range is then measured against the forecast as it stood when that period opened, which is the honest comparison for past periods. Without dates the numbers cover the configured window. Either way SummaryText states exactly which periods were measured - quote it when you answer.

Returns the forecasting configuration for this StockIQ instance: demand series (historical data sources), demand forecast series (forecast outputs), which series is the operational/primary, and key date settings. Use this to understand what forecast series exist and how they are configured. This is instance-wide series configuration only. For the forecast settings that apply to a specific item, site or hierarchy node - Auto/Manual control, the auto-forecast resume date, the Algorithm Start Date, freeze periods, locked periods - use GetForecastSettings, which also returns the instance defaults when no node is named.

Returns period-by-period forecast quantities for specific snapshot(s). Use after GetForecastSnapshots to drill into period data. Filter by snapshotName (e.g. 'Current - Operational') or snapshotDate (finds closest match). For comparing two snapshots, call this tool twice with different filters and compare the quantities by PeriodDate.

Returns historical forecast snapshots for a hierarchy node, showing how the forecast has evolved over time. Each snapshot captures what the forecast looked like at a point in time, along with accuracy metrics (backward error, vs-current error, lag-period MAE). The most recent entry is the current live forecast (named 'Current - {SeriesName}'). Use GetForecastSnapshotPeriods to compare period-level quantities between snapshots.

Ranks hierarchy nodes by how they compare to forecast, in ONE call. Use this for any 'which of these are above/below/beating forecast', 'what is off forecast', or 'fastest forecast growth' question - never fetch forecasts node by node and rank them yourself. metric=VarianceToForecast compares actuals to the forecast for the same periods (default; use for 'above or below forecast for July', 'beating their forecast this month'). metric=ForecastGrowth compares the last N periods of actuals to the next N periods of forecast (use for 'fastest forecasted growth over the last 6 months'); it is the Forecast Growth screen's Forecast Growth %. Scope it with parentNodeId to rank the children of one grouping, or with hierarchyLevel to rank a whole level. Resolve parentNodeId with FindHierarchyNodes first - do not guess a node id. thresholdPercent filters to nodes at least that far from forecast (pass 15 for 15%), and direction picks the side. Read the SummaryText before answering: it states the exact periods used and whether the current, in-progress period was projected or left out.

Returns sales actuals by item-site. Two shapes, chosen with groupBy. groupBy="itemSite" returns ONE ROW PER item-site, summed across every period in the window. Use this for any 'top N items' or 'best selling items' question — otherwise the top rows are the highest single periods, not the highest items, and the same item appears several times. Omitting groupBy (the default) returns one row per item-site per period, for 'how much did we sell last month' and trend questions. To answer 'the products in that product line at that branch', resolve the group by name with FindHierarchyNodes and pass its id as hierarchyNodeIds together with siteIds - the node expands to its item-sites server-side, so do not ask for the item list first. For 'which items are down the most since last year', pass comparisonPeriod="priorYear" (or explicit comparison dates) with rankDirection=Ascending. The tool queries both windows, subtracts and ranks the change itself — never call it twice and do that arithmetic in your answer. SummaryText carries accurate totals across all rows even when the grid is truncated, and states the period the result actually covers. That covered period can be wider than the dates requested, because actuals are stored in whole periods and the date filter selects whole periods rather than clipping them — describe the result using the covered dates it reports, never the dates you asked for.

Imports the forecast file the user attached to this conversation into StockIQ's demand forecast. Call DescribeAttachment first to see the file's headers. The file is read by its column headers, in either layout: horizontal (one row per item, one column per period, each period column headed by its start date such as '2026-01-01' or 'Jan-26') or vertical (one row per period with Period Date and Value columns). Columns headed 'Item Code', 'Site Code', 'Item', 'SKU', 'Site', 'Warehouse', 'Customer', 'Ship To', 'Series', 'Category1', 'Date', 'Qty' and the like bind with no mapping; map only headers that differ. You supply the column mapping and any settings the user stated; never retype the file's rows. Settings the user does not state come from the persisted Forecast Import Settings, and the interval and unit of measure are inferred from the file. The preview lists every effective setting with its source. Confirmation flow: (a) call with userConfirmed=false first - nothing is written; you get the file as read, the settings, how many nodes would be touched and what exists on them today, and a 'This import will...' list of consequences. Show ALL of that to the user and stop. (b) call again with userConfirmed=true and the same arguments only after they approve. If the result is NeedsClarification, nothing was imported: pass the message on and ask. Series: the file's own series column wins per row; forecastSeriesCode fills rows without one; otherwise the operational series is assumed and the preview says so - relay that assumption. Level: hierarchyLevel names the HierarchyProperty the rows describe (Site for item-site rows, Customer, ItemSiteCategory1...); when omitted the persisted default (usually the bottom level) is used and validated against the file's columns.

Saves forecast quantities for ONE node of the forecast hierarchy - an item at a site, or a group node such as a product line - the way Forecast Manager's Save Forecast does: the change is applied AT that node, the node takes control of its own forecast settings, and StockIQ cascades the new values top-down to the node's children by fair share (a child with its own settings override keeps its forecast unless removeChildSettings=true). Use this when the number the user gives is FOR the node they named: 'raise 0305001 at site 95 by 10% for the next 3 months', 'set Headphones to 300 a month through June', '100 in December'. Do NOT use it when the change is to be applied to each of many nodes under a group, or the user names a cross-cutting dimension ('raise Walmart by 10% across Headphones') - that is AdjustChildForecasts. Adjustment: adjustmentType Percent, UnitDelta or SetValue with quantity, over an optional startDate..endDate (default: the first period a save may change through the forecast horizon); or PeriodValues with periodValues for named periods. Values are units. Two-step confirmation: call with userConfirmed=false first - nothing is written; you get a grid of period, current, proposed and change plus a 'This save will' list naming the node and level, the series (the operational series is assumed when none is named - relay that), the instance's manual mode and what the save does to the node's settings (resume date or locked periods, an override created), the children cascaded to and their overrides, depletion, and any periods refused as history or inside the freeze fence. Show ALL of it to the user and stop. Call again with userConfirmed=true and the same arguments only after they approve. A confirmed save returns the node's trend chart with the new values.

Works out what componentry a set of builds needs, which components are short, and which components are contended between the builds. This is the Allocation Wizard's calculation from Place Orders, run read-only - it allocates nothing and changes no order. Use for 'what do I need to build 500 of X', 'can I build these, and what is stopping me', 'which components do these assemblies compete for', 'what is short if I build all of these'. Pass ALL the assemblies you care about in one call: a component's requirement is summed over the parents present in the same analysis, so asking one assembly at a time makes contention between assemblies invisible. The quantity is always the caller's own number - this tool does not invent one from the suggested order quantity or from stock. If the user has not named a quantity, ask for one. For the structure alone use GetBillOfMaterials; for the requirement the existing plan already generates use GetDependentDemand; for what to order use GetOrderSuggestions.

Returns ONE grid of expedite recommendations across every current and projected stockout in scope - the open PO lines to pull in, line by line. Use this for 'expedite plan for all stockouts', 'what POs should I expedite for supplier X', 'which orders do I pull in for the items stocking out this month'. Do NOT loop GetExpediteRecommendations or GetOnOrder item by item - this tool runs the same engine for every item-site in one call. Scope like GetProjectedStockOuts: resolve a supplier with ResolveSupplier and pass primarySupplierIds; sites, buyers, ABC classes and item-site categories narrow it further; horizonDays limits it to items stocking out within N days. Each row is one PO line (Order #, Line), with the quantity to expedite, its current ship and receipt dates, the date the stock is needed BY, and the latest date the supplier can ship it by standard freight and still make it ('Ship By'). The 'Expedited Receipt (Air)' column is expedited shipping from the line's current ship date, not a production pull-in - say so if you quote it. Item-sites with nothing on order that can be pulled in appear as rows with action NoOpenPO or NothingToExpedite: those need a NEW order, not an expedite. NoShortfallComputed means the item is projected to run out with stock on order, but the engine sized no units short - say that plainly rather than calling it covered. A note saying the ship-by date has passed means standard freight can no longer make the need date. The result is one grid, so EmailCurrentUser attaches all of it.

Ranks buyers by whether they ordered what StockIQ asked them to, when it asked. Use for "is my buyer ordering according to what StockIQ is asking them to", "which buyers are editing lines", "what percent of lines are edited", and "look at mismatches or late order placements". Two independent measures, and they answer different questions. timeliness asks whether an order appeared when StockIQ started asking for one: a suggestion episode is a run of days where StockIQ wanted a release, and it counts as on time when an order for that item and supplier was placed within the grace window of the first day of the episode, late when it arrived after that, and unordered when none arrived at all. editing asks what the buyer did to the quantity once they were in the order: how many lines they changed, and whether they went up (buying more than the plan) or down. important — an episode is dated from the day StockIQ actually started asking, even when that is before the window. Days late is therefore not capped by the window length: a 140-day lateness on a 90-day window is a correct answer about an episode that was already running, not an error, and the assumptions say how many verdicts are anchored that way. Where history does not reach far enough back to date the first ask, those episodes are reported as episodesStartUnknown and are left out of every rate — describe them as unmeasurable, never as compliant. important — a null rate is not a zero. A buyer StockIQ never asked to order anything has no on-time rate, and reporting 0% would accuse them of ignoring instructions that were never given. Say "not applicable" for a null, never "0%". important — attribution is by the buyer who owns the SKU (ItemSite.BuyerId), not the user who keyed the order. The Buyer Scorecard screen's order-dollar column attributes to the placing user instead, so the two can legitimately disagree where somebody orders outside their own buyer's items. The timeliness half counts an order placed directly in the ERP as a valid response, because the buyer did in fact respond; the editing half covers only StockIQ-placed lines, because an ERP line never carried a StockIQ suggestion to edit. important — the inventory columns (SKUs, Inventory, vs Target, Stocked Out) are a different kind of number from the rest. They are a position on ONE date — the latest inventory capture on or before the end of the window, reported as inventoryAsOf in the assumptions — not a total accumulated across the window. Describe them as "as of" that date. Everything else on the row is behaviour measured across the whole window.

Returns de-expedite recommendations for open supply orders when inventory is in excess. Recommends actions like Delay, Cancel, or Reduce on incoming orders to reduce overstock. Use when the user asks about de-expediting orders, delaying shipments, canceling orders due to excess, or how to reduce overstock.

Returns expedite recommendations for open supply orders. Analyzes projected inventory and recommends which orders to expedite or redirect to avoid stockouts. Use when the user asks about expediting orders, rushing shipments, or how to prevent a stockout. supplier scope: with no supplierCode this covers every active supplier's open orders for the item-site — wider than the single-relationship tools, because an incoming order is worth expediting whichever supplier it comes from. Name a supplier to narrow it to one relationship.

Returns the time-phased order schedule detail for ONE item-site-supplier — projected inventory, demand, and suggested orders bucketed by week (or day/month), rendered as an interactive grid. This is the drill-IN view for a single row; it mirrors the StockIQ UI pattern where the Order Schedule screen shows a header list (one row per item-site-supplier) and clicking a row opens the detail. Use this only when the user has named or selected a specific item AND site (or single itemSiteSupplierId). Examples: 'show the order schedule for item 0305001 at site DC1', 'drill into acme's order schedule for X1234'. DO NOT use this tool to list or browse the order schedule — for any 'show me the order schedule for supplier X', 'order schedule for item Y' (no site named), 'all out-of-stock items on the schedule', or 'order schedule rows matching <filter>' use GetOrderScheduleHeader. Calling this tool repeatedly to build a list will exhaust the per-turn tool budget. Easiest call shape: pass itemCode + siteCode (the server picks the primary supplier automatically). Pass supplierCode only if the user named a specific non-primary supplier. If you already have itemSiteSupplierIds (e.g., from ResolveItemSiteSupplier or a prior GetOrderScheduleHeader row), pass those instead and skip the codes — do NOT call this tool twice with different argument shapes. several itemSiteSupplierIds are aggregated into ONE combined schedule, the same as selecting several rows on the Order Schedule screen: every bucket is the SUM across them, not any one of them. Pass several only when the user wants that combined view; never use it to compare sites. date window: the result covers fromDate to toDate. Omit both for the default: 90 days of history through the later of 180 days out or the lead time plus 90 days, which always includes the bucket an order released today would arrive in. Pass them when the user names a period. The window only drops buckets; every bucket shown carries the same figures as the screen. interval default: leave interval at the default (Weekly) unless the user explicitly asks for Daily or Monthly buckets. There is no system-default interval setting; Weekly is what every order-schedule screen in StockIQ starts on. grid layout: when the user explicitly asks for 'horizontal' or 'vertical' layout (e.g. 'show this in horizontal layout', 'switch to vertical'), pass gridLayout Horizontal or Vertical. When the user has not said anything about layout, omit this parameter (leave it null) so the user's saved layout preference is honored. After rendering, briefly offer the user the option to switch the bucket interval (daily / weekly / monthly) and the grid layout (vertical / horizontal) — these are surfaced as follow-up suggestions in the result.

Returns a list of order schedule headers — one row per item-site-supplier — showing inventory position, on-hand, on-order quantity, safety stock, max stock, and projected stockout dates. This is the list/browse entry point for the order schedule (the same grid the user sees on the main Order Schedule screen). Use this whenever the user wants to see order schedule rows for a SET of item-site-suppliers — e.g. 'show the order schedule for item 0305001', 'order schedule for supplier acme', 'all out-of-stock items on the order schedule', 'order schedule for site DC1'. Filters: itemCode (single item across all sites/suppliers), supplierCode, siteCode, buyerName, ABC/XYZ class, inventory position. DO NOT call GetOrderScheduleDetail repeatedly to build a list — use this single call. GetOrderScheduleDetail is only for drilling into the time-phased schedule of ONE item-site-supplier the user has named or selected. If you need PO-level detail (purchase order numbers, due dates) for an item, use GetOnOrder instead. important: Always pass at least one filter (item, supplier, site, buyer, ABC/XYZ class, or inventory position) to avoid returning too many rows.

Returns supplier-level purchase order suggestions showing which suppliers need orders and for how much. Use this to answer questions like 'what do I need to order today?', 'what do I need to order this week?', or 'what do I need to order from supplier X?'. Returns a grid of suppliers with item counts, suggested order costs, minimum percentages, and projected stock-out counts. scope — this tool is supplier-anchored and returns every supplier in the user's permitted view unless you narrow it; an unscoped call on a real catalogue can exceed the whole per-turn budget on its own. If the question names particular items ('what should I order for item X?'), pass `itemCodes` or `itemIds` — that is the item-anchored route into this tool, and it narrows both this grid and the downstream GetSuggestedOrderLines drilldown. There is no singular `itemCode` parameter here and an undeclared argument is refused, so pass the list form. If the question names an item-site category value instead — a buy category, product line, price group or similar ('plan an order for the lifx buy category') — pass it in the matching `itemSiteCategoryNIds` parameter: call GetCategoryMetadata to learn which category number (1-8) the user's term is, then ResolveItemSiteCategory to turn the value into its Id. Never guess the Id. The category scopes the whole chain: the SupplierIssContext this returns holds only that category's item-sites, so GetSuggestedOrderLines and PlaceOrder stay inside it without being told again. A category order can span many suppliers — leave the supplier filter off unless the user named one. For one item at one site — 'should I order this, why this quantity, why is it not suggested' — ExplainPlannedSupplyOrder is the better route: it re-runs the engine for that single item-site-supplier and explains the decision rather than summarizing suppliers. The result also includes IssIdsToOrder per supplier — preserve these in context for any follow-up place-orders request. narrowing THE plan: when you have agreed with the user on a subset of suppliers (for example, budget allocation across selected vendors), re-call this tool with `supplierCodes` (or `supplierIds`) containing only that subset before any confirmation or placement step, so the rendered grid matches the prose the user just approved. The downstream GetSuggestedOrderLines and PlaceOrder tools accept supplierContexts but consumers see the Step 1 grid alongside narration — show the same scope you described.

Returns a sawtooth chart showing projected inventory over time for an item-site-supplier. Displays stacked demand, supply, forecast bars and projected inventory line with safety stock and max stock thresholds. Use when the user asks to see the sawtooth, inventory projection chart, or supply/demand visualization.

Returns the detailed list of supply order lines (items, sites, suppliers, quantities, costs, dates) that StockIQ recommends ordering — the same lines a user would see on Place Orders Step 2 after picking suppliers in Step 1. Use this after GetOrderSuggestions when the user asks 'show me the items/products/lines to order from supplier X', 'what would I order from acme', or any drill-down request from a supplier summary row. Pass the SupplierIssContext entries you received from GetOrderSuggestions verbatim — the IssIdsToOrder and MatchedIssIds values are required to populate the supplier selections the server-side matcher reads. Also pass the same coverage settings (daysOfCoverage / coverageDateStr / coverageMode / extendToNextScheduleDate / orderLineFilterOption) you used in the upstream call; mismatched coverage triggers a re-match and may return different rows. item anchor: to answer 'what should I order for item X', pass `itemCodes` (or `itemIds`) here AND on the upstream GetOrderSuggestions call. Upstream it narrows which suppliers are considered; here it narrows the returned lines. The item filter is applied to the finished lines only — it does not alter the supplier selections or the coverage inputs the matcher reads, so it cannot change which lines the engine produced. category: there is no category parameter here. To order by an item-site category (a buy category, product line, price group...), pass `itemSiteCategoryNIds` to GetOrderSuggestions and use the SupplierIssContext it returns — those contexts already hold only that category's item-sites, so the lines here are scoped to it. dimension note: each returned line is one item-site-supplier row. GetOrderSuggestions' 'NumberOfItemsToOrder' counts distinct items per supplier — so this tool's line count can exceed that when the same item ships from multiple sites under the same supplier. When the user asks 'why did N lines come back when supplier X had M items?', explain it's items × sites at that supplier, not a discrepancy.

Projects what we OWE suppliers over a forward window, bucketed by month (or another interval), per supplier, in money AND in units. Use for "how much do we need to pay our suppliers over the next few months", "what is the monthly projection", "how many units are we ordering per supplier", and supplier cash-flow or payment planning. important — firm and planned are reported as separate columns and must stay separate when you describe them. Firm is money committed on purchase orders that already exist. Planned is money StockIQ intends to spend on orders nobody has placed yet, so it can still be changed, deferred or cancelled. Quoting only the combined total tells a customer they are committed to spending money they are not committed to. Lead with firm, then say what planned adds. important — dates are payment DUE dates, not order or receipt dates. Each order's payment terms shift its cost from the expected receipt of the goods to the day the cash actually leaves, and milestone terms split one order across several due dates. So a month's figure is what falls due for payment that month, which is NOT the same as what arrives that month. important — units are apportioned across a payment schedule by each installment's share, so a 100-unit line paid 10/40/50 contributes 10, 40 and 50 units to those three months. Totals across the whole window are exact; a single month can therefore show a fractional unit count when terms are milestone-based. Describe units as "units being paid for", not as a delivery schedule. important — the discount column is money available if we paid early, not money already saved. StockIQ projects the full amount at the net due date and never assumes the discount is taken. This is a projection as of the last full calculate, not a live query — the assumptions say so. It has no forecast component: StockIQ forecasts demand, not future purchasing, so beyond the planned orders it already suggests there is nothing further to project.

Returns suppliers whose suggested order cost is at or above a percentage of their order minimum or free-freight minimum. Use this to answer questions like 'which suppliers am I close to hitting minimums on?', 'where am I close to free freight?', or 'which suppliers should I top off?'. Results are sorted by PercentOfOrderMinimum descending so the most critical suppliers appear first.

Places a purchase order from the order file the user attached to this conversation. Call DescribeAttachment first to see the file's headers - you cannot map columns you have not looked at. You supply only a column mapping; never retype the file's rows. The file itself is read server-side by the same parser the Upload Order screen uses. Columns whose headers already match a field name (with or without spaces) - 'Item Code', 'Site', 'Order Qty', 'Release Quantity', 'Supplier Code' - need no mapping entry at all; map only the ones that differ. ItemCode, SiteCode and ReleaseQuantity are required; the import fails if the file has no column for one of them. Confirmation flow: (a) Call with userConfirmed=false first. The tool reads and converts the file without writing anything and returns a preview: the file name, the mapping used, any supplier it had to assume, per-row errors, and the line totals. Show that to the user and stop - wait for their explicit approval. (b) Call again with userConfirmed=true, and the same arguments, only after they have approved. Supplier: if the file has a supplier column, that wins per line. Otherwise pass the supplier the user named in supplierCodeOrName; if they named none, the tool assumes each item-site's primary supplier and tells you what it assumed and what else was available - relay that to the user in your confirmation. If the result is NeedsClarification, the file was NOT imported: pass the message on and ask.

Packs the order's current quantities into shipping containers and reports how many containers are needed, how full each one is, and what is in each. This is StockIQ's Load Containers wizard, the same one on the Place Orders screen. nothing IS saved. To place the packed order, pass the ContainerLoadingSpec from this result into PlaceOrder's `containerLoading` argument, verbatim. It does NOT change the total quantity of anything - it decides which container each line rides in, splitting a line across containers where it has to. To change quantities so they fill a container, use TargetOrder with targetType="Containers" first, then pack the result with this tool. required inputs are the supplierContexts from GetOrderSuggestions plus the same coverage parameters you used for GetSuggestedOrderLines - pass them verbatim, because the lines are rebuilt server-side from them. ⭐ Use action="Recalculate" to answer "how full are my containers?" without moving anything - it reports the current position and rearranges nothing. Lines are grouped into containers by destination site and ship-window date, always - items for the same site share a container, items for different sites never do. That is not configurable. The result leads with Assumptions: one line per loading option, saying whether the user chose it or a default was applied. Show those alongside the container summary. If a required choice is missing, or the items lack the weights and measures loading needs, the tool returns NeedsClarification explaining what is missing rather than loading nothing silently.

Places the supply orders the user has confirmed via the Edison Place-Orders flow. required inputs are the supplierContexts you received from GetOrderSuggestions and the same coverage parameters you used for GetSuggestedOrderLines — pass them verbatim. The tool re-builds the order lines server-side from those contexts so that all entity IDs and line state are guaranteed fresh and correct. To exclude a line, drop its ItemSiteSupplierId from the matching SupplierIssContext.IssIdsToOrder list. To place an order for one item-site category (a buy category, product line...), scope GetOrderSuggestions with `itemSiteCategoryNIds` and pass the contexts it returns — they hold only that category's item-sites. There is no category parameter here. Confirmation flow: (a) Call with userConfirmed=true directly when the user has already reviewed the suggested order lines via GetSuggestedOrderLines and has explicitly approved placement (e.g. they said 'yes, place this order' / 'go ahead and order these'). (b) Call with userConfirmed=false only when you have not yet shown the user the specific lines that will be placed — the tool will return a fresh structured preview for the user to approve. Per the system prompt's two-step rule, after returning a preview you must stop and wait for explicit approval before re-calling with userConfirmed=true. If validation flags errors, the tool blocks unless you also pass proceedDespiteWarnings=true on the confirm call. Order status defaults to the system DefaultOrderStatus from GlobalOrderNumberingSettings; pass orderStatus="Review" to route the order to manual review instead. Quantities: the preview lists every line it will place in Lines, each with its ItemSiteSupplierId, the ReleaseQuantity that will be written and the SuggestedReleaseQuantity StockIQ arrived at. Quote those numbers to the user rather than computing your own. If the user agrees quantities that differ from StockIQ's suggestion, you must send them back in lineQuantities on the confirm call — describing adjusted quantities and then omitting lineQuantities places the engine's figures instead, which is not what the user approved. The tool refuses the whole call rather than placing a partly-adjusted order. On success the result lists each created order's StockIqOrderNumber and ErpOrderNumber, the per-line quantities actually written in Lines, and tells the user to visit Order History.

Adjusts the quantities on a suggested supply order so the order reaches a target the user described — "fill this to a full container", "get me to 40,000 cubes", "take this up to the supplier minimum", "round everything to pack size". This is StockIQ's Order Targeting (Order Wizard) engine, the same one behind the Place Orders screen's targeting dialog. nothing IS saved — it computes and returns adjusted quantities. To actually place them, pass the TargetingSpec from this tool's result into PlaceOrder's `targeting` argument, verbatim. required inputs are the supplierContexts from GetOrderSuggestions plus the same coverage parameters you used for GetSuggestedOrderLines — pass them verbatim, exactly as PlaceOrder requires, because the lines are rebuilt server-side from them. The result leads with Assumptions: one line per targeting option, saying whether the user chose it or a default was applied. show those TO THE user along with the before/after totals — the whole point is that they can see what was assumed and correct it in one sentence before placing. Then it carries Changes: only the lines whose quantity moved, with old and new quantities. ⚠️ Watch the maximumDaysOfSupply assumption. The default caps every line at 180 days of projected supply, so targeting can legitimately stop short of the number asked for; Outcome says when that happened. If the user wants the target hit regardless, re-run with quantityLimit="None". If a required choice is missing — which shipping container, what number to aim at — the tool returns NeedsClarification naming the options rather than guessing.