feat(tools): add getToolExplanation() method with XML examples for LLM tool calling

Each tool now provides comprehensive documentation including parameter
schemas and concrete <tool_call> XML examples. This helps smaller LLMs
understand the exact format required for tool invocation.

ts/smartagent.tools.shell.ts

@@ -148,6 +148,54 @@ export class ShellTool extends BaseToolWrapper {
     }
   }
 
+  public getToolExplanation(): string {
+    return `## Tool: shell
+Execute shell commands securely. Uses execSpawn (shell:false) to prevent command injection.
+
+### Actions:
+
+**execute** - Execute a command with arguments (secure, no shell injection possible)
+Parameters:
+  - command (required): The command to execute (e.g., "ls", "cat", "grep", "node")
+  - args (optional): Array of arguments (each argument is properly escaped)
+  - cwd (optional): Working directory for the command
+  - timeout (optional): Timeout in milliseconds
+  - env (optional): Additional environment variables (key-value object)
+
+Example - List files:
+<tool_call>
+  <tool>shell</tool>
+  <action>execute</action>
+  <params>{"command": "ls", "args": ["-la", "/path/to/dir"]}</params>
+</tool_call>
+
+Example - Run Node script:
+<tool_call>
+  <tool>shell</tool>
+  <action>execute</action>
+  <params>{"command": "node", "args": ["script.js"], "cwd": "/path/to/project"}</params>
+</tool_call>
+
+Example - Search in files:
+<tool_call>
+  <tool>shell</tool>
+  <action>execute</action>
+  <params>{"command": "grep", "args": ["-r", "pattern", "src/"]}</params>
+</tool_call>
+
+**which** - Check if a command exists and get its path
+Parameters:
+  - command (required): Command name to look up (e.g., "node", "git")
+
+Example:
+<tool_call>
+  <tool>shell</tool>
+  <action>which</action>
+  <params>{"command": "node"}</params>
+</tool_call>
+`;
+  }
+
   public getCallSummary(action: string, params: Record<string, unknown>): string {
     switch (action) {
       case 'execute': {