Question Tool
The ask-user prompt. Takes over the composer card or sits inline as a transcript card.
Kinds
Single choice, multi choice, and free text. Choice prompts include an Other
field unless allowCustomAnswer is false. A choice question with
layout: 'grid' fills two columns with short, label-only options.
Single choice
Multi choice
Free text
Two columns
States
A multi-step prompt, the compact prompt, the standalone card used in a
transcript, and a completed card. compact replaces the footer with a header
pager and a trailing Skip or Next; pass it to promptSlot on a compact
composer. Once answered, the card shows a one-line summary. The composer
variant has no summary; it stays disabled until the host removes it.
Multi-step
Compact
Ask a question…
Card
Question
Which brand should this agent use?
Completed card
Usage
QuestionTool is presentational. Product chats own submit, skip, and
multi-question navigation, then pass the result in. If a submit handler
throws or rejects, the tool shows an error and keeps the answer editable.
QuestionTool Properties
Prompt list. Each item is single, multi, or text. See QuestionConfig below.
1-based index when the host owns navigation. Omit to let the card step locally.
Progress denominator. Defaults to questions.length.
Resets local drafts when the host starts a new tool call.
Completed answer from the host. Marks a single-question prompt done.
Composer fills the takeover slot. Card is the inline transcript treatment.
Default: card
Composer only. A header pager and a trailing Skip/Next replace the footer, and choices start unselected.
Default: false
Disables the prompt while host-owned work is still pending.
Default: false
Host stream status. Disables the card variant while streaming. Ignored for composer.
Shows the skip action.
Default: true
Primary action on the last question.
Primary action on earlier questions in a multi-step prompt.
Skip action copy.
Summary text for a skipped question on a completed card.
Default: Skipped
Called with the last answer, or the only answer on a single prompt. May return a promise.
Called with every answer, keyed by 1-based index, when the last question in a multi-step prompt is submitted. May return a promise.
Called when the user advances to the next question.
Called when the user goes back a question.
Replaces the composer header's step counter on multi-step prompts.
Extra classes on the card frame.
Extra classes on the scrollable choices list, e.g. a scroll edge fade.
Where the composer variant shows the active question's title. `step` keeps it inside the animated step so it crossfades and resizes with the choices.
Default: 'header'
QuestionConfig
Question type
Question text
Stable id for the question
Choices for single and multi questions. Each has id, label, and an optional description.
Grid fills two columns top to bottom with short, label-only options; the Other field spans both. Described options always render as a list.
Default: list
Shows the Other field. False submits only offered ids.
Default: true
Placeholder for the Other field when customPlaceholder is not set
Placeholder for the Other field
Fewest picks needed to submit
Default: 1
Most picks allowed
Multi only. Picks are ranked in order and each badge shows its rank. With maxSelections, the rest lock once that many are picked.
Ids selected when the question opens. Defaults to the first option; compact questions open empty.
Placeholder for a text question