diff --git a/packages/core/src/tools/definitions/coreTools.ts b/packages/core/src/tools/definitions/coreTools.ts
index 4a585ebd1f..2156653d78 100644
--- a/packages/core/src/tools/definitions/coreTools.ts
+++ b/packages/core/src/tools/definitions/coreTools.ts
@@ -9,39 +9,9 @@ import type { ToolDefinition } from './types.js';
 import { READ_FILE_TOOL_NAME, SHELL_TOOL_NAME } from '../tool-names.js';
 import * as os from 'node:os';
 
-export function getShellToolDescription(
-  enableInteractiveShell: boolean,
-): string {
-  const returnedInfo = `
-
-      The following information is returned:
-
-      Output: Combined stdout/stderr. Can be \`(empty)\` or partial on error and for any unwaited background processes.
-      Exit Code: Only included if non-zero (command failed).
-      Error: Only included if a process-level error occurred (e.g., spawn failure).
-      Signal: Only included if process was terminated by a signal.
-      Background PIDs: Only included if background processes were started.
-      Process Group PGID: Only included if available.`;
-
-  if (os.platform() === 'win32') {
-    const backgroundInstructions = enableInteractiveShell
-      ? 'To run a command in the background, set the `is_background` parameter to true. Do NOT use PowerShell background constructs.'
-      : 'Command can start background processes using PowerShell constructs such as `Start-Process -NoNewWindow` or `Start-Job`.';
-    return `This tool executes a given shell command as \`powershell.exe -NoProfile -Command <command>\`. ${backgroundInstructions}${returnedInfo}`;
-  } else {
-    const backgroundInstructions = enableInteractiveShell
-      ? 'To run a command in the background, set the `is_background` parameter to true. Do NOT use `&` to background commands.'
-      : 'Command can start background processes using `&`.';
-    return `This tool executes a given shell command as \`bash -c <command>\`. ${backgroundInstructions} Command is executed as a subprocess that leads its own process group. Command process group can be terminated as \`kill -- -PGID\` or signaled as \`kill -s SIGNAL -- -PGID\`.${returnedInfo}`;
-  }
-}
-
-export function getCommandDescription(): string {
-  if (os.platform() === 'win32') {
-    return 'Exact command to execute as `powershell.exe -NoProfile -Command <command>`';
-  }
-  return 'Exact bash command to execute as `bash -c <command>`';
-}
+// ============================================================================
+// READ_FILE TOOL
+// ============================================================================
 
 export const READ_FILE_DEFINITION: ToolDefinition = {
   base: {
@@ -70,6 +40,53 @@ export const READ_FILE_DEFINITION: ToolDefinition = {
   },
 };
 
+// ============================================================================
+// SHELL TOOL
+// ============================================================================
+
+/**
+ * Generates the platform-specific description for the shell tool.
+ */
+export function getShellToolDescription(
+  enableInteractiveShell: boolean,
+): string {
+  const returnedInfo = `
+
+      The following information is returned:
+
+      Output: Combined stdout/stderr. Can be \`(empty)\` or partial on error and for any unwaited background processes.
+      Exit Code: Only included if non-zero (command failed).
+      Error: Only included if a process-level error occurred (e.g., spawn failure).
+      Signal: Only included if process was terminated by a signal.
+      Background PIDs: Only included if background processes were started.
+      Process Group PGID: Only included if available.`;
+
+  if (os.platform() === 'win32') {
+    const backgroundInstructions = enableInteractiveShell
+      ? 'To run a command in the background, set the `is_background` parameter to true. Do NOT use PowerShell background constructs.'
+      : 'Command can start background processes using PowerShell constructs such as `Start-Process -NoNewWindow` or `Start-Job`.';
+    return `This tool executes a given shell command as \`powershell.exe -NoProfile -Command <command>\`. ${backgroundInstructions}${returnedInfo}`;
+  } else {
+    const backgroundInstructions = enableInteractiveShell
+      ? 'To run a command in the background, set the `is_background` parameter to true. Do NOT use `&` to background commands.'
+      : 'Command can start background processes using `&`.';
+    return `This tool executes a given shell command as \`bash -c <command>\`. ${backgroundInstructions} Command is executed as a subprocess that leads its own process group. Command process group can be terminated as \`kill -- -PGID\` or signaled as \`kill -s SIGNAL -- -PGID\`.${returnedInfo}`;
+  }
+}
+
+/**
+ * Returns the platform-specific description for the 'command' parameter.
+ */
+export function getCommandDescription(): string {
+  if (os.platform() === 'win32') {
+    return 'Exact command to execute as `powershell.exe -NoProfile -Command <command>`';
+  }
+  return 'Exact bash command to execute as `bash -c <command>`';
+}
+
+/**
+ * Returns the tool definition for the shell tool, customized for the platform.
+ */
 export function getShellDefinition(
   enableInteractiveShell: boolean,
 ): ToolDefinition {