Interactive Questions with the Question Tool

Use the question tool to ask users structured, interactive questions with selectable options instead of plain yes/no or free-text prompts. This produces a numbered option list the user navigates with arrow keys and confirms with Enter.

Core Rule

Never ask a yes/no question in plain text when the answer can be expressed as a set of options. Always use the question tool with explicit choices.

Wrong:

"Do you want to proceed? (yes/no)"

Right: use the question tool with options such as "Proceed" and "Cancel".

When to Use the Question Tool

Use it whenever you need the user to make a decision:

Confirmation — before destructive or irreversible actions (delete, overwrite, push, deploy)
Strategy selection — when multiple valid approaches exist and user preference matters
Clarification — when a request is ambiguous and each interpretation leads to meaningfully different work
Multi-step workflows — to let the user steer direction between phases

Do not use it for simple informational acknowledgement where no decision is required.

How to Call the Question Tool

The tool accepts an array of questions. Each question has:

Field	Required	Notes
`question`	yes	The full question text shown to the user
`header`	yes	A very short label (max 30 chars) shown as the prompt title
`options`	yes	Array of `{ label, description }` objects
`multiple`	no	Set `true` to allow selecting more than one option

The tool automatically appends a "Type your own answer" option — do not add an "Other" catch-all yourself.

Option Design Rules

Label: 1–5 words, concise action or noun phrase (e.g., "Proceed", "Cancel", "Edit message")
Description: one sentence explaining what that choice does (e.g., "Commit with the proposed message", "Abort the operation")
Order: put the recommended or most common option first; add (Recommended) at the end of its label when helpful
Coverage: include all meaningful paths — at minimum a "do it" option and a "cancel" option
No duplicates: each option must represent a distinct outcome

Confirmation Pattern

For any action that cannot easily be undone, use a three-option confirmation:

Proceed with <action>?
  1. Proceed (Recommended) — <short description of what happens>
  2. Cancel                 — Abort the operation
  3. Edit / Adjust          — <relevant alternative, e.g., "Provide a revised message">

Strategy Selection Pattern

When multiple valid approaches exist:

How should I handle <situation>?
  1. <Approach A> (Recommended) — <one sentence tradeoff>
  2. <Approach B>               — <one sentence tradeoff>
  3. <Approach C>               — <one sentence tradeoff>

Always explain the tradeoff in the description so the user can decide without needing additional context.

Clarification Pattern

When a request is ambiguous, clarify before starting work rather than assuming:

What should <term / feature> include?
  1. <Interpretation A> — <what this means concretely>
  2. <Interpretation B> — <what this means concretely>

Limit clarification questions to genuine ambiguities. Do not ask about details you can decide using reasonable defaults.

Multiple Selection

Set multiple: true only when the user genuinely needs to pick more than one item — for example, selecting which files to include, which environments to target, or which checks to run. Keep the option list short (2–7 items) to avoid overwhelming the user.

Avoid These Anti-Patterns

Anti-pattern	Problem	Fix
Asking yes/no in text	Requires typing; no structured response	Use `question` tool with Proceed / Cancel options
Too many options (8+)	Overwhelming; hard to scan	Group related options or split into sequential questions
Vague labels ("Option 1")	User cannot decide without reading description	Use action-oriented labels ("Deploy to staging")
Catch-all "Other" option	Redundant — tool adds "Type your own answer" automatically	Remove it
Asking every minor detail	Slows workflow; irritates user	Reserve questions for decisions that genuinely affect the outcome
Multiple questions at once	Harder to process	Ask one question per tool call unless questions are tightly coupled

Quick Reference

question tool fields:
  questions[].question     — full question text
  questions[].header       — short label (≤30 chars)
  questions[].options[]
    .label                 — 1–5 words
    .description           — one sentence
  questions[].multiple     — true | false (default false)

Do NOT add "Other" — tool appends "Type your own answer" automatically.
Put recommended option first, label it "(Recommended)".

interactive-questions