Skip to main content

Ask User Questions

The Ask User Questions tool lets your AI Agent pause in the middle of a task and ask you a question — or a short series of questions — before continuing. It's the other flavour of Human-in-the-Loop alongside tool approval: instead of "approve this action?", it's "pick one of these options".

Use it when:

  • Your AI Agent found multiple matching records and needs to know which one.
  • Your AI Agent has a choice to make that only you can decide (for example which plan to put a customer on).
  • You want your AI Agent to confirm an assumption before it acts.

Don't use it for questions your AI Agent could answer itself from context, or for simple open-ended replies — at that point, plain chat is fine.

Add the tool to your AI Agent​

  1. Open your AI Agent → Tools tab.
  2. Click Add Tool and pick Ask User Questions.
  3. Give the tool a name and a description (see writing a good description).
  4. Click Save.

That's all the configuration you need. The tool generates the question content at runtime — you don't configure a fixed question list.

info

You generally don't need Requires Human Approval Before Execution on Ask User Questions itself. The tool is inherently interactive — it always pauses for you — so approval would be redundant.

Writing a good description​

The tool description tells your AI Agent when to use Ask User Questions. A weak description means your AI Agent never reaches for it; a strong one means it uses the tool at exactly the right moments.

Good description:

Use this tool when you need the user to make a choice before you proceed. Examples: selecting between multiple matching records, confirming a destructive action the user hasn't explicitly asked for, or collecting structured preferences. Bundle related choices into one call rather than pausing repeatedly.

Weak description:

Ask user questions.

The first tells your AI Agent when and how often to pause. The second leaves it guessing.

Question types​

Each question your AI Agent generates is one of two shapes:

  • Single choice — a list of options; the user picks exactly one.
  • Multi-choice — a list of options; the user ticks zero, one, or many.

Questions can optionally include an Other option. When the user selects Other, a free-text field appears so they can type their own answer.

From the user's side, questions are answered one at a time in a wizard-style UI. See Answer AI Agent questions for what that looks like.

Example scenarios​

CRM disambiguation​

User: "Update Sarah's phone number to 555-0123."

AI Agent (via Ask User Questions, single choice): "I found two contacts named Sarah. Which one did you mean?"

Scoped update​

User: "Update the Acme Corp contact."

AI Agent (multi-choice): "Which fields should I update?"

  • ☑ Email
  • ☐ Phone
  • ☐ Job title

Destructive confirmation​

User: "Clean up duplicate contacts."

AI Agent (single choice): "I found 12 duplicates. Before I delete them, should I:"

  • Merge into the oldest contact
  • Merge into the newest contact
  • Only delete exact email matches

Pair this with Requires Human Approval Before Execution on the actual delete tool for two layers of safety.

Combining with tool approval​

Ask User Questions and tool approval solve different problems. They compose well:

  • Ask User Questions — before a decision, to disambiguate.
  • Tool approval — after the decision, to confirm the specific action.

Example: your AI Agent uses Ask User Questions to confirm which of three contacts to update, then pauses again for approval on the Update Contact tool with the exact payload. Two pauses, both necessary — one is "which one?", the other is "do this exact thing?".

Where pending questions show up​

Questions cards behave like approvals:

  • They appear in the chat as a wizard the user walks through.
  • They also show up on the Dashboard in the Pending Approvals tab so you can answer them without digging for the right conversation.

Limits​

DetailValue
Min questions per call1
Max questions per call4
Min options per single/multi-choice question2
Max options per single/multi-choice question4
Card timeoutNone — waits indefinitely.

If your AI Agent needs more than four questions, ask it to split them across two separate calls instead.