---
description: "Says that a tool is waiting for the person (a choice, a confirmation) and what they should do."
---

# `waitingForUser`

Says that a tool is waiting for the person (a choice, a confirmation) and what they should do. Reach for it inside a tool's `execute` when the call cannot finish without them: the chat shows the prompt on the call, and agents do not time the call out while the person is being asked.

## Import

```ts
import { waitingForUser } from "@webmcp-agents/core";
```

## Example

A tool that needs a size the agent did not give. It asks, waits, and answers with a coded error if the person does not choose.

```ts title="tools/add-to-cart.ts"
import {
  defineWebTool,
  waitingForUser,
  WebToolError,
} from "@webmcp-agents/core";
import { z } from "zod";

/** The size the person picks, or null if they dismiss it. */
declare function askForSize(): Promise<string | null>;

export const addToCart = defineWebTool({
  id: "add_to_cart",
  title: "Add to cart",
  description:
    "Add the product to the cart. Needs a size: if none is given " +
    "the person is asked to choose one.",
  inputSchema: z.object({
    size: z.string().optional().describe("e.g. M"),
  }),
  execute: async ({ size }) => {
    let chosen = size ?? null;
    if (!chosen) {
      waitingForUser("add_to_cart", "Choose a size");
      chosen = await askForSize();
    }
    if (!chosen)
      throw new WebToolError(
        "needs_user",
        "The person did not choose a size. Ask which one they want.",
      );
    return `Added one in size ${chosen}.`;
  },
});
```

## Options

`waitingForUser(tool, prompt)`.

| Name | Type | Default | Description |
|---|---|---|---|
| `tool` | `string` | required | The id of the tool that is waiting: the events and the chat attach the prompt to that tool's call. |
| `prompt` | `string` | required | What the person should do, in a few words, e.g. `"Choose a size"`. Shown to them. |

## Returns

Nothing (`void`). It emits `{ type: "park", tool, prompt }` to every [`onAgentEvent`](/docs/reference/core/on-agent-event) listener.

## Notes

- Use it for waits beyond a confirm the browser already pauses on: a tool with `requireConfirmation` and a declarative form without `toolautosubmit` already emit `park`. `get_location` from `@webmcp-agents/tools` uses it while the browser asks for permission.
- It only says the tool waits; the waiting itself is your code (an await on the person's choice).
- If the person does not answer, finish with a [`WebToolError`](/docs/reference/core/web-tool-error) of code `needs_user` so the agent knows to ask them.

## See also

- [Confirm before it runs](/docs/build/confirm-before-it-runs), the built-in wait
- [`onAgentEvent`](/docs/reference/core/on-agent-event), where the `park` event arrives
- [`toolError`](/docs/reference/core/tool-error), the `needs_user` code
- [Errors](/docs/concepts/errors), time limits and waiting for the person