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.filesystem.ts

@@ -666,6 +666,170 @@ export class FilesystemTool extends BaseToolWrapper {
     }
   }
 
+  public getToolExplanation(): string {
+    return `## Tool: filesystem
+Read, write, list, and delete files and directories.
+
+### Actions:
+
+**read** - Read file contents (full or specific line range)
+Parameters:
+  - path (required): Path to the file
+  - encoding (optional): File encoding - "utf8" (default), "binary", or "base64"
+  - startLine (optional): First line to read (1-indexed, inclusive)
+  - endLine (optional): Last line to read (1-indexed, inclusive)
+
+Example:
+<tool_call>
+  <tool>filesystem</tool>
+  <action>read</action>
+  <params>{"path": "/path/to/file.txt"}</params>
+</tool_call>
+
+Example with line range:
+<tool_call>
+  <tool>filesystem</tool>
+  <action>read</action>
+  <params>{"path": "/path/to/file.txt", "startLine": 10, "endLine": 20}</params>
+</tool_call>
+
+**write** - Write content to a file (creates or overwrites)
+Parameters:
+  - path (required): Absolute path to the file
+  - content (required): Content to write
+  - encoding (optional): File encoding - "utf8" (default), "binary", or "base64"
+
+Example:
+<tool_call>
+  <tool>filesystem</tool>
+  <action>write</action>
+  <params>{"path": "/path/to/output.txt", "content": "Hello, World!"}</params>
+</tool_call>
+
+**list** - List files and directories in a path
+Parameters:
+  - path (required): Directory path to list
+  - recursive (optional): List recursively (default: false)
+  - filter (optional): Glob pattern to filter results (e.g., "*.ts")
+
+Example:
+<tool_call>
+  <tool>filesystem</tool>
+  <action>list</action>
+  <params>{"path": "/path/to/dir", "recursive": true, "filter": "*.ts"}</params>
+</tool_call>
+
+**exists** - Check if a file or directory exists
+Parameters:
+  - path (required): Path to check
+
+Example:
+<tool_call>
+  <tool>filesystem</tool>
+  <action>exists</action>
+  <params>{"path": "/path/to/check"}</params>
+</tool_call>
+
+**mkdir** - Create a directory
+Parameters:
+  - path (required): Directory path to create
+  - recursive (optional): Create parent directories if needed (default: true)
+
+Example:
+<tool_call>
+  <tool>filesystem</tool>
+  <action>mkdir</action>
+  <params>{"path": "/path/to/new/dir"}</params>
+</tool_call>
+
+**delete** - Delete a file or directory
+Parameters:
+  - path (required): Path to delete
+  - recursive (optional): For directories, delete recursively (default: false)
+
+Example:
+<tool_call>
+  <tool>filesystem</tool>
+  <action>delete</action>
+  <params>{"path": "/path/to/delete", "recursive": true}</params>
+</tool_call>
+
+**copy** - Copy a file to a new location
+Parameters:
+  - source (required): Source file path
+  - destination (required): Destination file path
+
+Example:
+<tool_call>
+  <tool>filesystem</tool>
+  <action>copy</action>
+  <params>{"source": "/path/to/source.txt", "destination": "/path/to/dest.txt"}</params>
+</tool_call>
+
+**move** - Move a file to a new location
+Parameters:
+  - source (required): Source file path
+  - destination (required): Destination file path
+
+Example:
+<tool_call>
+  <tool>filesystem</tool>
+  <action>move</action>
+  <params>{"source": "/path/to/old.txt", "destination": "/path/to/new.txt"}</params>
+</tool_call>
+
+**stat** - Get file or directory statistics (size, dates, etc.)
+Parameters:
+  - path (required): Path to get stats for
+
+Example:
+<tool_call>
+  <tool>filesystem</tool>
+  <action>stat</action>
+  <params>{"path": "/path/to/file.txt"}</params>
+</tool_call>
+
+**append** - Append content to a file
+Parameters:
+  - path (required): Absolute path to the file
+  - content (required): Content to append
+
+Example:
+<tool_call>
+  <tool>filesystem</tool>
+  <action>append</action>
+  <params>{"path": "/path/to/log.txt", "content": "New log entry\\n"}</params>
+</tool_call>
+
+**tree** - Show directory structure as a tree
+Parameters:
+  - path (required): Root directory path
+  - maxDepth (optional): Maximum depth to traverse (default: 3)
+  - filter (optional): Glob pattern to filter files
+  - showSizes (optional): Include file sizes in output (default: false)
+  - format (optional): Output format - "string" (default) or "json"
+
+Example:
+<tool_call>
+  <tool>filesystem</tool>
+  <action>tree</action>
+  <params>{"path": "/path/to/dir", "maxDepth": 2}</params>
+</tool_call>
+
+**glob** - Find files matching a glob pattern
+Parameters:
+  - pattern (required): Glob pattern (e.g., "**/*.ts", "src/**/*.js")
+  - path (optional): Base path to search from
+
+Example:
+<tool_call>
+  <tool>filesystem</tool>
+  <action>glob</action>
+  <params>{"pattern": "**/*.ts", "path": "/path/to/project"}</params>
+</tool_call>
+`;
+  }
+
   public getCallSummary(action: string, params: Record<string, unknown>): string {
     switch (action) {
       case 'read': {