Loading ToolBench
WisWes MCP module for Magento 2 — exposes catalog, cart, checkout, customer, sales and wishlist tools to the WisWes shopping assistant via Model Context Protocol.
Strong tool definitions with comprehensive descriptions and well-structured schemas. All 12 tools have detailed, LLM-optimized descriptions (100-400 chars) explaining WHAT, WHEN, and HOW. Input schemas are present with typed parameters and descriptions. However, output schemas are not formally documented in the code, and error handling lacks structured recovery guidance. Tool naming follows verb_noun convention (cart-add, product-filter). Configurable product handling is sophisticated but adds complexity to descriptions. No tool annotations (readOnlyHint/destructiveHint) detected despite clear risk classifications.
Adds a product to the cart (works for guests and signed-in customers). Arguments: sku (string, required — the parent SKU for configurable products); quoteId (int, REQUIRED — pass the quote_id from your session context. Returned in every cart-* response under context.quote_id and threaded into your state automatically); qty (float, default 1); options (object, optional — product-type specific). For configurable products: pass options.configurable as an array of {attribute_id, value_index} where attribute_id is the configurable attribute's id (e.g. 144 for size, 93 for color) and value_index is the chosen option's value_index (e.g. 167 for "S", 49 for "Black"). Both are integers — DO NOT pass labels like "S" or "Black", and DO NOT confuse value_index with attribute_id. If you call cart-add for a configurable parent without all required attributes, the response is {needs_options: true, attributes: [...]} listing exactly which attribute_id/value_index pairs to ask the customer about — confirm with them, then re-call with the chosen pairs. For other product types the failing response/error will tell you the right shape (e.g. options.bundle = [{option_id, option_qty, option_selections: [int]}], options.custom = [{option_id, option_value}], options.downloadable = [{link_id}]). Returns the updated cart snapshot.
Returns the active cart in one shot — header, line items with options, and totals (subtotal, discount, shipping, tax, grand_total, currency). Argument: quoteId (int, optional) — pass the cart_id from session context if you have one. If omitted, returns an empty cart snapshot. Works for both signed-in customers and guests.
Removes an item from a cart by item ID. Arguments: itemId (int, required); quoteId (int, required) — pass from session context (state.context.quote_id). Returns the updated cart snapshot. Works for both signed-in customers and guests.
Output schemas not formally documented. Tool descriptions mention return values (e.g., 'Returns the updated cart snapshot', 'Returns {order_id, increment_id, ...}') but no structured JSON Schema definitions visible in code. LLMs cannot reliably extract fields from unstructured descriptions.
No tool annotations (readOnlyHint, destructiveHint, idempotentHint) despite clear risk classifications. cart-add, cart-remove, cart-update, checkout-place-order are marked WRITE/IRREVERSIBLE but lack @McpTool annotations to signal this to clients.
Error handling lacks structured recovery guidance. CartAddTool.describeAddFailure() generates helpful shape hints, but other tools (product-filter, checkout-*) do not document what errors are retryable, user-fixable, or fatal. No error classification pattern visible.
| Scored | Grade | Overall | Spec posture | Rubric |
|---|---|---|---|---|
| 2026-09-23 | C | 61 | 2026-07-28+ | v2 |
Updates a cart. Two modes: (1) update item quantity — pass itemId (int) + qty (float); (2) manage coupon — pass couponCode (string) to apply or removeCoupon (true) to remove. Pass quoteId (int, required) from session context (state.context.quote_id). Returns the updated cart snapshot. Works for both signed-in customers and guests.
Returns the category tree as a nested list of {name, url_key, children}. Arguments: rootCategoryName (string, optional — name of the category to use as root, e.g. "Men"; defaults to the store root); depth (int, default 2, max 3).
List payment methods available for the cart. Argument: cartId (required for guests). Returns array of {code, title} — pass code into checkout-place-order as paymentMethodCode. Magento exposes payment methods only after the shipping address and method are saved (checkout-set-address with type=shipping), so call this immediately after that succeeds.
Place the order: saves the chosen payment method on the cart and finalizes purchase. Required: paymentMethodCode (from checkout-payment-methods, e.g. "checkmo", "cashondelivery"). Guests must also pass cartId and email. Prerequisite: shipping address+method already saved via checkout-set-address (type=shipping). Returns {order_id, increment_id, grand_total, currency}.
Set billing or shipping address on the cart. Arguments: type ("billing"|"shipping"); firstname, lastname, street, city, postcode, countryId, telephone; regionId or region (optional); cartId (required for guests); shippingCarrierCode + shippingMethodCode (required when type="shipping"); email (optional).
List shipping methods available for the cart given a destination. Required: countryId (ISO-2, e.g. "US"). Optional: postcode, region, regionId, cartId (required for guests). Returns an array of {carrier_code, method_code, carrier_title, method_title, amount, available} — pass carrier_code + method_code into checkout-set-address. Call this BEFORE checkout-set-address so the codes are known.
Lists up to 5 products matching simple equality filters (field = value) and/or a free-text phrase. Backed by the storefront catalog search index (Opensearch), so attribute filters work for configurable parents — child variant attributes (color, size, etc.) are aggregated onto the parent at index time. PREFER THIS TOOL over product:search whenever the customer mentions ANY product characteristic — color, size, gender, manufacturer, brand, material, style, price range, or any other attribute. Filtering by characteristics is faster, more accurate, and lets the customer keep narrowing the result set. Recommended workflow: 1. If the customer mentioned any characteristic (e.g. "red shoes for men", "size M shirt", "Nike sneakers"), call product-filter-options FIRST to discover the valid field names and value_index values for color/size/gender/manufacturer (and any others). Always probe at minimum: color, size, gender, manufacturer. 2. Pick the matching value_index for each characteristic the customer named, and call product-filter with filters = [{field: <attribute_code>, value: <value_index>}, ...]. Use phrase only for the free-text portion (e.g. "summer shirt" → phrase="summer shirt"). 3. Only fall back to product:search when the customer's request is purely descriptive/semantic with no concrete characteristics. Arguments: filters (array of {field, value} — combined as AND; pass option_id / value_index for select attributes, raw string/number otherwise); phrase (string, optional — free-text fragment matched by the search engine against name/sku/description); sort (array of {field, direction?} — direction ASC or DESC). Returns compact rows: id, sku, name, type_id, price, url_key, color, size. For configurable products, color/size are comma-joined labels of all variants (e.g. "Red, Blue, Green"); for simple products, the single label.
Lists dropdown/select product attributes flagged as filterable in the Magento admin, with their valid option values. Always call this BEFORE product-filter to discover acceptable field names and values. Returns {filters: [{code, label, type, options: [{value, label}]}]}. options[] is capped at 10 entries per attribute.
Retrieve a single product by SKU (or numeric ID). Returns the full product payload: id, sku, name, type, status, visibility, price, description, images, custom options, stock. For configurable products, also returns: - configurable.attributes[]: {attribute_id, attribute_code, values: [{value_index, label}]} - configurable.variants[]: {sku, price, attributes: [value_index, value_index, ...]} variants[].attributes is a positional array of value_index entries matching the order of configurable.attributes[]. Example: if attributes = [color, size], a variant with attributes [49, 167] means color=49 ("Red") + size=167 ("M"). Cross-reference value_index → label via attributes[].values to show human-readable choices. Arguments: sku (string, required unless id is given); id (int, optional — used when SKU is unknown).
Parameter constraints not fully formalized. product-filter 'sort' parameter accepts array of {field, direction?} but no enum for direction values (ASC|DESC) visible in schema. category-list 'depth' has max=3 in description but not in JSON Schema maxItems.
Pagination not implemented. product-filter returns 'up to 5 products' but no limit/offset parameters or next_cursor. Large result sets could exhaust context; no guidance on how to iterate through results.