shopware-mcp

Download document PDF

document_download

Read-onlyIdempotent

Download a Shopware order document such as an invoice or delivery note as a PDF using its documentId, returning the file as an embedded resource with metadata for read-only access.

Instructions

Fetch one order document (invoice, delivery note, credit note, cancellation invoice) as a PDF. The file is returned to the host as an embedded resource next to the document's metadata; the model sees the metadata only. Get the documentId from order_documents_list. Read-only, nothing is marked as sent. Returns { id, type, documentNumber, orderNumber, mimeType, bytes, attachments[] }.

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": {
      "documentId": "<documentId>"
    },
    "name": "document_download"
  }
}

Input Schema

Name	Required	Description	Default
`documentId`	Yes	Document UUID from order_documents_list

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.11.1Nov 6, 2026

TDQS

A4.5/5.0

Behavior5/5

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

Goes well beyond the annotations by explaining the delivery mechanism: the file is returned to the host as an embedded resource while the model only sees metadata — a critical behavior an agent must know before calling. It also discloses the side-effect profile ('nothing is marked as sent') and the returned payload fields despite having no output schema.

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?

Four short sentences, nothing wasted: purpose, delivery behavior, prerequisite, safety, and return shape, in that order. The most decision-relevant facts (PDF fetch, model-sees-metadata-only) are front-loaded.

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 no output schema, the description supplies the return shape ({ id, type, documentNumber, orderNumber, mimeType, bytes, attachments[] }), and it covers the non-obvious host-vs-model visibility split. Nothing an agent needs to call this correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% and the single documentId parameter is fully documented with its UUID pattern. The description's 'Get the documentId from order_documents_list' restates the schema's own hint rather than adding format or edge-case detail, so baseline 3 applies.

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 ('Fetch one order document ... as a PDF') and enumerates the document types covered (invoice, delivery note, credit note, cancellation invoice). This clearly separates it from sibling order_documents_list, which is named as the source of IDs rather than the downloader.

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?

Gives an explicit prerequisite/entry point ('Get the documentId from order_documents_list'), so the agent knows the list-then-download workflow. It stops short of stating when NOT to use it or what to do if the document is missing, but the sibling routing is clear.

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