From c4ab2efef64ee97e85ec91ab2a799b9e68221748 Mon Sep 17 00:00:00 2001 From: Waishnav <86405648+Waishnav@users.noreply.github.com> Date: Mon, 7 Sep 2026 22:52:34 +0530 Subject: [PATCH 1/2] refactor(mcp): trim server model instructions --- src/server.ts | 8 ++++---- src/tool-surfaces/claude.ts | 2 +- src/tool-surfaces/codex.ts | 2 +- 3 files changed, 6 insertions(+), 6 deletions(-) diff --git a/src/server.ts b/src/server.ts index d92ae592..72ec1b88 100644 --- a/src/server.ts +++ b/src/server.ts @@ -126,15 +126,15 @@ function serverInstructions( ): string { const artifactInstruction = config.artifactsEnabled && isArtifactDownloadSupportedPlatform() - ? " When the user supplies or generates a file that is not present on the DevSpace host, use download_artifact with its native file value, the existing workspace ID, and a suitable relative destination path chosen from the user's request and project structure. The tool refuses to overwrite an existing destination and returns the normalized workspace-relative path. Use normal workspace tools when explicit inspection, replacement, movement, renaming, or deletion is needed. Do not recreate binary files with write/edit calls or place signed URLs, native file objects, base64 content, or invented host paths in shell commands or logs." + ? " When the user provides an attached or generated file that needs to be added to the workspace, pass the provided file directly to download_artifact with the existing workspace_id and a suitable relative destination path. Do not reconstruct attached files manually." : ""; const showChangesInstruction = - " If the turn successfully modifies files by creating, editing, overwriting, deleting, moving, or applying patches, call show_changes exactly once for that workspace after the final related file change and before your final response so the user can inspect the aggregate diff for that turn. Do not call it after every individual file change."; + " If files are modified, call show_changes once after the final related change and before the final response."; const skills = config.skillsEnabled - ? `When ${toolNames.openWorkspace} returns available skills and a task matches a skill, use ${toolNames.read} to read that skill's path before proceeding. Skill paths may be outside the workspace, and ${toolNames.read} permits files within advertised skill directories. ` + ? `When ${toolNames.openWorkspace} returns available skills and a task matches one, use ${toolNames.read} with the returned skill path before proceeding. ` : ""; const agents = `Follow instructions returned by ${toolNames.openWorkspace}. Before working under a path listed in available_agents_files, use ${toolNames.read} to inspect that instruction file and follow it. `; - const common = `Use DevSpace for coding work. Call ${toolNames.openWorkspace} once for each project folder or isolated worktree, then keep using its workspace_id. During continued work in the same project or worktree, do not call ${toolNames.openWorkspace} again. Open another workspace only when changing projects, switching checkout/worktree mode, creating another isolated worktree, or when the current workspace_id is rejected.`; + const common = `Call ${toolNames.openWorkspace} when starting work in a project folder or isolated worktree without a usable workspace_id, then reuse the returned workspace_id for subsequent operations in that workspace.`; return `${common} ${toolSurface.instructions({ agents, skills })}${artifactInstruction}${showChangesInstruction}`; } diff --git a/src/tool-surfaces/claude.ts b/src/tool-surfaces/claude.ts index 635179d9..2b9c30c4 100644 --- a/src/tool-surfaces/claude.ts +++ b/src/tool-surfaces/claude.ts @@ -22,7 +22,7 @@ import { textBlock, } from "./shared.js"; -const CLAUDE_INSTRUCTIONS = `Use ${toolNames.read} for direct file reads, ${toolNames.edit} for targeted modifications, ${toolNames.write} only for new files or complete rewrites, and ${toolNames.shell} for inspection, tests, builds, and other commands. Shell commands run with the local user's authority and are not sandboxed; workspace validation only selects their initial working directory. Follow instructions returned by ${toolNames.openWorkspace}; read applicable instruction and skill files before working in their scope.`; +const CLAUDE_INSTRUCTIONS = `Follow instructions returned by ${toolNames.openWorkspace}; read applicable instruction and skill files before working in their scope.`; export function claudeInstructions({ agents, diff --git a/src/tool-surfaces/codex.ts b/src/tool-surfaces/codex.ts index eff3bbde..cf249067 100644 --- a/src/tool-surfaces/codex.ts +++ b/src/tool-surfaces/codex.ts @@ -20,7 +20,7 @@ import { type CodexRegistration = (context: ToolRegistrationContext) => void; -const CODEX_INSTRUCTIONS = `Use ${toolNames.read} for direct file reads, apply_patch for all file modifications, exec_command for inspection, tests, builds, and other commands, and write_stdin to poll or interact with running processes. Commands run with the local user's authority and are not sandboxed; workspace validation only selects their initial working directory. Follow instructions returned by ${toolNames.openWorkspace}; read applicable instruction and skill files before working in their scope.`; +const CODEX_INSTRUCTIONS = `Follow instructions returned by ${toolNames.openWorkspace}; read applicable instruction and skill files before working in their scope.`; export function codexInstructions(): string { return CODEX_INSTRUCTIONS; From 7191afb29c493d562660dc3e4916851882968f92 Mon Sep 17 00:00:00 2001 From: Waishnav <86405648+Waishnav@users.noreply.github.com> Date: Mon, 7 Sep 2026 22:53:11 +0530 Subject: [PATCH 2/2] refactor(mcp): simplify tool descriptions --- src/artifact-tools.ts | 4 ++-- src/server.ts | 6 +++--- src/tool-surfaces/claude.ts | 7 ++++--- src/tool-surfaces/codex.ts | 4 ++-- 4 files changed, 11 insertions(+), 10 deletions(-) diff --git a/src/artifact-tools.ts b/src/artifact-tools.ts index d6afd418..1a9338d1 100644 --- a/src/artifact-tools.ts +++ b/src/artifact-tools.ts @@ -98,10 +98,10 @@ export function registerArtifactTools( { title: "Download attached or generated file", description: - "Stream one MCP-host-provided native file to a requested relative path inside a workspace. Existing destinations, arbitrary URLs, absolute paths, traversal, symlinked parents, source filesystem paths, and malformed file objects are rejected.", + "Save an attached or generated file to a relative path inside a workspace. The destination must not already exist.", inputSchema: { file: openAIFileReferenceInputSchema.describe( - "Native file value authorized and supplied by the MCP host.", + "Attached or generated file to save.", ), workspace_id: z.string().min(1).describe( "Workspace to use. Reuse the current project's workspace_id.", diff --git a/src/server.ts b/src/server.ts index 72ec1b88..608498a4 100644 --- a/src/server.ts +++ b/src/server.ts @@ -619,10 +619,10 @@ function registerMcpSurface( title: "Read file", description: [ - "Read a file in a workspace. Use this for file inspection instead of shell commands like cat or sed.", + "Read all or part of a file in a workspace.", "Use this tool to inspect relevant AGENTS.md or CLAUDE.md files listed by open_workspace before working in nested directories.", config.skillsEnabled - ? "If available skills were returned and a task matches one, read that skill's path before proceeding. Skill paths may be outside the workspace; files within advertised skill directories are readable." + ? "If available skills were returned and a task matches one, read the returned skill path before proceeding." : "", ] .filter(Boolean) @@ -635,7 +635,7 @@ function registerMcpSurface( .string() .describe( config.skillsEnabled - ? "File path to read, relative to the workspace root. May also be an advertised skill path from open_workspace skills." + ? "File path relative to the workspace root, or a skill path returned by open_workspace." : "File path to read, relative to the workspace root.", ), offset: z diff --git a/src/tool-surfaces/claude.ts b/src/tool-surfaces/claude.ts index 2b9c30c4..d7d17f65 100644 --- a/src/tool-surfaces/claude.ts +++ b/src/tool-surfaces/claude.ts @@ -36,7 +36,7 @@ export function registerClaudeTools(context: ToolRegistrationContext): void { registerShellTool(context); } -const CLAUDE_SHELL_DESCRIPTION = `Run a shell command with the local user's authority. Commands are not sandboxed; workspace validation only selects the initial working directory. Use this for file inspection, tests, builds, package scripts, and other commands.`; +const CLAUDE_SHELL_DESCRIPTION = "Run a shell command in a workspace with the user's local permissions."; function registerClaudeMutationTools(context: ToolRegistrationContext): void { const { server, config, workspaces } = context; @@ -45,7 +45,7 @@ function registerClaudeMutationTools(context: ToolRegistrationContext): void { toolNames.write, { title: "Write file", - description: `Create or completely overwrite a file in a workspace. Prefer ${toolNames.edit} for targeted changes to existing files.`, + description: "Create or completely overwrite a file in a workspace.", inputSchema: { workspace_id: z.string().describe(workspaceIdDescription), path: z @@ -101,7 +101,8 @@ function registerClaudeMutationTools(context: ToolRegistrationContext): void { toolNames.edit, { title: "Edit file", - description: `Edit one file in a workspace by replacing exact text blocks. Prefer this over ${toolNames.write} for targeted changes. Each old_text must match a unique, non-overlapping region of the original file; merge nearby changes into one edit and keep old_text as small as possible while still unique.`, + description: + "Edit one file in a workspace by replacing exact text blocks. Each old_text must match a unique, non-overlapping region of the original file.", inputSchema: { workspace_id: z.string().describe(workspaceIdDescription), path: z diff --git a/src/tool-surfaces/codex.ts b/src/tool-surfaces/codex.ts index cf249067..23b3e853 100644 --- a/src/tool-surfaces/codex.ts +++ b/src/tool-surfaces/codex.ts @@ -84,7 +84,7 @@ function registerApplyPatchTool(context: ToolRegistrationContext): void { { title: "Apply patch", description: - "Apply one Codex-style patch in a workspace. Supports adding, overwriting, updating, deleting, and moving files. Use this for all file modifications. Paths must be relative to the workspace.", + "Apply one Codex-style patch to add, overwrite, update, delete, or move workspace files. Paths must be relative to the workspace.", inputSchema: { workspace_id: z.string().describe(workspaceIdDescription), patch: z @@ -146,7 +146,7 @@ function registerCodexProcessTools(context: ToolRegistrationContext): void { { title: "Execute command", description: - "Run a command with the local user's authority. Commands are not sandboxed; workspace validation only selects the initial working directory. Returns the result when it exits during the yield window, otherwise returns a session_id to continue with write_stdin. Use this for file inspection, tests, builds, package scripts, and long-running processes.", + "Run a shell command in a workspace with the user's local permissions. Returns the result when it exits during the yield window, otherwise returns a session_id for write_stdin.", inputSchema: { workspace_id: z.string().describe(workspaceIdDescription), cmd: z.string().min(1).describe("Shell command to execute."),