Ambiguous Request Clarification vs Tool Call Decision Prompt

This prompt is for product teams building conversational agents that must decide, in a single step, whether to ask the user for clarification or proceed with a tool call. The core job is binary classification: given a user request that could map to multiple tools, the prompt forces a clarify or proceed decision with explicit reasoning. The ideal user is an AI engineer or product lead who needs to reduce silent wrong-tool execution by making ambiguity explicit before any function is invoked. Required context includes the user's raw input, the full set of available tool definitions with their descriptions, and any conversation history that might disambiguate intent.

Use this prompt when your system has tools with overlapping capabilities—such as search_knowledge_base and search_ticket_history—and user requests like 'find my recent issues' could reasonably trigger either. The prompt is designed for pre-execution gating: it runs before any tool is called, not after a failure. It is most valuable in customer-facing systems where a wrong tool call produces a visible error or a confusing response that erodes trust. Do not use this prompt when the tool set is small and non-overlapping, when latency constraints prohibit an extra model round-trip, or when you already have a deterministic router that can resolve ambiguity through keyword matching or user profile data. In those cases, the prompt adds cost without reducing risk.

The prompt requires careful eval design. You must measure two competing failure modes: the unnecessary clarification rate (asking the user to disambiguate when the intent was actually clear) and the wrong-tool selection rate (proceeding with a tool call that turns out to be incorrect). These metrics trade off against each other, and the right threshold depends on your product's tolerance for friction versus errors. Before deploying, build a golden dataset of at least 50 examples spanning clear single-tool intents, genuinely ambiguous requests, and edge cases where context from conversation history should resolve the ambiguity. Run the prompt against this dataset and tune the decision boundary by adjusting the system instructions, not by modifying the prompt template itself. If you cannot achieve both an unnecessary clarification rate below 15% and a wrong-tool selection rate below 5%, consider adding a confidence scoring layer or routing ambiguous cases to human review instead of forcing a binary decision.

This template is the core decision engine for your conversational agent. It receives a user request and a list of available tools, then produces a single, auditable output: either a tool call with arguments or a clarification question. The prompt is designed to be strict. It must not guess, silently default to the most popular tool, or call a tool with hallucinated arguments. The output schema includes a decision field ("clarify" or "proceed"), a reasoning string, and, if proceeding, a tool_call object. This structure makes the decision testable and traceable in logs, which is essential for measuring unnecessary clarification rates and wrong-tool selection rates.

textCopy
SYSTEM:
You are a tool-selection router in a production AI system. Your only job is to decide whether a user request can be safely routed to a single tool or requires clarification.

You have access to the following tools:
[TOOLS]

RULES:
1. If exactly one tool clearly matches the user's intent AND all required arguments for that tool are present or can be safely defaulted from context, respond with `"decision": "proceed"` and include the `tool_call`.
2. If zero tools match, respond with `"decision": "clarify"` and ask what the user wants to do.
3. If multiple tools match AND you cannot determine which one the user intends, respond with `"decision": "clarify"`. List the ambiguous tools and ask a specific disambiguating question.
4. If one tool matches but a required argument is missing and cannot be safely defaulted, respond with `"decision": "clarify"` and ask only for the missing argument.
5. Never call a tool with made-up or assumed argument values.
6. Never call a write, delete, or execute tool (any tool tagged `risk: high`) if confidence is not explicit.

OUTPUT SCHEMA:
{
  "decision": "clarify" | "proceed",
  "reasoning": "string explaining which tools matched, which didn't, and why the decision was made",
  "clarification_question": "string, only if decision is clarify",
  "ambiguous_tools": ["tool_name"],
  "tool_call": {
    "name": "string",
    "arguments": {}
  }
}

USER REQUEST:
[INPUT]

CONTEXT (conversation history, user profile, document data):
[CONTEXT]

To adapt this template, replace [TOOLS] with your actual function definitions in JSON Schema format. The model needs parameter names, types, descriptions, and required fields to make accurate argument-filling decisions. If you have a risk taxonomy, add a risk field to each tool definition and enforce Rule 6. Replace [INPUT] with the current user utterance. Replace [CONTEXT] with any retrieved information, conversation history, or user profile data that could help disambiguate intent or supply default argument values. If no context exists, pass an empty object. For high-stakes domains like healthcare or finance, add a [RISK_LEVEL] placeholder and a rule that forces "clarify" for any tool tagged above a certain threshold. The output schema is deliberately flat to simplify parsing; do not nest tool_call inside conditional blocks. After copying, run this prompt against your golden eval set of ambiguous and unambiguous requests to measure the unnecessary clarification rate and wrong-tool selection rate before shipping.

This prompt operates as a pre-execution gate in your tool-calling pipeline. Before any tool is invoked, the user's request passes through this prompt to produce a binary decision: clarify or proceed. The proceed path includes the selected tool and arguments; the clarify path includes the specific question to ask the user. Wire this prompt as a synchronous step after intent detection but before tool dispatch. The model call should be made with temperature=0 to maximize decision stability, and you should set a low max_tokens value (around 300–500) since the output is a compact JSON decision object, not a conversational response.

Validation and retry logic is critical here because a malformed decision can silently skip the gate. Implement a JSON schema validator that checks for the required fields: decision (enum: clarify or proceed), reasoning (string), and conditional fields clarification_question (required when decision=clarify) and selected_tool plus arguments (required when decision=proceed). If validation fails, retry the prompt once with the validation error appended to the system message. If the second attempt also fails, default to the clarify path with a generic fallback question and log the failure as a gate_validation_error for immediate review. Never silently proceed to tool execution when the gate output is unparseable.

Observability and logging should capture the full decision trace: the raw user input, the model's JSON output, the validation result, and the final routing action. Log the reasoning field alongside your application-level metrics so you can audit why the model chose to clarify or proceed. Track two primary eval metrics in production: unnecessary clarification rate (how often the model asks for clarification when the user's request was actually unambiguous) and wrong-tool selection rate (how often the model proceeds but selects the incorrect tool). Both metrics require human annotation or a separate judge model comparing the decision against ground-truth labels. If either rate exceeds your threshold, escalate to prompt revision or model upgrade before the gate silently degrades user experience.