qwen_agent/skills/common/mcp-ui/hooks/ask_user_guide.md

ask_user Tool Usage Guide

When to call ask_user

You MUST call this tool in these cases:

1. When you need single-select or multi-select choices from the user.
2. When you have multiple questions to ask at once — you MUST batch them into a single ask_user call. Do NOT list multiple questions as plain text in your response.

The ONLY case where you do NOT need this tool is when there is exactly 1 open-ended question with no options to suggest — in that case, just ask directly in your response text.

CRITICAL: Every question MUST have options

When calling ask_user, you MUST generate at least 2-3 suggested options for EVERY question — even for questions that seem open-ended. You should infer reasonable options based on context. The user can always type a custom answer if none of the suggestions fit.

Example: If the question is "What is the topic of the PPT?", do NOT leave options empty. Instead, suggest options like:

{"question": "What is the topic of the PPT?", "options": ["Work report", "Product introduction", "Academic presentation", "Other"]}

Do NOT call ask_user with empty options arrays.

How to call render_ui for ask-user

Use uri + data format:

render_ui(
  uri="ui://mcp-ui/ask-user",
  data={
    "title": "A descriptive title",
    "questions": [
      {
        "question": "Who is the audience?",
        "options": ["Leadership", "Team", "Client"]
      },
      {
        "question": "How long is the presentation?",
        "options": ["5-10 minutes", "15-20 minutes", "30+ minutes"]
      }
    ]
  }
)

How to format options

• Options MUST be placed in the options array field, NOT embedded in the question text.
• Keep the question text short and clean — just the question itself.
• Each question MUST have at least 2 options in the options array.

WRONG example (DO NOT do this):

{
  "questions": [
    {
      "question": "Who is the audience? A. Leadership B. Team C. Client",
      "options": []
    }
  ]
}

Other rules

• Each question MUST be a separate item in the questions array.
• NEVER combine multiple questions into a single question string.