docs(tools): refine discovery and extraction guidance for glob, grep, and shell tools (#17545)

packages/core/src/tools/glob.ts

@@ -268,7 +268,7 @@ export class GlobTool extends BaseDeclarativeTool<GlobToolParams, ToolResult> {
     super(
       GlobTool.Name,
       'FindFiles',
-      'Efficiently finds files matching specific glob patterns (e.g., `src/**/*.ts`, `**/*.md`), returning absolute paths sorted by modification time (newest first). Ideal for quickly locating files based on their name or path structure, especially in large codebases.',
+      'Finds files matching glob patterns (e.g., `src/**/*.ts`). Results are sorted by modification time (newest first). Ideal for structural discovery. For finding logic or symbols, `grep_search` is preferred as it provides matching context.',
       Kind.Search,
       {
         properties: {

packages/core/src/tools/ripGrep.ts

@@ -499,7 +499,7 @@ export class RipGrepTool extends BaseDeclarativeTool<
     super(
       RipGrepTool.Name,
       'SearchText',
-      'Searches for a regular expression pattern within file contents. Max 100 matches.',
+      'FAST, optimized regular expression search. Use context parameters (`context`, `after`, `before`) to read code surrounding matches in a single turn. For surgical extraction (e.g., regex ranges), see `run_shell_command`.',
       Kind.Search,
       {
         properties: {

packages/core/src/tools/shell.ts

@@ -467,12 +467,16 @@ function getShellToolDescription(enableInteractiveShell: boolean): string {
     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}`;
+    const examples =
+      'Versatile for complex discovery or surgical extraction. Examples: `Get-Content file | Select-Object -Index (49..99)` for range reading, or `Get-ChildItem -Recurse -Filter *.ts | Select-String "pattern"`.';
+    return `This tool executes a given shell command as \`powershell.exe -NoProfile -Command <command>\`. ${backgroundInstructions} ${examples}${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}`;
+    const examples =
+      "Versatile for complex discovery or surgical extraction. Examples: `sed -n '50,100p' file` for range reading, `sed -n '/class X/,/^}/p' file` for block extraction, or `find . -name '*.ts' | xargs grep 'pattern'`.";
+    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\`. ${examples}${returnedInfo}`;
   }
 }