Ambiguity Detection Prompt for User Queries

This prompt is designed for a specific job: classifying user queries for ambiguity before they reach downstream systems that assume clear intent. It detects four ambiguity types—referential (unclear pronouns or references), scope (unclear boundaries of the request), intent (unclear goal), and entity (unclear named objects)—and assigns a severity score. The primary user is a developer or AI engineer building a pipeline where ambiguous inputs cause expensive, silent failures: a RAG system retrieving irrelevant documents, a tool-calling agent executing a destructive action based on a guess, or a support routing queue sending a ticket to the wrong team. The prompt acts as a guard, enabling your application to decide whether to proceed, ask for clarification, or escalate to a human.

Integrate this prompt as a synchronous pre-processing step in any non-trivial AI pipeline. For a RAG system, place it after user input and before retrieval query construction; if the ambiguity score is high, return a clarification request instead of a hallucinated answer. For an agent with tool access, run this check before the planning step to prevent the agent from inventing missing parameters. The prompt is most valuable when the cost of a wrong action is high—think financial transactions, medical information retrieval, or destructive database operations. It is less useful in exploratory, real-time chat where users expect a fast, conversational flow and can easily correct the model in the next turn. In those cases, the latency added by the classification step and the interruption of a clarification request may degrade the user experience more than a minor misinterpretation.

Do not use this prompt when the model has no context to judge ambiguity. For example, in a completely open-domain chatbot with no defined task, almost every query could be considered ambiguous in some way, leading to a high false-positive rate and a frustrating user experience. The prompt's effectiveness is directly tied to a well-defined [CONTEXT] block that specifies the system's purpose and the user's expected tasks. Before deploying, run a targeted evaluation: collect a set of genuinely ambiguous queries that previously broke your system and a set of clear queries that should pass through. Measure the prompt's precision and recall on this dataset. The primary failure mode is a false negative—an ambiguous query that slips through with a low severity score, which you can mitigate by tuning the severity thresholds in your application logic and monitoring downstream error rates.

This prompt template is designed to be dropped directly into a classification step before any retrieval, routing, or agent execution. It forces the model to act as a pure classifier, returning structured JSON without answering the user's question. The template uses square-bracket placeholders that your application must populate at runtime: [USER_QUERY] for the raw input, [CONVERSATION_CONTEXT] for prior turns if available, and [DOMAIN_CONTEXT] for any system-level framing that helps disambiguate references. The output schema is strict, making it safe to parse programmatically before deciding whether to proceed, clarify, or escalate.

textCopy
Classify the user query below for ambiguity. Return a JSON object with the ambiguity type, severity score, and a brief explanation. Do not answer the query. Do not ask the user for clarification. Only classify.

Ambiguity types:
- referential: unclear what a pronoun, reference, or entity points to
- scope: unclear boundaries, time ranges, or inclusion criteria
- intent: unclear what action or outcome the user wants
- entity: unclear which specific person, product, account, or item is meant

Severity levels:
- none: the query is unambiguous
- low: minor ambiguity that downstream systems can likely resolve
- medium: ambiguity that may cause incorrect downstream results
- high: ambiguity that makes the query unanswerable without clarification

User query: [USER_QUERY]

Conversation context (if available): [CONVERSATION_CONTEXT]

Domain context (optional): [DOMAIN_CONTEXT]

Return ONLY valid JSON with this exact schema:
{
  "ambiguity_type": "referential" | "scope" | "intent" | "entity" | "none",
  "severity": "none" | "low" | "medium" | "high",
  "explanation": "string explaining the classification",
  "ambiguous_span": "the specific text that is ambiguous, or null if none"
}

To adapt this template, start by populating [DOMAIN_CONTEXT] with a short description of your system's scope—for example, "This is a customer support system for a payment processing platform." This helps the model resolve entity references like "my last transaction" against a known domain. If you have multi-turn conversations, pass the last 3-5 messages as [CONVERSATION_CONTEXT] so the model can resolve pronouns like "it" or "that one" against prior turns. For single-turn systems, set [CONVERSATION_CONTEXT] to "No prior conversation." The ambiguous_span field is critical for debugging: it tells you exactly which substring triggered the classification, letting you build targeted clarification prompts or log patterns for prompt improvement. Validate the output against the schema before routing—reject any response that doesn't parse as valid JSON with all required fields. For high-severity ambiguity, route to a clarification prompt or human queue rather than attempting downstream processing.

The Ambiguity Detection Prompt is not a standalone classifier; it is a synchronous pre-processing gate that must execute after user input is received but before any downstream retrieval, tool selection, or agent planning. Its job is to prevent ambiguous queries from reaching expensive or stateful systems where failure is harder to diagnose. Call this prompt immediately after input ingestion, parse the JSON response, and branch on the severity field. Queries classified as none or low can proceed directly to the main pipeline. A medium severity should trigger a clarification request back to the user or attach a confidence flag to the downstream context so subsequent steps can adjust their behavior. A high severity must stop the pipeline entirely—either by asking the user to rephrase or by escalating to a human review queue. Do not expose the raw classification fields (ambiguity_type, severity, reasoning) to end users; these are system-internal signals that drive routing and observability, not user-facing explanations.

Log the full classification payload—including ambiguity_type, severity, and the model's reasoning string—as structured metadata on every request. This is critical for observability: you need to know how often ambiguous queries reach your system, which types dominate, and whether your severity thresholds are calibrated correctly. If the model returns malformed JSON, retry once with a repair prompt that includes the raw output and a request to fix the parse error. If the second attempt also fails, treat the query as severity: "medium" and route to clarification. The most dangerous failure mode is a false negative: a query classified as none that downstream systems cannot handle. Capture every instance where a none-classified query produces a downstream error, empty result, or hallucinated response. Log these as false negatives and use them to build an eval set for prompt improvement. Over time, this feedback loop will tighten the boundary between safe autonomous processing and queries that need human intervention.

Model choice matters here. Use a fast, inexpensive model for this gate—the goal is low latency and high recall on ambiguity, not deep reasoning. A lightweight model like GPT-4o-mini, Claude Haiku, or a fine-tuned small classifier works well. Set a short timeout (under 2 seconds) and a retry budget of one. If the ambiguity detector itself times out or fails, fail open by routing to clarification rather than blocking the user. For high-throughput systems, consider caching classifications for identical or near-identical queries to reduce cost and latency. When wiring this into an agent harness, ensure the ambiguity check runs before any tool authorization or state mutation—you do not want an ambiguous query to trigger a destructive action. Finally, periodically review the distribution of severity classifications against human-labeled samples to detect drift in the model's sensitivity, and adjust your routing thresholds accordingly.