Multi-Tool Disambiguation System Prompt

This prompt is designed for AI applications where a model has access to multiple tools with overlapping or similar capabilities. For example, a customer support agent might have both a search_knowledge_base tool and a search_ticket_history tool. Without explicit disambiguation instructions, the model may select the wrong tool, call both unnecessarily, or default to a familiar but suboptimal choice. This prompt embeds a decision framework directly into the system message, forcing the model to compare tool capabilities against the user's intent before selecting one. Use this when your toolset has grown beyond five tools, when two or more tools share similar verbs or domains, or when selection errors in production have caused downstream failures.

The ideal user is an AI engineer or product developer who has observed tool selection failures in logs or evals and needs a systematic fix. You should have a clear inventory of your tools, their descriptions, and the specific overlap points that cause confusion. Before deploying this prompt, run a baseline evaluation: collect 50-100 real user requests that exercise the overlapping tools, record which tool the model selects without disambiguation, and measure the error rate. This gives you a concrete metric to improve against. The prompt works best when paired with structured logging that captures the model's tool selection reasoning, so you can trace why a particular tool was chosen and refine the disambiguation rules over time.

Do not use this prompt for single-tool applications or when tools have completely non-overlapping domains. Adding disambiguation logic where no ambiguity exists adds unnecessary token cost and can confuse the model by introducing decision criteria for choices it doesn't need to make. Also avoid this prompt when your tool selection logic is better handled in application code through keyword matching, intent classifiers, or deterministic routing. If you can reliably route requests to the correct tool without involving the model's judgment, do that instead. The model should handle disambiguation only when the decision genuinely requires semantic understanding of the user's intent. Finally, if you're in a high-risk domain like healthcare or finance, pair this prompt with a human review step for tool selection decisions that could have significant consequences if wrong.

This template is designed to be the primary system message for an AI application where multiple tools have overlapping capabilities. It instructs the model to analyze the user's request against all available tool definitions, identify any tools that could potentially satisfy the request, and explicitly resolve the conflict by selecting the single most appropriate tool based on precision, side effects, and required parameters. The prompt enforces a 'reason-then-act' pattern, requiring the model to output its disambiguation rationale before emitting the final tool call.

textCopy
You are a precise tool-selection router. Your job is to choose the single correct tool for a user's request when multiple tools might apply.

# AVAILABLE TOOLS
[TOOLS]

# DISAMBIGUATION RULES
1.  **Analyze Intent:** Map the user's request to the core action they want to perform.
2.  **Identify Candidates:** List every tool from the AVAILABLE TOOLS that *could* fulfill this intent, even partially.
3.  **Resolve Conflicts:** If more than one tool is a candidate, select the best one by applying these tie-breakers in order:
    - **Specificity:** Prefer the tool whose description and parameters most precisely match the user's specific nouns and verbs.
    - **Least Privilege:** Prefer the tool with the narrowest scope and fewest side effects that still gets the job done.
    - **Parameter Completeness:** Prefer the tool for which the user's request provides all required parameters without needing to guess.
4.  **Clarification Gate:** If no single tool is a clear winner after applying the tie-breakers, or if the winning tool is missing a required parameter, do not call any tool. Instead, respond with a concise clarification question asking the user to disambiguate.

# OUTPUT FORMAT
If a single tool is selected, you MUST respond with a JSON object containing your reasoning and the tool call. Do not include any other text.
{
  "disambiguation_reasoning": "A brief explanation of why the chosen tool was selected over the other candidates.",
  "tool_call": {
    "name": "selected_tool_name",
    "arguments": {
      "arg1": "value1",
      "arg2": "value2"
    }
  }
}

If clarification is needed, respond with:
{
  "disambiguation_reasoning": "Explanation of the conflict and why clarification is needed.",
  "clarification_question": "A clear, single question for the user."
}

To adapt this template, replace the [TOOLS] placeholder with your application's complete tool definitions. The format of these definitions should match the model provider's expected schema (e.g., a JSON array of function objects for OpenAI, or an XML block for Anthropic). The tie-breaker rules in the prompt are ordered to prioritize precision and safety; adjust the order of 'Specificity', 'Least Privilege', and 'Parameter Completeness' to match your application's risk tolerance. For high-stakes actions, you should integrate a human-in-the-loop step by adding a rule that forces the 'Clarification Gate' for any tool tagged with requires_confirmation: true in its definition, regardless of parameter completeness.

The multi-tool disambiguation prompt is not a standalone artifact; it is a decision-making component inside a larger tool-calling pipeline. In production, this prompt typically sits between the user's request and the tool execution layer. The application receives a user message, assembles the system prompt with the current set of available tool definitions and their descriptions, injects the user's query, and sends the combined payload to the model. The model's response is then parsed to extract the selected tool name and arguments before the tool is actually invoked. This prompt's job is to make that selection step reliable when multiple tools could plausibly satisfy the request.

To wire this into an application, start by defining a ToolRegistry object that holds the canonical list of available tools, each with a unique name, a description optimized for disambiguation, and a parameters schema. At runtime, filter the registry based on user permissions, feature flags, or session context to produce the active tool set. Inject this filtered set into the [AVAILABLE_TOOLS] placeholder of the prompt template. The prompt should be assembled fresh for each request rather than cached, because tool availability may change between turns. After receiving the model's response, validate that the selected tool name exists in the active registry and that all required arguments are present and match the expected types. If validation fails, route to a retry prompt that includes the validation error context, or escalate to a human if the retry budget is exhausted.

For observability, log the assembled prompt, the model's raw tool selection, the validation result, and the final tool invoked. Attach a trace ID that links the user request, the disambiguation decision, and the tool execution outcome. This trace is essential for debugging selection errors: when the model picks the wrong tool, you need to see exactly which tools were presented, how their descriptions were worded, and whether the user's query contained ambiguous signals. Set up an eval harness that runs a golden set of ambiguous queries against the prompt and measures selection accuracy. Queries like 'cancel my subscription' when both cancel_subscription and cancel_account exist should consistently route to the correct tool. Track precision and recall per tool pair, and set a threshold below which you revise tool descriptions or add few-shot examples to the prompt.

Model choice matters here. Smaller or faster models may struggle with fine-grained disambiguation, especially when tool descriptions are similar. If latency allows, route disambiguation decisions to a more capable model while using a smaller model for straightforward single-tool cases. Implement a fast-path check: if only one tool matches the user's intent based on a lightweight classifier or keyword match, skip the full disambiguation prompt and call the tool directly. Reserve the disambiguation prompt for cases where two or more tools have overlapping descriptions or the classifier confidence is below a threshold. This reduces cost and latency for the common case while preserving accuracy for ambiguous requests.

Finally, treat tool descriptions as product-facing copy. Ambiguous or overlapping descriptions are the root cause of most disambiguation failures. When eval metrics show selection errors between a specific tool pair, rewrite the descriptions to emphasize distinguishing features, side effects, or required inputs. For example, instead of 'Deletes a user record' and 'Removes a user from the system,' use 'Permanently deletes the user and all associated data; irreversible' versus 'Suspends the user account and queues it for administrator review; reversible.' The prompt can only disambiguate what the descriptions differentiate. Pair this prompt with a tool description optimization workflow that iterates on descriptions based on production selection accuracy data.