Built-in Tool Reference

A destructive tool gets an optional confirm parameter. Without confirm: true, it runs nothing and returns a non-error confirmation_required response that names the tool and its action but none of its arguments. With confirmation it runs.

Seven built-in tools are destructive. They are marked destructive in the tables below. One of them, place_order, is a shop tool: placing an order is a real-money action, so it is gated like the destructive admin tools.

confirm is a request to the agent, not a lock: a host should ask its user before running a tool annotated destructiveHint: true, and use rate limits and the tool call log as further controls.

Tool toggles

Administrators can enable or disable any individual tool, from the Tools page of the dashboard's MCP Server section or through the setMcpToolEnabled mutation (gated by UpdateMcpServer). A disabled tool disappears from tools/list and cannot be called. Tool toggles are the primary lever for scoping what an agent can do.

Shop tools

Cart & Checkout

Catalog (browse)

Orders & account

Admin tools

Catalog (manage)

Orders

Customers

Stock & inventory

Channels

Assets & media

Shared conventions

These rules apply to many tools at once.

How prices are returned

Prices on products, variants, orders and shipping quotes appear twice. The plain field is a whole number in the currency's smallest unit, which is what Vendure stores and what you should use for any calculation. The field whose name ends in Decimal is the same amount written out with the decimal point in the right place. Show that one to a shopper, or hand it to a language model.

The number of decimal places comes from your store's moneyStrategy.precision setting, which defaults to 2. It is one setting for the whole store rather than one per currency. A store selling in currencies with different numbers of decimal places handles that itself.

What an order contains

Order and cart responses contain:

• Customer and address details, product variant names, payments, refunds, and fulfillments. Amounts follow the integer and Decimal format above.
• customer is { id, emailAddress, firstName, lastName }, or null on a cart nobody has claimed yet.
• Each payment carries publicMetadata, which holds only the public key of whatever the payment handler stored.
• An empty shippingLines means no shipping method has been chosen.
• Each entry in fulfillments is { id, state, method, trackingCode, lines: [{ orderLineId, quantity }] }. The cart tools leave the field out altogether, because an open cart has no shipments to report.
• couponCodes and discounts are always included, with discounts grouped by promotion. Discount amounts are negative and include both standard and Decimal values.
• An order returned with a Vendure error, such as insufficient stock, has the same shape as a successful result.

A valid coupon does not always reduce the cart price. It may appear in couponCodes without changing the total or discounts, so compare these fields with the previous cart before reporting a discount.

Cart tools use an existing cart's currency. A cart started through add_to_cart uses the channel's default currency.

Where IDs come from

Every required ID input of a built-in tool has a tool that returns it:

• Variant IDs for add_to_cart come from the shop get_product.
• Variant IDs for get_stock_levels, adjust_stock and update_variant, and option IDs for create_variant, come from the admin get_product.

Optional inputs such as facetValueIds and taxCategoryId have no such tool, so their values come from the dashboard or the Admin API.

Paging and filtering lists

Every list tool takes limit (a whole number from 1 to 100, defaulting to 25) and offset. A value outside that range is refused with a validation error naming the field, so a call for 0 rows or 1000 rows is refused instead of returning every row in the channel.

The cap of 100 belongs to the MCP tools; it is deliberately stricter than the Admin API's adminListQueryLimit, which defaults to 1000, because a tool result has to fit in a model's context.

list_products, list_orders and list_customers also take a filter object. Its keys are fields and its values are operator objects, and every condition in it has to hold for a record to be returned. There is no way to express "either or": for that, call the tool twice.

contains is case-insensitive on Postgres; on other databases it follows the collation of the column.

totalWithTax is a whole number in the currency's smallest unit, like every other price these tools return.

Finding the orders that have been sitting at payment since before noon:

Tool details

Notes on the tools whose behavior is not obvious from the tables. Tools not listed here have nothing to add.

add_to_cart

• Takes exactly one of variantId or productId.
• Product IDs and variant IDs are separate numbering sequences that overlap. A product ID used where a variant ID belongs would resolve to a real but unrelated variant, and put the wrong item in the cart.
• Given a productId for a product with several variants, the tool adds nothing. It returns an error listing each variant with its ID, so the caller can retry with the right one.
• Use get_product to get variant IDs in the first place.

set_checkout_details

• Sets the shipping address, the billing address, or both. billingSameAsShipping: true copies the shipping address from the call or the existing cart.
• For guest checkout, pass customer with emailAddress, firstName, and lastName, with addresses or separately. A signed-in caller cannot pass it. When the order is placed, a guest's checkout address is saved to the new customer's address book.
• Address updates are one transaction, so a rejected address changes neither one.
• Refused: a call with none of shippingAddress, billingAddress, billingSameAsShipping, or customer, and a call with both billingAddress and billingSameAsShipping.

