Skip to content

Optimize description #23

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 4 commits into
base: main
Choose a base branch
from
Open

Optimize description #23

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
18728bf
chore: optimize the descriptions for tools
thuanphamchezzi Aug 4, 2025
6fd6dde
chore: optimize todo tools description to get it invoked in prior to …
thuanphamchezzi Aug 4, 2025
b7af8cc
chore: remove params examples in tool description as params has their…
thuanphamchezzi Aug 5, 2025
c442358
chore: update README to reflects the tools descriptions
thuanphamchezzi Aug 5, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
75 changes: 38 additions & 37 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 |
Expand All @@ -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

Expand All @@ -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
{
Expand All @@ -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

Expand All @@ -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

Expand Down Expand Up @@ -184,7 +184,7 @@ Supported Languages:

#### search_code

Fast content search tool using regular expressions:
Regex-based content search:

```json
{
Expand All @@ -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

Expand Down Expand Up @@ -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
{}
Expand Down Expand Up @@ -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
{
Expand All @@ -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
{
Expand Down Expand Up @@ -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

Expand Down
19 changes: 6 additions & 13 deletions src/aidd/tools/code_analysis.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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"]
Expand Down
57 changes: 13 additions & 44 deletions src/aidd/tools/code_execution.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -28,42 +28,26 @@ 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",
"properties": {
"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, <?php will be prepended if not present.",
"description": "Code to execute. Auto-wraps Go/Rust main functions, adds PHP tags.",
},
"timeout": {
"type": "integer",
"description": "Maximum execution time in seconds. The execution will be terminated if it exceeds this time limit, returning a " + "timeout message. Must be between 1 and 30 seconds.",
"description": "Max execution time (1-30 seconds). Default: 5.",
"default": 5,
"minimum": 1,
"maximum": 30,
Expand All @@ -78,36 +62,21 @@ def execute_shell_script_tool() -> 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,
},
Expand Down
Loading