shopware-mcp

Sales report

sales_report

Read-onlyIdempotent

Aggregate Shopware sales for a period: orders, gross/net revenue, average order value, state/payment/channel breakdowns, timeline, top products, and prior-period comparison for performance reporting.

Instructions

Aggregate sales figures for a period straight from Shopware: order count, gross/net revenue, average order value, breakdowns by order/payment/delivery state, payment method, currency and sales channel, a revenue timeline (day/week/month) and the top-selling products. Use it for 'how did we do last month?' questions instead of paging through orders. compareWithPrevious adds the period of equal length before from and the change in orders and revenue. Defaults to the last 30 days, cancelled orders excluded. Returns one object.

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

Input Schema

Name	Required	Description	Default
`to`	No	End (inclusive; a date without time covers the whole day), ISO date. Default: now
`from`	No	Start (inclusive), ISO date. Default: 30 days ago
`interval`	No	Timeline bucket size	day
`timeZone`	No	IANA time zone, e.g. Europe/Berlin: date-only from/to and daily buckets become local days. Default: UTC
`topProducts`	No
`salesChannelId`	No	Restrict to one sales channel
`excludeCancelled`	No
`compareWithPrevious`	No	Also report the preceding period of equal length and the change

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.11.1Nov 6, 2026

TDQS

A4.5/5.0

Behavior4/5

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, openWorld), and the description adds genuinely useful behavior: default time window, cancelled-order exclusion, the exact comparison window logic for compareWithPrevious, and that a single object is returned. It stops short of mentioning row limits, performance cost, or permissions, which keeps it from a 5 for an aggregate-over-all-orders tool.

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?

Front-loaded with the verb and scope, followed by the output inventory and then the usage guidance; no filler sentences. The middle metric enumeration is dense and slightly run-on, but each clause maps to a real returned field rather than padding.

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?

With no output schema, the description carries the burden of describing returns and does so by listing the metric groups and stating "Returns one object." For an 8-parameter analytics tool it is close to complete; only the meaning of salesChannelId scoping and the topProducts count are left entirely to the schema.

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 75%, and the description fills the most consequential gap by explaining that compareWithPrevious reports "the period of equal length before `from` and the change in orders and revenue" — semantics the one-line schema description does not convey. It also reinforces the from/to default window and the cancelled-order default, though it leaves interval bucketing and topProducts limits to the schema.

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?

"Aggregate sales figures for a period straight from Shopware" gives a specific verb and resource, then enumerates the exact outputs (order count, gross/net revenue, AOV, breakdowns by state/payment/currency/channel, timeline, top products). It is unmistakably distinct from the order-listing siblings it explicitly contrasts with ("instead of paging through orders").

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

Usage Guidelines5/5

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

Provides a concrete trigger question ("how did we do last month?") and names the alternative it replaces (paging through orders_search-style results). It also states defaults (last 30 days), an exclusion default (cancelled orders excluded), and what compareWithPrevious adds, so the agent knows both when to call it and which flags to set.

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