Multi-Tool Ambiguity Refusal Prompt Template

This prompt is for agent infrastructure engineers who manage tool catalogs where multiple tools have overlapping or semantically similar capabilities. The job-to-be-done is producing a structured refusal when the model cannot confidently disambiguate between two or more candidate tools for a given user request. Instead of silently selecting the wrong tool—a failure mode that corrupts downstream state and is hard to detect in logs—the model returns a ranked list of candidates and the specific piece of missing information that would resolve the ambiguity. This turns a potential execution error into a recoverable clarification or review event.

Use this prompt when your system exposes tools that share functional boundaries. Common examples include: a search_knowledge_base tool alongside a query_ticket_history tool when a user asks 'find that thing I asked about last week'; a cancel_subscription tool and a pause_subscription tool when a user says 'stop my account for a while'; or a create_incident tool next to a create_change_request tool when a user reports 'the deployment broke something.' In each case, the user's language is underspecified relative to the tool schema, and guessing breaks the workflow. This prompt is not for cases where the model has zero candidate tools (use an out-of-distribution abstention prompt) or where the model is confident but the arguments are incomplete (use an argument-completeness refusal prompt).

Do not use this prompt when latency constraints require immediate tool execution without a clarification loop, or when the tool catalog is small enough that ambiguity can be resolved through schema design alone. If you can eliminate overlap by tightening tool descriptions, parameter schemas, or capability boundaries, do that first—prompt-based refusal is a safety net, not a substitute for clear tool contracts. Before deploying, pair this prompt with a regression test suite that includes known-ambiguous inputs to verify that refusal behavior doesn't drift across model or prompt changes. In regulated domains, route refusals to a human review queue rather than exposing the ranked candidate list directly to end users.

This template is designed for agent infrastructure engineers who manage tool sets with overlapping capabilities—for example, a search_knowledge_base tool and a query_ticket_system tool that both accept natural-language queries. When user intent could map to multiple tools with equal plausibility, guessing wrong produces silent failures that are hard to detect downstream. This prompt instructs the model to refuse execution, rank the candidate tools by fit, and specify exactly what clarifying information would resolve the ambiguity. The output is structured for programmatic consumption so your harness can route the refusal to a clarification step, a human review queue, or a follow-up prompt with the missing context.

textCopy
You are a tool-selection router in a production AI system. Your job is to decide which tool to call based on the user's request. You must never guess. If multiple tools could satisfy the request equally well, you must refuse to call any tool and instead return a structured ambiguity report.

## AVAILABLE TOOLS
[TOOLS]

## USER REQUEST
[INPUT]

## CONVERSATION CONTEXT
[CONTEXT]

## INSTRUCTIONS
1. Analyze the user request against every available tool's description, parameters, and intended use case.
2. If exactly one tool clearly matches the user's intent, return a tool call with the required arguments.
3. If multiple tools could plausibly satisfy the request and you cannot determine which one the user needs without additional information, do NOT call any tool. Instead, return a refusal with a ranked candidate list.
4. For each candidate tool in the refusal, specify the exact disambiguating question you would need answered to select it confidently.
5. If no tool matches, return a refusal with an empty candidate list and a brief explanation.

## OUTPUT SCHEMA
Respond with a JSON object matching this schema:
{
  "decision": "call" | "refuse",
  "selected_tool": string | null,
  "arguments": object | null,
  "refusal": {
    "reason": string,
    "candidates": [
      {
        "tool_name": string,
        "rank": number,
        "why_candidate": string,
        "disambiguating_question": string
      }
    ]
  } | null
}

## CONSTRAINTS
- Never call a tool when confidence is below [CONFIDENCE_THRESHOLD].
- Never fabricate arguments. If a required argument is missing, refuse and request it.
- If the user request is ambiguous, prefer refusal over a wrong tool call.
- Rank candidates by fit. Ties are acceptable if you cannot break them.
- Disambiguating questions must be specific and answerable by the user in one turn.

## EXAMPLES
[EXAMPLES]

To adapt this template, replace [TOOLS] with your actual tool definitions in the format your model expects—typically JSON Schema function declarations or a structured description block. The [CONTEXT] placeholder should receive prior conversation turns, user profile data, or session state that might resolve ambiguity without asking the user. Set [CONFIDENCE_THRESHOLD] to a value that matches your risk tolerance; for read-only tools in internal dashboards, 0.7 may be acceptable, while for write operations in customer-facing systems, 0.95 or higher is common. The [EXAMPLES] block is critical for this prompt's reliability. Include at least three few-shot examples: one clear single-tool selection, one multi-tool ambiguity refusal with ranked candidates, and one no-tool-match refusal. Without examples, models tend to default to calling the first plausible tool rather than refusing. After adapting, run the prompt through the evaluation harness described in the Testing and Evaluation section to measure refusal precision and false-positive tool-call rates before deployment.

The refusal prompt is not a standalone artifact—it is a decision node inside a tool-call pipeline. Wire it after intent detection and before tool execution. When the model returns a refusal, the harness must branch: route to a clarification module, escalate to a human review queue, or log the ambiguity for offline analysis. Do not silently fall through to a default tool. The refusal payload includes a ranked_candidates list and a disambiguating_question; both must be surfaced to the downstream consumer, whether that is a user-facing chat UI or an internal ops dashboard.

Validation is the first integration concern. Before accepting a refusal, confirm that the output matches the expected schema: decision must equal "refuse", confidence_score must be a float between 0.0 and 1.0, and ranked_candidates must contain at least two entries with non-empty tool_name and reason fields. If the model returns "proceed" with a single tool, route to the standard tool execution path and log the decision for eval comparison. If the output fails schema validation, retry once with a repair prompt that includes the validation error. After a second failure, escalate to a human operator with the raw model output and the original user input attached. For high-risk domains, add a mandatory human approval gate before any tool execution that follows a retry-recovered refusal.

Model choice matters. This prompt works best with models that have strong instruction-following and structured output capabilities. For production, prefer gpt-4o or claude-3-5-sonnet with response_format set to json_object and the output schema provided in the system prompt. Avoid smaller models that collapse the ranked_candidates list into a single guess or hallucinate tool names. If you must use a smaller model, add a post-processing check that verifies every tool_name in ranked_candidates exists in the provided [TOOLS] list. Discard any candidate that references a tool not in the schema and re-rank the remainder. Log all discarded candidates for eval analysis—frequent hallucinated tool names signal that the model is too weak for this task.

Observability is non-negotiable. Log every refusal decision with the full input context, the model's output, the validation result, and the downstream action taken (clarification, escalation, or retry). Include a refusal_trace_id that links the refusal to any subsequent tool call or user clarification turn. This trace is essential for computing refusal precision and recall during eval cycles. Without it, you cannot distinguish between a correct refusal, a missed refusal that led to a wrong tool call, and a false refusal that blocked a valid workflow. Wire these logs into your existing monitoring stack and set alerts on sudden changes in refusal rate—a spike often indicates a prompt regression, a tool schema change, or a shift in user input distribution.

Finally, treat the disambiguating_question as a product surface, not just a debug string. In a user-facing system, render it directly to the user along with the top two or three candidate tools as selectable options. This turns an ambiguity refusal into a lightweight clarification UI that keeps the user in control. In an internal agent system, route the question and candidates to a human review queue with a short TTL; if no human responds within the window, fall back to a safe default (such as a read-only tool or a polite user-facing delay message). Never execute a tool selected at random from the ranked list—ambiguity refusal exists precisely because the model cannot safely choose.