shopware-mcp

Search product reviews

reviews_search

Read-onlyIdempotent

Search product reviews by rating, reviewer, product, moderation status, or date range, returning paginated results with average rating.

Instructions

Search product reviews with their rating (1-5 points), text, reviewer, product and moderation state. Filter on status (false = awaiting approval), points, productId, product.productNumber or createdAt ranges. Newest first. Adds averagePoints over the whole match. Use review_moderate to approve or hide one. Returns { total, page, limit, averagePoints, items[] }.

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

Input Schema

Name	Required	Description
`page`	No	1-based page
`sort`	No	Sort order; defaults per tool
`term`	No	Full-text search term
`limit`	No	Items per page, max 50 (default from SHOPWARE_MCP_DEFAULT_LIMIT)
`fields`	No	Extra raw entity fields to add to each item, e.g. ['customFields', 'ean']. Dot-paths allowed.
`filter`	No	Criteria filters, combined with AND

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.11.1Nov 6, 2026

TDQS

A4.2/5.0

Behavior3/5

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

Annotations already declare readOnly/idempotent/openWorld, so the safety bar is low. The description adds real value: newest-first ordering and the note that averagePoints is computed over the whole match (an aggregation trait). It does not mention pagination limits or rate/permission details, but the schema covers limits.

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 purpose, then filters, ordering, aggregation, alternative, and return shape. Dense and mostly waste-free, though tightly packed into a few sentences.

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?

No output schema exists, so the description supplies the return shape { total, page, limit, averagePoints, items[] }, covers filter fields, ordering and aggregation, and points to the moderation sibling. Nothing essential is missing for a search tool.

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% (baseline 3), but the description adds meaning beyond it: it names filterable fields (status, points, productId, product.productNumber, createdAt ranges) and clarifies status=false means awaiting approval, which the schema does not.

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?

States a specific verb (Search) and resource (product reviews) and enumerates the returned fields (rating, text, reviewer, product, moderation state). It also names review_moderate as the sibling for a different task, letting an agent distinguish it.

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?

Clear usage context: filterable on status/points/product/date, newest first, and explicitly routes moderation actions to review_moderate. Lacks explicit when-not guidance for this tool, but the alternative is named.

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