1  <tools>
 2    <tool name="execute_shell">
 3      <description>Execute a shell command in a subprocess and return the output.
 4  Use this tool when you need to run system commands, manage files, interact with command-line tools, or perform system operations.</description>
 5      <details>This tool executes shell commands using subprocess with configurable timeout.
 6  Important notes:
 7  - Commands run through the system shell (/bin/sh or cmd.exe)
 8  - Captures both stdout and stderr
 9  - Default timeout is 30 seconds
10  - Returns stdout, stderr, and return code
11  - Supports piping, redirection, and other shell features
12  
13      Security considerations:
14      - Commands execute with the same permissions as the agent process
15      - Be extremely careful with destructive operations (rm, del, etc.)
16      - Avoid executing untrusted commands
17      - Commands will affect the actual system (not sandboxed)
18      - Use absolute paths when possible for clarity</details>
19  <parameters>
20      <parameter name="command" type="string" required="true">
21          <description>The shell command to execute. Can include pipes, redirections, and other shell syntax.</description>
22      </parameter>
23      <parameter name="timeout" type="integer" required="false">
24          <description>Maximum execution time in seconds. Default is 300 seconds. Use higher values for long-running commands.</description>
25      </parameter>
26      <parameter name="cwd" type="string" required="false">
27          <description>The working directory in which to execute the command. If not specified, defaults to the current working directory of the agent.</description>
28      </parameter>
29  </parameters>
30  <returns type="Dict[str, Any]">
31      <description>Response containing:
32          - success: Whether the command executed successfully (return code 0)
33          - message: Status message
34          - Dictionary with stdout, stderr, and return_code</description>
35  </returns>
36  <examples>
37      # List files
38      <function=execute_shell>
39      <parameter=command>ls -la</parameter>
40  </function>
41  
42          # Check disk space
43  <function=execute_shell>
44  <parameter=command>df -h</parameter>
45          </function>
46  
47          # Using pipes
48  <function=execute_shell>
49  <parameter=command>cat /etc/hosts | grep localhost</parameter>
50          </function>
51  
52          # With custom timeout
53  <function=execute_shell>
54  <parameter=command>sleep 5 && echo "Done waiting"</parameter>
55  <parameter=timeout>10</parameter>
56          </function>
57  
58          # Create directory structure
59  <function=execute_shell>
60  <parameter=command>mkdir -p project/{src,tests,docs} && ls -R project</parameter>
61          </function>
62  
63          # Git operations
64          <function=execute_shell>
65          <parameter=command>git status</parameter>
66          </function>
67  
68          # Execute in a specific directory
69          <function=execute_shell>
70          <parameter=command>ls -la</parameter>
71          <parameter=cwd>/app/AIG-PromptSecurity</parameter>
72          </function>
73      </examples>
74    </tool>
75  </tools>