Shopkeeper MCP

Overview Schema Source Related Servers Discussions Admin

Sales report

sales_report

Read-onlyIdempotent

Generates sales for a date range grouped by day, week, month, product, or customer, reporting gross, refunds, and net totals in cents while excluding pending and cancelled orders that never captured money.

Instructions

Sales for a date range (by order placed date), grouped by day, ISO week, month, product, or customer. Reports gross, refunds and net (gross minus refunds issued against those orders), all in cents. Pending and cancelled orders are excluded because no money was captured.

Input Schema

Name	Required	Description	Default
`to`	Yes	Last day included (YYYY-MM-DD).
`from`	Yes	First day included (YYYY-MM-DD, by order placed date).
`group_by`	No	day \| week (ISO, Monday start) \| month \| product \| customer	month

Output Schema

Name	Required	Description
`to`	Yes
`from`	Yes
`rows`	Yes
`basis`	Yes	order_totals: gross = order totals incl. shipping. line_items (product view): gross = item revenue excl. shipping, refunds allocated pro-rata.
`totals`	Yes
`group_by`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.1.0Oct 26, 2026

TDQS

A4.9/5.0

Behavior5/5

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

Beyond the annotations (readOnlyHint=true), the description details the complex calculation logic (net = gross minus refunds), the unit of measurement (all in cents), and the specific filtering behavior (excluding pending/cancelled orders).

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

Conciseness5/5

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

The description is highly dense but structured logically, moving from what the tool generates to its calculations, and finally its limitations. Every sentence adds unique, essential information.

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?

Given the complexity of multiple grouping options and specific financial calculations, the description covers all critical behavioral details—including what is excluded and how data is processed—making it maximally complete for an AI agent.

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?

Since schema coverage is 100%, the description's primary value is reinforcing the context of the grouping parameters. It specifies that the grouping (day, week, month, etc.) operates on the 'order placed date,' adding vital context to the input constraints.

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 clearly defines the tool's function: generating a 'Sales report.' It specifies the resource (sales data) and the scope (date range), making its purpose unambiguous relative to other sibling tools.

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?

It provides critical constraints on how the tool behaves, specifying that it aggregates data based on the 'order placed date' and explicitly excluding 'Pending and cancelled orders.' This gives the agent precise boundaries on appropriate usage.

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

Deploy Server