waitingForUser

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

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

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.

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 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 of code needs_user so the agent knows to ask them.