ask-user-question

name	ask-user-question
description	Ask users questions via the UI. Use when you need clarification, user preferences, or confirmation before proceeding. The user CANNOT see CLI output - this tool is the ONLY way to communicate with them.

Ask User Question

Use this MCP tool to ask users questions and get their responses. This is the ONLY way to communicate with the user - they cannot see CLI/terminal output.

Critical Rule

The user CANNOT see your text output or CLI prompts!

If you write "Let me ask you..." and then just output text - THE USER WILL NOT SEE IT. You MUST call this tool to display a modal in the UI.

When to Use

• Clarifying questions before starting ambiguous tasks
• Asking user preferences (e.g., "How would you like files organized?")
• Confirming actions before executing (especially destructive/irreversible ones)
• Getting approval for sensitive actions (financial, messaging, deletion, etc.)
• Any situation where you need user input to proceed

Parameters

{
  "questions": [{
    "question": "Your question to the user",
    "header": "Short label (max 12 chars)",
    "options": [
      { "label": "Option 1", "description": "What this does" },
      { "label": "Option 2", "description": "What this does" }
    ],
    "multiSelect": false
  }]
}

• question (required): The question text to display
• header (optional): Short category label, shown as modal title (max 12 chars)
• options (optional): Array of selectable choices (2-4 recommended)
• multiSelect (optional): Allow selecting multiple options (default: false)

Custom text input: To allow users to type their own response, include an option with label "Other" (case-insensitive). When selected, the UI shows a text input field.

{ "label": "Other", "description": "Type your own response" }

Important: When "Other" is selected, the response will be User responded: [their text] instead of User selected: Other. You must wait for and handle this text response - do NOT proceed as if they selected a predefined option.

Examples

Asking about organization preferences

AskUserQuestion({
  "questions": [{
    "question": "How would you like to organize your Downloads folder?",
    "header": "Organize",
    "options": [
      { "label": "By file type", "description": "Group into Documents, Images, Videos, etc." },
      { "label": "By date", "description": "Group by month/year" },
      { "label": "By project", "description": "You'll help me name project folders" }
    ]
  }]
})

Confirming a destructive action

AskUserQuestion({
  "questions": [{
    "question": "Delete these 15 duplicate files?",
    "header": "Confirm",
    "options": [
      { "label": "Delete all", "description": "Remove all 15 duplicates" },
      { "label": "Review first", "description": "Show me the list before deleting" },
      { "label": "Cancel", "description": "Don't delete anything" }
    ]
  }]
})

Simple yes/no confirmation

AskUserQuestion({
  "questions": [{
    "question": "Should I proceed with sending this email?",
    "header": "Send email",
    "options": [
      { "label": "Send", "description": "Send the email now" },
      { "label": "Cancel", "description": "Don't send" }
    ]
  }]
})

Response Format

The tool returns the user's selection:

• User selected: By file type - Single selection
• User selected: Option A, Option B - Multiple selections (if multiSelect: true)
• User responded: [custom text] - If user typed a custom response
• User declined to answer the question. - If user dismissed the modal

Wrong vs Correct

WRONG (user won't see this):

I'll help organize your files. How would you like them organized?
- By type
- By date
- By project

CORRECT (user will see a modal):

AskUserQuestion({
  "questions": [{
    "question": "How would you like your files organized?",
    "options": [
      { "label": "By type" },
      { "label": "By date" },
      { "label": "By project" }
    ]
  }]
})