diff --git a/agentscope-harness/src/main/java/io/agentscope/harness/agent/tool/ShellExecuteTool.java b/agentscope-harness/src/main/java/io/agentscope/harness/agent/tool/ShellExecuteTool.java
index 1563a094f..cc8d2b7b2 100644
--- a/agentscope-harness/src/main/java/io/agentscope/harness/agent/tool/ShellExecuteTool.java
+++ b/agentscope-harness/src/main/java/io/agentscope/harness/agent/tool/ShellExecuteTool.java
@@ -26,7 +26,9 @@
  */
 public class ShellExecuteTool {
 
-    /** Registered tool name (derived from the {@link #execute} method name). */
+    /**
+     * Registered tool name (derived from the {@link #execute} method name).
+     */
     public static final String NAME = "execute";
 
     private final AbstractSandboxFilesystem sandbox;
@@ -37,19 +39,23 @@ public ShellExecuteTool(AbstractSandboxFilesystem sandbox) {
 
     /**
      * @param runtimeContext per-call agent runtime injected by the framework (not an LLM argument);
-     *     may be {@code null} when no merged context is available
+     *                       may be {@code null} when no merged context is available
      */
     @Tool(
             description =
                     "Execute a shell command. Use for git, npm, build, test, and other terminal"
-                            + " operations. Returns combined output and exit code.")
+                        + " operations. Returns combined output and exit code. If a dedicated tool"
+                        + " exists (e.g., read_file, write_file), you MUST use it instead of shell"
+                        + " commands.")
     public String execute(
             RuntimeContext runtimeContext,
             @ToolParam(name = "command", description = "Shell command to execute") String command,
             @ToolParam(
                             name = "working_directory",
                             description =
-                                    "Working directory (relative to workspace root, optional)")
+                                    "Optional relative path from workspace root. Must not start"
+                                            + " with /, ~, or ..(e.g., ., src).",
+                            required = false)
                     String workingDirectory,
             @ToolParam(name = "timeout", description = "Timeout in seconds (default: 30)")
                     int timeout) {