shopware-mcp

Order history

order_history

Read-onlyIdempotent

Retrieve an order’s chronological state history, including payment and delivery transitions, actions, and who triggered them, to see what happened and when.

Instructions

The state history of one order: every order, payment and delivery transition in chronological order with the previous and new state, the action name and who triggered it (admin user, API integration or the system). Use it for 'what happened to this order and when?'. Orders imported without transitions have an empty history. When there are more transitions than limit, the newest ones are kept. Returns { orderId, orderNumber, orderDate, total, entries[], note? }.

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": "order_history"
  }
}

Input Schema

Name	Required	Description
`limit`	No
`orderId`	No	Order UUID
`orderNumber`	No	Order number as shown to the customer

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.11.1Nov 6, 2026

TDQS

A4.1/5.0

Behavior4/5

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

The annotations already signal a safe read, so the description adds the important behavioral details: transitions are chronological, who triggered them is recorded (admin user, API integration or the system), and imported orders without transitions return an empty history. It also discloses truncation behavior, which the annotations do not cover; the only real gap is that it does not describe pagination semantics beyond the limit.

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 description front-loads the core definition, then the use case, the edge case and the truncation rule, and it ends with the return shape. Each sentence adds information, and nothing reads as filler.

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

Completeness4/5

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

There is no output schema, so stating the return shape {orderId, orderNumber, orderDate, total, entries[], note?} is a useful addition. The empty-history and truncation quirks are covered, but the ambiguity in how orderId and orderNumber combine is left unresolved, which matters for a tool with zero required parameters.

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

Parameters3/5

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

Schema coverage is 67%: orderId and orderNumber are documented, while limit is not. The description partly compensates by explaining what limit does when transitions are truncated, since the newest transitions are kept. It never explains how orderId and orderNumber relate, and since neither is required, how the lookup resolves those two parameters is left unclear.

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

Purpose5/5

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

The description names a specific verb-and-resource combination: the full state history of a single order, covering order, payment and delivery transitions in chronological order. That clearly separates it from orders_get (current state) and order_documents_list (documents), so an agent can choose between them without opening a schema.

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 trigger phrase, 'what happened to this order and when?', which is a clear when-to-use cue. It does not state when not to use it or point to the nearest alternative, such as orders_get, but there is still clear context for invoking it.

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