<!--
name: 'Tool Description: AskUserQuestion'
description: Default SDK built-in tool description and input schema for AskUserQuestion.
sdkPackage: '@anthropic-ai/claude-agent-sdk@0.3.168'
claudeCodeVersion: '2.1.168'
tool: "AskUserQuestion"
-->
# Tool Description: AskUserQuestion

## Metadata

- Request location: `tools[]`
- Tool name: `AskUserQuestion`
- Input schema properties: `questions`, `answers`, `annotations`, `metadata`

## Description

Use this tool only when you are blocked on a decision that is genuinely the user's to make: one you cannot resolve from the request, the code, or sensible defaults.

Usage notes:
- Users will always be able to select "Other" to provide custom text input
- Use multiSelect: true to allow multiple answers to be selected for a question
- If you recommend a specific option, make that the first option in the list and add "(Recommended)" at the end of the label

Plan mode note: To switch into plan mode, use EnterPlanMode (not this tool). Once in plan mode, use this tool to clarify requirements or choose between approaches BEFORE finalizing your plan. Do NOT use this tool to ask "Is my plan ready?", "Should I proceed?", or otherwise reference "the plan" in questions — the user cannot see the plan until you call ExitPlanMode for approval.

Reserve this for decisions where the user's answer changes what you do next — not for choices with a conventional default or facts you can verify in the codebase yourself. In those cases pick the obvious option, mention it in your response, and proceed.


## Input Schema

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "questions": {
      "description": "Questions to ask the user (1-4 questions)",
      "minItems": 1,
      "maxItems": 4,
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "question": {
            "description": "The complete question to ask the user. Should be clear, specific, and end with a question mark. Example: \"Which library should we use for date formatting?\" If multiSelect is true, phrase it accordingly, e.g. \"Which features do you want to enable?\"",
            "type": "string"
          },
          "header": {
            "description": "Very short label displayed as a chip/tag (max 12 chars). Examples: \"Auth method\", \"Library\", \"Approach\".",
            "type": "string"
          },
          "options": {
            "description": "The available choices for this question. Must have 2-4 options. Each option should be a distinct, mutually exclusive choice (unless multiSelect is enabled). There should be no 'Other' option, that will be provided automatically.",
            "minItems": 2,
            "maxItems": 4,
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "label": {
                  "description": "The display text for this option that the user will see and select. Should be concise (1-5 words) and clearly describe the choice.",
                  "type": "string"
                },
                "description": {
                  "description": "Explanation of what this option means or what will happen if chosen. Useful for providing context about trade-offs or implications.",
                  "type": "string"
                },
                "preview": {
                  "description": "Optional preview content rendered when this option is focused. Use for mockups, code snippets, or visual comparisons that help users compare options. See the tool description for the expected content format.",
                  "type": "string"
                }
              },
              "required": [
                "label",
                "description"
              ],
              "additionalProperties": false
            }
          },
          "multiSelect": {
            "description": "Set to true to allow the user to select multiple options instead of just one. Use when choices are not mutually exclusive.",
            "default": false,
            "type": "boolean"
          }
        },
        "required": [
          "question",
          "header",
          "options",
          "multiSelect"
        ],
        "additionalProperties": false
      }
    },
    "answers": {
      "description": "User answers collected by the permission component",
      "type": "object",
      "propertyNames": {
        "type": "string"
      },
      "additionalProperties": {
        "type": "string"
      }
    },
    "annotations": {
      "description": "Optional per-question annotations from the user (e.g., notes on preview selections). Keyed by question text.",
      "type": "object",
      "propertyNames": {
        "type": "string"
      },
      "additionalProperties": {
        "type": "object",
        "properties": {
          "preview": {
            "description": "The preview content of the selected option, if the question used previews.",
            "type": "string"
          },
          "notes": {
            "description": "Free-text notes the user added to their selection.",
            "type": "string"
          }
        },
        "additionalProperties": false
      }
    },
    "metadata": {
      "description": "Optional metadata for tracking and analytics purposes. Not displayed to user.",
      "type": "object",
      "properties": {
        "source": {
          "description": "Optional identifier for the source of this question (e.g., \"remember\" for /remember command). Used for analytics tracking.",
          "type": "string"
        }
      },
      "additionalProperties": false
    }
  },
  "required": [
    "questions"
  ],
  "additionalProperties": false
}
```

## Token Impact

<!-- TOKEN_COUNT_START -->
- Complete definition estimated tokens: **1,411**
- Measurement: captured tool object serialized independently as JSON text against the common baseline
- Additivity: independent, non-additive estimate
<!-- TOKEN_COUNT_END -->