AskUserQuestion
Claude Code’s AskUserQuestion tool for structured clarifications, what it is, how it shows up in Plan mode, and prompt patterns that invite questions instead of guesses.
AskUserQuestion is a built-in Claude Code tool: the model can pause and present multiple-choice (or multi-select) clarifying questions instead of picking an assumption and running with it. Anthropic documents it under built-in tools in the Agent SDK overview and in Handle user input.
In Plan mode, Claude may call AskUserQuestion to gather requirements before it finalizes a plan. See Plan mode and Use Plan Mode for safe code analysis.
What the tool looks like (shape)
From the TypeScript and Python SDK references:
questions: array of blocks, each with:question: full wording shown to the user.header: very short label (docs mention a chip/tag style; keep it compact).options: each option haslabel(short) anddescription(what it means);previewis optional in TypeScript.multiSelect:trueif the user may pick more than one answer.
The runtime returns answers your client (or Claude Code’s UI) feeds back to the model. In custom SDK apps you implement a canUseTool handler that displays choices and returns allow with updatedInput containing questions and answers. See Handle clarifying questions.
Why teach it next to planning
Ambiguous goals (“refactor the API,” “make it faster,” “add auth”) are where agents hallucinate scope. AskUserQuestion nudges the model toward explicit tradeoffs (framework, migration strategy, breaking vs compatible changes) before large edits, especially when paired with Plan mode.
Prompt patterns that encourage clarifying questions
You do not call the tool yourself; you instruct the agent when to use it. Copy or adapt lines like:
Before changing any files, use AskUserQuestion to clarify anything ambiguous: target environment, compatibility guarantees, and which user-facing behavior must stay identical. Do not assume, ask.If more than one reasonable approach exists (e.g. sync vs async, new module vs extend existing), use AskUserQuestion with concrete options and short descriptions. Wait for answers before proposing a plan.In Plan mode: explore the repo read-only, then use AskUserQuestion for any open product or API decisions. Only after answers should you write the implementation plan.Good options in the model’s question blocks are mutually intelligible to a human skimming fast: label is the quick scan; description carries the real tradeoff.
Agent SDK caveat (custom apps)
If you build on the SDK and pass an explicit tools list, you must include AskUserQuestion or the model cannot call it. See Pass a canUseTool callback. The interactive Claude Code CLI manages this for you; the pitfall mainly hits embedded agents.