ref~/zaguan-blade/TOOL_CALLS.mdreference

$cat TOOL_CALLS.md

Updated 2026-06-26

Tool calls,wired into your prompts.

Reference for the tool calls that Zaguán Blade's local executor supports. Add these to your Local AI system prompts for file operations, search, editor control, code intelligence, and command execution.

NOTEServer-side tools such as ask_followup_question, attempt_completion, new_task, generate_image, and todo_write are handled by Zaguán Coder Daemon and are not executed locally. This reference covers the local executor.

Scope Limits Editor Context File Read File Write & Edit Filesystem Directory & Search Code Intelligence Composite Project Index Command

01 // Scope

Server-Side Tools

These are handled by Zaguán Coder Daemon and should not be executed by Blade's local executor:

ask_followup_questionattempt_completionnew_taskgenerate_imagetodo_write

If Blade receives one of these for local execution, it reports a protocol error.

02 // Limits

Tool Result Limits

Local tool output is truncated for large results before it is sent back to the model:

50KBMax size

2000Max lines

Truncation keeps a head and tail preview. read_many_files, grep_search, and several index tools also return their own count, truncation, health, or timing metadata.

03 // Editor Context

Editor Context Tools

get_editor_stateEDITORRECOMMENDED

Returns current editor context: active file, open files, active tab index, cursor position, and selection range when available.

Parameters

None

open_fileCONTROL

Request that the UI open a file.

Parameters

Name	Type	Description
`path`	required string	Workspace path
`line`	optional integer	Optional target line
`column`	optional integer	Optional target column

goto_lineCONTROL

Request that the UI navigate to a line in the active file.

Parameters

Name	Type	Description
`line`	required integer
`column`	optional integer

get_selectionSELECTION

Returns current selection metadata from editor state when available.

Parameters

None

replace_selectionEDIT

Request replacement of the current editor selection.

Parameters

Name	Type	Description
`text`	required string

insert_at_cursorEDIT

Request insertion at the current editor cursor.

Parameters

Name	Type	Description
`text`	required string

04 // File Read

File Read Tools

read_fileREAD

Reads a full file.

Parameters

Name	Type	Description
`path`	required string	`file_path`, `filepath`, `filename`

read_file_rangeREAD

Reads a 1-indexed line range with optional surrounding context.

Parameters

Name	Type	Description
`path`	required string	aliases: `file_path`, `filepath`, `filename`
`start_line`	optional integer	Defaults to `1`
`end_line`	optional integer	Defaults to end of file
`context_lines`	optional integer	Defaults to `0`

read_many_filesREAD

Reads many files matched by glob patterns and returns JSON with per-file content and summary metadata.

Parameters

Name	Type	Description
`paths`	required string[]	aliases: `globs`, `patterns`; single aliases: `path`, `pattern`, `glob`
`exclude`	optional string[]	alias: `excludes`
`max_files`	optional integer	default `100`, cap `500`
`max_bytes_per_file`	optional integer	cap `512 KB`
`include_line_numbers`	optional boolean	defaults to `true`

05 // File Write & Edit

File Write and Edit Tools

Writes and edits create history snapshots and update Blade's uncommitted-change tracking when executed inside the app.

write_fileWRITE

Writes content to a file, creating parent directories when needed.

Aliases: write_file_validated, create_file, write_to_file

Parameters

Name	Type	Description
`path`	required string	`file_path`, `filepath`, `filename`
`content`	required string	`contents`, `text`, `data`

edit_fileEDITLEGACY

Legacy single search/replace edit.

Parameters

Name	Type	Description
`path`	required string	`file_path`, `filepath`, `filename`
`old_content`	required string	`old`, `from`
`new_content`	required string	`new`, `to`

apply_patchEDITRECOMMENDED

Preferred exact search/replace edit tool.

Aliases: apply_edit, apply_patch_validated, replace_file_content, multi_replace_file_content

Single-Patch Parameters

Name	Type	Description
`path`	required string	`file_path`, `filepath`, `filename`
`old_text`	required string	`old_content`, `old`, `from`
`new_text`	required string	`new_content`, `new`, `to`
`start_line`	optional integer	Optional disambiguation hint
`end_line`	optional integer	Optional disambiguation hint

Multi-Patch Parameters

Name	Type	Description
`path`	required string	Target file
`patches`	required array	Atomic list of `{ old_text, new_text, start_line?, end_line? }`

