feat(prompts): add native tool-use guidance

hannesrudolph · hannesrudolph · commit 191cb238107e · 2025-12-23T13:26:01.000-07:00
diff --git a/src/core/prompts/sections/__tests__/tool-use.spec.ts b/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")
+		})
+	})
+})
diff --git a/src/core/prompts/sections/tool-use.ts b/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 `====
diff --git a/src/core/prompts/system.ts b/src/core/prompts/system.ts
@@ -138,7 +138,7 @@ async function generatePrompt(
 
 ${markdownFormattingSection()}
 
-${getSharedToolUseSection(effectiveProtocol)}${toolsCatalog}
+${getSharedToolUseSection(effectiveProtocol, experiments)}${toolsCatalog}
 
 ${getToolUseGuidelinesSection(effectiveProtocol)}
 
diff --git a/src/core/prompts/tools/native-tools/write_to_file.ts b/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",
