From 260accbab46b9689c2e47a97894c75e96ebc1cb3 Mon Sep 17 00:00:00 2001
From: Roo Code <roomote@roocode.com>
Date: Sat, 4 Oct 2025 12:10:53 +0000
Subject: [PATCH] fix: improve MCP tool prompt clarity to prevent format
 confusion

- Added explicit warnings about NOT using direct tool name format
- Added clear examples showing incorrect vs correct usage
- Emphasized the requirement to always use use_mcp_tool wrapper
- Updated MCP servers section to reinforce proper format

This should help prevent AI models from forgetting to wrap MCP tool
calls in the proper use_mcp_tool format, addressing issue #8507
---
 src/core/prompts/sections/mcp-servers.ts |  6 +++-
 src/core/prompts/tools/use-mcp-tool.ts   | 40 +++++++++++++++++++-----
 2 files changed, 38 insertions(+), 8 deletions(-)

diff --git a/src/core/prompts/sections/mcp-servers.ts b/src/core/prompts/sections/mcp-servers.ts
index 643233ab6f80..658c0a3573d0 100644
--- a/src/core/prompts/sections/mcp-servers.ts
+++ b/src/core/prompts/sections/mcp-servers.ts
@@ -58,7 +58,11 @@ The Model Context Protocol (MCP) enables communication between the system and MC
 
 # Connected MCP Servers
 
-When a server is connected, you can use the server's tools via the \`use_mcp_tool\` tool, and access the server's resources via the \`access_mcp_resource\` tool.
+When a server is connected, you MUST use the server's tools via the \`use_mcp_tool\` wrapper, and access the server's resources via the \`access_mcp_resource\` wrapper.
+
+**CRITICAL**: Never call MCP tools directly by their tool name. Always use the \`use_mcp_tool\` wrapper format:
+- ❌ WRONG: \`<tool_name>...\</tool_name>\`
+- ✅ CORRECT: \`<use_mcp_tool><server_name>...\</server_name><tool_name>...\</tool_name><arguments>...\</arguments>\</use_mcp_tool>\`
 
 ${connectedServers}`
 
diff --git a/src/core/prompts/tools/use-mcp-tool.ts b/src/core/prompts/tools/use-mcp-tool.ts
index ac9ef5b075db..6693ed691cd1 100644
--- a/src/core/prompts/tools/use-mcp-tool.ts
+++ b/src/core/prompts/tools/use-mcp-tool.ts
@@ -6,32 +6,58 @@ export function getUseMcpToolDescription(args: ToolArgs): string | undefined {
 	}
 	return `## use_mcp_tool
 Description: Request to use a tool provided by a connected MCP server. Each MCP server can provide multiple tools with different capabilities. Tools have defined input schemas that specify required and optional parameters.
+
+**IMPORTANT**: You MUST always use the \`use_mcp_tool\` wrapper format shown below. Do NOT call MCP tools directly by their tool name.
+
 Parameters:
 - server_name: (required) The name of the MCP server providing the tool
 - tool_name: (required) The name of the tool to execute
 - arguments: (required) A JSON object containing the tool's input parameters, following the tool's input schema
-Usage:
+
+Correct Usage Format:
 <use_mcp_tool>
 <server_name>server name here</server_name>
 <tool_name>tool name here</tool_name>
 <arguments>
 {
-  "param1": "value1",
-  "param2": "value2"
+	 "param1": "value1",
+	 "param2": "value2"
 }
 </arguments>
 </use_mcp_tool>
 
-Example: Requesting to use an MCP tool
+❌ INCORRECT - Do NOT use this format:
+<get_pull_request>
+<owner>username</owner>
+<repo>repository</repo>
+<pullNumber>123</pullNumber>
+</get_pull_request>
+
+✅ CORRECT - Always use this format:
+<use_mcp_tool>
+<server_name>github</server_name>
+<tool_name>get_pull_request</tool_name>
+<arguments>
+{
+	 "owner": "username",
+	 "repo": "repository",
+	 "pullNumber": 123
+}
+</arguments>
+</use_mcp_tool>
+
+Example: Using a weather MCP tool
 
 <use_mcp_tool>
 <server_name>weather-server</server_name>
 <tool_name>get_forecast</tool_name>
 <arguments>
 {
-  "city": "San Francisco",
-  "days": 5
+	 "city": "San Francisco",
+	 "days": 5
 }
 </arguments>
-</use_mcp_tool>`
+</use_mcp_tool>
+
+Remember: ALWAYS wrap MCP tool calls in the \`use_mcp_tool\` format, never call them directly by their tool name.`
 }