diff --git a/docs/tools/filesystem/index.md b/docs/tools/filesystem/index.md
index 921d252735..42a5471619 100644
--- a/docs/tools/filesystem/index.md
+++ b/docs/tools/filesystem/index.md
@@ -28,6 +28,15 @@ When a file is not found, error messages include the resolved absolute path to h
 > [!IMPORTANT]
 > Agents must use paths appropriate for the host OS. A Windows absolute path like `C:\file.txt` on a Unix system (or vice versa) is rejected with a clear error message.
 
+### Empty directory detection
+
+When `list_directory` encounters an empty directory or a directory where all entries are hidden by ignore patterns (e.g., only a `.git` folder when `ignore_vcs: true`), it explicitly reports the state:
+
+- **Empty directory**: "Directory is empty: /path/to/dir"
+- **All entries ignored**: "Directory has no visible entries (N hidden by ignore patterns): /path/to/dir"
+
+This helps agents distinguish between an empty directory and a tool failure, avoiding unnecessary retries with shell commands.
+
 ## Available Tools
 
 | Tool                   | Description                                                               |
@@ -36,7 +45,7 @@ When a file is not found, error messages include the resolved absolute path to h
 | `read_multiple_files`  | Read several files in one call (more efficient than multiple `read_file`) |
 | `write_file`           | Create or overwrite a file with new content                               |
 | `edit_file`            | Make line-based edits (find-and-replace) in an existing file              |
-| `list_directory`       | List files and directories at a given path                                |
+| `list_directory`       | List files and directories at a given path (explicitly reports empty directories) |
 | `directory_tree`       | Recursive tree view of a directory                                        |
 | `create_directory`     | Create a new directory (creates parent directories as needed)             |
 | `remove_directory`     | Remove an empty directory                                                 |
diff --git a/docs/tools/shell/index.md b/docs/tools/shell/index.md
index 297c457ef9..4649dff3aa 100644
--- a/docs/tools/shell/index.md
+++ b/docs/tools/shell/index.md
@@ -15,6 +15,17 @@ The shell tool allows agents to execute arbitrary shell commands synchronously.
 
 Commands have a default 30-second timeout and require user confirmation unless `--yolo` is used. For servers, watchers, and other long-running commands, add the [`background_jobs`](../background-jobs/index.md) toolset alongside `shell`.
 
+### Shell interpreter detection
+
+The shell tool automatically detects and names the resolved shell interpreter (e.g., `bash`, `zsh`, `powershell`, `pwsh`, `cmd`) in its description to the model, along with the operating system (Linux, macOS, Windows). This helps models use the correct shell syntax for the host environment.
+
+For example:
+
+- On Linux with bash: "Executes the given shell command with bash on Linux."
+- On Windows with PowerShell: "Executes the given shell command with powershell on Windows. Use Windows PowerShell 5.1 syntax: chain commands with ";" (not "&&"), and avoid POSIX commands/flags like "ls -la"."
+
+This reduces wasted turns where models assume POSIX syntax on Windows or vice versa.
+
 ## Configuration
 
 ```yaml