[DOCS] AskUserQuestion docs missing multiple-choice prompt decision threshold

Documentation Type

Missing documentation (feature not documented)

Documentation Location

https://code.claude.com/docs/en/tools-reference

Section/Topic

AskUserQuestion row in the built-in tools table

Current Documentation

The tools reference currently describes the tool only at a high level:

AskUserQuestion | Asks multiple-choice questions to gather requirements or clarify ambiguity | No

Related guidance describes ways to make Claude more or less proactive, but does not define the default threshold for using the multiple-choice prompt.

The Proactive output style says:

Claude executes immediately, makes reasonable assumptions instead of pausing for routine decisions, and prefers action over planning.

The auto mode docs say:

Auto mode also nudges Claude to keep working without stopping for clarifying questions, though Claude still asks when your prompt or a skill explicitly relies on it.

What's Wrong or Missing?

The docs do not explain the v2.1.154 behavior change that Claude now reserves the multiple-choice question prompt for decisions it genuinely cannot make itself, instead of asking when it already has enough context to proceed.

This leaves a gap between the tool reference and current behavior:

• The tools reference says what AskUserQuestion does, but not when Claude should use it.
• The Proactive and auto mode pages discuss ways to reduce routine pauses, but the v2.1.154 behavior is not limited to selecting those modes.
• Users who previously saw more frequent multiple-choice prompts may not know whether fewer prompts are intentional, a regression, or dependent on output style or permission mode.
• Users who want an interview-style flow need clearer guidance that they should explicitly ask Claude to use AskUserQuestion when they want questions even if Claude could make reasonable assumptions.

Suggested Improvement

Add a short note to the AskUserQuestion row or a small subsection near the built-in tools table:

Claude uses AskUserQuestion for decisions it cannot reasonably infer from the current prompt and session context. When Claude already has enough context to proceed, it should make a reasonable assumption and continue instead of opening a multiple-choice question prompt. If you want Claude to interview you before proceeding, ask for that explicitly, for example: "Interview me with AskUserQuestion before implementing this."

Optionally cross-link to the "Let Claude interview you" section in Best practices so users can intentionally request an interview workflow.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

| Page | Line(s) | Context |
|------|---------|---------|
| https://code.claude.com/docs/en/tools-reference | 16 | AskUserQuestion description lacks the decision threshold for using the multiple-choice prompt |
| https://code.claude.com/docs/en/output-styles | 21 | Proactive style says Claude makes reasonable assumptions instead of pausing for routine decisions |
| https://code.claude.com/docs/en/permission-modes | 167 | Auto mode guidance mentions fewer clarifying questions but not the general v2.1.154 prompt-threshold behavior |
| https://code.claude.com/docs/en/best-practices | 354-367 | Interview workflow shows explicit prompting for AskUserQuestion but does not explain that explicit prompting is how to force an interview when Claude could otherwise proceed |

Total scope: 4 pages affected

Behavior changed in Claude Code v2.1.154.