Tool Name Correction and Disambiguation Prompt Template

This prompt is for agent platform engineers and tool-integration developers who need to recover from an agent loop that has called a non-existent or misspelled tool. The job-to-be-done is to map an incorrect tool name to the closest valid entry in a provided tool registry, preventing a hard failure in the agent's execution. The ideal user is someone building a resilient agent harness who needs an automated, inline repair step before escalating to a human or aborting the task. Required context includes the exact incorrect tool name the model produced, the full list of available tool names and their descriptions, and the recent conversation or reasoning trace that led to the invalid call.

Do not use this prompt when the tool name is correct but the arguments are malformed—that is a job for a parameter repair prompt. It is also unsuitable when the agent's intent is fundamentally ambiguous and requires clarification from a user; this prompt is for disambiguation against a known registry, not for resolving vague user requests. This prompt assumes a single incorrect tool name as input. If the model hallucinated an entirely new workflow that has no semantic match in the registry, the fuzzy-match confidence will be low, and the correct behavior is to escalate, not to force a match. The harness should enforce a minimum confidence threshold before accepting the correction.

Before wiring this into your agent loop, ensure your tool registry is complete and that each tool has a clear, descriptive purpose string. The prompt's effectiveness depends on semantic similarity between the incorrect name and the registry descriptions. Test the prompt with common failure modes from your logs: misspellings, aliases from other platforms, and tool names the model might confabulate. After implementing, monitor the correction_confidence score and the rate of escalations to verify the prompt is reducing manual interventions without introducing silent misroutings.

This prompt template is the core instruction set for recovering from a failed tool call where the model requested a tool that doesn't exist. It takes the incorrect name, the full list of available tools with their descriptions, and the original user intent, then returns the best match along with a confidence score. The template is designed to be copied directly into your agent's error-recovery loop, with square-bracket placeholders you replace with runtime values from your tool registry and execution context.

textCopy
You are a tool name disambiguation system. Your job is to map an incorrect or misspelled tool name to the closest matching tool in the available tool registry.

## INPUT
- Incorrect tool name: [INCORRECT_TOOL_NAME]
- User's original request or agent context: [USER_CONTEXT]
- Available tools (name and description):
[AVAILABLE_TOOLS_LIST]

## TASK
1. Compare the incorrect tool name against every available tool name and description.
2. Identify the single best match using:
   - Edit distance (typos, character swaps, missing characters)
   - Semantic similarity (synonyms, alternate phrasings, related concepts)
   - Functional fit (does the tool's described purpose match what the user was trying to do?)
3. If no tool is a reasonable match, return a "no_match" result.

## OUTPUT SCHEMA
Return ONLY valid JSON with this exact structure:
{
  "matched_tool": "<exact tool name from registry or null>",
  "confidence": <float between 0.0 and 1.0>,
  "rationale": "<brief explanation of why this match was chosen or why no match exists>",
  "requires_escalation": <boolean>
}

## CONSTRAINTS
- [CONFIDENCE_THRESHOLD]: If confidence is below this value, set requires_escalation to true.
- [MAX_CANDIDATES_TO_CONSIDER]: Limit fuzzy matching to this many top candidates before detailed comparison.
- [ESCALATION_ACTION]: When escalation is required, include this recommended action in the rationale.
- Never invent tool names. Only return names exactly as they appear in the available tools list.
- If the incorrect name could plausibly match multiple tools, choose the one with the strongest functional fit to the user context.

To adapt this template, replace the square-bracket placeholders with runtime data from your agent loop. [INCORRECT_TOOL_NAME] comes from the failed function call. [USER_CONTEXT] should include the original user message and any preceding agent reasoning to provide functional fit signals. [AVAILABLE_TOOLS_LIST] must be a complete dump of your tool registry—include both the tool name and its description for each entry, as semantic matching depends on descriptions. Set [CONFIDENCE_THRESHOLD] based on your risk tolerance (0.7 is a common starting point). Wire [ESCALATION_ACTION] to your human review queue or a clarification prompt that asks the user to specify the intended tool. Before deploying, run this prompt against a golden set of known misspellings, aliases, and completely absent tool names to calibrate your confidence threshold and catch false-positive matches.

This prompt is designed to be called as a recovery step inside an agent execution loop when a tool call fails with a 'tool not found' or similar error. The harness should intercept the failure, extract the incorrect tool name and the full list of available tools from the agent's tool registry, and invoke this prompt before retrying the action. Do not use this prompt for initial tool selection; it is strictly a post-failure correction mechanism. The primary integration point is the error handler of your agent's tool execution layer—whether that's a LangChain tool executor, a custom ReAct loop, or an MCP client.

To wire this in, build a tool_name_correction function that accepts three arguments: incorrect_name (the name the model tried to call), available_tools (a list of tool definition objects including name, description, and parameter schemas), and context (the last N messages of the conversation or agent trace). Populate the prompt's [INCORRECT_TOOL_NAME], [AVAILABLE_TOOLS_JSON], and [CONVERSATION_CONTEXT] placeholders with these values. The model will return a JSON object with corrected_name, confidence_score, and reasoning. Your harness must parse this output and apply a configurable confidence threshold—we recommend starting at 0.85 for automatic correction and routing anything below that to a human review queue or a clarification prompt back to the agent. Log every correction attempt with the original name, corrected name, confidence score, and whether the correction was accepted or escalated. This log becomes your primary observability surface for tool naming drift and model confusion patterns.

For the fuzzy-match fallback, implement a secondary validation layer in your harness that runs even if the model returns a high-confidence correction. Take the corrected_name and perform an exact case-insensitive match against your tool registry. If no exact match exists, fall back to a Levenshtein distance or token-sort-ratio check against all registered tool names, and select the closest match above a similarity threshold of 0.8. If both the model correction and the fuzzy fallback fail, escalate the failure to the agent's error policy—do not silently substitute a tool. This dual-layer approach prevents the model from hallucinating tool names that don't exist while still recovering from common misspellings and aliases. For production deployments, instrument the harness with metrics: correction attempt rate, confidence score distribution, fuzzy-match fallback rate, and escalation rate. These metrics will tell you whether your tool naming conventions need adjustment or whether the model requires fine-tuning on your specific tool registry.