diff --git a/README.md b/README.md index 584ef3f..491e129 100644 --- a/README.md +++ b/README.md @@ -59,19 +59,19 @@ If you're using MseeP AI Helper app, you can search for "SkyDeckAI Code" and ins | **File System** | `get_allowed_directory` | Get the current working directory path | | | `update_allowed_directory` | Change the working directory | | | `create_directory` | Create a new directory or nested directories | -| | `write_file` | Create or overwrite a file with new content | -| | `edit_file` | Make line-based edits to a text file | -| | `read_file` | Read the contents of one or more files | +| | `write_file` | Create or overwrite files with auto-directory creation | +| | `edit_file` | Make targeted text replacements with diff output | +| | `read_file` | Read file contents with optional line range support | | | `list_directory` | Get listing of files and directories | -| | `move_file` | Move or rename a file or directory | -| | `copy_file` | Copy a file or directory to a new location | -| | `search_files` | Search for files matching a name pattern | -| | `delete_file` | Delete a file or empty directory | -| | `get_file_info` | Get detailed file metadata | +| | `move_file` | Move or rename files/directories with auto-directory creation | +| | `copy_file` | Copy files or directories with recursive support | +| | `search_files` | Find files by name pattern (recursive, case-insensitive) | +| | `delete_file` | Delete files or empty directories safely | +| | `get_file_info` | Get file metadata without reading content | | | `directory_tree` | Get a recursive tree view of directories | | | `read_image_file` | Read an image file as base64 data | | **Code Tools** | `codebase_mapper` | Analyze code structure across files | -| | `search_code` | Find text patterns in code files | +| | `search_code` | Search file contents using regex patterns | | | `execute_code` | Run code in various languages | | | `execute_shell_script` | Run shell/bash scripts | | **Web Tools** | `web_fetch` | Get content from a URL | @@ -82,9 +82,9 @@ If you're using MseeP AI Helper app, you can search for "SkyDeckAI Code" and ins | **System** | `get_system_info` | Get detailed system information | | **Utility** | `batch_tools` | Run multiple tool operations together | | | `think` | Document reasoning without making changes | -| **Todo** | `todo_read` | Read current workspace todo list | -| | `todo_write` | Replace entire todo list with validation | -| | `todo_update` | Update specific todo item by ID | +| **Todo** | `todo_read` | Read current workspace todo list | +| | `todo_write` | Create/replace todo list for workspace workflow | +| | `todo_update` | Update todo status during task execution | ## Detailed Tool Documentation @@ -103,7 +103,7 @@ If you're using MseeP AI Helper app, you can search for "SkyDeckAI Code" and ins #### edit_file -Pattern-based file editing with preview support: +Targeted text replacement in files with efficient batch editing: ```json { @@ -114,14 +114,14 @@ Pattern-based file editing with preview support: "newText": "def new_function():" } ], - "dryRun": false, "options": { - "partialMatch": true + "partialMatch": true, + "confidenceThreshold": 0.8 } } ``` -Returns: Diff of changes or preview in dry run mode. +Returns: Git-style diff with success/failure details for each edit. ### Directory Operations @@ -133,7 +133,7 @@ Returns: Diff of changes or preview in dry run mode. | create_directory | path: string | Success confirmation | | search_files | pattern: string, path?: string, include_hidden?: boolean | Matching files list | -The `search_files` tool searches for files by name pattern, while the `search_code` tool searches within file contents using regex. Use `search_files` when looking for files with specific names or extensions, and `search_code` when searching for specific text patterns inside files. +The `search_files` tool finds files by name pattern (recursive, case-insensitive), while the `search_code` tool searches file contents using regex patterns. Use `search_files` for locating files by extension or name, and `search_code` for finding specific code patterns, function definitions, or variable usage within files. #### directory_tree @@ -184,7 +184,7 @@ Supported Languages: #### search_code -Fast content search tool using regular expressions: +Regex-based content search: ```json { @@ -193,24 +193,26 @@ Fast content search tool using regular expressions: "exclude": "node_modules/**", "max_results": 50, "case_sensitive": false, - "path": "src" + "path": "src", + "include_hidden": false } ``` **Parameters:** | Parameter | Type | Required | Description | |-----------|------|----------|-------------| -| patterns | array of strings | Yes | List of regular expression patterns to search for in file contents | -| include | string | No | File pattern to include (glob syntax, default: "\*") | -| exclude | string | No | File pattern to exclude (glob syntax, default: "") | +| patterns | array of strings | Yes | Regular expression patterns to search for in file contents | +| include | string | No | File inclusion pattern (glob syntax, default: "*") | +| exclude | string | No | File exclusion pattern (glob syntax, default: "") | | max_results | integer | No | Maximum results to return per pattern (default: 100) | -| case_sensitive | boolean | No | Whether search is case-sensitive (default: false) | +| case_sensitive | boolean | No | Case-sensitive search (default: false) | | path | string | No | Base directory to search from (default: ".") | +| include_hidden | boolean | No | Include hidden files (.env, .config, etc.) (default: false) | **Returns:** -Matching lines grouped by file with line numbers, sorted by file modification time with newest files first. +Matching lines with file paths and line numbers, sorted by file modification time (newest first). -This tool uses ripgrep when available for optimal performance, with a Python fallback implementation. It's ideal for finding specific code patterns like function declarations, imports, variable usages, or error handling. +This tool uses ripgrep when available for superior performance, with a Python fallback. Ideal for finding function definitions, variable usage, imports, or any code patterns across your codebase. ### System Information @@ -584,11 +586,11 @@ This tool executes arbitrary shell commands on your system. Always: ### Todo Tools -The todo tools provide sequential task management capabilities for workspace-first development workflows. Tasks are executed in order without priority systems, ensuring structured progress through development phases. +The todo tools provide mandatory workspace-bound task management for structured development workflows. Each workspace maintains isolated todo context, and todo checking is required before file operations. #### todo_read -Read the current todo list for the workspace. +**CRITICAL**: Must be called first before any file/directory operations. Returns the active todo list for the current workspace. ```json {} @@ -616,7 +618,7 @@ Read the current todo list for the workspace. #### todo_write -Replace the entire todo list for sequential execution workflow. Tasks are executed in array order, building upon previous work. +Create or replace the complete todo list when no active todos exist. Triggered after `todo_read` returns empty or when starting new work. ```json { @@ -638,17 +640,16 @@ Replace the entire todo list for sequential execution workflow. Tasks are execut } ``` -**Sequential Workflow Rules:** -- Each todo must have unique ID -- Only one task can be "in_progress" at a time (sequential execution) -- Tasks execute in array order - no priority system -- Required fields: id, content, status -- Status values: "pending", "in_progress", "completed" -- Workspace-first: Todo management is mandatory for all workspace operations +**Workflow Protocol:** +1. Call `todo_read` first +2. If empty → call `todo_write` +3. Then proceed with file operations +4. Only one task "in_progress" at a time +5. Tasks execute sequentially in array order #### todo_update -Update a specific todo item by ID for sequential workflow progression. +Update todo status during file operations. Required after each task completion to maintain workspace integrity. ```json { @@ -685,7 +686,7 @@ Update a specific todo item by ID for sequential workflow progression. } ``` -The todo system maintains separate sequential task lists for each workspace, enforcing mandatory usage for all workspace operations. Tasks execute in order, building upon previous work without priority-based scheduling. +**Critical**: Todo status must reflect actual work progress. Update after every file operation to maintain workspace protocol compliance. ## Configuration diff --git a/src/aidd/tools/code_analysis.py b/src/aidd/tools/code_analysis.py index 6351894..757588b 100644 --- a/src/aidd/tools/code_analysis.py +++ b/src/aidd/tools/code_analysis.py @@ -57,24 +57,17 @@ def codebase_mapper_tool(): return { "name": "codebase_mapper", - "description": "Build a structural map of source code files in a directory. " - "This tool analyzes code structure to identify classes, functions, and methods. " - "WHEN TO USE: When you need to understand the structure of a codebase, discover classes and " - "functions across multiple files, identify inheritance relationships, or get a high-level overview of code organization without " - "reading every file individually. " - "WHEN NOT TO USE: When you need to search for specific text patterns (use search_files instead), when you " - "need to analyze a single known file (use read_file instead), or when you're working with non-code files. " - "SUPPORTED LANGUAGES: Python (.py), JavaScript (.js/.jsx), TypeScript (.ts/.tsx), Java (.java), C++ (.cpp), Ruby (.rb), Go (.go), Rust (.rs), PHP (.php), " - "C# (.cs), Kotlin (.kt). " - "RETURNS: A text-based tree structure showing classes and functions in the codebase, along with statistics " - "about found elements. Only analyzes files within the allowed directory. " - "Example: Enter '.' to analyze all source files in current directory, or 'src' to analyze all files in the src directory.", + "description": "Generate structural map of code: classes, functions, methods using tree-sitter. " + "USE: Understand codebase architecture, discover code structure. " + "NOT: Text search (use search_code), single file analysis. " + "SUPPORTS: Python, JS/TS, Java, C++, Ruby, Go, Rust, PHP, C#, Kotlin. " + "RETURNS: Text tree of classes/functions with statistics", "inputSchema": { "type": "object", "properties": { "path": { "type": "string", - "description": "Root directory to analyze. Examples: '.' for current directory, 'src' for src directory, 'lib/components' for a specific subdirectory. The path must point to a directory within the allowed workspace." + "description": "Root directory to analyze. Examples: '.', 'src', 'lib/components'." } }, "required": ["path"] diff --git a/src/aidd/tools/code_execution.py b/src/aidd/tools/code_execution.py index ebd61a5..d796cb4 100644 --- a/src/aidd/tools/code_execution.py +++ b/src/aidd/tools/code_execution.py @@ -28,20 +28,10 @@ def execute_code_tool() -> Dict[str, Any]: return { "name": "execute_code", "description": ( - "Execute arbitrary code in various programming languages on the user's local machine within the current working directory. " - "WHEN TO USE: When you need to run small code snippets to test functionality, compute values, process data, or " - "demonstrate how code works. Useful for quick prototyping, data transformations, or explaining programming concepts with running " - "examples. " - "WHEN NOT TO USE: When you need to modify files (use write_file or edit_file instead), when running potentially harmful " - "operations, or when you need to install external dependencies. " - "RETURNS: Text output including stdout, stderr, and exit code of the " - "execution. The output sections are clearly labeled with '=== stdout ===' and '=== stderr ==='. " - "Supported languages: " + ", ".join(LANGUAGE_CONFIGS.keys()) + ". " - "Always review the code carefully before execution to prevent unintended consequences. " - "Examples: " - "- Python: code='print(sum(range(10)))'. " - "- JavaScript: code='console.log(Array.from({length: 5}, (_, i) => i*2))'. " - "- Ruby: code='puts (1..5).reduce(:+)'. " + "Execute code snippets in sandbox. Supports: python, javascript, ruby, php, go, rust. " + "USE: Test functions, compute values, prototype. " + "NOT: File modifications, system operations, dependencies. " + "Auto-wraps Go/Rust main functions. Timeout: 30s max" ), "inputSchema": { "type": "object", @@ -49,21 +39,15 @@ def execute_code_tool() -> Dict[str, Any]: "language": { "type": "string", "enum": list(LANGUAGE_CONFIGS.keys()), - "description": "Programming language to use. Must be one of the supported languages: " - + ", ".join(LANGUAGE_CONFIGS.keys()) - + ". " - + "Each language requires the appropriate runtime to be installed on the user's machine. The code will be executed using: python3 for " - + "Python, node for JavaScript, ruby for Ruby, php for PHP, go run for Go, and rustc for Rust.", + "description": "Programming language. Requires runtime: python3, node, ruby, php, go, rustc.", }, "code": { "type": "string", - "description": "Code to execute on the user's local machine in the current working directory. The code will be saved to a " - + "temporary file and executed within the allowed workspace. For Go and Rust, main function wrappers will be added automatically if " - + "not present. For PHP, Dict[str, Any]: return { "name": "execute_shell_script", "description": ( - "Execute a shell script (bash/sh) on the user's local machine within the current working directory. " - "WHEN TO USE: When you need to automate system tasks, run shell commands, interact with the operating system, or perform operations " - "that are best expressed as shell commands. Useful for file system operations, system configuration, or running system utilities. " - "Also ideal when you need to run code linters to check for style issues or potential bugs in the codebase, " - "or when you need to perform version control operations such as initializing git repositories, checking status, " - "committing changes, cloning repositories, and other git commands without dedicated tools. " - "WHEN NOT TO USE: When you need more structured programming (use execute_code instead), when you need to execute potentially " - "dangerous system operations, or when you want to run commands outside the allowed directory. " - "RETURNS: Text output including stdout, stderr, and exit code of the execution. The output sections are clearly labeled with " - "'=== stdout ===' and '=== stderr ==='. " - "This tool can execute shell commands and scripts for system automation and management tasks. " - "It is designed to perform tasks on the user's local environment, such as opening applications, installing packages and more. " - "Always review the script carefully before execution to prevent unintended consequences. " - "Examples: " - "- script='echo \"Current directory:\" && pwd'. " - "- script='for i in {1..5}; do echo $i; done'. " - "- script='eslint src/ --format stylish' (for linting). " - "- script='git init && git add . && git commit -m \"Initial commit\"' (for git operations)." + "Run bash/sh scripts for system tasks, git operations, linters. " + "USE: System automation, file operations, version control, code linting. " + "NOT: Structured programming (use execute_code), dangerous operations. " + "Timeout: 10 minutes maximum" ), "inputSchema": { "type": "object", "properties": { "script": { "type": "string", - "description": "Shell script to execute on the user's local machine. Can include any valid shell commands or scripts that would " - "run in a standard shell environment. The script is executed using /bin/sh for maximum compatibility across systems.", + "description": "Shell script to execute (uses /bin/sh for compatibility).", }, "timeout": { "type": "integer", - "description": "Maximum execution time in seconds. The execution will be terminated if it exceeds this time limit. Default is 300 seconds (5 minutes), with a maximum allowed value of 600 seconds (10 minutes).", + "description": "Max execution time (up to 600 seconds). Default: 300.", "default": 300, "maximum": 600, }, diff --git a/src/aidd/tools/code_tools.py b/src/aidd/tools/code_tools.py index 4bfd51b..a0f4686 100644 --- a/src/aidd/tools/code_tools.py +++ b/src/aidd/tools/code_tools.py @@ -14,16 +14,10 @@ def search_code_tool(): return { "name": "search_code", - "description": "Fast content search tool using regular expressions. " - "WHEN TO USE: When you need to search for specific patterns within file contents across a codebase. " - "Useful for finding function definitions, variable usages, import statements, or any text pattern " - "in source code files. " - "WHEN NOT TO USE: When you need to find files by name (use search_files instead), when you need " - "semantic code understanding (use codebase_mapper instead), or when analyzing individual file " - "structure. " - "RETURNS: Lines of code matching the specified patterns, grouped by file with line numbers. " - "Results are sorted by file modification time with newest files first. Respects file filtering " - "and ignores binary files. Search is restricted to the allowed directory.", + "description": "Regex search in file contents. Uses ripgrep when available. " + "USE: Find function definitions, variable usage, code patterns. " + "NOT: File names (use search_files), semantic analysis. " + "RETURNS: Matching lines with file paths, line numbers, sorted by modification time", "inputSchema": { "type": "object", "properties": { @@ -32,46 +26,36 @@ def search_code_tool(): "items": { "type": "string" }, - "description": "List of regular expression patterns to search for in file contents. Supports full regex syntax. " - "Examples: ['function\\s+\\w+', 'class\\s+\\w+'] to find both function and class declarations." + "description": "Regex patterns to search. Examples: ['function\\s+\\w+', 'class\\s+\\w+']." }, "include": { "type": "string", - "description": "File pattern to include in the search. Supports glob patterns including wildcards and braces. " - "Examples: '*.js' for all JavaScript files, '*.{ts,tsx}' for TypeScript files, " - "'src/**/*.py' for Python files in the src directory and subdirectories.", + "description": "File inclusion pattern (glob). Examples: '*.js', '*.{ts,tsx}', 'src/**/*.py'.", "default": "*" }, "exclude": { "type": "string", - "description": "File pattern to exclude from the search. Supports glob patterns including wildcards and braces. " - "Examples: 'node_modules/**' to exclude node_modules directory, '*.min.js' to exclude minified JS.", + "description": "File exclusion pattern (glob). Examples: 'node_modules/**', '*.min.js'.", "default": "" }, "max_results": { "type": "integer", - "description": "Maximum number of matching results to return per pattern. Use to limit output size for common patterns. " - "Default is 100, which is sufficient for most searches while preventing excessive output.", + "description": "Max results per pattern. Default: 100.", "default": 100 }, "case_sensitive": { "type": "boolean", - "description": "Whether to perform a case-sensitive search. When true, 'Error' will not match 'error'. " - "Default is false, which makes searches case-insensitive.", + "description": "Case-sensitive search. Default: false.", "default": False }, "path": { "type": "string", - "description": "Base directory to search from. This is the starting point for the search. " - "Examples: '.' for current directory, 'src' to search only within src directory. " - "Default is the root of the allowed directory.", + "description": "Base directory to search. Examples: '.', 'src'. Default: '.'.", "default": "." }, "include_hidden": { "type": "boolean", - "description": "Whether to include hidden files. When true, also include the hidden files like" - ".env, .config on Unix/Posix/Linux, or files with hidden attribute on Windows" - "Default is false, which exclude the hidden files from search", + "description": "Include hidden files (.env, .config, etc). Default: false.", "default": False, }, }, diff --git a/src/aidd/tools/directory_tools.py b/src/aidd/tools/directory_tools.py index d617638..2f45328 100644 --- a/src/aidd/tools/directory_tools.py +++ b/src/aidd/tools/directory_tools.py @@ -11,19 +11,16 @@ def list_directory_tool(): return { "name": "list_directory", - "description": "Get a detailed listing of files and directories in the specified path, including type, size, and modification " - "date. WHEN TO USE: When you need to explore the contents of a directory, understand what files are available, check file sizes or " - "modification dates, or locate specific files by name. WHEN NOT TO USE: When you need to read the contents of files (use read_file " - "instead), when you need a recursive listing of all subdirectories (use directory_tree instead), or when searching for files by name pattern " - "(use search_files instead). RETURNS: Text with each line containing file type ([DIR]/[FILE]), name, size (in B/KB/MB), and " - "modification date. Only works within the allowed directory. Example: Enter 'src' to list contents of the src directory, or '.' for " - "current directory.", + "description": "List directory contents with metadata. " + "USE: Explore folder contents, check file sizes/dates. " + "NOT: Recursive listing (use directory_tree), file content. " + "RETURNS: [DIR]/[FILE] entries with size and timestamps", "inputSchema": { "type": "object", "properties": { "path": { "type": "string", - "description": "Path of the directory to list. Examples: '.' for current directory, 'src' for src directory, 'docs/images' for a nested directory. The path must be within the allowed workspace.", + "description": "Directory path. Examples: '.', 'src', 'docs/images'.", } }, "required": ["path"], @@ -82,20 +79,16 @@ async def handle_list_directory(arguments: dict): def create_directory_tool(): return { "name": "create_directory", - "description": "Create a new directory or ensure a directory exists. " - "Can create multiple nested directories in one operation. " - "WHEN TO USE: When you need to set up project structure, organize files, create output directories before saving files, or establish a directory hierarchy. " - "WHEN NOT TO USE: When you only want to check if a directory exists (use get_file_info instead), or when trying to create directories outside the allowed workspace. " - "RETURNS: Text message confirming either that the directory was successfully created or that it already exists. " - "The operation succeeds silently if the directory already exists. " - "Only works within the allowed directory. " - "Example: Enter 'src/components' to create nested directories.", + "description": "Create directory or nested directories. " + "USE: Set up project structure, organize files. " + "NOT: Check existence (use get_file_info). " + "Succeeds silently if directory exists", "inputSchema": { "type": "object", "properties": { "path": { "type": "string", - "description": "Path of the directory to create. Can include nested directories which will all be created. Examples: 'logs' for a simple directory, 'src/components/buttons' for nested directories. Both absolute and relative paths are supported, but must be within the allowed workspace.", + "description": "Directory path to create (creates nested paths). Examples: 'logs', 'src/components/buttons'.", } }, "required": ["path"], @@ -140,26 +133,20 @@ async def handle_create_directory(arguments: dict): def directory_tree_tool(): return { "name": "directory_tree", - "description": "Get a recursive tree view of files and directories in the specified path as a JSON structure. " - "WHEN TO USE: When you need to understand the complete structure of a directory tree, visualize the hierarchy of files and directories, or get a comprehensive overview of a project's organization. " - "Particularly useful for large projects where you need to see nested relationships. " - "WHEN NOT TO USE: When you only need a flat list of files in a single directory (use directory_listing instead), or when you're only interested in specific file types (use search_files instead). " - "RETURNS: JSON structure where each entry includes 'name', 'type' (file/directory), and 'children' for directories. " - "Files have no children array, while directories always have a children array (which may be empty). " - "The output is formatted with 2-space indentation for readability. For Git repositories, shows tracked files only. " - "Only works within the allowed directory and only for non-hidden files, or files that are not inside hidden directory. " - "If you want to show the hidden files also, use commands like execute_shell_script. " - "Example: Enter '.' for current directory, or 'src' for a specific directory.", + "description": "Recursive JSON tree of directory structure. Uses git ls-files when available. " + "USE: Understand project hierarchy, visualize structure. " + "NOT: Single directory listing, file content analysis. " + "RETURNS: JSON with name/type/children. Excludes hidden files", "inputSchema": { "type": "object", "properties": { "path": { "type": "string", - "description": "Root directory to analyze. This is the starting point for the recursive tree generation. Examples: '.' for current directory, 'src' for the src directory. Both absolute and relative paths are supported, but must be within the allowed workspace.", + "description": "Root directory to analyze. Examples: '.', 'src'.", }, "max_depth": { "type": "integer", - "description": "Max depth for traversing in case of big and deeply nested directory", + "description": "Max traversal depth for large nested directories.", "default": 3, }, }, diff --git a/src/aidd/tools/file_tools.py b/src/aidd/tools/file_tools.py index 0ac6c80..11ebac6 100644 --- a/src/aidd/tools/file_tools.py +++ b/src/aidd/tools/file_tools.py @@ -17,16 +17,10 @@ def read_file_tool(): return { "name": "read_file", - "description": "Read the contents of one or more files from the file system. " - "WHEN TO USE: When you need to examine the actual content of one or more files, view source code, check configuration files, or analyze text data. " - "This is the primary tool for accessing file contents directly. " - "WHEN NOT TO USE: When you only need file metadata like size or modification date (use get_file_info instead), when you need to list directory contents " - "(use directory_listing instead). " - "RETURNS: The complete text content of the specified file(s) or the requested portion if offset/limit are specified. Binary files or files with unknown encodings will return an error message. " - "Each file's content is preceded by a header showing the file path (==> path/to/file <==). " - "Handles various text encodings and provides detailed error messages if a file cannot be read. Only works within the allowed directory. " - "Example: Use 'files: [{\"path\": \"src/main.py\"}]' to read a Python file, or add offset/limit to read specific line ranges. " - "For multiple files, use 'files: [{\"path\": \"file1.txt\"}, {\"path\": \"file2.txt\"}]' with optional offset/limit for each file.", + "description": "Read file contents with optional line range. " + "USE: View source code, config files, text content. " + "NOT: File metadata (use get_file_info), directory listing. " + "RETURNS: Complete text or specified line range with file headers", "inputSchema": { "type": "object", "properties": { @@ -37,15 +31,15 @@ def read_file_tool(): "properties": { "path": { "type": "string", - "description": "Path to the file to read. This must be a path to a file, not a directory. Examples: 'README.md', 'src/main.py', 'config.json'. Both absolute and relative paths are supported, but must be within the allowed workspace." + "description": "File path (not directory). Examples: 'README.md', 'src/main.py'. Absolute/relative paths within workspace." }, "offset": { "type": "integer", - "description": "Line number to start reading from (1-indexed). If specified, the file will be read starting from this line. Default is to start from the beginning of the file." + "description": "Start line number (1-indexed). Default: beginning of file." }, "limit": { "type": "integer", - "description": "Maximum number of lines to read after the offset. If specified along with offset, only this many lines will be read. Default is to read to the end of the file." + "description": "Max lines to read from offset. Default: to end of file." } }, "required": ["path"] @@ -60,25 +54,20 @@ def read_file_tool(): def write_file_tool(): return { "name": "write_file", - "description": "Create a new file or overwrite an existing file with new content. " - "WHEN TO USE: When you need to save changes, create new files, or update existing ones with new content. " - "Useful for generating reports, creating configuration files, or saving edited content. " - "WHEN NOT TO USE: When you want to make targeted edits to parts of a file while preserving the rest (use edit_file instead), " - "when you need to append to a file without overwriting existing content, or when you need to preserve the original file. " - "RETURNS: A confirmation message indicating that the file was successfully written. " - "Creates parent directories automatically if they don't exist. " - "Use with caution as it will overwrite existing files without warning. Only works within the allowed directory. " - "Example: Path='notes.txt', Content='Meeting notes for project X'", + "description": "Create/overwrite file. Auto-creates parent directories. " + "USE: Save new content, generate files. " + "NOT: Targeted edits (use edit_file). " + "WARNING: Overwrites existing files", "inputSchema": { "type": "object", "properties": { "path": { "type": "string", - "description": "Path where to write the file. Both absolute and relative paths are supported, but must be within the allowed workspace. Examples: 'README.md', 'logs/debug.log', 'reports/report.txt'. Parent directories will be created automatically if they don't exist." + "description": "File path within workspace. Examples: 'README.md', 'logs/debug.log'. Auto-creates parent dirs." }, "content": { "type": "string", - "description": "Content to write to the file. The complete text content that should be saved to the file. This will completely replace any existing content if the file already exists." + "description": "Text content to write. Replaces existing content if file exists." } }, "required": ["path", "content"] @@ -88,25 +77,20 @@ def write_file_tool(): def move_file_tool(): return { "name": "move_file", - "description": "Move or rename a file or directory to a new location. " - "WHEN TO USE: When you need to reorganize files or directories, rename files or folders, or move items to a different location within the allowed workspace. " - "Useful for organizing project files, restructuring directories, or for simple renaming operations. " - "WHEN NOT TO USE: When you want to copy a file while keeping the original (copying functionality is not available in this tool set), " - "when destination already exists (the operation will fail), or when either source or destination is outside the allowed workspace. " - "RETURNS: A confirmation message indicating that the file or directory was successfully moved. " - "Parent directories of the destination will be created automatically if they don't exist. " - "Both source and destination must be within the allowed directory. " - "Example: source='old.txt', destination='new/path/new.txt'", + "description": "Move/rename file or directory. " + "USE: Reorganize files, rename items. " + "NOT: Copy operations (use copy_file). " + "Auto-creates parent directories", "inputSchema": { "type": "object", "properties": { "source": { "type": "string", - "description": "Source path of the file or directory to move. This file or directory must exist. Both absolute and relative paths are supported, but must be within the allowed workspace. Examples: 'document.txt', 'src/utils.js', 'config/old-settings/'" + "description": "Source file/directory path (must exist). Examples: 'document.txt', 'src/utils.js'." }, "destination": { "type": "string", - "description": "Destination path where to move the file or directory. If this path already exists, the operation will fail. Parent directories will be created automatically if they don't exist. Both absolute and relative paths are supported, but must be within the allowed workspace. Examples: 'renamed.txt', 'backup/document.txt', 'src/new-location/'" + "description": "Destination path (must not exist). Auto-creates parent dirs. Examples: 'renamed.txt', 'backup/document.txt'." } }, "required": ["source", "destination"] @@ -116,30 +100,24 @@ def move_file_tool(): def copy_file_tool(): return { "name": "copy_file", - "description": "Copy a file or directory to a new location. " - "WHEN TO USE: When you need to duplicate files or directories while keeping the original intact, create backups, " - "or replicate configuration files for different environments. Useful for testing changes without risking original files, " - "creating template files, or duplicating project structures. " - "WHEN NOT TO USE: When you want to move a file without keeping the original (use move_file instead), when the destination " - "already exists (the operation will fail), or when either source or destination is outside the allowed workspace. " - "RETURNS: A confirmation message indicating that the file or directory was successfully copied. " - "For directories, the entire directory structure is copied recursively. Parent directories of the destination " - "will be created automatically if they don't exist. Both source and destination must be within the allowed directory. " - "Example: source='config.json', destination='config.backup.json'", + "description": "Copy file or directory to new location. " + "USE: Duplicate files, create backups, replicate structures. " + "NOT: Move operations (use move_file). " + "Recursive directory copying. Auto-creates parent directories", "inputSchema": { "type": "object", "properties": { "source": { "type": "string", - "description": "Source path of the file or directory to copy. This file or directory must exist. Both absolute and relative paths are supported, but must be within the allowed workspace. Examples: 'document.txt', 'src/utils.js', 'config/settings/'" + "description": "Source file/directory path (must exist). Examples: 'document.txt', 'src/utils.js'." }, "destination": { "type": "string", - "description": "Destination path where to copy the file or directory. If this path already exists, the operation will fail. Parent directories will be created automatically if they don't exist. Both absolute and relative paths are supported, but must be within the allowed workspace. Examples: 'document.backup.txt', 'backup/document.txt', 'src/new-project/'" + "description": "Destination path (must not exist). Auto-creates parent dirs. Examples: 'document.backup.txt', 'backup/document.txt'." }, "recursive": { "type": "boolean", - "description": "Whether to copy directories recursively. If set to true and the source is a directory, all subdirectories and files will be copied. If set to false and the source is a directory, the operation will fail. Defaults to true.", + "description": "Copy directories recursively. If false and source is directory, operation fails. Default: true.", "default": True } }, @@ -150,30 +128,24 @@ def copy_file_tool(): def search_files_tool(): return { "name": "search_files", - "description": "Search for files and directories matching a pattern in their names. " - "WHEN TO USE: When you need to find files or directories by name pattern across a directory tree, locate files with specific extensions, " - "or find items containing certain text in their names. Useful for locating configuration files, finding all files of a certain type, " - "or gathering files related to a specific feature. " - "WHEN NOT TO USE: When searching for content within files (use search_code tool for that), when you need a flat listing of a single directory " - "(use list_directory instead), or when you need to analyze code structure (use codebase_mapper instead). " - "RETURNS: A list of matching files and directories with their types ([FILE] or [DIR]) and relative paths. " - "For Git repositories, only shows tracked files and directories by default. " - "The search is recursive and case-insensitive. Only searches within the allowed directory. " - "Example: pattern='.py' finds all Python files, pattern='test' finds all items with 'test' in the name.", + "description": "Find files/directories by name pattern. Recursive, case-insensitive. " + "USE: Locate files by extension, find items with specific names. " + "NOT: Content search (use search_code), single directory listing. " + "Shows tracked files in Git repos", "inputSchema": { "type": "object", "properties": { "pattern": { "type": "string", - "description": "Pattern to search for in file and directory names. The search is case-insensitive and matches substrings. Examples: '.js' to find all JavaScript files, 'test' to find all items containing 'test' in their name, 'config' to find configuration files and directories." + "description": "Name pattern (case-insensitive substring). Examples: '.js', 'test', 'config'." }, "path": { "type": "string", - "description": "Starting directory for the search (defaults to allowed directory). This is the root directory from which the recursive search begins. Examples: '.' for current directory, 'src' to search only in the src directory tree. Both absolute and relative paths are supported, but must be within the allowed workspace." + "description": "Search root directory. Examples: '.', 'src'. Default: allowed directory." }, "include_hidden": { "type": "boolean", - "description": "Whether to include hidden files and directories (defaults to false). On Unix-like systems, hidden items start with a dot (.). Set to true to include them in the search results." + "description": "Include hidden files/dirs (start with '.'). Default: false." } }, "required": ["pattern"] @@ -183,19 +155,16 @@ def search_files_tool(): def get_file_info_tool(): return { "name": "get_file_info", - "description": "Get detailed information about a file or directory. " - "WHEN TO USE: When you need to check file metadata like size, timestamps, permissions, or file type without reading the contents. " - "Useful for determining when files were modified, checking file sizes, verifying file existence, or distinguishing between files and directories. " - "WHEN NOT TO USE: When you need to read the actual content of a file (use read_file instead), or when you need to list all files in a directory (use directory_listing instead). " - "RETURNS: Text with information about the file or directory including type (file/directory), size in bytes, creation time, modification time, access time (all in ISO 8601 format), and permissions. " - "Only works within the allowed directory. " - "Example: path='src/main.py' returns details about main.py", + "description": "Get file metadata: size, timestamps, permissions, type. " + "USE: Check file properties without reading content. " + "NOT: Reading content (use read_file), directory listing. " + "RETURNS: Type, size, creation/modification times, permissions", "inputSchema": { "type": "object", "properties": { "path": { "type": "string", - "description": "Path to the file or directory to get information about. Can be either a file or directory path. Examples: 'README.md', 'src/components', 'package.json'. Both absolute and relative paths are supported, but must be within the allowed workspace." + "description": "File or directory path. Examples: 'README.md', 'src/components'." } }, "required": ["path"] @@ -205,21 +174,16 @@ def get_file_info_tool(): def delete_file_tool(): return { "name": "delete_file", - "description": "Delete a file or empty directory from the file system. " - "WHEN TO USE: When you need to remove unwanted files, clean up temporary files, or delete empty directories. " - "Useful for cleaning up workspaces, removing intermediate build artifacts, or deleting temporary files. " - "WHEN NOT TO USE: When you need to delete non-empty directories (the operation will fail), when you want to move files instead of deleting them (use move_file instead), " - "or when you need to preserve the file for later use. " - "RETURNS: A confirmation message indicating that the file or empty directory was successfully deleted. " - "For safety, this tool will not delete non-empty directories. " - "Use with caution as this operation cannot be undone. Only works within the allowed directory. " - "Example: path='old_file.txt' removes the specified file.", + "description": "Delete file or empty directory. " + "USE: Remove unwanted files, clean up temporary files. " + "NOT: Non-empty directories (will fail). " + "WARNING: Cannot be undone. Safety: only deletes empty directories", "inputSchema": { "type": "object", "properties": { "path": { "type": "string", - "description": "Path to the file or empty directory to delete. For directories, they must be completely empty or the operation will fail. Examples: 'temp.txt', 'build/cache.json', 'empty-dir/'. Both absolute and relative paths are supported, but must be within the allowed workspace." + "description": "File or empty directory path. Examples: 'temp.txt', 'empty-dir/'." } }, "required": ["path"] @@ -229,24 +193,17 @@ def delete_file_tool(): def edit_file_tool(): return { "name": "edit_file", - "description": "Make line-based edits to a text file. " - "WHEN TO USE: When you need to make selective changes to specific parts of a file while preserving the rest of the content. " - "Useful for modifying configuration values, updating text while maintaining file structure, or making targeted code changes. " - "IMPORTANT: For multiple edits to the same file, use a single tool call with multiple edits in the 'edits' array rather than multiple tool calls. " - "This is more efficient and ensures all edits are applied atomically. " - "WHEN NOT TO USE: When you want to completely replace a file's contents (use write_file instead), when you need to create a new file (use write_file instead), " - "or when you want to apply highly complex edits with context. " - "RETURNS: A git-style diff showing the changes made, along with information about any failed matches. " - "The response includes sections for failed matches (if any) and the unified diff output. " - "Only works within the allowed directory. " - "EXAMPLES: For a single edit: {\"path\": \"config.js\", \"edits\": [{\"oldText\": \"port: 3000\", \"newText\": \"port: 8080\"}]}. " - "For multiple edits: {\"path\": \"app.py\", \"edits\": [{\"oldText\": \"debug=False\", \"newText\": \"debug=True\"}, {\"oldText\": \"version='1.0'\", \"newText\": \"version='2.0'\"}]}", + "description": "Targeted text replacement in files. " + "CRITICAL: Use single call with multiple edits array for efficiency. " + "USE: Modify specific parts while preserving rest. " + "NOT: Complete rewrites (use write_file). " + "RETURNS: Git-style diff with success/failure details", "inputSchema": { "type": "object", "properties": { "path": { "type": "string", - "description": "File to edit. Must be a text file that exists within the allowed workspace. Examples: 'README.md', 'src/config.js', 'settings.json'. Both absolute and relative paths are supported, but must be within the allowed workspace." + "description": "Text file to edit. Examples: 'README.md', 'src/config.js'." }, "edits": { "type": "array", @@ -255,32 +212,28 @@ def edit_file_tool(): "properties": { "oldText": { "type": "string", - "description": "Text to search for in the file. This should be a unique segment of text to identify where the change should be made. Include enough context (lines before/after) to ensure the right match is found." + "description": "Text to find and replace. Include context for unique match." }, "newText": { "type": "string", - "description": "Text to replace the matched section with. This will completely replace the oldText section. To delete text, use an empty string." + "description": "Replacement text. Empty string to delete." } }, "required": ["oldText", "newText"] }, - "description": "MUST be an array of edit objects, NOT a string. Each edit object must contain 'oldText' and 'newText' properties. " - "For multiple edits, use: [{\"oldText\": \"text1\", \"newText\": \"replacement1\"}, {\"oldText\": \"text2\", \"newText\": \"replacement2\"}]. " - "For single edit, still use array: [{\"oldText\": \"text\", \"newText\": \"replacement\"}]. " - "The edits are applied in sequence, and each one can modify the result of previous edits. " - "AVOID multiple tool calls for the same file - instead, group all edits into a single call." + "description": "Array of edit objects with oldText/newText. Applied sequentially. Group all edits for same file." }, "options": { "type": "object", "properties": { "partialMatch": { "type": "boolean", - "description": "Enable fuzzy matching for finding text. When true, the tool will try to find the best match even if it's not an exact match, using the confidenceThreshold (default 80%).", + "description": "Enable fuzzy text matching. Uses confidenceThreshold (default 80%).", "default": True }, "confidenceThreshold": { "type": "number", - "description": "Minimum confidence threshold for fuzzy matching (0.0 to 1.0). Higher values require more exact matches. Default is 0.8 (80% confidence).", + "description": "Fuzzy match confidence (0.0-1.0). Higher = more exact. Default: 0.8.", "minimum": 0.0, "maximum": 1.0, "default": 0.8 diff --git a/src/aidd/tools/get_active_apps_tool.py b/src/aidd/tools/get_active_apps_tool.py index 13a0e56..bbd1ea4 100644 --- a/src/aidd/tools/get_active_apps_tool.py +++ b/src/aidd/tools/get_active_apps_tool.py @@ -23,26 +23,17 @@ def get_active_apps_tool(): """Define the get_active_apps tool.""" return { "name": "get_active_apps", - "description": "Get a list of currently active applications running on the user's system. " - "WHEN TO USE: When you need to understand what software the user is currently working with, " - "gain context about their active applications, provide application-specific assistance, or " - "troubleshoot issues related to running programs. Especially useful for providing targeted " - "help based on what the user is actively using. " - "WHEN NOT TO USE: When you need information about specific windows rather than applications " - "(use get_available_windows instead), when you need a screenshot of what's on screen " - "(use capture_screenshot instead), or when application context isn't relevant to the task at hand. " - "RETURNS: JSON object containing platform information, success status, count of applications, " - "and an array of application objects. Each application object includes name, has_windows flag, " - "and when details are requested, information about visible windows. Works on macOS, Windows, " - "and Linux, with platform-specific implementation details.", + "description": "List currently active applications. " + "USE: Understand user's active software, provide app-specific assistance. " + "NOT: Window details (use get_available_windows), screenshots. " + "RETURNS: JSON with platform, app count, array of apps with names/windows. " + "Cross-platform: macOS, Windows, Linux", "inputSchema": { "type": "object", "properties": { "with_details": { "type": "boolean", - "description": "Whether to include additional details about each application. When true, returns extra " - "information like window_count, visible_windows with their names and dimensions. When false, " - "returns a simpler list with just application names and whether they have windows. Default is False." + "description": "Include app details (window_count, visible_windows). Default: false." } }, "required": [] diff --git a/src/aidd/tools/get_available_windows_tool.py b/src/aidd/tools/get_available_windows_tool.py index 2af0af1..cd40250 100644 --- a/src/aidd/tools/get_available_windows_tool.py +++ b/src/aidd/tools/get_available_windows_tool.py @@ -30,18 +30,11 @@ def get_available_windows_tool(): """Define the get_available_windows tool.""" return { "name": "get_available_windows", - "description": "Get detailed information about all available windows currently displayed on the user's screen. " - "WHEN TO USE: When you need to know exactly what windows are visible to the user, find a specific " - "window by title, provide guidance related to something the user is viewing, or need window-level " - "context that's more detailed than application-level information. Useful for referencing specific " - "content the user can see on their screen. " - "WHEN NOT TO USE: When application-level information is sufficient (use get_active_apps instead), " - "when you need to capture what's on screen (use capture_screenshot instead), or when window " - "context isn't relevant to the task at hand. " - "RETURNS: JSON object containing platform information, success status, count of windows, and an " - "array of window objects. Each window object includes title, application owner, visibility status, " - "and platform-specific details like window IDs. Works on macOS, Windows, and Linux, with " - "platform-specific implementation details.", + "description": "List all visible windows with details. " + "USE: Find specific windows by title, get window-level context. " + "NOT: App-level info (use get_active_apps), screen capture. " + "RETURNS: JSON with window count, array of windows with title/app/visibility. " + "Cross-platform: macOS, Windows, Linux", "inputSchema": { "type": "object", "properties": {}, diff --git a/src/aidd/tools/image_tools.py b/src/aidd/tools/image_tools.py index 0bd63a7..81c903d 100644 --- a/src/aidd/tools/image_tools.py +++ b/src/aidd/tools/image_tools.py @@ -17,32 +17,20 @@ def read_image_file_tool(): return { "name": "read_image_file", - "description": "Read an image file from the file system and return its contents as a base64-encoded string. " - "WHEN TO USE: When you need to view or process image files, include images in responses, analyze " - "image content, or convert images to a format that can be transmitted as text. Useful for examining " - "screenshots, diagrams, photos, or any visual content stored in the file system. " - "WHEN NOT TO USE: When you only need information about the image file without its contents " - "(use get_file_info instead), when working with extremely large images (over 100MB), or when you " - "need to read text files (use read_file instead). " - "RETURNS: A base64-encoded data URI string prefixed with the appropriate MIME type " - "(e.g., 'data:image/png;base64,...'). Images that are very small or very large will be automatically " - "resized to between 20-800 pixels wide while maintaining aspect ratio. This tool supports common image " - "formats like PNG, JPEG, GIF, and WebP. Only works within the allowed directory.", + "description": "Read image as base64 data URI. Auto-resizes to 20-800px width. 100MB limit. " + "USE: View/process images, include in responses, analyze visual content. " + "NOT: Image metadata only, text files, very large images. " + "RETURNS: data:image/format;base64,... string. Supports PNG/JPEG/GIF/WebP", "inputSchema": { "type": "object", "properties": { "path": { "type": "string", - "description": "Path to the image file to read. This must be a valid image file in a supported format " - "(PNG, JPEG, GIF, WebP). Examples: 'screenshots/screen.png', 'images/logo.jpg', " - "'diagrams/flowchart.gif'. Both absolute and relative paths are supported, but must be " - "within the allowed workspace." + "description": "Image file path (PNG/JPEG/GIF/WebP). Examples: 'screenshots/screen.png', 'images/logo.jpg'." }, "max_size": { "type": "integer", - "description": "Maximum file size in bytes to allow. Files larger than this size will be rejected to " - "prevent memory issues. Default is 100MB (104,857,600 bytes). For most use cases, the " - "default value is sufficient, but you can lower this when working with limited memory.", + "description": "Max file size in bytes. Default: 100MB.", "optional": True } }, diff --git a/src/aidd/tools/other_tools.py b/src/aidd/tools/other_tools.py index 06c1106..ab12df1 100644 --- a/src/aidd/tools/other_tools.py +++ b/src/aidd/tools/other_tools.py @@ -9,34 +9,20 @@ def batch_tools_tool(): return { "name": "batch_tools", - "description": "Execute multiple tool invocations in parallel or serially. " - "WHEN TO USE: When you need to run multiple operations efficiently in a single request, " - "combine related operations, or gather results from different tools. Useful for bulk operations, " - "coordinated tasks, or performing multiple queries simultaneously. " - "WHEN NOT TO USE: When operations need to be performed strictly in sequence where each step depends " - "on the previous step's result, when performing simple operations that don't benefit from batching, " - "or when you need fine-grained error handling. " - "RETURNS: Results from all tool invocations grouped together. Each result includes the tool name " - "and its output. If any individual tool fails, its error is included but other tools continue execution. " - "Parallelizable tools are executed concurrently for performance. Each tool's output is presented in " - "a structured format along with the description you provided. " - "IMPORTANT NOTE: All tools in the batch execute in the same working directory context. If a tool creates a directory " - "and a subsequent tool needs to work inside that directory, you must either use paths relative to the current working directory " - "or include an explicit tool invocation to change directories (e.g., update_allowed_directory).", + "description": "Execute multiple tools in parallel/sequential. " + "USE: Bulk operations, coordinated tasks, multiple queries. " + "NOT: Sequential dependencies between steps, fine-grained error handling. " + "All tools execute in same working directory context", "inputSchema": { "type": "object", "properties": { "description": { "type": "string", - "description": "A short (3-5 word) description of the batch operation. This helps identify the purpose " - "of the batch and provides context for the results. Examples: 'Setup new project', " - "'Analyze codebase', 'Gather system info'." + "description": "Short batch operation description (3-5 words). Examples: 'Setup new project', 'Analyze codebase'." }, "sequential": { "type": "boolean", - "description": "Whether to run tools in sequential order (true) or parallel when possible (false). " - "Use sequential mode when tools need to build on the results of previous tools. " - "Default is false (parallel execution).", + "description": "Sequential (true) or parallel (false) execution. Default: false.", "default": False }, "invocations": { @@ -46,18 +32,16 @@ def batch_tools_tool(): "properties": { "tool": { "type": "string", - "description": "Name of the tool to invoke. Must be a valid tool name registered in the system." + "description": "Tool name to invoke." }, "arguments": { "type": "object", - "description": "Arguments to pass to the tool. These should match the required arguments " - "for the specified tool." + "description": "Tool arguments." } }, "required": ["tool", "arguments"] }, - "description": "List of tool invocations to execute. Each invocation specifies a tool name and its arguments. " - "These will be executed in parallel when possible, or serially when necessary." + "description": "Tool invocations to execute (parallel or sequential)." } }, "required": ["description", "invocations"] @@ -190,23 +174,16 @@ async def _execute_tool_with_error_handling(handler, arguments, tool_name, index def think_tool(): return { "name": "think", - "description": "Use the tool to methodically think through a complex problem step-by-step. " - "WHEN TO USE: When tackling complex reasoning tasks that benefit from breaking down problems, exploring multiple perspectives, " - "or reasoning through chains of consequences. Ideal for planning system architecture, debugging complex issues, " - "anticipating edge cases, weighing tradeoffs, or making implementation decisions. " - "WHEN NOT TO USE: For simple explanations, direct code writing, retrieving information, or when immediate action is needed. " - "RETURNS: Your structured thinking process formatted as markdown. This tool helps you methodically document your reasoning " - "without making repository changes. Structuring your thoughts with this tool can lead to more reliable reasoning " - "and better decision-making, especially for complex problems where it's easy to overlook important considerations.", + "description": "Structured reasoning for complex problems. Documents thought process without file changes. " + "USE: Planning architecture, debugging complex issues, weighing tradeoffs. " + "NOT: Simple explanations, direct coding, information retrieval. " + "RETURNS: Markdown-formatted thinking process", "inputSchema": { "type": "object", "properties": { "thought": { "type": "string", - "description": "Your step-by-step thinking process, including: breaking down problems, exploring alternatives, " - "considering pros/cons, examining assumptions, listing requirements, or working through edge cases. " - "Structure your thinking using markdown elements like bullet points, numbered lists, headings, or code blocks. " - "The more systematic your thinking, the better the outcome." + "description": "Step-by-step thinking process using markdown (bullet points, lists, headings, code blocks)." } }, "required": ["thought"] diff --git a/src/aidd/tools/path_tools.py b/src/aidd/tools/path_tools.py index 6bdf0cd..5e4d2a2 100644 --- a/src/aidd/tools/path_tools.py +++ b/src/aidd/tools/path_tools.py @@ -8,14 +8,10 @@ def get_allowed_directory_tool(): """Define the get_allowed_directory tool.""" return { "name": "get_allowed_directory", - "description": "Get the current working directory that this server is allowed to access. " - "WHEN TO USE: When you need to understand the current workspace boundaries, determine " - "the root directory for relative paths, or verify where file operations are permitted. " - "Useful for commands that need to know the allowed workspace root. " - "WHEN NOT TO USE: When you already know the current working directory or when you need " - "to actually list files in the directory (use directory_listing instead). " - "RETURNS: A string containing the absolute path to the current allowed working directory. " - "This is the root directory within which all file operations must occur.", + "description": "Get current allowed working directory. " + "USE: Understand workspace boundaries, verify file operation scope. " + "NOT: List directory contents (use list_directory). " + "RETURNS: Absolute path to workspace root", "inputSchema": { "type": "object", "properties": {}, @@ -27,24 +23,16 @@ def update_allowed_directory_tool(): """Define the update_allowed_directory tool.""" return { "name": "update_allowed_directory", - "description": "Change the working directory that this server is allowed to access. " - "WHEN TO USE: When you need to switch between different projects, change the workspace " - "root to a different directory, or expand/modify the boundaries of allowed file operations. " - "Useful when working with multiple projects or repositories in different locations. " - "WHEN NOT TO USE: When you only need to create a subdirectory within the current workspace " - "(use create_directory instead), or when you just want to list files in a different directory " - "(use directory_listing instead). " - "RETURNS: A confirmation message indicating that the allowed directory has been successfully " - "updated to the new path.", + "description": "Change allowed working directory. " + "USE: Switch projects, modify workspace boundaries. " + "NOT: Create subdirectories (use create_directory). " + "RETURNS: Confirmation of directory change", "inputSchema": { "type": "object", "properties": { "directory": { "type": "string", - "description": "Directory to allow access to. Must be an absolute path that exists on the system. " - "Use ~ to refer to the user's home directory. Examples: '/Users/username/projects', " - "'~/Documents/code', '/home/user/repositories'. The directory must exist and be " - "accessible to the user running the application." + "description": "Directory path (absolute, must exist). Examples: '/Users/username/projects', '~/Documents/code'." } }, "required": ["directory"] diff --git a/src/aidd/tools/screenshot_tool.py b/src/aidd/tools/screenshot_tool.py index 8f79202..8d5fc03 100644 --- a/src/aidd/tools/screenshot_tool.py +++ b/src/aidd/tools/screenshot_tool.py @@ -107,53 +107,37 @@ def capture_screenshot_tool(): """Define the capture_screenshot tool.""" return { "name": "capture_screenshot", - "description": "Capture a screenshot of the current screen and save it to a file. " - "This tool allows capturing the entire screen, the active window, or a specific named window. " - "The screenshot will be saved to the specified output path or to a default location if not provided. " - "WHEN TO USE: When you need to visually document what's on screen, capture a specific application " - "window, create visual references for troubleshooting, or gather visual information about the user's " - "environment. Useful for documenting issues, creating tutorials, or assisting with visual tasks. " - "WHEN NOT TO USE: When you need information about windows without capturing them (use get_available_windows " - "instead). " - "RETURNS: A JSON object containing success status, file path where the screenshot was saved, and a " - "message. On failure, includes a detailed error message. If debug mode is enabled, also includes debug " - "information about the attempted capture. Windows can be captured in the background without bringing " - "them to the front. Works on macOS, Windows, and Linux with platform-specific implementations.", + "description": "Screenshot full screen, active window, or named window. " + "USE: Visual documentation, troubleshooting, UI reference. " + "NOT: Window info without capture (use get_available_windows). " + "Captures windows in background. Requires permissions on macOS. " + "RETURNS: JSON with success, path, message", "inputSchema": { "type": "object", "properties": { "output_path": { "type": "string", - "description": "Optional path where the screenshot should be saved. If not provided, a default path will be used." - "Examples: 'screenshots/main_window.png', 'docs/current_state.png'. Both absolute " - "and relative paths are supported, but must be within the allowed workspace." + "description": "Optional save path. Examples: 'screenshots/main_window.png', 'docs/current_state.png'." }, "capture_mode": { "type": "object", - "description": "Specifies what to capture in the screenshot.", + "description": "What to capture.", "properties": { "type": { "type": "string", - "description": "The type of screenshot to capture. Use 'full' for the entire screen, 'active_window' " - "for the currently active window (foreground window), or 'named_window' for a specific " - "window by name or application name.", + "description": "Screenshot type: 'full' (entire screen), 'active_window' (foreground), 'named_window' (specific window).", "enum": ["full", "active_window", "named_window"] }, "window_name": { "type": "string", - "description": "Name of the specific application or window to capture. Required when type is 'named_window'. " - "This can be a partial window title or application name, and the search is case-insensitive. " - "Examples: 'Chrome', 'Visual Studio Code', 'Terminal'. Windows can be captured in the " - "background without bringing them to the front." + "description": "Application/window name (required for 'named_window'). Case-insensitive. Examples: 'Chrome', 'Terminal'." } }, "required": ["type"] }, "debug": { "type": "boolean", - "description": "Whether to include detailed debug information in the response when the operation fails. When " - "set to true, the response will include additional information about available windows, match " - "attempts, and system-specific details that can help diagnose capture issues. Default is False.", + "description": "Include debug info on failure (shows available windows, match attempts). Default: false.", } }, "required": ["capture_mode"] diff --git a/src/aidd/tools/system_tools.py b/src/aidd/tools/system_tools.py index bfa0029..43abd7c 100644 --- a/src/aidd/tools/system_tools.py +++ b/src/aidd/tools/system_tools.py @@ -13,18 +13,10 @@ def get_system_info_tool(): return { "name": "get_system_info", - "description": "Get detailed system information about the host computer. " - "WHEN TO USE: When you need to understand the system environment, diagnose performance issues, " - "verify hardware specifications, check resource availability, or determine the operating environment " - "for compatibility reasons. Useful for system analysis, troubleshooting, environment verification, " - "and providing context-aware assistance. " - "WHEN NOT TO USE: When you only need the current working directory (use get_allowed_directory instead), " - "when specific file information is needed (use get_file_info instead), or when you need to interact " - "with applications rather than system information (use get_active_apps instead). " - "RETURNS: A JSON object containing comprehensive system details including: working directory path, " - "OS details (name, version, architecture), Python version, WiFi network name, CPU information " - "(cores, usage), memory statistics (total, available, usage percentage), disk information " - "(total, free, usage percentage), and on macOS, additional hardware details (model, chip, serial number).", + "description": "System information: OS, hardware, resources, network. " + "USE: Environment analysis, compatibility checks, diagnostics. " + "NOT: Current directory (use get_allowed_directory), file info. " + "RETURNS: JSON with system stats, WiFi, Mac hardware details", "inputSchema": { "type": "object", "properties": {}, diff --git a/src/aidd/tools/todo_tools.py b/src/aidd/tools/todo_tools.py index c0ce5ea..a530156 100644 --- a/src/aidd/tools/todo_tools.py +++ b/src/aidd/tools/todo_tools.py @@ -7,16 +7,11 @@ def todo_read_tool(): """Define the todo_read tool.""" return { "name": "todo_read", - "description": "Read the current task list from the workspace-specific todo storage. " - "MANDATORY: This tool MUST be called FIRST before ANY workspace operations including file reads, code analysis, development tasks, project creation, or directory manipulation. " - "WORKSPACE-FIRST RULE: Every LLM interaction with workspaces, directories, projects, or repositories requires todo management. " - "WHEN TO USE: Always when starting workspace operations - check task status, review pending/completed work, understand project context, pick up previous progress. " - "Essential for: Project initialization, code development, file operations, debugging, testing, deployment, refactoring. " - "WHEN NOT TO USE: Pure informational queries unrelated to workspace development. " - "RETURNS: Sequential task list with status and metadata. Tasks execute in order - no priority system. " - "Each workspace maintains isolated todo lists for project organization. " - "CRITICAL: Bypassing this tool for workspace operations violates mandatory protocol. " - "EXAMPLES: \n- Creating new projects: Read todos to check existing project structure tasks\n- Code development: Check current development phase and next sequential steps\n- File modifications: Understand task context before making changes\n- Project analysis: Review completed analysis and next investigation steps", + "description": "🚨 CRITICAL: MUST be called FIRST before ANY file/directory operations. WORKSPACE-BOUND REQUIREMENT. ⚠️ " + "ENFORCE: Every read_file, write_file, edit_file, directory operation REQUIRES checking todos first. " + "WORKSPACE ISOLATION: Each directory has isolated todo context - check current workspace todos before ANY action. " + "FATAL ERROR if skipped: File operations without todo context violate workflow protocol. " + "RETURNS: Active todo list for current directory/workspace. Essential for maintaining project state.", "inputSchema": { "type": "object", "properties": {}, @@ -29,29 +24,24 @@ def todo_write_tool(): """Define the todo_write tool.""" return { "name": "todo_write", - "description": "Update the entire task list (complete replacement) for the current workspace. " - "MANDATORY: This tool MUST be called when planning, adding, or reorganizing tasks during ANY workspace operations. " - "WORKSPACE-FIRST RULE: All workspace development requires structured task management through sequential execution. " - "WHEN TO USE: Task planning for new projects, adding development phases, reorganizing workflow, batch status updates. " - "Sequential execution model: Tasks are completed in order, building upon previous work. No priority system - order determines execution. " - "Essential for: Project planning, development workflows, feature implementation, debugging sequences, deployment phases. " - "WHEN NOT TO USE: Single task updates (use todo_update), pure reading (use todo_read). " - "RETURNS: Success status and task count. Enforces sequential execution (only one in-progress task). " - "CRITICAL: Sequential task management is mandatory for all workspace development activities. " - "EXAMPLES: \n- New project setup: Create sequential tasks for initialization, structure, dependencies\n- Feature development: Plan design, implementation, testing, documentation phases\n- Bug fixing: Create investigation, fix, test, validation sequence\n- Code refactoring: Plan analysis, changes, testing, cleanup steps", + "description": "🚨 WORKSPACE PROTOCOL: Create/replace todo list when no active todos exist for current directory. ⚠️ " + "TRIGGER: After todo_read returns empty list OR when starting new file/directory work. " + "MANDATORY WORKFLOW: 1) todo_read first 2) If empty→todo_write 3) Then proceed with file operations. " + "VIOLATION PREVENTION: Never perform write_file, edit_file, directory operations without active todo context. " + "EXECUTION RULE: Create essential todos only. One 'in_progress' maximum. Focus on key milestones not micro-tasks.", "inputSchema": { "type": "object", "properties": { "todos": { "type": "array", - "description": "Complete list of todo items to replace the current list for sequential execution. Each todo must contain id, content, and status fields. Tasks execute in array order.", + "description": "Complete todo list for sequential execution. Tasks execute in array order.", "items": { "type": "object", "properties": { - "id": {"type": "string", "description": "Unique identifier for the task. Must be unique across all todos."}, - "content": {"type": "string", "description": "Task description or content. Cannot be empty."}, - "status": {"type": "string", "enum": ["pending", "in_progress", "completed"], "description": "Current status of the task. Only one task can be 'in_progress' at a time."}, - "metadata": {"type": "object", "description": "Optional additional data for the task.", "additionalProperties": True}, + "id": {"type": "string", "description": "Unique task identifier."}, + "content": {"type": "string", "description": "Task description (required)."}, + "status": {"type": "string", "enum": ["pending", "in_progress", "completed"], "description": "Task status (only one 'in_progress' allowed)."}, + "metadata": {"type": "object", "description": "Optional task metadata.", "additionalProperties": True}, }, "required": ["id", "content", "status"], "additionalProperties": True, @@ -67,28 +57,21 @@ def todo_update_tool(): """Define the todo_update tool.""" return { "name": "todo_update", - "description": "Update a specific todo item by ID for sequential workflow management. " - "MANDATORY: This tool MUST be called when progressing through tasks during workspace operations. " - "WORKSPACE-FIRST RULE: Task progress updates are required for all workspace development activities. " - "WHEN TO USE: Mark tasks in-progress when starting, completed when finished, update content for clarification. " - "Sequential workflow: Progress through tasks in order, maintaining single active task constraint. " - "Essential for: Task status transitions, progress tracking, workflow advancement, content updates. " - "WHEN NOT TO USE: Multiple task updates (use todo_write), adding new tasks (use todo_write). " - "RETURNS: Updated todo with status counts showing workflow progress. " - "Enforces sequential execution - only one task can be in-progress at any time. " - "CRITICAL: Sequential progress tracking is mandatory for workspace development workflows. " - "EXAMPLES: \n- Starting work: Update task from 'pending' to 'in_progress'\n- Completing work: Update task from 'in_progress' to 'completed'\n- Task refinement: Update content for better clarity\n- Workflow progression: Move to next sequential task", + "description": "🚨 WORKFLOW ENFORCEMENT: Update todo status during file/directory operations. REQUIRED after each task. ⚠️ " + "PROTOCOL: Mark 'in_progress' when starting task, 'completed' when finished. Update after EVERY file operation. " + "CRITICAL SYNC: Todo status must reflect actual work progress. Failure to update breaks workspace integrity. " + "SEQUENTIAL RULE: Only one task 'in_progress' at a time. Complete current before starting next.", "inputSchema": { "type": "object", "properties": { - "todo_id": {"type": "string", "description": "The unique ID of the todo to update."}, + "todo_id": {"type": "string", "description": "Todo ID to update."}, "updates": { "type": "object", - "description": "Fields to update in the todo for sequential workflow. Can include content, status, or metadata.", + "description": "Fields to update (content, status, metadata).", "properties": { - "content": {"type": "string", "description": "New task description or content."}, - "status": {"type": "string", "enum": ["pending", "in_progress", "completed"], "description": "New status of the task."}, - "metadata": {"type": "object", "description": "Additional data for the task.", "additionalProperties": True}, + "content": {"type": "string", "description": "New task description."}, + "status": {"type": "string", "enum": ["pending", "in_progress", "completed"], "description": "New task status."}, + "metadata": {"type": "object", "description": "Additional task data.", "additionalProperties": True}, }, "additionalProperties": True, }, diff --git a/src/aidd/tools/web_tools.py b/src/aidd/tools/web_tools.py index 029a218..ba34080 100644 --- a/src/aidd/tools/web_tools.py +++ b/src/aidd/tools/web_tools.py @@ -13,50 +13,36 @@ def web_fetch_tool(): return { "name": "web_fetch", - "description": "Fetches content from a URL. " - "WHEN TO USE: When you need to retrieve data from web APIs, download documentation, " - "check external resources, or gather information from websites. Useful for getting " - "real-time data, documentation, or referencing external content. " - "WHEN NOT TO USE: When you need to interact with complex websites requiring authentication " - "or session management, when the data needs to be processed in a specific format not supported, " - "or when you need to make authenticated API calls with OAuth. " - "TIP: Use 'web_search' first to find relevant URLs, then use this tool to fetch detailed content. " - "RETURNS: The content of the URL as text. For HTML pages, returns the raw HTML content. " - "For JSON endpoints, returns the JSON content as a string. Successful response includes HTTP " - "status code. Failed requests include error details. Maximum request size enforced for safety.", + "description": "Fetch URL content with HTML→markdown conversion. 10MB limit. " + "USE: Get web data, API responses, documentation. " + "NOT: Complex auth, session management, OAuth interactions. " + "TIP: Use web_search first to find URLs. " + "Auto-converts HTML to markdown", "inputSchema": { "type": "object", "properties": { "url": { "type": "string", - "description": "The URL to fetch content from. Must be a valid URL with supported protocol " - "(http or https). Examples: 'https://example.com', 'https://api.github.com/repos/user/repo'. " - "The URL must be publicly accessible." + "description": "URL to fetch (http/https only). Examples: 'https://example.com', 'https://api.github.com/repos/user/repo'." }, "headers": { "type": "object", - "description": "Optional HTTP headers to include in the request. Useful for API calls that " - "require specific headers like User-Agent or Accept. Example: {'User-Agent': 'SkyDeckAI', " - "'Accept': 'application/json'}.", + "description": "Optional HTTP headers. Examples: {'User-Agent': 'SkyDeckAI', 'Accept': 'application/json'}.", "default": {} }, "timeout": { "type": "integer", - "description": "Request timeout in seconds. Maximum time to wait for the server to respond before " - "aborting the request. Defaults to 10 seconds.", + "description": "Request timeout in seconds. Default: 10.", "default": 10 }, "save_to_file": { "type": "string", - "description": "Optional path to save the response content to a file. If provided, the content " - "will be saved to this location. Must be within the allowed directory. Example: " - "'downloads/page.html', 'data/api_response.json'.", + "description": "Optional save path. Examples: 'downloads/page.html', 'data/api_response.json'.", "default": None }, "convert_html_to_markdown": { "type": "boolean", - "description": "If set to true and the content is HTML, it will be converted to markdown format " - "for better readability. This is especially useful for web pages with a lot of content.", + "description": "Convert HTML content to markdown for better readability. Default: true.", "default": True } }, @@ -192,36 +178,30 @@ async def handle_web_fetch(arguments: dict) -> List[TextContent]: def web_search_tool(): return { "name": "web_search", - "description": "Performs a web search and returns the search results. " - "WHEN TO USE: When you need to find information on the web, get up-to-date data, " - "or research a topic. This provides more current information than your training data. " - "WHEN NOT TO USE: For queries requiring complex authentication, accessing private data, " - "or when you want to browse interactive websites. " - "TIP: For best results, use this tool to find relevant URLs, then use 'web_fetch' to get the full content of specific pages. " - "RETURNS: A list of search results including titles, URLs, and snippets for each result.", + "description": "Web search with Bing/DuckDuckGo. Returns titles, URLs, snippets. " + "USE: Find current information, research topics. " + "NOT: Private data, authenticated content, interactive sites. " + "TIP: Use with web_fetch for detailed content", "inputSchema": { "type": "object", "properties": { "query": { "type": "string", - "description": "The search query to send to search engine. Be specific to get better results. " - "Example: 'latest python release features' or 'climate change statistics 2023'." + "description": "Search query (be specific). Examples: 'latest python release features', 'climate change statistics 2023'." }, "num_results": { "type": "integer", - "description": "Number of search results to return. Maximum is 20 to prevent abuse.", + "description": "Number of results to return (max 20). Default: 10.", "default": 10 }, "convert_html_to_markdown": { "type": "boolean", - "description": "If true, search result snippets will be converted from HTML to markdown " - "for better readability.", + "description": "Convert search snippets from HTML to markdown. Default: true.", "default": True }, "search_engine": { "type": "string", - "description": "Specifies which search engine to use. Options: 'auto' (tries all in sequence), " - "'bing', or 'duckduckgo'. Some engines may block automated requests.", + "description": "Search engine to use. Options: 'auto', 'bing', 'duckduckgo'. Default: 'auto'.", "enum": ["auto", "bing", "duckduckgo"], "default": "auto" }