zblade.dev/docs/TOOL_CALLS.md

Zaguán Blade Tool Calls Reference

This document lists the tool calls that are actually executable in the local zblade runtime.

It intentionally excludes:

• ZLP-related tooling
• Anything handled server-side by zcoderd
• Schema-only entries that are not currently executed by zblade

The authoritative implementation lives in src-tauri/src/tools.rs.

---

Scope

These tools are the ones zblade can execute locally in its own tool executor.

Excluded server-side tools include:

• ask_followup_question
• attempt_completion
• new_task
• generate_image
• todo_write

Also excluded from this document:

• symbol_references because it is present in tool schema definitions but is not currently dispatched by the local executor.

---

File Tools

read_file

Read the full contents of a file.

Parameters:

Name	Type	Required	Description
path	string	Yes	File path

Accepted aliases for path: file_path, filepath, filename

Example:

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

read_file_range

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

Parameters:

Name	Type	Required	Description
path	string	Yes	File path
start_line	integer	No	Start line, 1-indexed. Defaults to 1.
end_line	integer	No	End line, 1-indexed. Defaults to end of file.
context_lines	integer	No	Extra lines before and after the requested range. Defaults to 0.

Accepted aliases for path: file_path, filepath, filename

Example:

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

write_file

Write content to a file. Parent directories are created if needed.

create_file

Alias of write_file.

Parameters:

Name	Type	Required	Description
path	string	Yes	Target file path
content	string	Yes	File contents

Accepted aliases:

• path: file_path, filepath, filename
• content: contents, text, data

Example:

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

edit_file

Legacy single search/replace edit tool.

Parameters:

Name	Type	Required	Description
path	string	Yes	File path
old_content	string	Yes	Text to find
new_content	string	Yes	Replacement text

Accepted aliases:

• path: file_path, filepath, filename
• old_content: old, from
• new_content: new, to

apply_patch

Preferred patch/edit tool for search/replace edits.

apply_edit

Alias of apply_patch.

Supports both a single replacement and an atomic multi-patch mode.

Single-patch parameters:

Name	Type	Required	Description
path	string	Yes	File path
old_text	string	Yes	Exact text to 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 supports:

• old_text — required
• new_text — required
• start_line — optional hint
• end_line — optional hint

Accepted aliases in single-patch mode:

• path: file_path, filepath, filename
• old_text: old_content, old, from
• new_text: new_content, new, to

Important behavior:

• Matching is exact.
• If the match is ambiguous, the edit fails.
• Multi-patch application is atomic: if one patch fails validation, none are applied.

delete_file

Delete a file, or a directory when recursive: true is provided.

Parameters:

Name	Type	Required	Description
path	string	Yes	Path to delete
recursive	boolean	No	Required when deleting a directory

move_file

Move or rename a file.

Parameters:

Name	Type	Required	Description
source	string	Yes	Source path
destination	string	Yes	Destination path

copy_file

Copy a file or recursively copy a directory.

Parameters:

Name	Type	Required	Description
source	string	Yes	Source path
destination	string	Yes	Destination path

create_directory

Create a directory and any missing parent directories.

Parameters:

Name	Type	Required	Description
path	string	Yes	Directory path

get_file_info

Return basic filesystem metadata.

Parameters:

Name	Type	Required	Description
path	string	Yes	Path to inspect

Returns: JSON including path, size, is_directory, is_file, modified, and readonly.

---

Directory and Search Tools

list_dir

List directory contents using a compact tree-like view.

list_directory

Alias of list_dir.

This is implemented by forwarding to get_workspace_structure with a default shallow depth.

Parameters:

Name	Type	Required	Description
path	string	No	Directory path. Defaults to ..

Notes:

• list_dir / list_directory exists mainly as a compatibility entry point.
• The underlying structured traversal behavior is defined by get_workspace_structure.
• Prefer get_workspace_structure when you need explicit traversal controls.

get_workspace_structure

Return a tree view of the workspace or a subdirectory.

Parameters:

Name	Type	Required	Description
path	string	No	Starting path. Defaults to ..
depth	integer	No	Max traversal depth. Defaults to 2.
limit	integer	No	Max returned entries. Defaults to 50, capped at 200.

Accepted aliases for path: dir, directory

Behavior notes:

• Hidden files are skipped.
• Common heavy/generated directories are skipped.
• Gitignored paths are filtered when project settings enable that behavior.

