diff --git a/nanobot/agent/tools/shell.py b/nanobot/agent/tools/shell.py
index f6d37f14..6fb4c5b6 100644
--- a/nanobot/agent/tools/shell.py
+++ b/nanobot/agent/tools/shell.py
@@ -90,9 +90,13 @@ class _PreparedCommand:
         ),
         shell=StringSchema(
             (
-                "Optional shell binary to launch. Windows: powershell, pwsh, cmd."
+                "Override the Windows shell only when needed. Omit to use "
+                "PowerShell by default (pwsh when available, else powershell). "
+                "Pass 'cmd' only for cmd.exe syntax or cmd built-ins."
                 if _IS_WINDOWS
-                else "Optional shell binary to launch. Unix: sh, bash, zsh."
+                else "Override the Unix shell only when needed. Omit to use "
+                "bash by default. Pass 'sh' for POSIX sh or 'zsh' for "
+                "zsh-specific syntax."
             ),
             nullable=True,
         ),
diff --git a/tests/tools/test_tool_descriptions.py b/tests/tools/test_tool_descriptions.py
index 9ae2fc58..ef5e8b8c 100644
--- a/tests/tools/test_tool_descriptions.py
+++ b/tests/tools/test_tool_descriptions.py
@@ -63,10 +63,14 @@ def test_exec_tool_shell_guidance_matches_platform() -> None:
 
     shell_parameter = ExecTool().parameters["properties"]["shell"]["description"].lower()
     if sys.platform == "win32":
+        assert "override the windows shell only when needed" in shell_parameter
+        assert "omit to use powershell by default" in shell_parameter
         assert "powershell" in shell_parameter
         assert "cmd" in shell_parameter
         assert "unix" not in shell_parameter
     else:
+        assert "override the unix shell only when needed" in shell_parameter
+        assert "omit to use bash by default" in shell_parameter
         assert "unix" in shell_parameter
         assert "powershell" not in shell_parameter
         assert "cmd" not in shell_parameter