Behavior

Matching is exact.
Ambiguous matches fail.
Multi-patch mode is atomic: if one patch fails, no changes are written.

ℹ️

Semantic Patch Mode: apply_patch also accepts a structured semantic_patch object, or patch object, handled by the semantic patch applier. This can update a primary file and additional generated changes atomically through the language service.

06 // Filesystem

Filesystem Tools

create_directoryCREATE

Creates a directory and missing parents.

Parameters

Name	Type	Description
`path`	required string

delete_fileDELETEDELETE

Deletes a file. Deletes a directory only when recursive: true.

Parameters

Name	Type	Description
`path`	required string
`recursive`	optional boolean

move_fileMOVE

Moves or renames a file.

Parameters

Name	Type	Description
`source`	required string
`destination`	required string

copy_fileCOPY

Copies a file or recursively copies a directory.

Parameters

Name	Type	Description
`source`	required string
`destination`	required string

get_file_infoINFO

Returns JSON metadata: path, size, is_directory, is_file, modified timestamp, and readonly flag.

Parameters

Name	Type	Description
`path`	required string

07 // Directory & Search

Directory and Search Tools

list_dirDIRECTORY

Lists immediate directory contents as JSON.

Aliases: list_directory

Parameters

Name	Type	Description
`path`	optional string	Defaults to `.`

get_workspace_structurePROJECT

Returns a compact tree-like directory view.

Parameters

Name	Type	Description
`path`	optional string	aliases: `dir`, `directory`; defaults to `.`
`depth`	optional integer	default `2`
`limit`	optional integer	default `50`, cap `200`

Behavior

Hidden files and directories are skipped.
Heavy/generated directories such as node_modules, .git, target, dist, and .zblade are skipped.
Gitignored paths are filtered unless project settings allow them.

find_filesSEARCH

Finds files by substring match on entry name.

Parameters

Name	Type	Description
`pattern`	required string
`path`	optional string
`max_depth`	optional integer

find_files_globSEARCH

Finds files with a glob pattern.

Aliases: glob

Parameters

Name	Type	Description
`pattern`	required string	`glob`
`path`	optional string	Base path
`case_sensitive`	optional boolean	Defaults to `false`

grep_searchCONTENT

Searches file contents with a regular expression.

Aliases: rg

Parameters

Name	Type	Description
`pattern`	required string	aliases: `query`; regular expression
`path`	optional string	Defaults to `.`
`include_dependencies`	optional boolean	Include directories such as `node_modules` and `vendor`
`timeout_ms`	optional integer	default `8000`, min `500`, max `30000` when timeout enforcement is enabled
`max_results`	optional integer	alias: `limit`; capped at `20`

codebase_searchCONTENT

Legacy regex search that returns matching lines with nearby context.

Parameters

Name	Type	Description
`query`	required string	Regular expression
`file_pattern`	optional string	Comma-separated filename patterns
`max_results`	optional integer	Defaults to `50`

08 // Code Intelligence

Code Intelligence Tools

fast_contextCONTEXTRECOMMENDED

Plans broad or uncertain code tasks and returns targeted context, ranked files, symbol and semantic-anchor metadata, related files, index health, language-support metadata, a compact index schema summary, confidence, suggested ranges, and next steps.

Parameters

Name	Type	Description
`query`	required string
`queries`	optional string[]
`intent`	optional string
`max_results`	optional integer
`include_tests`	optional boolean
`include_docs`	optional boolean
`include_memory`	optional boolean
`include_project_index_min`	optional boolean

symbol_searchSYMBOLS

Searches indexed symbols by name or qualified name. Results include code definitions plus partial scanner symbols such as CSS selectors/custom properties, markup class/id selectors, and JSON/YAML/TOML config key paths.

Parameters

Name	Type	Description
`query`	required string
`path`	optional string	`file`, `file_path`
`file_pattern`	optional string	comma-separated file path glob or substring filter; alias `path_pattern`
`name_pattern`	optional string	comma-separated symbol-name glob or substring filter
`qualified_name_pattern`	optional string	comma-separated qualified-name glob or substring filter; alias `qualified_pattern`
`kind`	optional string	`symbol_type`
`limit`	optional integer	cap `100`
`offset`	optional integer	zero-based pagination offset; cap `1000`
`include_connected`	optional boolean	compact one-hop connected-symbol preview for returned results; use `symbol_references` for one-hop expansion or `symbol_trace` for bounded multi-hop traversal

