> ## Documentation Index
> Fetch the complete documentation index at: https://betterdatainc.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Mcp reference

# MCP Tool Reference

<Note>
  For **which MCP surfaces exist** (gateway-console vs Registry MCP vs hosted gateway MCP), see the system reference: [MCP surfaces](/reference/mcp-surfaces).
</Note>

This reference documents tool names exported by the Commerce Gateway MCP handler registry.

## Tool Discovery

If your org enables dynamic tool filtering, query your gateway tool discovery endpoint for the live tool set:

```bash theme={null}
GET https://api.betterdata.co/gateway/{orgSlug}/tools
```

## Tool Catalog

### `shop`

<ParamField path="query" type="string">`@shop` style natural-language lookup query.</ParamField>
<ParamField path="intent" type="string">One of `browse`, `search`, `lookup`, `price`, `availability`.</ParamField>
<ResponseField name="content" type="array">Resolved brand/gateway guidance and routing hints.</ResponseField>

### `search_products`

<ParamField path="query" type="string">Natural-language product query.</ParamField>
<ParamField path="filters" type="object">Optional category/tags/price/stock filters.</ParamField>
<ParamField path="limit" type="number">Result limit (1-20).</ParamField>
<ParamField path="offset" type="number">Pagination offset.</ParamField>
<ResponseField name="content" type="array">Formatted product results.</ResponseField>

### `get_product_details`

<ParamField path="productId" type="string">Product identifier.</ParamField>
<ResponseField name="content" type="array">Detailed product view and optional generated link.</ResponseField>

### `check_availability`

<ParamField path="productId" type="string">Product identifier.</ParamField>
<ParamField path="variantId" type="string">Optional variant identifier.</ParamField>
<ParamField path="quantity" type="number">Requested quantity.</ParamField>
<ResponseField name="content" type="array">Buyer-safe availability signal and delivery hints.</ResponseField>

### `check_inventory`

<ParamField path="productId" type="string">Product identifier.</ParamField>
<ParamField path="variantId" type="string">Optional variant identifier.</ParamField>
<ParamField path="locationId" type="string">Optional location filter.</ParamField>
<ResponseField name="content" type="array">Inventory-level stock output.</ResponseField>

### `get_recommendations`

<ParamField path="productIds" type="array">Optional product seed list.</ParamField>
<ParamField path="strategy" type="string">`similar`, `complementary`, `trending`, `personalized`, `bundle`.</ParamField>
<ParamField path="limit" type="number">Result limit (1-10).</ParamField>
<ResponseField name="content" type="array">Recommended products.</ResponseField>

### `add_to_cart`

<ParamField path="productId" type="string">Product identifier.</ParamField>
<ParamField path="variantId" type="string">Optional variant identifier.</ParamField>
<ParamField path="quantity" type="number">Quantity to add.</ParamField>
<ResponseField name="content" type="array">Updated cart and checkout-link context.</ResponseField>

### `create_order`

<ParamField path="shippingAddress" type="object">Required address payload.</ParamField>
<ParamField path="billingAddress" type="object">Optional billing payload.</ParamField>
<ParamField path="paymentMethod" type="string">`credit_card`, `paypal`, `apple_pay`, `google_pay`, `affirm`, `klarna`.</ParamField>
<ResponseField name="content" type="array">Order creation result.</ResponseField>

### SCM Placeholder Tools

The following are exported and capability-gated, but depend on approved SCM adapters in runtime:

* `get_shipment_status`
* `get_purchase_order_status`
* `get_trace_events`
* `get_demand_forecast`

<Note>
  Tool names and schemas are verified from `packages/commerce-gateway/src/mcp/tools/index.ts`.
</Note>