User Intent Disambiguation Prompt Template

This prompt is a planning pre-processor for conversational agents that encounter ambiguous, underspecified, or conflicting user instructions. Its job is to prevent the agent from executing a wrong or irreversible action by generating a ranked set of targeted clarification questions before task decomposition or tool selection begins. The ideal user is an AI engineer building an agent frontend where the cost of a wrong action—such as modifying a database, sending a customer-facing email, or executing a multi-step workflow with side effects—is higher than the cost of asking one or two clarifying questions. You should wire this prompt into the agent's intake layer, after initial input parsing but before the planning module commits to a sequence of tool calls.

When to use this prompt: The primary trigger is an instruction that contains multiple valid interpretations, lacks critical parameters (e.g., 'update the account' without specifying which account or what field), or presents conflicting constraints (e.g., 'send the report to everyone but keep it confidential'). It is also appropriate when the user's stated goal implies a high-risk action class—such as DELETE, SEND, DEPLOY, or TRANSFER—and the agent's policy requires explicit confirmation of intent. Use it when your agent has access to tools that produce irreversible side effects, when the user's request spans multiple domains that may have conflicting requirements, or when the agent's confidence in its interpretation falls below a defined threshold. When not to use this prompt: Do not use it for simple, unambiguous requests where clarification would add unnecessary friction (e.g., 'what's the weather in London?'). Avoid it in latency-sensitive, non-interactive batch pipelines where there is no user to answer questions. Do not use it as a substitute for proper tool schema design; if your tools have well-defined required parameters, let the model's function-calling mechanics handle missing arguments directly rather than routing through a separate disambiguation prompt. Finally, do not use this prompt when the agent's policy permits safe default assumptions with transparent communication—asking 'I'll assume you mean the production database, is that correct?' is sometimes better than a multi-question clarification interview.

Implementation context: This prompt belongs in the agent frontend or planning pre-processor layer. In a typical architecture, user input flows through a router that classifies the request's ambiguity and risk level. If the router flags the input as ambiguous or high-risk, it invokes this disambiguation prompt. The output is a ranked list of clarification questions, which the system presents to the user. The user's responses are then merged back into the original instruction before it proceeds to task decomposition. What to do next: After implementing this prompt, pair it with an eval harness that measures whether the generated questions actually resolve ambiguity—track the number of back-and-forth turns before execution begins, and compare against a baseline of agents that skip disambiguation. The most common failure mode is generating questions that are technically valid but low-impact, wasting user attention on details that don't change the execution plan. Your eval should flag questions that, when answered, produce no material change in the agent's subsequent actions.

This prompt template is designed to be the core instruction set for a conversational agent's disambiguation module. When a user's initial request is too vague, contradictory, or missing critical parameters for execution, this prompt forces the model to act as a diagnostic analyst. Instead of guessing or executing a flawed plan, the model will produce a ranked list of clarification questions. The goal is to resolve the ambiguity with the minimum number of user-facing questions, focusing only on what is necessary to unblock execution. The template uses square-bracket placeholders so you can inject the specific user input, the agent's available capabilities, and your risk tolerance before each call.

textCopy
You are an intent disambiguation specialist. Your role is to analyze a user's request and identify any ambiguities, missing constraints, or conflicting instructions that would prevent a downstream agent from executing the task correctly.

## User Request
[USER_INPUT]

## Available Capabilities
[AVAILABLE_TOOLS_AND_ACTIONS]

## Risk Profile
[RISK_LEVEL: low | medium | high]

## Instructions
1.  **Analyze the request:** Identify all points of ambiguity. Consider scope, desired output format, success criteria, constraints (time, cost, data sensitivity), and any conflicting instructions.
2.  **Rank by impact:** Prioritize the ambiguities based on how severely they would impact execution. A question about a destructive action is higher priority than a question about formatting.
3.  **Generate questions:** For each critical ambiguity, formulate a single, clear, and closed-ended question where possible. Each question must be answerable without requiring the user to understand the system's internal architecture.
4.  **Provide context:** For each question, briefly explain why the answer is necessary for successful task completion.
5.  **Respect the risk profile:**
    *   If [RISK_LEVEL] is 'high', generate questions for even minor ambiguities and always ask for confirmation before any state-changing action.
    *   If [RISK_LEVEL] is 'medium', focus on ambiguities that could lead to incorrect results or wasted resources.
    *   If [RISK_LEVEL] is 'low', only ask about blocking ambiguities that make execution impossible.
6.  **Output format:** Return a JSON object with a single key "clarification_questions" containing an array of objects. Each object must have the keys "priority" (integer, 1 is highest), "question" (string), and "context" (string). If the request is perfectly clear and executable, return an empty array.

## Examples of Ambiguity
*   **Scope:** "Clean up the database" (Which records? Which tables? Drop or archive?)
*   **Conflict:** "Delete the user but keep their purchase history." (Cascade vs. anonymize?)
*   **Missing Constraint:** "Generate a report." (What format? What time period? What metrics?)
*   **Irreversible Action:** "Shut down the production server." (Confirmation required, even if clear.)

## Output JSON Schema
{
  "clarification_questions": [
    {
      "priority": "number",
      "question": "string",
      "context": "string"
    }
  ]
}

To adapt this template, start by replacing the [USER_INPUT] placeholder with the raw, unmodified text from the user. The [AVAILABLE_TOOLS_AND_ACTIONS] placeholder should be a concise, structured list of what the downstream agent can actually do—this prevents the disambiguation model from asking questions about impossible actions. The [RISK_LEVEL] parameter is a critical control; wire it to a configuration variable in your application so product owners can adjust the agent's assertiveness without changing the prompt text. For high-stakes domains like healthcare or finance, always set the risk level to 'high' and consider adding a final human review step before any clarification questions are sent to the user. You can also extend the Output JSON Schema to include a requires_human_approval boolean field for each question if your workflow demands it.

This prompt is designed to be called as a pre-processing step inside a conversational agent loop, not as a standalone chat interface. When the primary agent detects an ambiguous or conflicting user instruction—either through a dedicated classifier or by observing low-confidence tool calls—it should invoke this disambiguation prompt with the full conversation history, the current proposed plan, and the specific points of ambiguity. The output is a ranked list of clarification questions that the agent can present to the user before proceeding. The prompt should be treated as a structured API call: you provide the required inputs, receive a JSON response, validate it, and then decide whether to surface the questions to the user or escalate for human review.

To wire this into an application, wrap the prompt in a function that accepts [CONVERSATION_HISTORY], [CURRENT_GOAL], [AMBIGUITY_POINTS], and [CONSTRAINTS] as arguments. The function should call the model with response_format set to JSON and enforce the output schema on the application side. Implement a validation layer that checks: (1) the response is valid JSON, (2) the questions array is non-empty, (3) each question has a non-empty question_text and a valid impact_rank integer, and (4) the resolution_criteria field is present for each question. If validation fails, retry once with the same inputs and an explicit error message appended to the prompt. If the retry also fails, log the failure and escalate to a human operator rather than presenting broken output to the user. For high-stakes domains such as healthcare, finance, or legal, always route the generated questions through a human reviewer before they reach the end user, even if validation passes.

Model choice matters here. Use a model with strong instruction-following and JSON output capabilities, such as GPT-4o, Claude 3.5 Sonnet, or Gemini 1.5 Pro. Avoid smaller or older models that may produce plausible-sounding but irrelevant questions or fail to adhere to the output schema. Set temperature to 0.2 or lower to reduce variance in question generation. For latency-sensitive applications, cache the prompt prefix (the system instructions and output schema) to reduce time-to-first-token. Log every invocation with the input conversation context, the generated questions, the validation result, and whether the questions were shown to the user or escalated. This audit trail is essential for debugging cases where the agent asked unnecessary questions or missed a critical ambiguity. Finally, integrate the user's answers back into the agent's context window as resolved clarifications, and re-run the planning step with the disambiguated goal before executing any irreversible actions.