ℹ️

Responses include _meta.language_support, _meta.search_health, _meta.index_health, _meta.filters, and pagination fields such as _meta.offset, _meta.limit, _meta.has_more, and _meta.total_lower_bound. Empty results should only be treated as trustworthy when language support says the relevant file type is supported and the index is fresh enough for the task. Pagination totals are lower-bound counts over the bounded candidate set, not an expensive exact workspace-wide total.

semantic_anchor_searchANCHORS

Searches indexed semantic anchors such as command names, event names, route-like strings, config keys, translation keys/text, and CSS/theme tokens. Use this for literals and anchors when structural symbol support is absent, shallow, or too narrow for the question.

Parameters

Name	Type	Description
`query`	required string
`path`	optional string	`file`, `file_path`
`limit`	optional integer	cap `100`

symbol_resolveRESOLVE

Resolves a symbol by stable ID or by name within a file.

Parameters

Name	Type	Description
`symbol_id`	optional string	`id`
`path`	optional string	`file`, `file_path`
`qualified_name`	optional string
`name`	optional string

symbol_outlineOUTLINE

Returns a compact symbol inventory and optional hierarchy for one file. Unsupported files return explicit diagnostics instead of silently implying that no symbols exist. Partial scanner languages report shallow support in _meta.language_support.

Parameters

Name	Type	Description
`path`	required string	`file`, `file_path`
`max_symbols`	optional integer	`limit`; default `120`, cap `300`
`include_outline`	optional boolean	defaults to `false`; returns compact nodes only
`max_outline_nodes`	optional integer	`outline_limit`; default `120`, cap `500`
`max_outline_depth`	optional integer	`outline_depth`; default `4`, cap `12`
`include_docstrings`	optional boolean	`include_docs`; defaults to `false`; docstrings are truncated when included

ℹ️

Response metadata includes _meta.language_support, _meta.line_count when the file index has stored line-count metadata, plus truncation fields such as _meta.symbols_truncated and _meta.outline_truncated.

symbol_relatedRELATED

Returns symbols related to a seed symbol. Results can include structural graph relationships, same-module/module-import context, and bounded lexical-similarity fallbacks. Each related item includes evidence; lexical-similarity results are labeled as structural: false and confidence: heuristic, so they should be treated as navigation hints rather than graph truth.

Parameters

Name	Type	Description
symbol_id` / `id	optional string
path` / `file` / `file_path	optional string
`qualified_name`	optional string
`name`	optional string
`limit`	optional integer

symbol_referencesREFERENCES

Finds semantic usages of one symbol. Use after symbol_search or symbol_resolve for where-used, callers, references, or impact questions.

Parameters

Name	Type	Description
symbol_id` / `id	optional string
path` / `file` / `file_path	optional string
`qualified_name`	optional string
`name`	optional string
`relationship`	optional string
`relationships`	optional string[]
`limit`	optional integer
`max_symbols`	optional integer

ℹ️

Relationship types include call, import, export, extends, implements, and contains.

symbol_graphGRAPH

Returns one-hop incoming and outgoing graph edges for one symbol.

Parameters

Name	Type	Description
symbol_id` / `id	optional string
path` / `file` / `file_path	optional string
`qualified_name`	optional string
`name`	optional string
`relationship`	optional string
`relationship_type`	optional string
`kind`	optional string
`limit`	optional integer

symbol_traceTRACE

Traces bounded multi-hop incoming and/or outgoing symbol relationships from one seed symbol. This is a structural index traversal, not a type-aware call graph. Responses include visited symbols, edges, hop depth, truncation status, and unresolved edge counts.

Parameters

Name	Type	Description
symbol_id` / `id	optional string
path` / `file` / `file_path	optional string
`qualified_name`	optional string
`name`	optional string
`direction`	optional string	`incoming`, `outgoing`, or `both`; defaults to `both`
`relationship`	optional string
`relationships`	optional string[]

symbol_schemaSCHEMA

Returns compact Symbols Index coverage and schema counts. Use this before trusting broad searches, investigating empty search results, or deciding whether a language/file type has enough indexed coverage.

Parameters

