claude-code - 💡(How to fix) Fix [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:

Total scope: 4 pages affected

Behavior changed in Claude Code v2.1.154.