find_files

Find files by substring match on filename.

Parameters:

Name	Type	Required	Description
pattern	string	Yes	Substring to match in entry names
path	string	No	Search root inside the workspace
max_depth	integer	No	Optional max traversal depth

find_files_glob

Find files with a glob pattern.

glob

Alias of find_files_glob.

Parameters:

Name	Type	Required	Description
pattern	string	Yes	Glob pattern
path	string	No	Optional base path
case_sensitive	boolean	No	Whether matching is case-sensitive

Accepted aliases:

• pattern: glob

grep_search

Search file contents with a regular expression.

rg

Alias of grep_search.

Parameters:

Name	Type	Required	Description
pattern	string	Yes	Regex pattern
path	string	No	Search root. Defaults to ..
include_dependencies	boolean	No	Include dependency directories like node_modules and vendor
timeout_ms	integer	No	Timeout used when timeout enforcement is enabled

Accepted aliases:

• pattern: query, regex
• path: dir, directory

Behavior notes:

• Returns matches in path:line:text form on success.
• If timeout enforcement is enabled and the search times out, it returns structured JSON with partial results and a hint.

codebase_search

Search the codebase with regex and return matches with surrounding context.

Parameters:

Name	Type	Required	Description
query	string	Yes	Regex pattern
file_pattern	string	No	Comma-separated filename patterns
max_results	integer	No	Max number of matches to return. Defaults to 50.

---

Editor and UI Interaction Tools

get_editor_state

Return the current local editor context.

Parameters: None.

Returns: JSON including:

• active_file
• open_files
• active_tab_index
• cursor_line
• cursor_column
• selection_start_line
• selection_end_line

The returned text may also include human-readable helper guidance for the active file and cursor location.

open_file

Emit an editor action that opens a file, optionally at a line.

Parameters:

Name	Type	Required	Description
path	string	Yes	File to open
line	integer	No	Line number to jump to

Note: This returns an action payload for the frontend to intercept.

goto_line

Emit an editor action that moves the cursor in the current file.

Parameters:

Name	Type	Required	Description
line	integer	Yes	Target line
column	integer	No	Optional target column

get_selection

Request the current selection.

Parameters: None.

Current status: implemented only as a placeholder action payload. It does not currently return the true selected text.

replace_selection

Emit an editor action that replaces the current selection.

Parameters:

Name	Type	Required	Description
content	string	Yes	Replacement content

insert_at_cursor

Emit an editor action that inserts content at the current cursor position.

Parameters:

Name	Type	Required	Description
content	string	Yes	Text to insert

---

Local Code-Intelligence Tools

These tools are local to zblade. They are not ZLP tools and do not require zcoderd, but they do depend on zblade's local language service / symbol index being available.

symbol_search

Search indexed symbols by name or qualified name.

Parameters:

Name	Type	Required	Description
query	string	Yes	Symbol query
path	string	No	Restrict to a file
kind	string	No	Symbol kind filter
limit	integer	No	Max results. Defaults to 20, capped at 100.

Accepted aliases:

• path: file, file_path
• kind: symbol_type

symbol_resolve

Resolve one symbol by ID, or by file plus name.

Parameters:

Name	Type	Required	Description
symbol_id	string	Conditionally	Stable symbol ID
path	string	Conditionally	Required when resolving by file-scoped lookup
qualified_name	string	No	Exact qualified name
name	string	No	Simple symbol name

Accepted aliases:

• symbol_id: id
• path: file, file_path

Rule: provide either symbol_id, or a path with a symbol name selector.

symbol_outline

Return the hierarchical symbol outline for one file.

Parameters:

Name	Type	Required	Description
path	string	Yes	File path

Accepted aliases for path: file, file_path

symbol_graph

Return incoming and outgoing graph edges for a symbol.

Parameters:

Name	Type	Required	Description
symbol_id	string	Conditionally	Stable symbol ID
path	string	Conditionally	File path when resolving by file/name
qualified_name	string	No	Exact qualified name
name	string	No	Simple symbol name
relationship_type	string	No	Edge type. Defaults to call.
limit	integer	No	Max edges. Defaults to 20, capped at 100.

Accepted aliases:

• symbol_id: id
• path: file, file_path
• relationship_type: edge_kind, kind

---

Project Index Tools

These tools read the local .zblade/context/project_index.md artifact, or a semantic overview generated by the local language service when available.

get_project_index_overview

