> ## 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.

# surprise_me

> Buy the user something totally unexpected and very silly/stupid-fun under a small dollar cap (default $10, hard max $25).

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

## What it does

Buy the user something totally unexpected and very silly/stupid-fun under a small dollar cap (default \$10, hard max \$25). Great when the user cannot decide what to order (from DoorDash etc.) or just wants a fun surprise. It kicks off a shopping conversation that FIRST brainstorms deliberately stupid ideas, picks ONE genuinely unexpected item, builds the cart, and shows the item + exact total. It NEVER checks out by itself: the reply includes a conversation\_id — relay the user's explicit confirmation ("yes, place it") through the `buy` tool on that SAME conversation\_id, exactly like a normal order. Each surprise\_me call starts a fresh surprise; use `buy` for all follow-ups (answers, tweaks, the confirmation).

## Inputs

| Field         | Type   | Description                                                                                               |
| ------------- | ------ | --------------------------------------------------------------------------------------------------------- |
| `max_dollars` | number | Hard spend cap in dollars, total including fees. Optional; default 10, values above 25 are clamped to 25. |
| `merchant`    | string | Optional merchant hint the surprise should come from, e.g. 'doordash'. Omit to let the agent pick.        |
| `vibe`        | string | Optional notes/vibe from the user, e.g. "make it food", "something for my desk", "they love ducks".       |

## 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": "surprise_me",
  "arguments": {}
}
```