ask_user
Resolve ambiguity or gather user preferences by bundling 1-3 questions into one form. Supports single/multi-select with auto-injected 'Other'.
Instructions
Ask the user 1-3 questions in a single form. Each question has its own options and can be single- or multi-select. Bundle related decisions in ONE call instead of multiple turns.
Use when:
The prompt is ambiguous on multiple dimensions (audience + aesthetic + length) — bundle them into one form
You need a decision before proceeding (delete existing? which section first?)
Multiple valid approaches exist and user preference matters
Returns one of:
{ answers: [...] } — array indexed to questions order. string for single-select, string[] for multi-select. The string MAY be one of the option labels OR custom text the user typed via the auto-injected "Other..." option.
{ freeText: "..." } — when the user typed a free-form answer in the chat input instead of submitting the form. Treat as authoritative — user is overriding the structured options.
Each question:
question: required prompt string. Self-contained — no separate header/label, the question text IS the heading.
options: 2-3 options, each { label, description? }. The form auto-injects an "Other..." row, so the user always sees options.length + 1 rows total — keep options ≤ 3 to stay within the 4-row visual cap.
multiSelect: optional boolean (default false). Use only when the answer is genuinely a list (e.g. "which features?"). For mutually exclusive choices keep false.
Conventions:
First option = recommended. If you have a strong default for the user, put it FIRST and add "(Recommended)" at the end of the label. The form auto-focuses the first option and the dev/auto-pick fallback selects it — both work better with a deliberate recommendation.
Do NOT include an "Other" option yourself — the form auto-injects an "Other..." row per question with an inline text input. Don't add a redundant one.
Bundle aggressively. 2 related dimensions in ONE call beats 2 sequential turns.
Example: ask_user({ questions: [ { question: "Who is this for?", options: [{label:"B2B SaaS"},{label:"Consumer"},{label:"Developer tool"}] }, { question: "What visual direction?", options: [{label:"Minimal"},{label:"Bold/Brutalist"},{label:"Neon/Cyber"}] } ]})
Skip when the prompt is already actionable — asking adds a turn and costs momentum.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| questions | Yes | 1-3 questions to present in a single form (3 is the soft cap; bundle related decisions but don't pad). |