ask_user
Presents a popup with selectable options to collect a single decision from the user, enabling interactive choice when you need confirmation or a preference.
Instructions
Ask the user to choose exactly ONE option from a list. Use this tool instead of listing options in your text response whenever you need the user to make a decision.
WHEN TO USE THIS TOOL:
You are about to list numbered options and ask "which do you prefer?"
You need user confirmation on a specific choice before proceeding
The user must pick one mutually exclusive option (e.g., "Which approach should I implement?", "Which file should I modify?", "What framework do you want?")
EXAMPLES OF WHEN TO USE:
"Should I use Option A, B, or C?" → Use this tool
"Which implementation approach?" → Use this tool
"What programming language?" → Use this tool
"Pick a template to scaffold" → Use this tool
⚠️ CRITICAL: Each parameter MUST be passed SEPARATELY. Do NOT combine them!
❌ WRONG (options contains title/description - WILL FAIL): options: [{"label": "A"}, {"label": "B"}], "title": "...", "description": "..."
✅ CORRECT (each parameter separate): options: [{"label": "A"}, {"label": "B"}] title: "Pick one" description: "Choose your preference"
PARAMETERS:
options (REQUIRED): Array of objects, each with "label" (required) and optional "description", "recommended"
title (optional): String displayed above options
description (optional): String displayed below title
allow_other (optional): Boolean to allow custom input
The tool opens a popup in the user's browser and waits for their selection. If allow_other is true, users can enter custom text if predefined options don't fit. Returns the selected option as a string, or indicates if the user skipped.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| title | No | Optional title displayed above the selection. Use to provide context or ask a question. | |
| options | Yes | List of options for the user to choose from. Each option must have a label property. Use description for additional context (pros/cons, code examples). The user will see these in a popup and select one. | |
| allow_other | No | If true, adds an "Other" option that allows the user to enter custom text. Use when the predefined options might not cover all possibilities. | |
| description | No | Optional description text displayed below the title. Use for additional instructions or clarification. | |
| other_label | No | Custom label for the "Other" option. Only used when allow_other is true. | Other |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| action | Yes | Whether the user submitted a selection, skipped, or requested an explanation for an option | |
| comments | No | Additional comments provided by the user (only present if allow_comments was true and user entered text) | |
| selection | No | The selected option (only present if action is "submit") | |
| explainOption | No | The option for which explanation was requested (only present if action is "request_explanation") | |
| explainMessage | No | A pre-formatted message asking for explanation (only present if action is "request_explanation") |