Read a compact overview window from the local project index.

Parameters:

Name	Type	Required	Description
path	string	No	Optional workspace sub-root
max_chars	integer	No	Character budget. Defaults to 6000, capped at 12000.
offset	integer	No	Character offset

get_project_index_chunk

Read a deterministic paged chunk from the local project index.

Parameters:

Name	Type	Required	Description
path	string	No	Optional workspace sub-root
offset	integer	No	Character offset
max_chars	integer	No	Character budget. Defaults to 4000, capped at 8000.

---

Composite Read-Only Tools

These tools are supported by zblade locally.

By default, schema exposure may be gated by model family and the composite_tools_enabled feature flag, but the local executor does support them.

read_many_files

Read multiple files selected by glob patterns in a single bounded call.

Parameters:

Name	Type	Required	Description
paths	array of strings	Yes	Include globs
exclude	array of strings	No	Exclude globs
max_files	integer	No	Max files. Defaults to 100, capped at 500.
max_bytes_per_file	integer	No	Per-file byte limit. Defaults to 65536, capped at 524288.
include_line_numbers	boolean	No	Include line numbers in returned content

Accepted aliases for include globs: globs, patterns

batch

Execute multiple read-only tool calls concurrently with all-settled behavior.

Parameters:

Name	Type	Required	Description
calls	array	Yes	Array of tool call objects
max_parallel	integer	No	Defaults to 8, capped at 16
fail_fast	boolean	No	Stop queued work after first failure
ordered	boolean	No	Preserve input order. Defaults to true.
cancel_after_ms	integer	No	Optional total budget

Each call object supports:

• tool or name
• arguments

Important behavior:

• Only read-only tools are allowed.
• batch itself and run_command are explicitly blocked inside batch.

codebase_investigator

Run a bounded read-only investigation pass and return structured findings.

Parameters:

Name	Type	Required	Description
objective	string	Yes	Investigation goal
scope	array of strings	No	Glob scope. Defaults to **/*.
max_turns	integer	No	Defaults to 8, capped at 16
max_tool_calls	integer	No	Defaults to 40, capped at 120
output_format	string	No	json or markdown
cancel_after_ms	integer	No	Optional total budget

---

Command Execution

run_command

Execute a command in the workspace. This requires approval in normal AI workflows.

Parameters:

Name	Type	Required	Description
command	string	Conditionally	Legacy shell command line
program	string	Conditionally	Executable path/name for structured execution
args	array of strings	No	Structured arguments when using program
shell	boolean	No	Force shell execution when using program
cwd	string	No	Working directory
blocking	boolean	No	Defaults to true
wait_ms_before_async	integer	No	Startup wait when non-blocking

Accepted aliases / alternate casing:

• command: Command, command_line, CommandLine
• program: Program
• args: Args
• shell: Shell
• cwd: Cwd
• blocking: Blocking
• wait_ms_before_async: WaitMsBeforeAsync

Rule: provide either command or program.

Behavior notes:

• If program is used, shell execution defaults to false unless explicitly enabled.
• If command is used, shell execution is enabled.

---

General Notes

Result truncation

Large tool results may be truncated.

• Max size: 50 KB
• Max lines: 2000

When truncation happens, the executor keeps a head/tail summary rather than returning the entire payload.

Path safety

Paths are generally constrained to the current workspace.

• Relative paths are resolved from the workspace root.
• Absolute paths must still resolve inside the workspace when validation is enforced.

Local vs advertised tools

This file documents what zblade can execute locally.

That is not always identical to what every model sees in advertised tool schemas:

• Some compatibility aliases are executor-only.
• Some composite tools are feature-flag and model-family gated for schema exposure.
• Some schema entries may exist before local execution support is complete.

---

Quick Reference

Locally executable non-server-side tools

• read_file
• read_file_range
• write_file
• create_file
• edit_file
• apply_patch
• apply_edit
• delete_file
• move_file
• copy_file
• create_directory
• get_file_info
• list_dir
• list_directory
• get_workspace_structure
• find_files
• find_files_glob
• glob
• grep_search
• rg
• codebase_search
• get_editor_state
• open_file
• goto_line
• get_selection
• replace_selection
• insert_at_cursor
• symbol_search
• symbol_resolve
• symbol_outline
• symbol_graph
• get_project_index_overview
• get_project_index_chunk
• read_many_files
• batch
• codebase_investigator
• run_command