feat(prompts): strengthen native tool-use guidance (#10311)

Author: hannesrudolph

src/core/prompts/sections/__tests__/tool-use-guidelines.spec.ts

@@ -1,5 +1,6 @@
 import { getToolUseGuidelinesSection } from "../tool-use-guidelines"
 import { TOOL_PROTOCOL } from "@roo-code/types"
+import { EXPERIMENT_IDS } from "../../../../shared/experiments"
 
 describe("getToolUseGuidelinesSection", () => {
 	describe("XML protocol", () => {
@@ -35,30 +36,53 @@ describe("getToolUseGuidelinesSection", () => {
 	})
 
 	describe("native protocol", () => {
-		it("should include proper numbered guidelines", () => {
-			const guidelines = getToolUseGuidelinesSection(TOOL_PROTOCOL.NATIVE)
+		describe("with MULTIPLE_NATIVE_TOOL_CALLS disabled (default)", () => {
+			it("should include proper numbered guidelines", () => {
+				const guidelines = getToolUseGuidelinesSection(TOOL_PROTOCOL.NATIVE)
 
-			// Check that all numbered items are present with correct numbering
-			expect(guidelines).toContain("1. Assess what information")
-			expect(guidelines).toContain("2. Choose the most appropriate tool")
-			expect(guidelines).toContain("3. If multiple actions are needed")
-			expect(guidelines).toContain("4. After each tool use")
-		})
+				// Check that all numbered items are present with correct numbering
+				expect(guidelines).toContain("1. Assess what information")
+				expect(guidelines).toContain("2. Choose the most appropriate tool")
+				expect(guidelines).toContain("3. If multiple actions are needed")
+				expect(guidelines).toContain("4. After each tool use")
+			})
+
+			it("should include single-tool-per-message guidance when experiment disabled", () => {
+				const guidelines = getToolUseGuidelinesSection(TOOL_PROTOCOL.NATIVE, {})
+
+				expect(guidelines).toContain("use one tool at a time per message")
+				expect(guidelines).not.toContain("you may use multiple tools in a single message")
+				expect(guidelines).not.toContain("Formulate your tool use using the XML format")
+				expect(guidelines).not.toContain("ALWAYS wait for user confirmation")
+			})
 
-		it("should include native protocol-specific guidelines", () => {
-			const guidelines = getToolUseGuidelinesSection(TOOL_PROTOCOL.NATIVE)
+			it("should include simplified iterative process guidelines", () => {
+				const guidelines = getToolUseGuidelinesSection(TOOL_PROTOCOL.NATIVE)
 
-			expect(guidelines).toContain("you may use multiple tools in a single message")
-			expect(guidelines).not.toContain("Formulate your tool use using the XML format")
-			expect(guidelines).not.toContain("ALWAYS wait for user confirmation")
+				expect(guidelines).toContain("carefully considering the user's response after tool executions")
+				// Native protocol doesn't have the step-by-step list
+				expect(guidelines).not.toContain("It is crucial to proceed step-by-step")
+			})
 		})
 
-		it("should include simplified iterative process guidelines", () => {
-			const guidelines = getToolUseGuidelinesSection(TOOL_PROTOCOL.NATIVE)
+		describe("with MULTIPLE_NATIVE_TOOL_CALLS enabled", () => {
+			it("should include multiple-tools-per-message guidance when experiment enabled", () => {
+				const guidelines = getToolUseGuidelinesSection(TOOL_PROTOCOL.NATIVE, {
+					[EXPERIMENT_IDS.MULTIPLE_NATIVE_TOOL_CALLS]: true,
+				})
+
+				expect(guidelines).toContain("you may use multiple tools in a single message")
+				expect(guidelines).not.toContain("use one tool at a time per message")
+			})
+
+			it("should include simplified iterative process guidelines", () => {
+				const guidelines = getToolUseGuidelinesSection(TOOL_PROTOCOL.NATIVE, {
+					[EXPERIMENT_IDS.MULTIPLE_NATIVE_TOOL_CALLS]: true,
+				})
 
-			expect(guidelines).toContain("carefully considering the user's response after tool executions")
-			// Native protocol doesn't have the step-by-step list
-			expect(guidelines).not.toContain("It is crucial to proceed step-by-step")
+				expect(guidelines).toContain("carefully considering the user's response after tool executions")
+				expect(guidelines).not.toContain("It is crucial to proceed step-by-step")
+			})
 		})
 	})
 

src/core/prompts/sections/__tests__/tool-use.spec.ts

@@ -0,0 +1,69 @@
+import { getSharedToolUseSection } from "../tool-use"
+import { TOOL_PROTOCOL } from "@roo-code/types"
+
+describe("getSharedToolUseSection", () => {
+	describe("XML protocol", () => {
+		it("should include one tool per message requirement", () => {
+			const section = getSharedToolUseSection(TOOL_PROTOCOL.XML)
+
+			expect(section).toContain("You must use exactly one tool per message")
+			expect(section).toContain("every assistant message must include a tool call")
+		})
+
+		it("should include XML formatting instructions", () => {
+			const section = getSharedToolUseSection(TOOL_PROTOCOL.XML)
+
+			expect(section).toContain("XML-style tags")
+			expect(section).toContain("Always use the actual tool name as the XML tag name")
+		})
+	})
+
+	describe("native protocol", () => {
+		it("should include one tool per message requirement when experiment is disabled", () => {
+			// No experiment flags passed (default: disabled)
+			const section = getSharedToolUseSection(TOOL_PROTOCOL.NATIVE)
+
+			expect(section).toContain("You must use exactly one tool call per assistant response")
+			expect(section).toContain("Do not call zero tools or more than one tool")
+		})
+
+		it("should include one tool per message requirement when experiment is explicitly disabled", () => {
+			const section = getSharedToolUseSection(TOOL_PROTOCOL.NATIVE, { multipleNativeToolCalls: false })
+
+			expect(section).toContain("You must use exactly one tool call per assistant response")
+			expect(section).toContain("Do not call zero tools or more than one tool")
+		})
+
+		it("should NOT include one tool per message requirement when experiment is enabled", () => {
+			const section = getSharedToolUseSection(TOOL_PROTOCOL.NATIVE, { multipleNativeToolCalls: true })
+
+			expect(section).not.toContain("You must use exactly one tool per message")
+			expect(section).not.toContain("every assistant message must include a tool call")
+			expect(section).toContain("You must call at least one tool per assistant response")
+			expect(section).toContain("Prefer calling as many tools as are reasonably needed")
+		})
+
+		it("should include native tool-calling instructions", () => {
+			const section = getSharedToolUseSection(TOOL_PROTOCOL.NATIVE)
+
+			expect(section).toContain("provider-native tool-calling mechanism")
+			expect(section).toContain("Do not include XML markup or examples")
+		})
+
+		it("should NOT include XML formatting instructions", () => {
+			const section = getSharedToolUseSection(TOOL_PROTOCOL.NATIVE)
+
+			expect(section).not.toContain("XML-style tags")
+			expect(section).not.toContain("Always use the actual tool name as the XML tag name")
+		})
+	})
+
+	describe("default protocol", () => {
+		it("should default to XML protocol when no protocol is specified", () => {
+			const section = getSharedToolUseSection()
+
+			expect(section).toContain("XML-style tags")
+			expect(section).toContain("You must use exactly one tool per message")
+		})
+	})
+})

src/core/prompts/sections/tool-use-guidelines.ts

@@ -1,7 +1,12 @@
 import { ToolProtocol, TOOL_PROTOCOL } from "@roo-code/types"
 import { isNativeProtocol } from "@roo-code/types"
 
-export function getToolUseGuidelinesSection(protocol: ToolProtocol = TOOL_PROTOCOL.XML): string {
+import { experiments, EXPERIMENT_IDS } from "../../../shared/experiments"
+
+export function getToolUseGuidelinesSection(
+	protocol: ToolProtocol = TOOL_PROTOCOL.XML,
+	experimentFlags?: Record<string, boolean>,
+): string {
 	// Build guidelines array with automatic numbering
 	let itemNumber = 1
 	const guidelinesList: string[] = []
@@ -17,9 +22,21 @@ export function getToolUseGuidelinesSection(protocol: ToolProtocol = TOOL_PROTOC
 
 	// Remaining guidelines - different for native vs XML protocol
 	if (isNativeProtocol(protocol)) {
-		guidelinesList.push(
-			`${itemNumber++}. If multiple actions are needed, you may use multiple tools in a single message when appropriate, or use tools iteratively across messages. Each tool use should be informed by the results of previous tool uses. Do not assume the outcome of any tool use. Each step must be informed by the previous step's result.`,
+		// Check if multiple native tool calls is enabled via experiment
+		const isMultipleNativeToolCallsEnabled = experiments.isEnabled(
+			experimentFlags ?? {},
+			EXPERIMENT_IDS.MULTIPLE_NATIVE_TOOL_CALLS,
 		)
+
+		if (isMultipleNativeToolCallsEnabled) {
+			guidelinesList.push(
+				`${itemNumber++}. If multiple actions are needed, you may use multiple tools in a single message when appropriate, or use tools iteratively across messages. Each tool use should be informed by the results of previous tool uses. Do not assume the outcome of any tool use. Each step must be informed by the previous step's result.`,
+			)
+		} else {
+			guidelinesList.push(
+				`${itemNumber++}. If multiple actions are needed, use one tool at a time per message to accomplish the task iteratively, with each tool use being informed by the result of the previous tool use. Do not assume the outcome of any tool use. Each step must be informed by the previous step's result.`,
+			)
+		}
 	} else {
 		guidelinesList.push(
 			`${itemNumber++}. If multiple actions are needed, use one tool at a time per message to accomplish the task iteratively, with each tool use being informed by the result of the previous tool use. Do not assume the outcome of any tool use. Each step must be informed by the previous step's result.`,

src/core/prompts/sections/tool-use.ts

@@ -1,12 +1,27 @@
 import { ToolProtocol, TOOL_PROTOCOL, isNativeProtocol } from "@roo-code/types"
 
-export function getSharedToolUseSection(protocol: ToolProtocol = TOOL_PROTOCOL.XML): string {
+import { experiments, EXPERIMENT_IDS } from "../../../shared/experiments"
+
+export function getSharedToolUseSection(
+	protocol: ToolProtocol = TOOL_PROTOCOL.XML,
+	experimentFlags?: Record<string, boolean>,
+): string {
 	if (isNativeProtocol(protocol)) {
+		// Check if multiple native tool calls is enabled via experiment
+		const isMultipleNativeToolCallsEnabled = experiments.isEnabled(
+			experimentFlags ?? {},
+			EXPERIMENT_IDS.MULTIPLE_NATIVE_TOOL_CALLS,
+		)
+
+		const toolUseGuidance = isMultipleNativeToolCallsEnabled
+			? " You must call at least one tool per assistant response. Prefer calling as many tools as are reasonably needed in a single response to reduce back-and-forth and complete tasks faster."
+			: " You must use exactly one tool call per assistant response. Do not call zero tools or more than one tool in the same response."
+
 		return `====
 
 TOOL USE
 
-You have access to a set of tools that are executed upon the user's approval. Use the provider-native tool-calling mechanism. Do not include XML markup or examples.`
+You have access to a set of tools that are executed upon the user's approval. Use the provider-native tool-calling mechanism. Do not include XML markup or examples.${toolUseGuidance}`
 	}
 
 	return `====

src/core/prompts/system.ts

@@ -138,9 +138,9 @@ async function generatePrompt(
 
 ${markdownFormattingSection()}
 
-${getSharedToolUseSection(effectiveProtocol)}${toolsCatalog}
+${getSharedToolUseSection(effectiveProtocol, experiments)}${toolsCatalog}
 
-${getToolUseGuidelinesSection(effectiveProtocol)}
+${getToolUseGuidelinesSection(effectiveProtocol, experiments)}
 
 ${mcpServersSection}
 

src/core/prompts/tools/native-tools/write_to_file.ts

@@ -4,20 +4,16 @@ const WRITE_TO_FILE_DESCRIPTION = `Request to write content to a file. This tool
 
 **Important:** You should prefer using other editing tools over write_to_file when making changes to existing files, since write_to_file is slower and cannot handle large files. Use write_to_file primarily for new file creation.
 
-When using this tool, use it directly with the desired content. You do not need to display the content before using the tool. ALWAYS provide the COMPLETE file content in your response. This is NON-NEGOTIABLE. Partial updates or placeholders like '// rest of code unchanged' are STRICTLY FORBIDDEN. You MUST include ALL parts of the file, even if they haven't been modified. Failure to do so will result in incomplete or broken code.
+When using this tool, use it directly with the desired content. You do not need to display the content before using the tool. ALWAYS provide the COMPLETE file content in your response. This is NON-NEGOTIABLE. Partial updates or placeholders like '// rest of code unchanged' are STRICTLY FORBIDDEN. Failure to do so will result in incomplete or broken code.
 
 When creating a new project, organize all new files within a dedicated project directory unless the user specifies otherwise. Structure the project logically, adhering to best practices for the specific type of project being created.
 
-Parameters:
-- path: (required) The path of the file to write to (relative to the current workspace directory)
-- content: (required) The content to write to the file. ALWAYS provide the COMPLETE intended content of the file, without any truncation or omissions. You MUST include ALL parts of the file, even if they haven't been modified. Do NOT include line numbers in the content.
-
 Example: Writing a configuration file
 { "path": "frontend-config.json", "content": "{\\n  \\"apiEndpoint\\": \\"https://api.example.com\\",\\n  \\"theme\\": {\\n    \\"primaryColor\\": \\"#007bff\\"\\n  }\\n}" }`
 
-const PATH_PARAMETER_DESCRIPTION = `Path to the file to write, relative to the workspace`
+const PATH_PARAMETER_DESCRIPTION = `The path of the file to write to (relative to the current workspace directory)`
 
-const CONTENT_PARAMETER_DESCRIPTION = `Full contents that the file should contain with no omissions or line numbers`
+const CONTENT_PARAMETER_DESCRIPTION = `The content to write to the file. ALWAYS provide the COMPLETE intended content of the file, without any truncation or omissions. You MUST include ALL parts of the file, even if they haven't been modified. Do NOT include line numbers in the content.`
 
 export default {
 	type: "function",