diff --git a/src/core/prompts/tools/native-tools/apply_diff.ts b/src/core/prompts/tools/native-tools/apply_diff.ts index 19ef8318843..faa65291bf2 100644 --- a/src/core/prompts/tools/native-tools/apply_diff.ts +++ b/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"], diff --git a/src/core/prompts/tools/native-tools/ask_followup_question.ts b/src/core/prompts/tools/native-tools/ask_followup_question.ts index 8ea03c00a05..f4f95b2cedd 100644 --- a/src/core/prompts/tools/native-tools/ask_followup_question.ts +++ b/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"], diff --git a/src/core/prompts/tools/native-tools/attempt_completion.ts b/src/core/prompts/tools/native-tools/attempt_completion.ts index 944ab875430..f0ac1c219f7 100644 --- a/src/core/prompts/tools/native-tools/attempt_completion.ts +++ b/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"], diff --git a/src/core/prompts/tools/native-tools/browser_action.ts b/src/core/prompts/tools/native-tools/browser_action.ts index 64977780b7a..0a13d168f9e 100644 --- a/src/core/prompts/tools/native-tools/browser_action.ts +++ b/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"], diff --git a/src/core/prompts/tools/native-tools/codebase_search.ts b/src/core/prompts/tools/native-tools/codebase_search.ts index 6ca1692c128..60a65a4ecfa 100644 --- a/src/core/prompts/tools/native-tools/codebase_search.ts +++ b/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"], diff --git a/src/core/prompts/tools/native-tools/execute_command.ts b/src/core/prompts/tools/native-tools/execute_command.ts index 76f3a79f8f9..4b97b99eb57 100644 --- a/src/core/prompts/tools/native-tools/execute_command.ts +++ b/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"], diff --git a/src/core/prompts/tools/native-tools/fetch_instructions.ts b/src/core/prompts/tools/native-tools/fetch_instructions.ts index c63f92139be..86ab184c58d 100644 --- a/src/core/prompts/tools/native-tools/fetch_instructions.ts +++ b/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"], }, }, diff --git a/src/core/prompts/tools/native-tools/generate_image.ts b/src/core/prompts/tools/native-tools/generate_image.ts index fb5fef8075d..cdf134a5cbb 100644 --- a/src/core/prompts/tools/native-tools/generate_image.ts +++ b/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"], diff --git a/src/core/prompts/tools/native-tools/insert_content.ts b/src/core/prompts/tools/native-tools/insert_content.ts index db106b9b3be..b39a09dab0f 100644 --- a/src/core/prompts/tools/native-tools/insert_content.ts +++ b/src/core/prompts/tools/native-tools/insert_content.ts @@ -1,27 +1,45 @@ import type OpenAI from "openai" +const INSERT_CONTENT_DESCRIPTION = `Use this tool specifically for adding new lines of content into a file without modifying existing content. Specify the line number to insert before, or use line 0 to append to the end. Ideal for adding imports, functions, configuration blocks, log entries, or any multi-line text block. + +Parameters: +- path: (required) File path relative to workspace +- line: (required) Line number where content will be inserted (1-based). Use 0 to append at end of file. Use any positive number to insert before that line +- content: (required) The content to insert at the specified line + +Example for inserting imports at start of file: +{ "path": "src/utils.ts", "line": 1, "content": "// Add imports at start of file\\nimport { sum } from './math';" } + +Example for appending to the end of file: +{ "path": "src/utils.ts", "line": 0, "content": "// This is the end of the file" }` + +const PATH_PARAMETER_DESCRIPTION = `File path to modify, expressed relative to the workspace` + +const LINE_PARAMETER_DESCRIPTION = `1-based line number to insert before, or 0 to append at the end of the file` + +const CONTENT_PARAMETER_DESCRIPTION = `Exact text to insert at the chosen location` + export default { type: "function", function: { name: "insert_content", - description: - "Insert new lines into a file without modifying existing content. Choose a line number to insert before, or use 0 to append to the end.", + description: INSERT_CONTENT_DESCRIPTION, strict: true, parameters: { type: "object", properties: { path: { type: "string", - description: "File path to modify, expressed relative to the workspace", + description: PATH_PARAMETER_DESCRIPTION, }, line: { type: "integer", - description: "1-based line number to insert before, or 0 to append at the end of the file", + description: LINE_PARAMETER_DESCRIPTION, minimum: 0, }, content: { type: "string", - description: "Exact text to insert at the chosen location", + description: CONTENT_PARAMETER_DESCRIPTION, }, }, required: ["path", "line", "content"], diff --git a/src/core/prompts/tools/native-tools/list_code_definition_names.ts b/src/core/prompts/tools/native-tools/list_code_definition_names.ts index 20841f884c9..c5b604c935e 100644 --- a/src/core/prompts/tools/native-tools/list_code_definition_names.ts +++ b/src/core/prompts/tools/native-tools/list_code_definition_names.ts @@ -1,18 +1,32 @@ import type OpenAI from "openai" +const LIST_CODE_DEFINITION_NAMES_DESCRIPTION = `Request to list definition names (classes, functions, methods, etc.) from source code. This tool can analyze either a single file or all files at the top level of a specified directory. It provides insights into the codebase structure and important constructs, encapsulating high-level concepts and relationships that are crucial for understanding the overall architecture. + +Parameters: +- path: (required) The path of the file or directory (relative to the current working directory) to analyze. When given a directory, it lists definitions from all top-level source files. + +Examples: + +1. List definitions from a specific file: +{ "path": "src/main.ts" } + +2. List definitions from all files in a directory: +{ "path": "src/" }` + +const PATH_PARAMETER_DESCRIPTION = `Path to the file or directory to analyze, relative to the workspace` + export default { type: "function", function: { name: "list_code_definition_names", - description: - "List definition names (classes, functions, methods, etc.) from source files to understand code structure. Works on a single file or across all top-level files in a directory.", + description: LIST_CODE_DEFINITION_NAMES_DESCRIPTION, strict: true, parameters: { type: "object", properties: { path: { type: "string", - description: "Path to the file or directory to analyze, relative to the workspace", + description: PATH_PARAMETER_DESCRIPTION, }, }, required: ["path"], diff --git a/src/core/prompts/tools/native-tools/list_files.ts b/src/core/prompts/tools/native-tools/list_files.ts index b8069837ff7..0aef52b9351 100644 --- a/src/core/prompts/tools/native-tools/list_files.ts +++ b/src/core/prompts/tools/native-tools/list_files.ts @@ -1,22 +1,37 @@ import type OpenAI from "openai" +const LIST_FILES_DESCRIPTION = `Request to list files and directories within the specified directory. If recursive is true, it will list all files and directories recursively. If recursive is false or not provided, it will only list the top-level contents. Do not use this tool to confirm the existence of files you may have created, as the user will let you know if the files were created successfully or not. + +Parameters: +- path: (required) The path of the directory to list contents for (relative to the current workspace directory) +- recursive: (required) Whether to list files recursively. Use true for recursive listing, false for top-level only. + +Example: Listing all files in the current directory (top-level only) +{ "path": ".", "recursive": false } + +Example: Listing all files recursively in src directory +{ "path": "src", "recursive": true }` + +const PATH_PARAMETER_DESCRIPTION = `Directory path to inspect, relative to the workspace` + +const RECURSIVE_PARAMETER_DESCRIPTION = `Set true to list contents recursively; false to show only the top level` + export default { type: "function", function: { name: "list_files", - description: - "List files and directories within a given directory. Optionally recurse into subdirectories. Do not use this tool to confirm file creation; rely on user confirmation instead.", + description: LIST_FILES_DESCRIPTION, strict: true, parameters: { type: "object", properties: { path: { type: "string", - description: "Directory path to inspect, relative to the workspace", + description: PATH_PARAMETER_DESCRIPTION, }, recursive: { type: "boolean", - description: "Set true to list contents recursively; false to show only the top level", + description: RECURSIVE_PARAMETER_DESCRIPTION, }, }, required: ["path", "recursive"], diff --git a/src/core/prompts/tools/native-tools/new_task.ts b/src/core/prompts/tools/native-tools/new_task.ts index 7bcb386115b..c2dcb8b9abe 100644 --- a/src/core/prompts/tools/native-tools/new_task.ts +++ b/src/core/prompts/tools/native-tools/new_task.ts @@ -1,27 +1,33 @@ import type OpenAI from "openai" +const NEW_TASK_DESCRIPTION = `This will let you create a new task instance in the chosen mode using your provided message and initial todo list (if required).` + +const MODE_PARAMETER_DESCRIPTION = `Slug of the mode to begin the new task in (e.g., code, debug, architect)` + +const MESSAGE_PARAMETER_DESCRIPTION = `Initial user instructions or context for the new task` + +const TODOS_PARAMETER_DESCRIPTION = `Optional initial todo list written as a markdown checklist; required when the workspace mandates todos` + export default { type: "function", function: { name: "new_task", - description: - "Create a new task instance in a specified mode, supplying the initial instructions and optionally a starting todo list when required by settings.", + description: NEW_TASK_DESCRIPTION, strict: true, parameters: { type: "object", properties: { mode: { type: "string", - description: "Slug of the mode to begin the new task in (e.g., code, debug, architect)", + description: MODE_PARAMETER_DESCRIPTION, }, message: { type: "string", - description: "Initial user instructions or context for the new task", + description: MESSAGE_PARAMETER_DESCRIPTION, }, todos: { type: ["string", "null"], - description: - "Optional initial todo list written as a markdown checklist; required when the workspace mandates todos", + description: TODOS_PARAMETER_DESCRIPTION, }, }, required: ["mode", "message", "todos"], diff --git a/src/core/prompts/tools/native-tools/read_file.ts b/src/core/prompts/tools/native-tools/read_file.ts index 81bee82d5e3..c1546ef7c38 100644 --- a/src/core/prompts/tools/native-tools/read_file.ts +++ b/src/core/prompts/tools/native-tools/read_file.ts @@ -1,5 +1,9 @@ import type OpenAI from "openai" +const READ_FILE_BASE_DESCRIPTION = `Read one or more files and return their contents with line numbers for diffing or discussion.` + +const READ_FILE_SUPPORTS_NOTE = `Supports text extraction from PDF and DOCX files, but may not handle other binary files properly.` + /** * Creates the read_file tool definition, optionally including line_ranges support * based on whether partial reads are enabled. @@ -9,8 +13,8 @@ import type OpenAI from "openai" */ export function createReadFileTool(partialReadsEnabled: boolean = true): OpenAI.Chat.ChatCompletionTool { const baseDescription = - "Read one or more files and return their contents with line numbers for diffing or discussion. " + - "Structure: { files: [{ path: 'relative/path.ts'" + + READ_FILE_BASE_DESCRIPTION + + " Structure: { files: [{ path: 'relative/path.ts'" + (partialReadsEnabled ? ", line_ranges: ['1-50', '100-150']" : "") + " }] }. " + "The 'path' is required and relative to workspace. " @@ -26,7 +30,7 @@ export function createReadFileTool(partialReadsEnabled: boolean = true): OpenAI. : "Example single file: { files: [{ path: 'src/app.ts' }] }. " + "Example multiple files: { files: [{ path: 'file1.ts' }, { path: 'file2.ts' }] }" - const description = baseDescription + optionalRangesDescription + examples + const description = baseDescription + optionalRangesDescription + READ_FILE_SUPPORTS_NOTE + " " + examples // Build the properties object conditionally const fileProperties: Record = { diff --git a/src/core/prompts/tools/native-tools/run_slash_command.ts b/src/core/prompts/tools/native-tools/run_slash_command.ts index 7a3e78e39b2..71bf2528ddc 100644 --- a/src/core/prompts/tools/native-tools/run_slash_command.ts +++ b/src/core/prompts/tools/native-tools/run_slash_command.ts @@ -1,22 +1,27 @@ import type OpenAI from "openai" +const RUN_SLASH_COMMAND_DESCRIPTION = `Execute a slash command to get specific instructions or content. Slash commands are predefined templates that provide detailed guidance for common tasks.` + +const COMMAND_PARAMETER_DESCRIPTION = `Name of the slash command to run (e.g., init, test, deploy)` + +const ARGS_PARAMETER_DESCRIPTION = `Optional additional context or arguments for the command` + export default { type: "function", function: { name: "run_slash_command", - description: - "Execute a predefined slash command to receive detailed instructions or content for a common task.", + description: RUN_SLASH_COMMAND_DESCRIPTION, strict: true, parameters: { type: "object", properties: { command: { type: "string", - description: "Name of the slash command to run (e.g., init, test, deploy)", + description: COMMAND_PARAMETER_DESCRIPTION, }, args: { type: ["string", "null"], - description: "Optional additional context or arguments for the command", + description: ARGS_PARAMETER_DESCRIPTION, }, }, required: ["command", "args"], diff --git a/src/core/prompts/tools/native-tools/search_files.ts b/src/core/prompts/tools/native-tools/search_files.ts index c4ab0306ae4..64a664c1aba 100644 --- a/src/core/prompts/tools/native-tools/search_files.ts +++ b/src/core/prompts/tools/native-tools/search_files.ts @@ -1,25 +1,44 @@ import type OpenAI from "openai" +const SEARCH_FILES_DESCRIPTION = `Request to perform a regex search across files in a specified directory, providing context-rich results. This tool searches for patterns or specific content across multiple files, displaying each match with encapsulating context. + +Parameters: +- path: (required) The path of the directory to search in (relative to the current workspace directory). This directory will be recursively searched. +- regex: (required) The regular expression pattern to search for. Uses Rust regex syntax. +- file_pattern: (optional) Glob pattern to filter files (e.g., '*.ts' for TypeScript files). If not provided, it will search all files (*). + +Example: Searching for all .ts files in the current directory +{ "path": ".", "regex": ".*", "file_pattern": "*.ts" } + +Example: Searching for function definitions in JavaScript files +{ "path": "src", "regex": "function\\s+\\w+", "file_pattern": "*.js" }` + +const PATH_PARAMETER_DESCRIPTION = `Directory to search recursively, relative to the workspace` + +const REGEX_PARAMETER_DESCRIPTION = `Rust-compatible regular expression pattern to match` + +const FILE_PATTERN_PARAMETER_DESCRIPTION = `Optional glob to limit which files are searched (e.g., *.ts)` + export default { type: "function", function: { name: "search_files", - description: "Run a regex search across files under a directory, returning matches with surrounding context.", + description: SEARCH_FILES_DESCRIPTION, strict: true, parameters: { type: "object", properties: { path: { type: "string", - description: "Directory to search recursively, relative to the workspace", + description: PATH_PARAMETER_DESCRIPTION, }, regex: { type: "string", - description: "Rust-compatible regular expression pattern to match", + description: REGEX_PARAMETER_DESCRIPTION, }, file_pattern: { type: ["string", "null"], - description: "Optional glob to limit which files are searched (e.g., *.ts)", + description: FILE_PATTERN_PARAMETER_DESCRIPTION, }, }, required: ["path", "regex", "file_pattern"], diff --git a/src/core/prompts/tools/native-tools/switch_mode.ts b/src/core/prompts/tools/native-tools/switch_mode.ts index 979ba124005..78e35a99c26 100644 --- a/src/core/prompts/tools/native-tools/switch_mode.ts +++ b/src/core/prompts/tools/native-tools/switch_mode.ts @@ -1,22 +1,27 @@ import type OpenAI from "openai" +const SWITCH_MODE_DESCRIPTION = `Request to switch to a different mode. This tool allows modes to request switching to another mode when needed, such as switching to Code mode to make code changes. The user must approve the mode switch.` + +const MODE_SLUG_PARAMETER_DESCRIPTION = `Slug of the mode to switch to (e.g., code, ask, architect)` + +const REASON_PARAMETER_DESCRIPTION = `Explanation for why the mode switch is needed` + export default { type: "function", function: { name: "switch_mode", - description: - "Request a switch to a different assistant mode. The user must approve the change before it takes effect.", + description: SWITCH_MODE_DESCRIPTION, strict: true, parameters: { type: "object", properties: { mode_slug: { type: "string", - description: "Slug of the mode to switch to (e.g., code, ask, architect)", + description: MODE_SLUG_PARAMETER_DESCRIPTION, }, reason: { type: "string", - description: "Explanation for why the mode switch is needed", + description: REASON_PARAMETER_DESCRIPTION, }, }, required: ["mode_slug", "reason"], diff --git a/src/core/prompts/tools/native-tools/update_todo_list.ts b/src/core/prompts/tools/native-tools/update_todo_list.ts index d7e678bcb9c..bad8e56e959 100644 --- a/src/core/prompts/tools/native-tools/update_todo_list.ts +++ b/src/core/prompts/tools/native-tools/update_todo_list.ts @@ -1,19 +1,50 @@ import type OpenAI from "openai" +const UPDATE_TODO_LIST_DESCRIPTION = `Replace the entire TODO list with an updated checklist reflecting the current state. Always provide the full list; the system will overwrite the previous one. This tool is designed for step-by-step task tracking, allowing you to confirm completion of each step before updating, update multiple task statuses at once (e.g., mark one as completed and start the next), and dynamically add new todos discovered during long or complex tasks. + +Checklist Format: +- Use a single-level markdown checklist (no nesting or subtasks) +- List todos in the intended execution order +- Status options: [ ] (pending), [x] (completed), [-] (in progress) + +Core Principles: +- Before updating, always confirm which todos have been completed +- You may update multiple statuses in a single update +- Add new actionable items as they're discovered +- Only mark a task as completed when fully accomplished +- Keep all unfinished tasks unless explicitly instructed to remove + +Example: Initial task list +{ "todos": "[x] Analyze requirements\\n[x] Design architecture\\n[-] Implement core logic\\n[ ] Write tests\\n[ ] Update documentation" } + +Example: After completing implementation +{ "todos": "[x] Analyze requirements\\n[x] Design architecture\\n[x] Implement core logic\\n[-] Write tests\\n[ ] Update documentation\\n[ ] Add performance benchmarks" } + +When to Use: +- Task involves multiple steps or requires ongoing tracking +- Need to update status of several todos at once +- New actionable items are discovered during execution +- Task is complex and benefits from stepwise progress tracking + +When NOT to Use: +- Only a single, trivial task +- Task can be completed in one or two simple steps +- Request is purely conversational or informational` + +const TODOS_PARAMETER_DESCRIPTION = `Full markdown checklist in execution order, using [ ] for pending, [x] for completed, and [-] for in progress` + export default { type: "function", function: { name: "update_todo_list", - description: - "Replace the entire todo list with an updated single-level markdown checklist that reflects the current plan and status. Always confirm completed work, keep unfinished items, add new actionable tasks, and follow the [ ], [x], [-] status rules.", + description: UPDATE_TODO_LIST_DESCRIPTION, strict: true, parameters: { type: "object", properties: { todos: { type: "string", - description: - "Full markdown checklist in execution order, using [ ] for pending, [x] for completed, and [-] for in progress", + description: TODOS_PARAMETER_DESCRIPTION, }, }, required: ["todos"], diff --git a/src/core/prompts/tools/native-tools/write_to_file.ts b/src/core/prompts/tools/native-tools/write_to_file.ts index 7a88982bbb4..2febb32b2ec 100644 --- a/src/core/prompts/tools/native-tools/write_to_file.ts +++ b/src/core/prompts/tools/native-tools/write_to_file.ts @@ -1,26 +1,41 @@ import type OpenAI from "openai" +const WRITE_TO_FILE_DESCRIPTION = `Request to write content to a file. This tool is primarily used for creating new files or for scenarios where a complete rewrite of an existing file is intentionally required. If the file exists, it will be overwritten. If it doesn't exist, it will be created. This tool will automatically create any directories needed to write the file. + +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. When performing a full rewrite of an existing file or creating a new one, 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 the line numbers in the content though, just the actual content of the file. +- line_count: (required) The number of lines in the file. Make sure to compute this based on the actual content of the file, not the number of lines in the content you're providing. + +Example: Writing a configuration file +{ "path": "frontend-config.json", "content": "{\\n \\"apiEndpoint\\": \\"https://api.example.com\\",\\n \\"theme\\": {\\n \\"primaryColor\\": \\"#007bff\\"\\n }\\n}", "line_count": 5 }` + +const PATH_PARAMETER_DESCRIPTION = `Path to the file to write, relative to the workspace` + +const CONTENT_PARAMETER_DESCRIPTION = `Full contents that the file should contain with no omissions or line numbers` + +const LINE_COUNT_PARAMETER_DESCRIPTION = `Total number of lines in the written file, counting blank lines` + export default { type: "function", function: { name: "write_to_file", - description: - "Create a new file or completely overwrite an existing file with the exact content provided. Use only when a full rewrite is intended; the tool will create missing directories automatically.", + description: WRITE_TO_FILE_DESCRIPTION, strict: true, parameters: { type: "object", properties: { path: { type: "string", - description: "Path to the file to write, relative to the workspace", + description: PATH_PARAMETER_DESCRIPTION, }, content: { type: "string", - description: "Full contents that the file should contain with no omissions or line numbers", + description: CONTENT_PARAMETER_DESCRIPTION, }, line_count: { type: "integer", - description: "Total number of lines in the written file, counting blank lines", + description: LINE_COUNT_PARAMETER_DESCRIPTION, }, }, required: ["path", "content", "line_count"],