zblade.dev/docs/TOOL_CALLS.md

# Zaguán Blade Tool Calls Reference

This document describes the regular tool calls that Zaguán Blade supports. These are the tools you can add to your Local AI system prompts to extend usability.

> **Note:** This does not cover Blade-specific or ZLP (Zaguán Language Protocol) tools. These are standard file/editor tools for general AI coding assistance.

---

## File Operations

### `read_file`

Read the complete contents of a file.

**Parameters:**
| Name | Type | Required | Description |
|------|------|----------|-------------|
| `path` | string | Yes | File path (relative to workspace or absolute) |

**Aliases:** `file_path`, `filepath`, `filename`

**Example:**
```json
{
  "path": "src/main.rs"
}
```

---

### `read_file_range`

Read a specific line range from a file with optional context.

**Parameters:**
| Name | Type | Required | Description |
|------|------|----------|-------------|
| `path` | string | Yes | File path |
| `start_line` | integer | No | Start line (1-indexed, default: 1) |
| `end_line` | integer | No | End line (1-indexed, default: end of file) |
| `context_lines` | integer | No | Extra context lines before/after range (default: 0) |

**Example:**
```json
{
  "path": "src/lib.rs",
  "start_line": 50,
  "end_line": 100,
  "context_lines": 3
}
```

---

### `write_file` / `create_file`

Write content to a file. Creates parent directories if needed.

**Parameters:**
| Name | Type | Required | Description |
|------|------|----------|-------------|
| `path` | string | Yes | File path |
| `content` | string | Yes | Content to write |

**Aliases for content:** `contents`, `text`, `data`

**Example:**
```json
{
  "path": "src/new_module.rs",
  "content": "pub fn hello() {\n    println!(\"Hello!\");\n}\n"
}
```

---

### `edit_file`

Apply a search/replace edit to a file (legacy tool).

**Parameters:**
| Name | Type | Required | Description |
|------|------|----------|-------------|
| `path` | string | Yes | File path |
| `old_content` | string | Yes | Text to find |
| `new_content` | string | Yes | Replacement text |

**Aliases:** `old`/`from` for old_content, `new`/`to` for new_content

**Example:**
```json
{
  "path": "src/main.rs",
  "old_content": "fn old_function()",
  "new_content": "fn new_function()"
}
```

---

### `apply_edit` / `apply_patch`

Apply search/replace edits with robust fuzzy matching. Supports both single patches and atomic multi-patch operations.

**Single Patch Parameters:**
| Name | Type | Required | Description |
|------|------|----------|-------------|
| `path` | string | Yes | File path |
| `old_text` | string | Yes | Text to find and replace |
| `new_text` | string | Yes | Replacement text |

**Multi-Patch Parameters:**
| Name | Type | Required | Description |
|------|------|----------|-------------|
| `path` | string | Yes | File path |
| `patches` | array | Yes | Array of patch objects |

Each patch object contains:
- `old_text` (string): Text to find
- `new_text` (string): Replacement text
- `start_line` (integer, optional): Hint for disambiguation
- `end_line` (integer, optional): Hint for disambiguation

**Single Patch Example:**
```json
{
  "path": "src/lib.rs",
  "old_text": "let x = 5;",
  "new_text": "let x = 10;"
}
```

**Multi-Patch Example:**
```json
{
  "path": "src/lib.rs",
  "patches": [
    {"old_text": "fn foo()", "new_text": "fn bar()"},
    {"old_text": "let a = 1;", "new_text": "let a = 2;"}
  ]
}
```

> **Note:** Multi-patch operations are atomic—all patches are validated before any are applied. If any patch fails, no changes are made.

---

### `delete_file`

Delete a file or directory.

**Parameters:**
| Name | Type | Required | Description |
|------|------|----------|-------------|
| `path` | string | Yes | Path to delete |
| `recursive` | boolean | No | Required for directories (default: false) |

**Example:**
```json
{
  "path": "temp/old_file.txt"
}
```

---

### `move_file`

Move or rename a file.

**Parameters:**
| Name | Type | Required | Description |
|------|------|----------|-------------|
| `source` | string | Yes | Source path |
| `destination` | string | Yes | Destination path |

**Example:**
```json
{
  "source": "src/old_name.rs",
  "destination": "src/new_name.rs"
}
```

---

### `copy_file`

Copy a file or directory (recursive for directories).

**Parameters:**
| Name | Type | Required | Description |
|------|------|----------|-------------|
| `source` | string | Yes | Source path |
| `destination` | string | Yes | Destination path |

**Example:**
```json
{
  "source": "templates/base.html",
  "destination": "src/templates/base.html"
}
```

---

### `get_file_info`

Get metadata about a file or directory.

**Parameters:**
| Name | Type | Required | Description |
|------|------|----------|-------------|
| `path` | string | Yes | Path to inspect |

**Returns:** JSON with `path`, `size`, `is_directory`, `is_file`, `modified`, `readonly`

**Example:**
```json
{
  "path": "Cargo.toml"
}
```

---

### `create_directory`

Create a directory (and parent directories if needed).

**Parameters:**
| Name | Type | Required | Description |
|------|------|----------|-------------|
| `path` | string | Yes | Directory path to create |

**Example:**
```json
{
  "path": "src/modules/new_feature"
}
```

---

## Directory & Search Tools

### `list_directory` / `list_dir`

List directory contents with tree view.

**Parameters:**
| Name | Type | Required | Description |
|------|------|----------|-------------|
| `path` | string | No | Directory path (default: ".") |
| `max_depth` | integer | No | Max traversal depth (default: 1) |

**Aliases:** `dir`, `directory`

**Example:**
```json
{
  "path": "src",
  "max_depth": 2
}
```

