@mastra/core/dist/docs/references/reference-tools-ask-user-tool.md

> Discover all available pages from the documentation index: https://mastra.ai/llms.txt

# askUserTool

A built-in, agent-agnostic tool that asks the user a question and waits for their response. The tool supports free-text questions, single-select prompts, and multi-select prompts.

The tool pauses through the native [tool suspension](https://mastra.ai/docs/agents/agent-approval) primitive: it calls `suspend()` with the question payload, which makes the agent emit a `tool-call-suspended` event and persist run state. Resume the run with `agent.resumeStream(answer, { runId })`.

When executed outside an agent run (no `suspend` available), the tool returns a readable fallback string containing the question and choices.

## Usage example

Add `askUserTool` to an agent's toolset:

```typescript
import { Agent } from '@mastra/core/agent'
import { askUserTool } from '@mastra/core/tools'

const agent = new Agent({
  id: 'assistant',
  name: 'Assistant',
  instructions: 'Ask the user for clarification when the request is ambiguous.',
  model,
  tools: { askUserTool },
})
```

Handle the suspension and resume:

```typescript
const stream = await agent.stream('Summarize my project')

for await (const chunk of stream.fullStream) {
  if (chunk.type === 'tool-call-suspended') {
    const { question, options, selectionMode } = chunk.payload.suspendPayload
    // Present the question to the user, collect their answer, then resume:
    const resumed = await agent.resumeStream('The main repo', { runId: stream.runId })
    for await (const c of resumed.textStream) process.stdout.write(c)
  }
}
```

For multi-select prompts, resume with a string array:

```typescript
await agent.resumeStream(['Add tests', 'Update docs'], { runId: stream.runId })
```

## Input schema

The model calls this tool with the following parameters:

**question** (`string`): The question to ask the user. Must be non-empty.

**options** (`AskUserOption[]`): Structured choices for the user. When omitted, the prompt is free-text.

**options.label** (`string`): Short display text for this option. This value is returned to the model when selected.

**options.description** (`string`): Explanation of what this option means.

**selectionMode** (`'single_select' | 'multi_select'`): Controls how many options the user can select. Defaults to 'single\_select' when options are provided. Requires options.

## Suspend payload

The `tool-call-suspended` event carries a `suspendPayload` with the same shape as the input:

**question** (`string`): The question being asked.

**options** (`AskUserOption[]`): The structured choices, if any.

**selectionMode** (`'single_select' | 'multi_select'`): The resolved selection mode. Omitted for free-text prompts.

## Resume data

Pass the user's answer to `agent.resumeStream()`:

- **Free-text and single-select:** A `string`.
- **Multi-select:** A `string[]` of selected option labels.