shopware-mcp

Search any entity

entity_search

Read-onlyIdempotent

Search any Shopware entity using filters, sorting, paging and aggregations when no dedicated tool covers it. Check the entity schema first to find fields and associations.

Instructions

Escape hatch for everything without a dedicated tool: search ANY Shopware entity (e.g. product_manufacturer, property_group, shipping_method, tax, country, newsletter_recipient, product_review, seo_url, cms_page, media) with the same Criteria filters, sort and paging. Use entity_schema first to see the available fields and associations. Credentials and internal fields are always stripped, long values such as stored files are truncated, and entities holding secrets (users, integrations, system config) are blocked. Prefer the dedicated tools when one exists. aggregations asks Shopware to count, sum or average over the whole match (terms, sum, avg, min, max, count, stats, histogram, one nested metric per bucket), e.g. orders per payment method or revenue per month for any entity; set limit: 1 when only the aggregations matter. Returns { entity, total, page, limit, items[], aggregations? } with raw (scrubbed) data.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "entity": "<entity>"
    },
    "name": "entity_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)
`entity`	Yes	Entity name in snake_case or kebab-case, e.g. 'product_manufacturer'
`fields`	No	Only return these fields of the entity (Shopware `includes`)
`filter`	No	Criteria filters, combined with AND
`aggregations`	No	Shopware aggregations computed over the whole match
`associations`	No	Association names to load, e.g. ['country', 'salesChannels']

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.11.1Nov 6, 2026

TDQS

A4.8/5.0

Behavior5/5

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

Annotations already declare readOnly/openWorld/idempotent/non-destructive, but the description adds substantial behavior beyond them: credentials and internal fields are always stripped, long values such as stored files are truncated, and secret-holding entities (users, integrations, system config) are blocked. It also states the exact return shape { entity, total, page, limit, items[], aggregations? }, which no annotation supplies.

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 and the escape-hatch framing, then moves through prerequisites, safety behavior, and aggregation semantics in a logical order. It is a dense block rather than broken into lines, and the aggregations sentence is long, but essentially every sentence carries distinct information an agent needs.

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?

For a 9-parameter, open-world search tool with no output schema, the description covers the routing decision, the entity_schema prerequisite, the scrubbing/blocking safety model, the return shape, and aggregation usage with examples. Nothing an agent needs in order to call it correctly or predict its behavior appears to be 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 the baseline is 3, but the description adds real meaning on the hardest parameter: it spells out that aggregations are computed over the whole match, lists the supported metric types and the one-nested-metric-per-bucket rule, and gives worked examples ('orders per payment method', 'revenue per month'). It does not expand on filter, fields, or associations beyond what the schema documents.

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 and resource ('search ANY Shopware entity') and enumerates concrete entity examples (product_manufacturer, property_group, seo_url, cms_page). It explicitly positions itself as the 'escape hatch' for entities without a dedicated tool, which immediately distinguishes it from the long sibling list of dedicated search/list 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?

Gives explicit routing rules: 'Use entity_schema first to see the available fields and associations' and 'Prefer the dedicated tools when one exists.' It also adds a task-level hint — 'set limit: 1 when only the aggregations matter' — so when-to-use, prerequisites, and the alternative path are all covered.

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