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

# MCP tools

> Every tool on the AgentMall MCP server, with its inputs.

The AgentMall MCP server has 43 tools. To connect to it, see [Connect your agent](https://agentmall.mintlify.site/connect-your-agent.md).

Inputs use `snake_case`.

> [!NOTE]
>
> In keyless test mode, only `search_catalog` and `get_product` at Walmart (`mrc_walmart`) work.
> Every other tool is listed with the same inputs, and returns `needs_test_key`. See [what test mode
> covers](https://agentmall.mintlify.site/connect-your-agent.md#what-test-mode-covers).

## Catalog

Find products at a merchant.

### `search_catalog`

Search a merchant's catalog by keyword. Works in keyless test mode.

| Input | Type | Required |
| - | - | - |
| `merchant_id` | string | Yes |
| `query` | string | Yes |
| `location_id` | string | No |

### `lookup_catalog`

Look up specific items by ID.

| Input | Type | Required |
| - | - | - |
| `merchant_id` | string | Yes |
| `item_ids` | array of strings | Yes |

### `get_product`

Get a single product by ID. Works in keyless test mode.

| Input | Type | Required |
| - | - | - |
| `merchant_id` | string | Yes |
| `product_id` | string | Yes |

## Locations

Find the merchant's stores.

### `search_locations`

Search for merchant locations in an area.

| Input | Type | Required |
| - | - | - |
| `merchant_id` | string | Yes |
| `area` | string | No |

### `lookup_locations`

Look up specific locations by ID.

| Input | Type | Required |
| - | - | - |
| `merchant_id` | string | Yes |
| `location_ids` | array of strings | Yes |

## Shoppers

The person the agent buys for.

### `create_shopper`

Create a new shopper profile.

| Input | Type | Required |
| - | - | - |
| `name` | string | Yes |
| `email` | string | Yes |
| `delivery_address` | object | Yes |
| `delivery_address.line1` | string | Yes |
| `delivery_address.city` | string | Yes |
| `delivery_address.region` | string | Yes |
| `delivery_address.postal_code` | string | Yes |
| `delivery_address.country` | string | Yes |

### `get_shopper`

Get a shopper by ID.

| Input | Type | Required |
| - | - | - |
| `shopper_id` | string | Yes |

## Payment methods

Add and manage payment methods without the agent seeing card details. See [Vault and credentials](https://agentmall.mintlify.site/concepts/vault-and-credentials.md).

### `create_payment_session`

Create a hosted payment method enrollment session.

| Input | Type | Required |
| - | - | - |
| `shopper_id` | string | Yes |
| `provider` | string | No |
| `type` | `card`, `bank-account`, `digital-wallet` | Yes |
| `return_url` | string | Yes |

### `get_payment_session`

Read enrollment status and the issued payment reference.

| Input | Type | Required |
| - | - | - |
| `payment_session_id` | string | Yes |

### `list_payment_references`

List a shopper's active opaque payment references.

| Input | Type | Required |
| - | - | - |
| `shopper_id` | string | Yes |

### `get_payment_reference`

Get a stored payment reference.

| Input | Type | Required |
| - | - | - |
| `reference_id` | string | Yes |

### `revoke_payment_reference`

Revoke a stored payment reference.

| Input | Type | Required |
| - | - | - |
| `reference_id` | string | Yes |

## Sessions

Record one agent's shopping run. See [Sessions](https://agentmall.mintlify.site/concepts/sessions.md).

### `create_session`

Start a new shopping session.

| Input | Type | Required |
| - | - | - |
| `shopper_id` | string | Yes |
| `merchant_id` | string | Yes |

### `get_session`

Get a session with outcome, duration, and tool call count.

| Input | Type | Required |
| - | - | - |
| `session_id` | string | Yes |

### `list_sessions`

List sessions with optional filters.

| Input | Type | Required |
| - | - | - |
| `shopper_id` | string | No |
| `outcome` | string | No |
| `limit` | number | No |

### `get_session_events`

Get every tool call made during a session.

| Input | Type | Required |
| - | - | - |
| `session_id` | string | Yes |

## Carts

Build a basket at one merchant.

### `create_cart`

Create a new shopping cart.

| Input | Type | Required |
| - | - | - |
| `merchant_id` | string | Yes |
| `location_id` | string | Yes |

### `get_cart`

Get a cart by ID.

| Input | Type | Required |
| - | - | - |
| `cart_id` | string | Yes |

### `update_cart`

Update line items in a cart.

| Input | Type | Required |
| - | - | - |
| `cart_id` | string | Yes |
| `line_items` | array of objects | Yes |
| `line_items[].product_id` | string | Yes |
| `line_items[].quantity` | number | Yes |

### `cancel_cart`

Cancel a cart.

| Input | Type | Required |
| - | - | - |
| `cart_id` | string | Yes |

## Checkout

Get a quote and place the order. See [Order flow](https://agentmall.mintlify.site/concepts/order-flow.md).

### `create_checkout`

Create a checkout session from a cart.

| Input | Type | Required |
| - | - | - |
| `session_id` | string | Yes |
| `cart_id` | string | Yes |
| `payment_reference_id` | string | Yes |
| `delivery_location_id` | string | Yes |

### `get_checkout`

Get a checkout session by ID.

| Input | Type | Required |
| - | - | - |
| `checkout_session_id` | string | Yes |

### `update_checkout`

Update a checkout session.

| Input | Type | Required |
| - | - | - |
| `checkout_session_id` | string | Yes |
| `updates` | object | Yes |

### `complete_checkout`

Complete a checkout and create an order.

| Input | Type | Required |
| - | - | - |
| `checkout_session_id` | string | Yes |
| `mandate_id` | string | Yes |
| `idempotency_key` | string | Yes |

### `cancel_checkout`

Cancel a checkout session.

| Input | Type | Required |
| - | - | - |
| `checkout_session_id` | string | Yes |

## Approval

Get the shopper's approval and the mandate. See [Mandates and approval](https://agentmall.mintlify.site/concepts/mandates-and-approval.md).

### `request_approval`

Create a shopper approval session for a checkout.

| Input | Type | Required |
| - | - | - |
| `checkout_session_id` | string | Yes |

### `get_approval`

Get the shopper decision and issued mandate.

| Input | Type | Required |
| - | - | - |
| `approval_id` | string | Yes |

### `get_mandate`

Get a spending mandate by ID.

| Input | Type | Required |
| - | - | - |
| `mandate_id` | string | Yes |

## Orders

Track an order and change it.

### `get_order`

Get an order by ID.

| Input | Type | Required |
| - | - | - |
| `order_id` | string | Yes |

### `get_order_events`

Get the append-only event timeline for an order.

| Input | Type | Required |
| - | - | - |
| `order_id` | string | Yes |

### `get_order_receipt`

Get the reconciled money breakdown for an order.

| Input | Type | Required |
| - | - | - |
| `order_id` | string | Yes |

### `cancel_order`

Cancel an order.

| Input | Type | Required |
| - | - | - |
| `order_id` | string | Yes |
| `reason` | string | Yes |

### `modify_order`

Modify an existing order.

| Input | Type | Required |
| - | - | - |
| `order_id` | string | Yes |
| `modifications` | object | Yes |

## Returns and refunds

Handle what happens after delivery.

### `create_return`

Request a return for order items.

| Input | Type | Required |
| - | - | - |
| `order_id` | string | Yes |
| `line_items` | array of objects | Yes |
| `line_items[].product_id` | string | Yes |
| `line_items[].quantity` | number | Yes |
| `reason` | string | Yes |

### `get_return`

Get a return by ID.

| Input | Type | Required |
| - | - | - |
| `return_id` | string | Yes |

### `create_refund`

Create a refund for an order.

| Input | Type | Required |
| - | - | - |
| `order_id` | string | Yes |
| `amount` | number | Yes |
| `reason` | string | Yes |

### `get_refund`

Get a refund by ID.

| Input | Type | Required |
| - | - | - |
| `refund_id` | string | Yes |

## Merchants

See which merchants and operations are supported.

### `list_merchants`

List all merchants on the platform.

No inputs.

### `get_merchant`

Get a merchant by ID.

| Input | Type | Required |
| - | - | - |
| `merchant_id` | string | Yes |

### `get_operations`

List all platform commerce operations and their certification status.

| Input | Type | Required |
| - | - | - |
| `merchant_id` | string | No |

## Flows

Step-by-step guides an agent can follow. Flow names are `checkout` and `return`.

### `get_flow_state`

Get the current state of an interactive flow.

| Input | Type | Required |
| - | - | - |
| `flow_name` | string | Yes |

### `advance_flow`

Advance to the next step in a flow.

| Input | Type | Required |
| - | - | - |
| `flow_name` | string | Yes |

### `reset_flow`

Reset a flow to its initial state.

| Input | Type | Required |
| - | - | - |
| `flow_name` | string | Yes |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.