A new shipping address can make the shipping method the shopper already chose ineligible. Vendure then swaps the cart's shipping line to the cheapest method that is still eligible, or drops the line when none is. Vendure does either without reporting it, so the tool reports it instead:

• The response carries shippingMethodChanged: true and a message saying which of the two happened.
• order.shippingLines shows the current state.
• A response without shippingMethodChanged means the chosen method survived the change.

get_eligible_shipping_methods

• A shipping quote carries no currency of its own, so the tool takes the currency from the cart the quote was calculated for.
• Anything a shipping calculator attached to the quote under metadata or customFields is returned unchanged alongside the price fields.

place_order

• An order in ArrangingPayment cannot be edited until paid in full.
• Vendure's default order process requires a customer, so its refusal names set_checkout_details. Stores that change arrangingPaymentRequiresCustomer or replace the process get their process's answer.

search_products

• Can be limited to a collection using either collectionId or collectionSlug.
• Product list results from search_products and the admin list_products include a priceRange. Use get_product for the full description, assets, and variants.

get_order (shop)

Answers order: null with a message when no order has that code or the caller may not see it.

get_my_account

Answers the customer's id, firstName, lastName, emailAddress and phoneNumber, plus addresses: one entry per saved address with its id, the address fields, and the defaultShippingAddress and defaultBillingAddress flags.

create_fulfillment

• Uses core's manual-fulfillment handler.
• Omit lines to fulfill every unfulfilled quantity, or pass [{ orderLineId, quantity }] for part of an order. Every line must belong to the order named by id.
• trackingCode defaults to an empty string.
• Without state, the new fulfillment is Pending and the order stays put. Shipped or Delivered moves it from Pending, and core moves the order to its corresponding full or partial state. Use Shipped to mark it shipped.
• The call is transactional: a refused transition rolls the fulfillment back.
• Core checks quantities and fulfillable stock, not order state, so an open cart can be fulfilled too.

update_order_state

Directly drives the order state machine. It can:

• move covered PaymentAuthorized orders to PaymentSettled
• return ArrangingPayment to AddingItems
• move AddingItems or Draft to ArrangingPayment

Other transitions belong elsewhere:

• Fulfillments, not this tool, move orders to Shipped or Delivered.
• cancel_order restocks lines.
• Cancelled needs every line cancelled unless the order is still in AddingItems or ArrangingPayment.
• Order modification and its follow-up payment need the Admin API.

refund_order

Refunds the selected payment.

• If paymentId is omitted, it uses the first settled payment with a refundable balance.
• If amount is omitted, it refunds that payment's remaining balance.

add_customer_to_group

• Holds UpdateCustomerGroup rather than ReadCustomer, so it returns the customer id and the customer's groups, and nothing else about the customer.
• Refuses a customer id that does not resolve in the active channel, instead of reporting a group the customer was never added to.

get_stock_levels and adjust_stock

• Both answer with one entry per stock location, carrying stockLocationId, stockLocationName, stockOnHand and stockAllocated.
• adjust_stock refuses a stock location that is not in the administrator's active channel.

upload_asset

• Fetches the URL once and does not follow redirects. Give it the final URL of the file.
• A URL that does not answer with the file is refused with a message saying so.

Tool exposure: direct vs discovery

toolExposure controls what tools/list returns.

direct (default)

Lists every permitted, enabled tool. Prefer it: modern agents and hosts do their own tool search. Scope an agent by disabling tools, not by hiding the list.

discovery (opt-in)

Replaces the full list with exactly two meta-tools.

search_tools({ query, limit? }) returns the tools that best match the query, ranked with BM25 over each tool's name, title, description, and author-supplied keywords. Each result includes the tool's input schema. query is required. An empty string skips ranking and returns the first limit tools by name, as a sample of what is available rather than the full list. limit defaults to 10 and is clamped to between 1 and 50.

execute_tool({ name, arguments }) runs a tool found via search_tools. It validates arguments against that tool's schema exactly as a direct call would.

Reach for discovery only when the full list is a problem:

• A host with a low tool cap: 42 tools exceeds some clients' limits.
• A model with no built-in tool search: older Claude and GPT models, Gemini, Grok, GLM, and most open-source models.

Discovery is a compatibility escape hatch, not the recommended default.

See also

• Registering Custom MCP Tools — add your own tools to these toolsets.
• @McpTool reference — the decorator and metadata types.