1 files changed, 53 insertions, 38 deletions
diff --git a/docs/tools/shell.md b/docs/tools/shell.md
index e60fb9a4..ff6e574e 100644
--- a/docs/tools/shell.md
+++ b/docs/tools/shell.md
@@ -1,46 +1,61 @@
-# Shell Tool
+# Shell Tool (`run_shell_command`)
 
-This document provides details on the shell tool.
+This document describes the `run_shell_command` tool for the Gemini CLI.
 
-## `run_shell_command`
+## Description
 
-- **Purpose:** Executes a given shell command. On Windows, this will be executed with `cmd.exe /c`. On other platforms, it will be executed with `bash -c`. This tool is essential for interacting with the underlying operating system, running scripts, or performing command-line operations.
-- **Arguments:**
-  - `command` (string, required): The exact shell command to execute.
-  - `description` (string, optional): A brief description of the command's purpose, which will be shown to the user.
-  - `directory` (string, optional): The directory (relative to the project root) in which to execute the command. If not provided, the command runs in the project root.
-- **Behavior:**
-  - The command is executed as a subprocess.
-  - It can start background processes using `&`.
-  - The tool returns detailed information about the execution, including:
-    - `Command`: The command that was executed.
-    - `Directory`: The directory where the command was run.
-    - `Stdout`: Output from the standard output stream.
-    - `Stderr`: Output from the standard error stream.
-    - `Error`: Any error message reported by the subprocess.
-    - `Exit Code`: The exit code of the command.
-    - `Signal`: The signal number if the command was terminated by a signal.
-    - `Background PIDs`: A list of PIDs for any background processes started.
-- **Examples:**
+Use `run_shell_command` to interact with the underlying system, run scripts, or perform command-line operations. `run_shell_command` executes a given shell command. On Windows, the command will be executed with `cmd.exe /c`. On other platforms, the command will be executed with `bash -c`.
 
-  - Listing files in the current directory:
+### Arguments
 
-    ```
+`run_shell_command` takes the following arguments:
 
-    run_shell_command(command="ls -la")
-    ```
+- `command` (string, required): The exact shell command to execute.
+- `description` (string, optional): A brief description of the command's purpose, which will be shown to the user.
+- `directory` (string, optional): The directory (relative to the project root) in which to execute the command. If not provided, the command runs in the project root.
 
-  - Running a script in a specific directory:
-    ```
-    run_shell_command(command="./my_script.sh", directory="scripts", description="Run my custom script")
-    ```
-  - Starting a background server:
-    ```
-    run_shell_command(command="npm run dev &", description="Start development server in background")
-    ```
+## How to use `run_shell_command` with the Gemini CLI
 
-- **Important Notes:**
-  - **Security:** Be cautious when executing commands, especially those constructed from user input, to prevent security vulnerabilities.
-  - **Interactive Commands:** Avoid commands that require interactive user input, as this can cause the tool to hang. Use non-interactive flags if available (e.g., `npm init -y`).
-  - **Error Handling:** Check the `Stderr`, `Error`, and `Exit Code` fields to determine if a command executed successfully.
-  - **Background Processes:** When a command is run in the background with `&`, the tool will return immediately and the process will continue to run in the background. The `Background PIDs` field will contain the process ID of the background process.
+When using `run_shell_command`, the command is executed as a subprocess. `run_shell_command` can start background processes using `&`. The tool returns detailed information about the execution, including:
+
+- `Command`: The command that was executed.
+- `Directory`: The directory where the command was run.
+- `Stdout`: Output from the standard output stream.
+- `Stderr`: Output from the standard error stream.
+- `Error`: Any error message reported by the subprocess.
+- `Exit Code`: The exit code of the command.
+- `Signal`: The signal number if the command was terminated by a signal.
+- `Background PIDs`: A list of PIDs for any background processes started.
+
+Usage:
+
+```
+run_shell_command(command="Your commands.", description="Your description of the command.", directory="Your execution directory.")
+```
+
+## `run_shell_command` examples
+
+List files in the current directory:
+
+```
+run_shell_command(command="ls -la")
+```
+
+Run a script in a specific directory:
+
+```
+run_shell_command(command="./my_script.sh", directory="scripts", description="Run my custom script")
+```
+
+Start a background server:
+
+```
+run_shell_command(command="npm run dev &", description="Start development server in background")
+```
+
+## Important notes
+
+- **Security:** Be cautious when executing commands, especially those constructed from user input, to prevent security vulnerabilities.
+- **Interactive commands:** Avoid commands that require interactive user input, as this can cause the tool to hang. Use non-interactive flags if available (e.g., `npm init -y`).
+- **Error handling:** Check the `Stderr`, `Error`, and `Exit Code` fields to determine if a command executed successfully.
+- **Background processes:** When a command is run in the background with `&`, the tool will return immediately and the process will continue to run in the background. The `Background PIDs` field will contain the process ID of the background process.