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

# Ask User Question Tool

> Pause agent execution to ask the user interactive questions before continuing

## What it does

The Ask User Question tool lets your agent pause mid-conversation to gather information from the user through an interactive question UI. The agent presents questions with predefined options or free text input, waits for the user's response, then continues with full context of their answers.

This is a **human-in-the-loop** tool — it only works in interactive chat sessions, not in scheduled tasks or automated workflows.

## Key features

* Interactive question UI with clickable option buttons
* Support for single or multiple questions in one tool call
* Client-side pagination for multi-question flows (no extra API round-trips)
* Free text input with optional predefined options
* Skip/dismiss option for each question
* Compact answered state after user responds

## Parameters

### Single question mode

| Parameter         | Type    | Required | Description                                                                             |
| ----------------- | ------- | -------- | --------------------------------------------------------------------------------------- |
| `question`        | string  | Yes\*    | The question to ask the user                                                            |
| `options`         | array   | No       | Predefined options with `label` (required) and `description` (optional)                 |
| `allow_free_text` | boolean | No       | Show free text input. Defaults to `true` when no options, `false` when options provided |

### Multiple questions mode

| Parameter   | Type  | Required | Description                                                                       |
| ----------- | ----- | -------- | --------------------------------------------------------------------------------- |
| `questions` | array | Yes\*    | Array of question objects, each with `question`, `options`, and `allow_free_text` |

<Note>Use either `question` (single) or `questions` (multiple), not both.</Note>

## Common use cases

### Gathering preferences before a task

```json theme={null}
{
  "questions": [
    {
      "question": "What's your budget?",
      "options": [
        {"label": "Under $1000"},
        {"label": "$1000-$3000"},
        {"label": "$3000+"}
      ]
    },
    {
      "question": "Do you prefer beach or mountains?",
      "options": [
        {"label": "Beach"},
        {"label": "Mountains"}
      ]
    }
  ]
}
```

Ask multiple questions at once with pagination — all answers submitted together.

### Quick clarification with options

```json theme={null}
{
  "question": "Which format would you like the report in?",
  "options": [
    {"label": "PDF", "description": "Best for sharing"},
    {"label": "PowerPoint", "description": "Best for presenting"},
    {"label": "Google Sheet", "description": "Best for collaboration"}
  ]
}
```

Single question with descriptive options.

### Open-ended input

```json theme={null}
{
  "question": "What specific topics should I focus on in the analysis?"
}
```

Free text input when predefined options don't make sense.

### Options with optional elaboration

```json theme={null}
{
  "question": "What's your experience level with this topic?",
  "options": [
    {"label": "Beginner"},
    {"label": "Intermediate"},
    {"label": "Expert"}
  ],
  "allow_free_text": true
}
```

User can select an option and optionally add more detail, or just click Next/Submit with their selection.

## How it works

1. Agent calls `ask_user_question` with question(s) and options
2. Agent execution **pauses** — no follow-up text is generated
3. The chat UI renders an interactive question component
4. For multiple questions, the user pages through each one client-side
5. After answering the last question, all answers are sent as a single user message
6. The agent receives the answers and continues naturally

## Best practices

* Use predefined options when possible — they're faster for users and produce cleaner answers for the agent
* Keep questions concise and specific
* Use the `questions` array to batch related questions instead of calling the tool multiple times
* Add `description` to options when the label alone might be ambiguous
* Use `allow_free_text: true` with options when you want the user to be able to elaborate

## Limitations

* Only works in interactive chat sessions (not scheduled tasks, email triggers, or API calls)
* The agent fully stops after calling this tool — it cannot do other work while waiting
* On page reload, previously answered questions show as "(answered)" without the specific answer text

## Related tools

* [Call Agent](/tools/call_agent) - Delegate tasks to other agents after gathering user preferences
* [Send Email](/tools/send_email) - Send results based on user choices
* [Schedule Task](/tools/schedule_task) - Set up recurring tasks based on user preferences