Read-Write Ambiguity Resolution Prompt

This prompt is designed for a specific and dangerous failure mode in AI copilots and agents: a user request is underspecified, and the system must decide whether to retrieve data or modify it. Guessing wrong can corrupt state, expose sensitive information, or violate compliance boundaries. The job-to-be-done is not tool selection or execution. It is the generation of ranked, neutral clarification questions that help a downstream system or UI resolve the ambiguity without leading the user toward a write operation. The ideal user is a product team building a copilot where the default user phrasing is ambiguous, and where the cost of a mistaken write is high.

Use this prompt when a user's natural language request could reasonably map to either a read-only tool (e.g., get_customer_record) or a write tool (e.g., update_customer_address). Common triggers include verbs like 'handle,' 'take care of,' 'fix,' or 'update' when the object of the action is unclear, or when the user references a record without specifying whether they want to view or change it. The prompt expects [USER_REQUEST] and [AVAILABLE_TOOL_DESCRIPTIONS] as inputs, and it produces a ranked list of clarification options. It does not select a tool, execute a call, or enforce authorization. Its only output is the clarification structure that a UI can render as buttons, quick replies, or a follow-up message.

Do not use this prompt when the user's intent is already unambiguous, when the system has a hard policy to always default to read-only and inform the user, or when latency constraints require immediate tool selection without a clarification round-trip. It is also inappropriate for systems where all tools are read-only or where write operations are fully reversible and low-risk. In high-risk domains such as healthcare, finance, or infrastructure control, this prompt should be paired with a human approval step before any write operation executes, even after intent is clarified. The clarification questions themselves must be audited for bias: a question like 'Would you like to delete this record?' leads the user, while 'Would you like to view this record or delete it?' preserves neutrality. Build eval checks that measure whether clarification options are balanced in their presentation of read and write paths.

This prompt template is designed to be placed in your system instructions or used as a pre-tool-selection clarification step. When a user request could map to either a read-only data retrieval tool or a write tool that produces side effects, the model generates clarifying questions that disambiguate intent without nudging the user toward any particular action. The output is a ranked list of clarification options, each with a neutral phrasing score, so your application can present choices to the user or automatically select the highest-confidence clarification.

textCopy
You are a clarification assistant that resolves ambiguity between read-only and write operations. Your job is to detect when a user request could be fulfilled by either a read tool or a write tool, and to generate neutral clarifying questions that help disambiguate intent.

## INPUT
User request: [USER_REQUEST]
Available tools with operation types:
[TOOL_CATALOG]

## TOOL CATALOG FORMAT
Each tool is described as:
- tool_name: string
- operation_type: "read" | "write" | "read_write"
- description: string
- parameters: list of parameter schemas

## CONSTRAINTS
1. Do NOT select a tool. Only generate clarification questions.
2. Questions must be neutral. Do not phrase questions that assume or nudge toward a write operation.
3. If the user request is unambiguously read-only, return an empty clarifications list and set "ambiguous": false.
4. If the user request is unambiguously a write, return an empty clarifications list and set "ambiguous": false.
5. If the request could map to both read and write tools, set "ambiguous": true and generate 1-3 clarification questions.
6. Each question must be self-contained and answerable with a short response.
7. Rank questions by how effectively they resolve the ambiguity. The first question should provide the most disambiguation value.
8. Do not ask questions that the user has already answered in their request.

## OUTPUT SCHEMA
Return a JSON object with this exact structure:
{
  "ambiguous": boolean,
  "reasoning": "Brief explanation of why the request is or is not ambiguous.",
  "clarifications": [
    {
      "rank": integer starting at 1,
      "question": "The neutral clarifying question.",
      "resolves_to": "read" | "write" | "either",
      "neutrality_check": "Explanation of why this question does not bias toward read or write."
    }
  ]
}

## EXAMPLES

Example 1: Ambiguous request
User request: "Show me the customer list"
Tools: [{"tool_name": "list_customers", "operation_type": "read"}, {"tool_name": "export_customers_csv", "operation_type": "write"}]
Output:
{
  "ambiguous": true,
  "reasoning": "The user asked to see a customer list. This could mean display on screen or export to a file.",
  "clarifications": [
    {
      "rank": 1,
      "question": "Would you like to view the customer list on screen or export it to a file?",
      "resolves_to": "either",
      "neutrality_check": "Both options are presented equally without favoring one."
    }
  ]
}

