// TOOL_CALLS.md

TOOL CALLS REFERENCE_

Reference for the regular tool calls that Zaguán Blade supports. Add these to your Local AI system prompts to extend usability with file operations, search, editor control, and command execution.

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 Directory & Search Editor Interaction Command Execution Result Handling Path Resolution System Prompt

[001] FILE_OPERATIONS

File Operations

read_file READ

Read the complete contents of a file.

Aliases: file_path, filepath, filename

Parameters

Name	Type	Description
`path`	required string	File path (relative to workspace or absolute)

Example

{ "path": "src/main.rs" }

read_file_range READ

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

Parameters

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

Example

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

write_file / create_file WRITE

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

Content aliases: contents, text, data

Parameters

Name	Type	Description
`path`	required string	File path
`content`	required string	Content to write

Example

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

edit_file EDIT LEGACY

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

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

Parameters

Name	Type	Description
`path`	required string	File path
`old_content`	required string	Text to find
`new_content`	required string	Replacement text

Example

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

apply_edit / apply_patch EDIT RECOMMENDED

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

Single Patch Parameters

Name	Type	Description
`path`	required string	File path
`old_text`	required string	Text to find and replace
`new_text`	required string	Replacement text

Multi-Patch Parameters

Name	Type	Description
`path`	required string	File path
`patches`	required array	Array of patch objects

Each patch: old_text, new_text, optional start_line/end_line hints

Single Patch

{
  "path": "src/lib.rs",
  "old_text": "let x = 5;",
  "new_text": "let x = 10;"
}

Multi-Patch

{
  "path": "src/lib.rs",
  "patches": [
    {"old_text": "fn foo()", "new_text": "fn bar()"},
    {"old_text": "let a = 1;", "new_text": "let a = 2;"}
  ]
}

ℹ️

Multi-patch operations are atomic - all patches are validated before any are applied. If any patch fails, no changes are made.

delete_file DELETE

Delete a file or directory.

Parameters

Name	Type	Description
`path`	required string	Path to delete
`recursive`	optional boolean	Required for directories (default: false)

Example

{ "path": "temp/old_file.txt" }

move_file MOVE

Move or rename a file.

Parameters

Name	Type	Description
`source`	required string	Source path
`destination`	required string	Destination path

Example

{
  "source": "src/old_name.rs",
  "destination": "src/new_name.rs"
}

copy_file COPY

Copy a file or directory (recursive for directories).

Parameters

Name	Type	Description
`source`	required string	Source path
`destination`	required string	Destination path

Example

{
  "source": "templates/base.html",
  "destination": "src/templates/base.html"
}

get_file_info INFO

Get metadata about a file or directory.

Parameters

Name	Type	Description
`path`	required string	Path to inspect

Returns

path size is_directory is_file modified readonly

Example

{ "path": "Cargo.toml" }

create_directory CREATE

Create a directory (and parent directories if needed).

Parameters

Name	Type	Description
`path`	required string	Directory path to create

Example

{ "path": "src/modules/new_feature" }

[002] DIRECTORY_&_SEARCH

Directory & Search Tools

list_directory / list_dir DIRECTORY

List directory contents with tree view.

Aliases: dir, directory

Parameters

Name	Type	Description
`path`	optional string	Directory path (default: ".")
`max_depth`	optional integer	Max traversal depth (default: 1)

Example

{
  "path": "src",
  "max_depth": 2
}

get_workspace_structure PROJECT RECOMMENDED

Get a tree view of the workspace structure.

Parameters

Name	Type	Description
`path`	optional string	Starting path (default: ".")
`depth`	optional integer	Max depth (default: 2)
`limit`	optional integer	Max entries (default: 50, max: 200)

Example

{
  "path": ".",
  "depth": 3,
  "limit": 100
}

ℹ️

Automatically ignores common directories like node_modules, target, .git, __pycache__, etc.

find_files SEARCH

Find files by name pattern (substring match).

Parameters

Name	Type	Description
`pattern`	required string	Substring to match in filenames
`path`	optional string	Starting path (default: workspace root)
`max_depth`	optional integer	Max search depth

Example

{
  "pattern": "test",
  "path": "src",
  "max_depth": 5
}

find_files_glob / glob SEARCH

Find files using glob patterns.

Parameters

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

Example

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

grep_search / rg CONTENT

Search file contents using regex patterns.

Pattern aliases: query, regex

Parameters

Name	Type	Description
`pattern`	required string	Regex pattern to search
`path`	optional string	Directory to search (default: ".")

Example

{
  "pattern": "fn\\s+main",
  "path": "src"
}

Returns

Matches in format filepath:line_number:line_content

codebase_search CONTENT

Search codebase with context lines around matches.

Parameters

Name	Type	Description
`query`	required string	Regex pattern to search
`file_pattern`	optional string	Filter files (e.g., `.rs,.toml`)
`max_results`	optional integer	Maximum results (default: 50)

Example

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

Returns

Matches with 2 lines of context before and after.

[003] EDITOR_INTERACTION

Editor Interaction Tools

get_editor_state INFO RECOMMENDED

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

Parameters

None

Returns

active_file open_files active_tab_index cursor_line cursor_column selection_start_line selection_end_line

open_file CONTROL

Open a file in the editor.

Parameters

Name	Type	Description
`path`	required string	File path to open
`line`	optional integer	Line number to jump to

Example

{
  "path": "src/main.rs",
  "line": 42
}

goto_line CONTROL

Navigate to a specific line in the active file.

Parameters

Name	Type	Description
`line`	required integer	Line number (1-indexed)
`column`	optional integer	Column number

Example

{
  "line": 100,
  "column": 15
}

get_selection SELECTION

Get the currently selected text in the editor.

Parameters

None

Returns

The selected text content.

replace_selection EDIT

Replace the current selection with new content.

Parameters

Name	Type	Description
`content`	required string	Replacement content

Example

{ "content": "new replacement text" }

insert_at_cursor EDIT

Insert content at the current cursor position.

Parameters

Name	Type	Description
`content`	required string	Content to insert

Example

{ "content": "// TODO: implement this\n" }

[004] COMMAND_EXECUTION

Command Execution

run_command TERMINAL

Execute a shell command (requires user approval).

Parameters

Name	Type	Description
`command`	required string	Shell command to execute
`cwd`	required string	Working directory

Example

{
  "command": "cargo build --release",
  "cwd": "."
}

⚠️

This tool requires user confirmation before execution for safety.

[005] TOOL_RESULTS

Tool Result Handling

Tool results are automatically truncated if they exceed limits:

50KB Max size

2000 Max lines

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

[006] PATH_RESOLUTION

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.

[007] SYSTEM_PROMPT

Adding Tools to Your AI System Prompt

To use these tools with a local AI, include the tool definitions in your system prompt. See the Local AI System Prompts section for setup instructions.

Example System Prompt Snippet text

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.