Loading ToolBench
Crystallize MCP — headless commerce tools for AI agents. Browse catalogue, search products, inspect shapes, manage orders via Model Context Protocol.
Strong foundation with 14 well-named tools, comprehensive descriptions (avg 150+ chars), and complete input schemas with types and descriptions. All tools follow verb_noun naming (browse_, get_, search_, create_, list_, discover_). Schemas use Zod with proper type definitions. However, output schemas are not explicitly documented in the source code, responses are inferred from handler implementations. Error handling exists but lacks recovery guidance (e.g., 'try search_catalogue first'). No tool annotations (readOnlyHint/destructiveHint) despite clear read/write distinction. Audit logging is present but optional. Missing idempotency guarantees for write tools.
Browse the catalogue tree by path. Returns child items (folders, products, documents) with names, paths, and types. Start with "/" to see the root.
Create a new item (product, document, or folder) in the catalogue. The item type is determined by the shape. Use get_shape first to understand available components. Respects CRYSTALLIZE_DRY_RUN — when enabled, returns a preview without creating.
Discover products using the Discovery API. Supports filtering by shape, tag, and price range. Returns product names, paths, SKUs, and pricing.
Get a single customer by ID with full details: name, email, phone, addresses, and order history. PII masking applies based on CRYSTALLIZE_PII_MODE.
Get a catalogue item by path with its full component data. Returns name, type, shape, components, and a deep link to the Crystallize UI.
Get a single order by ID with full details: customer info, items, pricing, shipping, and payment status.
Output schemas not documented in source code. Handlers return results but response structure is not formally specified for LLM planning.
No tool annotations (readOnlyHint, destructiveHint, idempotentHint) despite clear access mode distinction (read vs write). create_item is marked WRITE but lacks destructiveHint or confirmation pattern.
Error handling returns formatError() but does not provide recovery guidance. E.g., 'Item not found' should suggest 'Try search_catalogue() or browse_catalogue() first.'
| Scored | Grade | Overall | Spec posture | Rubric |
|---|---|---|---|---|
| 2026-09-23 | D | 56 | 2026-07-28+ | v2 |
Get all variants for a product by path. Returns SKUs, names, pricing, stock, and attributes.
Get the full GraphQL schema for the Crystallize API. Useful for understanding available queries and mutations beyond the predefined tools.
Get a shape by identifier with its full component definitions. Returns component IDs, names, types, and configuration. Use this before creating items to understand what components are available.
Get tenant metadata: name, identifier, ID, default language, and available languages. Useful for understanding the tenant's configuration.
List customers in the tenant. Supports filtering by email and date range. Returns customer IDs, names, emails, and creation dates. PII masking applies based on CRYSTALLIZE_PII_MODE.
List orders for the tenant. Supports filtering by status and date range. Returns order IDs, customer names, totals, and statuses.
List all available shapes (product types, document types, folder types) in the tenant. Returns shape identifiers, names, and types.
Search across the catalogue for products, documents, and folders. Supports filtering by type (PRODUCT, DOCUMENT, FOLDER). Returns names, paths, types, and deep links.
create_item supports dry-run via CRYSTALLIZE_DRY_RUN env var, but this is not documented in the tool description. Agents cannot invoke dry-run mode explicitly.
PII masking for list_customers and get_customer is controlled by CRYSTALLIZE_PII_MODE env var, not a tool parameter. Agents cannot control masking per-call.