The Shopify MCP server has 10 tools with mostly complete naming and parameter schemas, but critical gaps in descriptions, error handling, and output documentation. Tool names follow verb_noun patterns effectively (bulk-delete-products, create-product, etc.). Input schemas are well-structured with proper JSON Schema types, enums, and constraints. However, tool descriptions vary significantly in quality: some are clear and action-oriented (e.g., bulk-delete-products: 'Delete multiple products at once. This action is irreversible. Max 100 products per call.'), while others lack context about when to use them vs. similar tools. Parameter descriptions are generally present but sometimes lack constraints or context about dependencies. Critical weakness: no output schemas are documented anywhere in the provided code, the LLM cannot know what fields to expect from API responses, forcing it to reason about downstream tool inputs blindly. Error handling is not evident in the provided sample code. The server provides 3 tools for deletion/destruction (bulk-delete-products, delete-collection, delete-product) but the descriptions do not mention confirmation steps or dry-run capabilities, violating the confirmation-request pattern for irreversible operations.
Tools (61)
attach-file-to-productwriteauthsource verified
Attach an existing Shopify MediaImage file to a product without re-uploading it
No output schemas documented for any tool. LLMs cannot plan downstream tool calls or extract response data without knowing return field names, types, and structure. This forces agents to hallucinate response shapes and risks failures when chaining tools together.
Three destructive tools (bulk-delete-products, delete-collection, delete-product, delete-metafield) lack confirmation or dry-run capability. Descriptions warn about irreversibility but do not offer patterns for agent verification. Agents cannot safely execute these without risk of accidental data loss.
Document output schemas for all 10 tools in the MCP tool registration. Include field names, types, and which fields are needed for chaining (e.g., if create-product returns product_id, document that so agents can pass it to bulk-update-products).
Add dry-run or preview modes to destructive tools (bulk-delete-products, delete-*) so agents can verify the action scope before committing. Example: add optional 'dryRun=true' parameter that returns what would be deleted without executing.
Implement structured error handling with recovery guidance. When API calls fail, return error messages like 'Product not found (ID: prod_12345). Use bulk-update-products to see available product IDs.' instead of raw API errors.
Expand descriptions for delete-* and similar low-context tools to 100-150 characters. Include when to use each tool and what to do if it fails. Example for delete-collection: 'Delete a specific collection by ID. This removes the collection but does not delete products. Use after migrating products to another collection or archiving them.'
Add explicit field requirements and format constraints to nested object parameters. For shippingAddress in create-draft-order, document which fields are required (firstName, lastName, address1, city, province, zip, country are typical) and validate them server-side with clear error messages.
If bulk operations can return partial failures (e.g., 95 of 100 deletes succeed), document per-item success/failure in output schema and include recovery guidance (retry specific IDs, or list which ones failed).
Error handling patterns are not visible in provided code. No guidance on error recovery, retryability, or actionable error messages. Agents receiving API failures have no context for self-correction or fallback strategies.
Parameter descriptions for complex nested objects (shippingAddress, billingAddress, lineItems in create-draft-order) are present but lack detail about required sub-fields, format constraints, or interdependencies. LLMs may pass malformed nested structures.
Several tool descriptions are under 100 characters and lack context about when to use them vs. similar tools. E.g., delete-collection, delete-metafield, delete-product have minimal descriptions that do not explain their specific use cases or prerequisites.
No pagination parameters (limit, offset, page, cursor) visible on any tools that might return multiple results (e.g., implied by bulk operations). Large result sets risk context window exhaustion without pagination guidance.
Add permission/scope annotations to each tool. Document what Shopify OAuth scopes are required (e.g., write_products for bulk-update-products, write_draft_orders for complete-draft-order) so clients can configure least-privilege access.
For tools accepting IDs, clarify whether numeric IDs (123456) or full GraphQL GIDs (gid://shopify/Product/123456) are accepted. The current descriptions for delete-product mention 'numeric or full GID' but do not test which format the GraphQL API actually expects. Validate and coerce server-side if possible.
Add idempotency guarantees or document non-idempotent behavior. E.g., if complete-draft-order called twice with the same ID will error or succeed idempotently, state this so agents can safely retry.
Consider adding a 'get_product', 'list_products', or 'search_products' read tool so agents can discover product IDs before calling bulk update/delete. Currently all tools assume the agent already has IDs, forcing manual lookup workflows.