Example 2: Unambiguous read
User request: "How many customers signed up this week?"
Tools: [{"tool_name": "count_customers", "operation_type": "read"}, {"tool_name": "delete_customer", "operation_type": "write"}]
Output:
{
  "ambiguous": false,
  "reasoning": "The user is asking for a count, which is a read-only operation. No write tool matches this intent.",
  "clarifications": []
}

## RISK LEVEL
[RISK_LEVEL]

If RISK_LEVEL is "high", add an additional field "requires_human_approval": true to the output and include a note explaining why human review is recommended before presenting clarifications to the user.

To adapt this prompt, replace [USER_REQUEST] with the incoming user message, [TOOL_CATALOG] with your structured tool definitions including operation types, and [RISK_LEVEL] with either "low", "medium", or "high". For high-risk domains such as finance, healthcare, or destructive data operations, set [RISK_LEVEL] to "high" to enable the human-approval flag. The output schema is designed to be parsed by your application's clarification UI or fed into a downstream tool-selection step once the user responds. Before deploying, test this prompt against a golden set of ambiguous and unambiguous requests to verify that the neutrality check field correctly identifies biased phrasing.

The Read-Write Ambiguity Resolution Prompt is designed to sit between intent classification and tool execution. When a user request receives a low-confidence classification or an explicit 'ambiguous' label from an upstream read-vs-write classifier, this prompt generates ranked clarification questions. The harness must treat this prompt as a decision-support component, not an autonomous actor. The model proposes clarification options; the application decides whether to surface them to the user, re-route to a human, or default to a safe read-only path based on product policy.

Integration flow: (1) An upstream classifier labels the user request as ambiguous with a confidence score below your threshold. (2) The harness injects the original user request into [USER_REQUEST], the available tool catalog into [TOOL_CATALOG] (with each tool's operation type, description, and side-effect profile), and any conversation context into [CONVERSATION_CONTEXT]. (3) The model returns a structured JSON array of clarification options, each with a question string, a resolves_to field indicating whether the answer would lead to a read or write path, and a leading_score (0-1) where lower is better. (4) Post-processing validation checks that: no leading_score exceeds 0.3 (reject biased questions), at least one read-resolving and one write-resolving option exists (confirming genuine ambiguity), and no question contains imperative language like 'go ahead and' or 'just confirm' that nudges toward writes. Questions failing validation are dropped; if fewer than two valid options remain, the harness escalates to a human reviewer rather than presenting a single leading question.

Model choice and latency: This prompt benefits from models with strong instruction-following and structured output capabilities. GPT-4o, Claude 3.5 Sonnet, and Gemini 1.5 Pro all perform well. Latency is typically under 800ms, making this suitable for synchronous chat flows. For high-throughput systems, consider caching clarification templates for common ambiguity patterns (e.g., 'view vs. edit,' 'preview vs. publish') and only invoking the model for novel requests. Logging requirements: Every invocation must log the original user request, the upstream classifier's confidence score, the generated clarification options with their leading_score values, which options were surfaced to the user, and the user's selection. This audit trail is essential for detecting systemic bias toward write operations and for defending tool-selection decisions during security reviews. Retry policy: If the model returns malformed JSON or fails validation, retry once with the same inputs and an added [CONSTRAINTS] field explicitly listing the validation rules that failed. If the second attempt also fails, fall back to a static clarification template: 'Would you like to view or modify [RESOURCE]?' and flag the interaction for review.

What to avoid: Do not use this prompt as the sole gate before write operations. It generates clarification questions, not authorization decisions. A separate confirmation gate (see the Write Operation Confirmation Prompt Template) must still execute before any write tool is called, even after the user selects a write-resolving clarification path. Do not skip the leading_score validation—biased clarification questions are the primary failure mode, and they compound over conversational turns. Finally, never present clarification options that all resolve to the same operation type; if the model fails to generate genuine alternatives, the harness must escalate rather than pretend ambiguity exists.