MerchantFlow

Order Basket Analytics

query_order_basket_analytics

Read-onlyIdempotent

Analyse orders filtered by what is IN the basket (which products, and how many units), broken down by region, channel or month. Answers questions the pre-computed dashboard context cannot, such as 'orders containing two chairs, average shipping cost per region'. Returns order counts, net revenue, and BOTH shipping figures: what customers were charged (revenue) and what fulfilment actually cost the merchant, with an explicit coverage percentage for the cost side.

Input Schema

TableJSON Schema

Name	Required	Description
`limit`	No	Maximum groups to return, highest order count first. Defaults to 50.
`end_date`	Yes	Inclusive end of the window, YYYY-MM-DD, in the store's timezone.
`group_by`	No	Dimension to break results down by. Defaults to 'none' (one total row).
`start_date`	Yes	Inclusive start of the window, YYYY-MM-DD, in the store's timezone.
`product_ids`	No	Only count orders whose basket contains these products. Get IDs from resolve_products. Omit to analyse all orders in the window.
`min_quantity`	No	Order must contain at least this many units across product_ids. Use for 'two or more chairs'. Mutually exclusive with exact_quantity.
`region_codes`	No	Restrict to these ISO 3166-1 alpha-2 shipping country codes, e.g. ['AU','NZ'].
`sales_channel`	No	Restrict to a single sales channel value.
`exact_quantity`	No	Order must contain exactly this many units across product_ids. Use for 'orders with two chairs'. Mutually exclusive with min_quantity.

Output Schema

TableJSON Schema

Name	Required	Description
`note`	No	Present only when no orders matched.
`_meta`	No
`groups`	No
`_message`	No
`currency`	No
`truncated`	No	Present only when the matched order set hit the internal cap.
`_truncated`	No
`group_count`	No
`groups_omitted`	No	Present only when `limit` cut groups from the response.
`_tenant_context`	No
`filters_applied`	No
`truncation_note`	No
`matched_order_count`	No
`shipping_metric_definitions`	No	Definitions of the shipping metrics, restating that charged is revenue and cost is the merchant outlay. Absent on the no-matches branch.
`fulfillment_cost_coverage_percent`	No	Coverage across every matched order, not per group.

Schema Changelog

Changes observed during successful MCP inspections.

First observedSep 20, 2026

TDQS

A4.5/5.0

Behavior4/5

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

Annotations already declare read-only, idempotent, and non-destructive behavior. The description adds valuable context about the output: order counts, net revenue, charged vs. actual shipping cost, and an explicit coverage percentage for the cost side—details not inferable from the annotations or schema alone.

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 three tightly written sentences with no filler. It front-loads the core operation, then supplies a clarifying example, then describes the return payload. Every sentence earns its place.

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 9-parameter complexity, the description covers the essential aspects: the unique basket-filtering behavior, the grouping dimensions, and the non-obvious dual shipping figure semantics. The full input schema, annotations, and output schema handle the remaining details, so nothing critical 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 100%, so every parameter is documented. The description enriches these meanings by mapping the filter concept (basket products and quantities) to the relevant parameters and using the example 'orders containing two chairs' to clarify exact_quantity and min_quantity usage.

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 states the tool's specific function: analyzing orders filtered by basket contents and grouping by region, channel, or month. It also distinguishes itself from pre-computed dashboard context and provides a concrete example query, making its purpose unmistakable even among many sibling analytics tools.

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 explains when this tool is the right choice ('Answers questions the pre-computed dashboard context cannot') and gives a concrete example. However, it does not explicitly name alternative tools or state when not to use it, so it leaves some routing judgment to the agent.

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

All MerchantFlow tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources

Need Help?