Enhance native tool descriptions with examples and clarifications (#9486)

Author: daniel-lxs

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

@@ -1,12 +1,21 @@
 import type OpenAI from "openai"
 
+const APPLY_DIFF_DESCRIPTION = `Apply precise, targeted modifications to an existing file using one or more search/replace blocks. This tool is for surgical edits only; the 'SEARCH' block must exactly match the existing content, including whitespace and indentation. To make multiple targeted changes, provide multiple SEARCH/REPLACE blocks in the 'diff' parameter. Use the 'read_file' tool first if you are not confident in the exact content to search for.`
+
+const DIFF_PARAMETER_DESCRIPTION = `A string containing one or more search/replace blocks defining the changes. The ':start_line:' is required and indicates the starting line number of the original content. You must not add a start line for the replacement content. Each block must follow this format:
+<<<<<<< SEARCH
+:start_line:[line_number]
+-------
+[exact content to find]
+=======
+[new content to replace with]
+>>>>>>> REPLACE`
+
 export const apply_diff_single_file = {
 	type: "function",
 	function: {
 		name: "apply_diff",
-		description: `
-Apply precise, targeted modifications to an existing file using one or more search/replace blocks. This tool is for surgical edits only; the 'SEARCH' block must exactly match the existing content, including whitespace and indentation. To make multiple targeted changes, provide multiple SEARCH/REPLACE blocks in the 'diff' parameter. Use the 'read_file' tool first if you are not confident in the exact content to search for.
-`,
+		description: APPLY_DIFF_DESCRIPTION,
 		parameters: {
 			type: "object",
 			properties: {
@@ -16,16 +25,7 @@ Apply precise, targeted modifications to an existing file using one or more sear
 				},
 				diff: {
 					type: "string",
-					description: `
-A string containing one or more search/replace blocks defining the changes. The ':start_line:' is required and indicates the starting line number of the original content.  You must not add a start line for the replacement content. Each block must follow this format:
-<<<<<<< SEARCH
-:start_line:[line_number]
--------
-[exact content to find]
-=======
-[new content to replace with]
->>>>>>> REPLACE
-`,
+					description: DIFF_PARAMETER_DESCRIPTION,
 				},
 			},
 			required: ["path", "diff"],

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

@@ -1,34 +1,51 @@
 import type OpenAI from "openai"
 
+const ASK_FOLLOWUP_QUESTION_DESCRIPTION = `Ask the user a question to gather additional information needed to complete the task. Use when you need clarification or more details to proceed effectively.
+
+Parameters:
+- question: (required) A clear, specific question addressing the information needed
+- follow_up: (required) A list of 2-4 suggested answers. Suggestions must be complete, actionable answers without placeholders. Optionally include mode to switch modes (code/architect/etc.)
+
+Example: Asking for file path
+{ "question": "What is the path to the frontend-config.json file?", "follow_up": [{ "text": "./src/frontend-config.json", "mode": null }, { "text": "./config/frontend-config.json", "mode": null }, { "text": "./frontend-config.json", "mode": null }] }
+
+Example: Asking with mode switch
+{ "question": "Would you like me to implement this feature?", "follow_up": [{ "text": "Yes, implement it now", "mode": "code" }, { "text": "No, just plan it out", "mode": "architect" }] }`
+
+const QUESTION_PARAMETER_DESCRIPTION = `Clear, specific question that captures the missing information you need`
+
+const FOLLOW_UP_PARAMETER_DESCRIPTION = `Required list of 2-4 suggested responses; each suggestion must be a complete, actionable answer and may include a mode switch`
+
+const FOLLOW_UP_TEXT_DESCRIPTION = `Suggested answer the user can pick`
+
+const FOLLOW_UP_MODE_DESCRIPTION = `Optional mode slug to switch to if this suggestion is chosen (e.g., code, architect)`
+
 export default {
 	type: "function",
 	function: {
 		name: "ask_followup_question",
-		description:
-			"Ask the user a question to gather additional information needed to complete the task. Use when clarification or more detail is required before proceeding.",
+		description: ASK_FOLLOWUP_QUESTION_DESCRIPTION,
 		strict: true,
 		parameters: {
 			type: "object",
 			properties: {
 				question: {
 					type: "string",
-					description: "Clear, specific question that captures the missing information you need",
+					description: QUESTION_PARAMETER_DESCRIPTION,
 				},
 				follow_up: {
 					type: "array",
-					description:
-						"Required list of 2-4 suggested responses; each suggestion must be a complete, actionable answer and may include a mode switch",
+					description: FOLLOW_UP_PARAMETER_DESCRIPTION,
 					items: {
 						type: "object",
 						properties: {
 							text: {
 								type: "string",
-								description: "Suggested answer the user can pick",
+								description: FOLLOW_UP_TEXT_DESCRIPTION,
 							},
 							mode: {
 								type: ["string", "null"],
-								description:
-									"Optional mode slug to switch to if this suggestion is chosen (e.g., code, architect)",
+								description: FOLLOW_UP_MODE_DESCRIPTION,
 							},
 						},
 						required: ["text", "mode"],

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

@@ -1,18 +1,29 @@
 import type OpenAI from "openai"
 
+const ATTEMPT_COMPLETION_DESCRIPTION = `After each tool use, the user will respond with the result of that tool use, i.e. if it succeeded or failed, along with any reasons for failure. Once you've received the results of tool uses and can confirm that the task is complete, use this tool to present the result of your work to the user. The user may respond with feedback if they are not satisfied with the result, which you can use to make improvements and try again.
+
+IMPORTANT NOTE: This tool CANNOT be used until you've confirmed from the user that any previous tool uses were successful. Failure to do so will result in code corruption and system failure. Before using this tool, you must confirm that you've received successful results from the user for any previous tool uses. If not, then DO NOT use this tool.
+
+Parameters:
+- result: (required) The result of the task. Formulate this result in a way that is final and does not require further input from the user. Don't end your result with questions or offers for further assistance.
+
+Example: Completing after updating CSS
+{ "result": "I've updated the CSS to use flexbox layout for better responsiveness" }`
+
+const RESULT_PARAMETER_DESCRIPTION = `Final result message to deliver to the user once the task is complete`
+
 export default {
 	type: "function",
 	function: {
 		name: "attempt_completion",
-		description:
-			"After each tool use, the user will respond with the result of that tool use, i.e. if it succeeded or failed, along with any reasons for failure. Once you've received the results of tool uses and can confirm that the task is complete, use this tool to present the result of your work to the user. The user may respond with feedback if they are not satisfied with the result, which you can use to make improvements and try again. IMPORTANT NOTE: This tool CANNOT be used until you've confirmed from the user that any previous tool uses were successful. Failure to do so will result in code corruption and system failure. Before using this tool, you must confirm that you've received successful results from the user for any previous tool uses. If not, then DO NOT use this tool.",
+		description: ATTEMPT_COMPLETION_DESCRIPTION,
 		strict: true,
 		parameters: {
 			type: "object",
 			properties: {
 				result: {
 					type: "string",
-					description: "Final result message to deliver to the user once the task is complete",
+					description: RESULT_PARAMETER_DESCRIPTION,
 				},
 			},
 			required: ["result"],

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

@@ -1,38 +1,51 @@
 import type OpenAI from "openai"
 
+const BROWSER_ACTION_DESCRIPTION = `Request to interact with a Puppeteer-controlled browser. Every action, except close, will be responded to with a screenshot of the browser's current state, along with any new console logs. You may only perform one browser action per message, and wait for the user's response including a screenshot and logs to determine the next action.
+
+Browser Session Lifecycle:
+- Browser sessions start with launch and end with close
+- The session remains active across multiple messages and tool uses
+- You can use other tools while the browser session is active - it will stay open in the background`
+
+const ACTION_PARAMETER_DESCRIPTION = `Browser action to perform`
+
+const URL_PARAMETER_DESCRIPTION = `URL to open when performing the launch action; must include protocol`
+
+const COORDINATE_PARAMETER_DESCRIPTION = `Screen coordinate for hover or click actions in format 'x,y@WIDTHxHEIGHT' where x,y is the target position on the screenshot image and WIDTHxHEIGHT is the exact pixel dimensions of the screenshot image (not the browser viewport). Example: '450,203@900x600' means click at (450,203) on a 900x600 screenshot. The coordinates will be automatically scaled to match the actual viewport dimensions.`
+
+const SIZE_PARAMETER_DESCRIPTION = `Viewport dimensions for the resize action in format 'WIDTHxHEIGHT' or 'WIDTH,HEIGHT'. Example: '1280x800' or '1280,800'`
+
+const TEXT_PARAMETER_DESCRIPTION = `Text to type when performing the type action, or key name to press when performing the press action (e.g., 'Enter', 'Tab', 'Escape')`
+
 export default {
 	type: "function",
 	function: {
 		name: "browser_action",
-		description:
-			"Interact with a browser session. Always start by launching at a URL and always finish by closing the browser. While the browser is active, do not call any other tools. Use coordinates within the viewport to hover or click, provide text for typing, and ensure actions are grounded in the latest screenshot and console logs.",
+		description: BROWSER_ACTION_DESCRIPTION,
 		strict: true,
 		parameters: {
 			type: "object",
 			properties: {
 				action: {
 					type: "string",
-					description: "Browser action to perform",
+					description: ACTION_PARAMETER_DESCRIPTION,
 					enum: ["launch", "click", "hover", "type", "press", "scroll_down", "scroll_up", "resize", "close"],
 				},
 				url: {
 					type: ["string", "null"],
-					description: "URL to open when performing the launch action; must include protocol",
+					description: URL_PARAMETER_DESCRIPTION,
 				},
 				coordinate: {
 					type: ["string", "null"],
-					description:
-						"Screen coordinate for hover or click actions in format 'x,y@WIDTHxHEIGHT' where x,y is the target position on the screenshot image and WIDTHxHEIGHT is the exact pixel dimensions of the screenshot image (not the browser viewport). Example: '450,203@900x600' means click at (450,203) on a 900x600 screenshot. The coordinates will be automatically scaled to match the actual viewport dimensions.",
+					description: COORDINATE_PARAMETER_DESCRIPTION,
 				},
 				size: {
 					type: ["string", "null"],
-					description:
-						"Viewport dimensions for the resize action in format 'WIDTHxHEIGHT' or 'WIDTH,HEIGHT'. Example: '1280x800' or '1280,800'",
+					description: SIZE_PARAMETER_DESCRIPTION,
 				},
 				text: {
 					type: ["string", "null"],
-					description:
-						"Text to type when performing the type action, or key name to press when performing the press action (e.g., 'Enter', 'Tab', 'Escape')",
+					description: TEXT_PARAMETER_DESCRIPTION,
 				},
 			},
 			required: ["action"],

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

@@ -1,22 +1,37 @@
 import type OpenAI from "openai"
 
+const CODEBASE_SEARCH_DESCRIPTION = `Find files most relevant to the search query using semantic search. Searches based on meaning rather than exact text matches. By default searches entire workspace. Reuse the user's exact wording unless there's a clear reason not to - their phrasing often helps semantic search. Queries MUST be in English (translate if needed).
+
+Parameters:
+- query: (required) The search query. Reuse the user's exact wording/question format unless there's a clear reason not to.
+- path: (optional) Limit search to specific subdirectory (relative to the current workspace directory). Leave empty for entire workspace.
+
+Example: Searching for user authentication code
+{ "query": "User login and password hashing", "path": "src/auth" }
+
+Example: Searching entire workspace
+{ "query": "database connection pooling", "path": null }`
+
+const QUERY_PARAMETER_DESCRIPTION = `Meaning-based search query describing the information you need`
+
+const PATH_PARAMETER_DESCRIPTION = `Optional subdirectory (relative to the workspace) to limit the search scope`
+
 export default {
 	type: "function",
 	function: {
 		name: "codebase_search",
-		description:
-			"Run a semantic search across the workspace to find files relevant to a natural-language query. Reuse the user's wording where possible and keep queries in English.",
+		description: CODEBASE_SEARCH_DESCRIPTION,
 		strict: true,
 		parameters: {
 			type: "object",
 			properties: {
 				query: {
 					type: "string",
-					description: "Meaning-based search query describing the information you need",
+					description: QUERY_PARAMETER_DESCRIPTION,
 				},
 				path: {
 					type: ["string", "null"],
-					description: "Optional subdirectory (relative to the workspace) to limit the search scope",
+					description: PATH_PARAMETER_DESCRIPTION,
 				},
 			},
 			required: ["query", "path"],

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

@@ -1,22 +1,40 @@
 import type OpenAI from "openai"
 
+const EXECUTE_COMMAND_DESCRIPTION = `Request to execute a CLI command on the system. Use this when you need to perform system operations or run specific commands to accomplish any step in the user's task. You must tailor your command to the user's system and provide a clear explanation of what the command does. For command chaining, use the appropriate chaining syntax for the user's shell. Prefer to execute complex CLI commands over creating executable scripts, as they are more flexible and easier to run. Prefer relative commands and paths that avoid location sensitivity for terminal consistency.
+
+Parameters:
+- command: (required) The CLI command to execute. This should be valid for the current operating system. Ensure the command is properly formatted and does not contain any harmful instructions.
+- cwd: (optional) The working directory to execute the command in
+
+Example: Executing npm run dev
+{ "command": "npm run dev", "cwd": null }
+
+Example: Executing ls in a specific directory if directed
+{ "command": "ls -la", "cwd": "/home/user/projects" }
+
+Example: Using relative paths
+{ "command": "touch ./testdata/example.file", "cwd": null }`
+
+const COMMAND_PARAMETER_DESCRIPTION = `Shell command to execute`
+
+const CWD_PARAMETER_DESCRIPTION = `Optional working directory for the command, relative or absolute`
+
 export default {
 	type: "function",
 	function: {
 		name: "execute_command",
-		description:
-			"Run a CLI command on the user's system. Tailor the command to the environment, explain what it does, and prefer relative paths or shell-appropriate chaining. Use the cwd parameter only when directed to run in a different directory.",
+		description: EXECUTE_COMMAND_DESCRIPTION,
 		strict: true,
 		parameters: {
 			type: "object",
 			properties: {
 				command: {
 					type: "string",
-					description: "Shell command to execute",
+					description: COMMAND_PARAMETER_DESCRIPTION,
 				},
 				cwd: {
 					type: ["string", "null"],
-					description: "Optional working directory for the command, relative or absolute",
+					description: CWD_PARAMETER_DESCRIPTION,
 				},
 			},
 			required: ["command", "cwd"],

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

@@ -1,18 +1,21 @@
 import type OpenAI from "openai"
 
+const FETCH_INSTRUCTIONS_DESCRIPTION = `Retrieve detailed instructions for performing a predefined task, such as creating an MCP server or creating a mode.`
+
+const TASK_PARAMETER_DESCRIPTION = `Task identifier to fetch instructions for`
+
 export default {
 	type: "function",
 	function: {
 		name: "fetch_instructions",
-		description:
-			"Retrieve detailed instructions for performing a predefined task, such as creating an MCP server or creating a mode.",
+		description: FETCH_INSTRUCTIONS_DESCRIPTION,
 		strict: true,
 		parameters: {
 			type: "object",
 			properties: {
 				task: {
 					type: "string",
-					description: "Task identifier to fetch instructions for",
+					description: TASK_PARAMETER_DESCRIPTION,
 					enum: ["create_mcp_server", "create_mode"],
 				},
 			},

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

@@ -1,28 +1,47 @@
 import type OpenAI from "openai"
 
+const GENERATE_IMAGE_DESCRIPTION = `Request to generate or edit an image using AI models through OpenRouter API. This tool can create new images from text prompts or modify existing images based on your instructions. When an input image is provided, the AI will apply the requested edits, transformations, or enhancements to that image.
+
+Parameters:
+- prompt: (required) The text prompt describing what to generate or how to edit the image
+- path: (required) The file path where the generated/edited image should be saved (relative to the current workspace directory). The tool will automatically add the appropriate image extension if not provided.
+- image: (optional) The file path to an input image to edit or transform (relative to the current workspace directory). Supported formats: PNG, JPG, JPEG, GIF, WEBP.
+
+Example: Generating a sunset image
+{ "prompt": "A beautiful sunset over mountains with vibrant orange and purple colors", "path": "images/sunset.png", "image": null }
+
+Example: Editing an existing image
+{ "prompt": "Transform this image into a watercolor painting style", "path": "images/watercolor-output.png", "image": "images/original-photo.jpg" }
+
+Example: Upscaling and enhancing an image
+{ "prompt": "Upscale this image to higher resolution, enhance details, improve clarity and sharpness while maintaining the original content and composition", "path": "images/enhanced-photo.png", "image": "images/low-res-photo.jpg" }`
+
+const PROMPT_PARAMETER_DESCRIPTION = `Text description of the image to generate or the edits to apply`
+
+const PATH_PARAMETER_DESCRIPTION = `Filesystem path (relative to the workspace) where the resulting image should be saved`
+
+const IMAGE_PARAMETER_DESCRIPTION = `Optional path (relative to the workspace) to an existing image to edit; supports PNG, JPG, JPEG, GIF, and WEBP`
+
 export default {
 	type: "function",
 	function: {
 		name: "generate_image",
-		description:
-			"Create a new image or edit an existing one using OpenRouter image models. Provide a prompt describing the desired output, choose where to save the image in the current workspace, and optionally supply an input image to transform.",
+		description: GENERATE_IMAGE_DESCRIPTION,
 		strict: true,
 		parameters: {
 			type: "object",
 			properties: {
 				prompt: {
 					type: "string",
-					description: "Text description of the image to generate or the edits to apply",
+					description: PROMPT_PARAMETER_DESCRIPTION,
 				},
 				path: {
 					type: "string",
-					description:
-						"Filesystem path (relative to the workspace) where the resulting image should be saved",
+					description: PATH_PARAMETER_DESCRIPTION,
 				},
 				image: {
 					type: ["string", "null"],
-					description:
-						"Optional path (relative to the workspace) to an existing image to edit; supports PNG, JPG, JPEG, GIF, and WEBP",
+					description: IMAGE_PARAMETER_DESCRIPTION,
 				},
 			},
 			required: ["prompt", "path", "image"],