Name	Type	Description
path` / `file` / `file_path	optional string
symbol_id` / `id	optional string
`qualified_name`	optional string
`name`	optional string
`limit`	optional integer
`max_symbols`	optional integer

ℹ️

Response includes indexed file counts by extension, language, and support level; symbol counts by type; relationship integrity stats including unresolved targets; semantic anchor counts by kind; _meta.index_health; and _meta.language_support. When scoped with path, responses include root-vs-scoped totals under schema.scope and _meta.scope.

edit_impactIMPACT

Analyzes likely impact before editing a file or symbol. Returns impacted files, likely tests, reference counts, risk, confidence, and suggested read ranges.

Parameters

Name	Type	Description
path` / `file` / `file_path	optional string
symbol_id` / `id	optional string
`qualified_name`	optional string
`name`	optional string
`limit`	optional integer
`max_symbols`	optional integer

09 // Composite

Composite Tools

batchCOMPOSITERECOMMENDED

Executes multiple read-only tool calls and returns ordered all-settled results.

Parameters

Name	Type	Description
`calls`	required array	Each item contains `tool` or `name`, plus `arguments` or `args`
`fail_fast`	optional boolean	Defaults to `false`
`ordered`	optional boolean	Defaults to `true`

ℹ️

Allowed tools in batch are read-only only, including file reads, search, workspace structure, code-intelligence tools, project-index fallback tools, and codebase_investigator. run_command, nested batch, and mutation tools are rejected.

codebase_investigatorCOMPOSITE

Runs a bounded read-only investigation and returns structured findings with evidence references.

Parameters

Name	Type	Description
`objective`	required string
`scope`	optional string[]
`max_turns`	optional integer
`max_tool_calls`	optional integer
`output_format`	optional string
`cancel_after_ms`	optional integer

10 // Project Index

Project Index Fallback Tools

get_project_index_overviewINDEX

Returns a bounded overview of .zblade/context/project_index.md.

Parameters

Name	Type	Description
`path`	optional string
`max_chars`	optional integer	default `6000`, cap `12000`

get_project_index_chunkINDEX

Returns a character window from .zblade/context/project_index.md.

Parameters

Name	Type	Description
`path`	optional string
`offset`	optional integer	default `0`
`max_chars`	optional integer	default `4000`, cap `8000`

11 // Command

Command Tool

run_commandTERMINALRECOMMENDED

Executes a shell command or structured program invocation inside the workspace after approval. This is intercepted by the workflow layer, not dispatched through tools.rs.

Parameters

Name	Type	Description
`command`	optional string	aliases: `Command`, `command_line`, `CommandLine`; uses shell mode
`program`	optional string	aliases: `Program`; structured non-shell mode
`args`	optional string[]	aliases: `Args`; used with `program`
`shell`	optional boolean	aliases: `Shell`; defaults to `false` for `program`, `true` for `command`
`cwd`	optional string	aliases: `Cwd`; must resolve inside the workspace
`blocking`	optional boolean	aliases: `Blocking`; defaults to `true`
`background`	optional boolean	alias: `Background`; model-facing alias for `blocking:false`; default `false`
`wait_ms`	optional integer	aliases: `wait_ms_before_async`, `WaitMsBeforeAsync`; clamped `250..30000`; defaults to `10000` when backgrounding

command_sessionTERMINAL

Interacts with a background command started by run_command(background: true): poll for new output (default), write to its stdin, send Ctrl-C, or force-kill it. Non-gated inline tool — no approval is needed because the underlying command was approved when it started.

Parameters

Name	Type	Description
`session_id`	required string	the `session_id` returned by a backgrounded `run_command`
`input`	optional string	bytes written to the process stdin; empty (default) = poll only; the ETX byte (`U+0003`) sends Ctrl-C, and the literal spellings `\x03`, `\u0003`, and `^C` are normalized to it
`kill`	optional boolean	force-kill the process, then return its final output; default `false`
`wait_ms`	optional integer	how long to wait for new output before returning; default `3000`, clamped `250..30000`

Behavior

Polls return only the output delta since the last poll, ANSI-stripped, with wall time and run/exit status. Returns early as soon as any new output arrives or the process exits.
A stdin write to a process that already exited is not an error: the tool falls through to a poll and reports the exit and final tail instead.
Unknown session IDs return an error (sessions may have been evicted or reaped — see the run_command background notes).