shopware-mcp

Stock forecast

stock_forecast

Read-onlyIdempotent

Forecast product stockouts from real sales and calculate days of cover, depletion date, and reorder quantity so you know what to reorder before items run out.

Instructions

Which products run out soon, from real sales: units sold per product in the last days (cancelled orders excluded), the current available stock, the days of cover at that pace, the date the stock reaches zero and a reorder quantity that keeps it in stock through the horizon plus restockDays more days (a negative stock is a backlog and is covered too). Lists the active products whose cover is below horizon days, soonest first. Products without sales in the window are never listed. Use it for 'what do I need to reorder?'. Returns { window, horizon, restockDays, total, items[], notes? }.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "stock_forecast"
  }
}

Input Schema

Name	Required	Description
`days`	No	Sales window in days
`limit`	No
`horizon`	No	List products that run out within this many days
`restockDays`	No	Days beyond the horizon the suggested reorder quantity should cover
`salesChannelId`	No	Count sales of one sales channel only

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.11.1Nov 6, 2026

TDQS

A4.3/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Beyond the readOnly/idempotent annotations, the description discloses the calculation basis (real sales, cancelled orders excluded), the edge-case interpretation (negative stock is a backlog and is covered), the filtering rule (only active products with cover below horizon), the sort order (soonest first), and the exact response shape. These are precisely the behavioral facts an agent cannot derive from the annotations or from a 5-parameter integer schema.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The intent is front-loaded in the first clause and every subsequent clause carries a distinct behavioral fact rather than filler. The main weakness is that the core sentence is a long comma-chained run of noun phrases, which reads as dense exposition rather than a scannable structure; the trailing return-shape note is well placed.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, this description carries the burden of describing the return value and does so explicitly ({ window, horizon, restockDays, total, items[], notes? }). Combined with the disclosed exclusion rules and edge-case handling for a computation-heavy read tool, nothing an agent needs to invoke it correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 80%, so `days` and `horizon` are already documented; the description still adds real value by explaining how they interact — cover is measured at the sales pace of the last `days`, and the reorder quantity must last through `horizon` plus `restockDays`. The remaining gap is `limit` and `salesChannelId`, which appear in neither the description nor a schema description (the channel is documented in schema, the limit is not).

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The opening clause names a specific computed resource — products that will run out soon, derived from real per-product sales — and the rest of the sentence enumerates the exact outputs (units sold, available stock, days of cover, zero-stock date, reorder quantity). That is far more than a restatement of the title. It stops short of 5 because it never names the adjacent tool (stock_get) that an agent would otherwise consider for inventory questions, leaving the differentiation to inference.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives an explicit triggering question, "Use it for 'what do I need to reorder?'", and an explicit exclusion rule: products without sales in the window are never listed, cancelled orders don't count. What it lacks is any guidance on when to prefer stock_get or sales_report instead, so the agent must infer the boundary itself.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.