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

# buy

> Shop and check out, in natural language, across the merchants the user has linked (DoorDash, etc.).

Connect to `https://mcp.agentcard.sh/mcp` with the **user's connection token** (or a `buy_token` for org-owned accounts).

**Behavior:** destructive.

## What it does

Shop and check out, in natural language, across the merchants the user has linked (DoorDash, etc.). Pass the whole ask as `request` — e.g. "order a caesar salad from Zuni on DoorDash" — and this tool runs the shopping flow for you. It is CONVERSATIONAL: this tool RETURNS a `conversation_id`; pass that SAME `conversation_id` back on every follow-up (your reply to a question, "add a coke", "yes, check out") so it continues the SAME order. Omit it (or set new\_order=true) only to start a fresh order. It will ask for the delivery address and have you confirm the cart and total. CHECKOUT (which charges a one-time card) happens ONLY after the user explicitly confirms in a later message — relay the confirmation through `request` ("yes, place the order") on the SAME conversation\_id. RELAY REPLIES VERBATIM: when the user answers a question from this tool ("yes", "the 16 oz one", "use my other card"), pass their reply through `request` as-is on the same conversation\_id — do NOT rewrite it into a fresh full order command; a rewritten command reads as a NEW ask and the confirmation never lands. NEVER use new\_order (or drop the conversation\_id) to recover from an error or a refused checkout — that discards the cart and any pending confirmation. Stay on the same conversation\_id and follow the error's instruction instead; new\_order is ONLY for the user starting an unrelated order. If it hands out a merchant login link (hosted connect), just reply on the SAME conversation\_id once the user finishes (e.g. "done — I logged in") and it verifies the link itself. Logins started here have no pending\_id, so the buy\_connect / buy\_connect\_status pair does not apply to them. Call get\_instructions FIRST for the current usage guide before your first buy.

## Inputs

| Field                  | Type    | Description                                                                                                                                          |
| ---------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| `request` *(required)* | string  | The natural-language ask or follow-up, e.g. "order a caesar salad from Zuni on DoorDash", "deliver to 123 Main St", or "yes, place the order".       |
| `conversation_id`      | string  | The conversation\_id returned by a previous buy call. Pass it to continue the SAME order (keeps the cart + confirmation). Omit to start a new order. |
| `new_order`            | boolean | Start a fresh shopping conversation instead of continuing the current one. Use when beginning an unrelated order (ignores any conversation\_id).     |

## Returns

| Field                  | Type                                                                      | Description                                                                                                                                                                                                                                     |
| ---------------------- | ------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `message` *(required)* | string                                                                    | The assistant's conversational turn (it may ask for the delivery address, show the cart + total, confirm, or report a placed order), or an error explanation.                                                                                   |
| `status`               | string: `assistant_turn` · `conversation_start_failed` · `request_failed` | Discriminator for the outcome. 'assistant\_turn' when the buy loop replied; 'conversation\_start\_failed' or 'request\_failed' on errors.                                                                                                       |
| `conversation_id`      | string                                                                    | The conversation id to thread back as conversation\_id on the next buy call to continue the SAME order. Present on a successful assistant turn.                                                                                                 |
| `messages`             | array                                                                     | The same turn split into ordered messages for multi-bubble surfaces (each narration segment, then the final reply/confirmation). `message` is the same content consolidated; clients that show one bubble should use `message` and ignore this. |

## Example call

```json theme={null}
{
  "tool": "buy",
  "arguments": {
    "request": "\u2026"
  }
}
```