docs: clarify exec shell override guidance

Maintainer edit: make the shell parameter description explain defaults and when to override instead of only listing shell names.

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,
         ),

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