The Sylius MCP server exhibits significant quality gaps across naming, descriptions, and schema documentation. Of 15 tools, only 8 have verified descriptions in source code; 7 are inferred from service registration with minimal or no explicit documentation. Parameter schemas are inconsistently defined, some tools lack explicit schema definitions, and descriptions frequently reference external concepts (IRIs, Hydra collections) without explaining them to an LLM. Error handling guidance is absent. The server attempts domain-specific e-commerce functionality (orders, products, payments) but implements it in a way that forces agents to understand Sylius API idioms (Hydra, IRIs, minor currency units) rather than abstracting them. Tool names follow a verb_noun pattern but lack consistency in scope, some tools conflate multiple responsibilities (e.g., fetch_order returns the entire order object with many fields; no pagination control). Inferred tools (9, 10, 11, 13, 14, 15) cannot be scored above 50 because their definitions are not directly visible in provided source.

• For all 15 tools, document the complete output schema in the description or a separate field. Example: 'Returns a JSON object with fields: { code: string, name: string, baseCurrency: { code: string } }' so agents know what to extract.
• Rewrite descriptions to target 50 - 150 characters and avoid jargon. Instead of 'raw JSON Hydra collection containing exactly one Sylius channel', write 'Returns the active sales channel with its code and currency.'
• Add parameter constraints and examples to descriptions. Example: 'code (string, required): ISO-4217 currency code, e.g. EUR, USD, GBP. List available codes by calling fetch_channel() first.'
• Provide error recovery guidance for each tool. Example in add_item_to_order: 'If the variant IRI is invalid, call search_products() to find the correct product and extract the variant IRI from the response.'
• Convert minor currency units (÷100) to decimal strings in responses. Instead of returning { total: 1050 }, return { total: '10.50', currency: 'EUR' }. This eliminates LLM conversion errors.
• Consolidate product and variant search into a single search tool with optional filters, or clearly document when to use each. Add a composition note: 'Use search_products() to find products by name/sku. Use search_product_variants() to list variants of a known product.'
• Implement server-side token management: return short-lived session tokens and validate them server-side rather than passing raw tokens in parameters. This reduces exposure in logs.
• Add pagination defaults to list_payment_methods and list_shipping_methods. Example: 'Returns paginated results (default 30 items per page). Pass page and itemsPerPage to control pagination.'

Inferred effective spec: <=2025-11-25.

• Relies on Stateful initialize / Mcp-Session-Id (removed; protocol is stateless) - make each request self-contained