---

### `get_workspace_structure`

Get a tree view of the workspace structure.

**Parameters:**
| Name | Type | Required | Description |
|------|------|----------|-------------|
| `path` | string | No | Starting path (default: ".") |
| `depth` | integer | No | Max depth (default: 2) |
| `limit` | integer | No | Max entries (default: 50, max: 200) |

**Example:**
```json
{
  "path": ".",
  "depth": 3,
  "limit": 100
}
```

> **Note:** Automatically ignores common directories like `node_modules`, `target`, `.git`, `__pycache__`, etc.

---

### `find_files`

Find files by name pattern (substring match).

**Parameters:**
| Name | Type | Required | Description |
|------|------|----------|-------------|
| `pattern` | string | Yes | Substring to match in filenames |
| `path` | string | No | Starting path (default: workspace root) |
| `max_depth` | integer | No | Max search depth |

**Example:**
```json
{
  "pattern": "test",
  "path": "src",
  "max_depth": 5
}
```

---

### `find_files_glob` / `glob`

Find files using glob patterns.

**Parameters:**
| Name | Type | Required | Description |
|------|------|----------|-------------|
| `pattern` | string | Yes | Glob pattern (e.g., `**/*.rs`) |
| `path` | string | No | Base path for search |
| `case_sensitive` | boolean | No | Case-sensitive matching (default: false) |

**Example:**
```json
{
  "pattern": "**/*.tsx",
  "path": "src"
}
```

---

### `grep_search` / `rg`

Search file contents using regex patterns.

**Parameters:**
| Name | Type | Required | Description |
|------|------|----------|-------------|
| `pattern` | string | Yes | Regex pattern to search |
| `path` | string | No | Directory to search (default: ".") |

**Aliases for pattern:** `query`, `regex`

**Example:**
```json
{
  "pattern": "fn\\s+main",
  "path": "src"
}
```

**Returns:** Matches in format `filepath:line_number:line_content`

---

### `codebase_search`

Search codebase with context lines around matches.

**Parameters:**
| Name | Type | Required | Description |
|------|------|----------|-------------|
| `query` | string | Yes | Regex pattern to search |
| `file_pattern` | string | No | Filter files (e.g., `*.rs,*.toml`) |
| `max_results` | integer | No | Maximum results (default: 50) |

**Example:**
```json
{
  "query": "struct.*Config",
  "file_pattern": "*.rs",
  "max_results": 20
}
```

**Returns:** Matches with 2 lines of context before and after.

---

## Editor Interaction Tools

### `get_editor_state`

Get current editor context including active file, cursor position, and open files.

**Parameters:** None

**Returns:** JSON with:
- `active_file`: Currently focused file
- `open_files`: List of open file paths
- `active_tab_index`: Index of active tab
- `cursor_line`, `cursor_column`: Cursor position
- `selection_start_line`, `selection_end_line`: Selection range

---

### `open_file`

Open a file in the editor.

**Parameters:**
| Name | Type | Required | Description |
|------|------|----------|-------------|
| `path` | string | Yes | File path to open |
| `line` | integer | No | Line number to jump to |

**Example:**
```json
{
  "path": "src/main.rs",
  "line": 42
}
```

---

### `goto_line`

Navigate to a specific line in the active file.

**Parameters:**
| Name | Type | Required | Description |
|------|------|----------|-------------|
| `line` | integer | Yes | Line number (1-indexed) |
| `column` | integer | No | Column number |

**Example:**
```json
{
  "line": 100,
  "column": 15
}
```

---

### `get_selection`

Get the currently selected text in the editor.

**Parameters:** None

**Returns:** The selected text content.

---

### `replace_selection`

Replace the current selection with new content.

**Parameters:**
| Name | Type | Required | Description |
|------|------|----------|-------------|
| `content` | string | Yes | Replacement content |

**Example:**
```json
{
  "content": "new replacement text"
}
```

---

### `insert_at_cursor`

Insert content at the current cursor position.

**Parameters:**
| Name | Type | Required | Description |
|------|------|----------|-------------|
| `content` | string | Yes | Content to insert |

**Example:**
```json
{
  "content": "// TODO: implement this\n"
}
```

---

## Command Execution

### `run_command`

Execute a shell command (requires user approval).

**Parameters:**
| Name | Type | Required | Description |
|------|------|----------|-------------|
| `command` | string | Yes | Shell command to execute |
| `cwd` | string | Yes | Working directory |

**Example:**
```json
{
  "command": "cargo build --release",
  "cwd": "."
}
```

> **Note:** This tool requires user confirmation before execution for safety.

---

## Tool Result Handling

Tool results are automatically truncated if they exceed limits:
- **Max size:** 50KB
- **Max lines:** 2000

When truncated, the first 100 lines and last 50 lines are shown with a truncation message.

---

## Path Resolution

All paths can be:
- **Relative:** Resolved from workspace root (e.g., `src/main.rs`)
- **Absolute:** Used as-is (must be within workspace)

Paths outside the workspace are rejected for security.

---

## Adding Tools to Your AI System Prompt

To use these tools with a local AI, include the tool definitions in your system prompt. Example format:

```
You have access to the following tools:

- read_file: Read file contents. Args: {"path": "string"}
- write_file: Write to file. Args: {"path": "string", "content": "string"}
- grep_search: Search with regex. Args: {"pattern": "string", "path": "string"}
- apply_edit: Edit file. Args: {"path": "string", "old_text": "string", "new_text": "string"}
...

To use a tool, respond with:
<tool_call>
{"name": "tool_name", "arguments": {...}}
</tool_call>
```

The exact format depends on your AI provider's tool calling conventions.