shopware-mcp

Customer report

customer_report

Read-onlyIdempotent

Generates Shopware customer figures for a chosen period, including new accounts, distinct buyers, repeat and guest order shares, and top customers by gross revenue; optionally compares prior period.

Instructions

Customer figures for a period straight from Shopware: new accounts (registered vs guest, by customer group), how many distinct customers ordered, the repeat share (two or more orders in the period), the guest order share and the top customers by gross revenue with their share of the total. compareWithPrevious adds the period of equal length before from and the change. 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": "customer_report"
  }
}

Input Schema

Name	Required	Description
`to`	No	End (inclusive; a date without time covers the whole day). Default: now
`from`	No	Start (inclusive), ISO date. Default: 30 days ago
`topCustomers`	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

A3.8/5.0

Behavior4/5

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

With readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint already declared by annotations, the description adds real behavior beyond them: the default window of the last 30 days, that cancelled orders are excluded by default, that compareWithPrevious pulls the equal-length window before `from` and reports the change, and that exactly one object is returned. Rate limits, permissions, and why a single object rather than a list are not addressed.

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?

Content is front-loaded with the metric inventory, then followed by short sentences covering the comparison flag, defaults, and return shape. Nearly every clause carries distinct information. The opening sentence is long and list-heavy, which slightly hurts scanability, but there is no 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?

For a six-parameter, read-only analytics tool with no output schema, the description lists the reported figures in enough detail that an agent knows what comes back, plus defaults and the cancelled-order rule. What is missing is minor: no statement about how metrics are scoped (currency, gross vs net beyond 'gross revenue'), and no hint that all parameters are optional.

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 67%, and the description compensates for the two undocumented parameters: topCustomers is given meaning ('top customers by gross revenue with their share of the total') and excludeCancelled is explained ('cancelled orders excluded'). It also clarifies compareWithPrevious semantics beyond the schema's one-liner and states the default range. Only salesChannelId and the ISO format details are left to the schema, which documents them adequately.

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 description names a concrete resource and enumerates the exact metrics produced: new accounts split by registered/guest and customer group, distinct ordering customers, repeat share, guest order share, and top customers by gross revenue with their share. That is far more specific than a restated title. It does not explicitly route against the closest sibling (sales_report), which also has a revenue dimension, so it falls short of a 5.

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

Usage Guidelines3/5

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

Usage context is implied rather than stated: 'Customer figures for a period straight from Shopware' plus the default window tells the agent this is a period-based analytics call. There is no explicit when-to-use statement and no exclusion pointing to sales_report or customers_search as alternatives. The compareWithPrevious and excludeCancelled notes help an agent choose option values but not tool choice.

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