Tool Reference

This page catalogs every tool the Nexgile Code agent can use, organized by tool group. For each tool you’ll find what it does, its key parameters, how approval works, and which modes expose it. For the conceptual overview — groups, mode gating, and the approval flow — see How Tools Work.

Nexgile Code uses native structured tool calling: each tool is presented to the model as a typed function with a JSON schema, and the model returns structured arguments rather than markup embedded in prose. This makes tool calls precise, validated, and — where the provider supports it — parallelizable within a single model turn.

Which modes get which groups

The active mode decides which groups exist for the model at all:

Mode	read	edit	command	mcp
Architect	Yes	Markdown files only	—	Yes
Code	Yes	Yes	Yes	Yes
Ask	Yes	—	—	Yes
Debug	Yes	Yes	Yes	Yes
Spec Bootstrap / Spec Sync	Yes	Spec directories only	Yes	Yes
Orchestrator	—	—	—	—
Tester	Yes	—	Yes	—
Reviewer	Yes	—	Yes	—
Shipper	—	—	Yes	—

Orchestrator has no tool groups — it works entirely through the always-available tools (delegating with new_task or new_parallel_tasks, asking questions, completing). It cannot read, edit, or run anything itself, which is the point: it can only make plans and hand them to modes that can. Specialist modes and custom modes declare their own group lists, optionally with file restrictions on the edit group.

Read group

Tool	Purpose
read_file	Read a file’s contents with line numbers
search_files	Regex search across files with surrounding context
list_files	List directory contents, optionally recursive
codebase_search	Semantic (meaning-based) search over the indexed codebase

Approval: read tools prompt for approval unless Read is auto-approved (alwaysAllowReadOnly). Reads outside the workspace additionally require alwaysAllowReadOnlyOutsideWorkspace. See Auto-Approving Actions.

read_file

Reads one file per call and returns its contents with line numbers. Two modes: slice (default) reads sequential lines with offset/limit — up to 2,000 lines per call by default, with lines longer than 2,000 characters truncated; indentation extracts the complete semantic code block (function, method, class) containing an anchor line, so code is never cut off mid-function. Because tool calling is native, the model typically issues several read_file calls in parallel in a single turn — that’s how multiple files are read in one round trip. Also extracts text from PDF and DOCX files, and returns image files for visual analysis when the active model supports image input.

Key parameters: path (required), mode (slice | indentation), offset, limit, and an indentation object with anchor_line, max_levels, include_siblings, include_header, max_lines.

search_files

Performs a regex search (Rust regex syntax) recursively through a directory and returns each match with surrounding context lines. Best for finding exact strings, patterns, TODO comments, or function definitions when you know roughly what the text looks like.

Key parameters: path (required), regex (required), file_pattern (optional glob such as *.ts).

list_files

Lists files and directories under a path, top-level or recursive. The agent uses it to orient itself in an unfamiliar directory structure.

Key parameters: path (required), recursive (required boolean).

codebase_search

Finds code by meaning rather than exact text, using the embeddings index described in Codebase Indexing & Semantic Search. A query like “user login and password hashing” surfaces the relevant implementation even when none of those words appear literally. Only useful once indexing is enabled and built; queries must be in English.

Key parameters: query (required), path (optional subdirectory to scope the search).

Edit group

Tool	Purpose	Availability
apply_diff	Targeted SEARCH/REPLACE edits	Default
write_to_file	Create a file or fully rewrite one	Default
generate_image	AI image generation/editing	imageGeneration experiment
search_replace	Exact single-occurrence replacement with heavy context	xAI Grok models
apply_patch	Multi-file patch: add, update, move, delete files in one call	OpenAI GPT-5.x / GPT-4.1 and Codex models

apply_diff and write_to_file are the defaults, but the edit toolset is per model, not fixed. Each entry in the model registry may add editors the family was trained on and remove the ones it handles poorly, and the result is intersected with whatever the active mode’s groups already allow. Three shapes ship:

Models	Editors offered
Most models — Claude, Gemini, Mistral, local models, and OpenAI’s o-series, gpt-4o, codex-mini-latest	apply_diff, write_to_file
OpenAI GPT-5.x and GPT-4.1 families, and every Codex / ChatGPT sign-in model	apply_patch only — apply_diff and write_to_file are removed
xAI Grok models	search_replace, write_to_file — apply_diff is removed

The practical consequence: the editors you see in a transcript depend on which model ran it, and a model that never calls apply_diff is not misconfigured. A GPT-5 task rewrites a file through apply_patch; the same task on Claude uses several apply_diff calls. Both are correct.

Approval: every edit renders a diff you approve or deny. With Write auto-approved (alwaysAllowWrite), edits apply automatically after a configurable pause (writeDelayMs, default 1000 ms) that lets diagnostics surface problems. Protected files always prompt unless alwaysAllowWriteProtected is set; writes outside the workspace require alwaysAllowWriteOutsideWorkspace. Every approved edit is captured as a checkpoint.

apply_diff

Applies one or more SEARCH/REPLACE blocks to a file. Each block carries a :start_line: hint and the exact content to find; the replacement lands in place. This makes apply_diff the workhorse for surgical multi-spot edits.

The match has to be exact, but the location is forgiving — which is what makes it survive a file that shifted since it was read:

1. The content at the :start_line: hint is compared first.
2. If that fails, a middle-out search sweeps 40 lines either side of the hint, testing each candidate slice.
3. If that still fails, line-number prefixes are stripped from both the search and replace text and the sweep runs again — this rescues blocks copied out of a numbered file listing.

Comparison normalizes typographic noise (smart quotes and similar characters) before testing, but there is no similarity tolerance to configure: the normalized text must match exactly. When nothing matches, the error reports how close the best candidate came (“62% similar, needs 100%”) along with the text it found, so the next attempt can be corrected rather than guessed. The usual fix is a fresh read_file before retrying.

Key parameters: path (required), diff (required — one or more <<<<<<< SEARCH … ======= … >>>>>>> REPLACE blocks).

write_to_file

Creates a new file or intentionally rewrites an existing one, creating any missing directories along the way. The agent must supply the complete file content — partial content with “rest unchanged” placeholders is forbidden by the tool contract. Preferred for new files; slower and riskier than targeted editors for existing ones.

Key parameters: path (required), content (required, the full file).

search_replace

Replaces exactly one occurrence of old_string with new_string. The contract demands 3–5 lines of context before and after the change point so the target is unambiguous; multiple instances require separate calls.

Key parameters: file_path, old_string, new_string (all required).

apply_patch

Applies a single human-readable patch that can span multiple files: *** Add File: sections create files, *** Delete File: removes them, and *** Update File: (optionally with *** Move to: for renames) patches hunks marked with context ( ), removals (-), and additions (+). Useful when one logical change touches several files at once.

Key parameter: patch (required — the full text from *** Begin Patch to *** End Patch).

Command group

Tool	Purpose
execute_command	Run a terminal command
read_command_output	Fetch persisted output from a long-running or verbose command

execute_command

Runs a CLI command in the integrated terminal, streaming output back into the chat. An optional cwd sets the working directory, and an optional timeout (seconds) is designed for commands that never exit on their own — dev servers, watchers — so the command keeps running in the background while the agent receives the output collected so far.

Key parameters: command (required), cwd (optional), timeout (optional seconds).

Approval: commands prompt with the exact command line unless Execute is auto-approved (alwaysAllowExecute) — and even then only commands passing the allowedCommands/deniedCommands prefix lists run unattended. See Command Guardrails & Limits.

read_command_output

When command output exceeds the inline preview size (configurable: small 5 KB / medium 10 KB / large 20 KB), the full output is persisted to disk and the truncated message names an artifact id like cmd-1706119234567.txt. This tool retrieves that persisted output — either paging through it by byte offset, or filtering lines with a case-insensitive regex/literal search pattern, grep-style. It requires no approval: it only reads output the agent already produced.

Key parameters: artifact_id (required), search (optional filter), offset (optional, default 0), limit (optional, default 40 KB).

MCP group

Tool	Purpose
use_mcp_tool	Invoke a tool on a connected MCP server
access_mcp_resource	Read a resource (data source) exposed by an MCP server

With native tool calling, each enabled tool on every connected server is additionally presented to the model as its own named function (prefixed mcp--<server>--<tool>), so the model sees the server’s real parameter schema. All MCP invocations flow through the same approval path.

Approval: MCP calls show the server, tool name, and arguments. Auto-approval requires both the MCP toggle (alwaysAllowMcp) and the specific tool being on that server’s alwaysAllow list — a deliberate two-key design. See Using MCP Tools.

Key parameters for access_mcp_resource: server_name, uri (both required).

Always available

These tools exist in every mode, including Orchestrator:

Tool	Purpose	Approval
ask_followup_question	Ask you a question with 2–4 clickable suggested answers (question, follow_up — each suggestion may carry a mode to switch to when chosen)	None to ask; with follow-up auto-approve on, the first suggestion is auto-selected after the timeout (default 60 s)
attempt_completion	Present the final result (result) and end the task	None
switch_mode	Request a change to another mode (mode_slug, reason)	Prompt unless alwaysAllowModeSwitch
new_task	Spawn a subtask in a chosen mode (mode, message, todos)	Prompt unless alwaysAllowSubtasks; Workflow Mode delegations are approved automatically
new_parallel_tasks	Delegate a batch of sibling subtasks in one call (tasks — an array of {mode, message, todos?})	One approval covers the whole batch; you see every child before any of them starts
update_todo_list	Replace the task’s todo checklist (todos — markdown checklist with [ ]/[x]/[-])	Always auto-approved
skill	Load a skill by name (skill, args)	Always auto-approved — skills are instructions you installed yourself
run_slash_command	Invoke a slash command (command, args)	Experimental — requires the runSlashCommand experiment; prompts for approval

new_parallel_tasks

Declares a batch of sibling subtasks in a single call instead of one new_task at a time. Its main caller is the Orchestrator in Workflow Mode, handing off verification work such as [tester, reviewer] together.

What it actually does is worth being precise about:

• A batch is capped at 5 children. A larger array is rejected outright rather than trimmed.
• Validation is atomic. Every entry is checked first — object shape, a mode that resolves to a real mode, a non-empty message, and a parseable todos checklist. One bad entry rejects the whole call; nothing is spawned.
• Approval is per batch, not per child. The prompt lists every child’s mode and message, so one decision covers work that would otherwise be several separate approvals.
• The children run one after another, not simultaneously. “Parallel” describes how they are declared and approved — as a set of siblings that share a parent. The batch is queued on the parent, the first child opens immediately, and each remaining sibling starts as the previous one completes. Control returns to the parent after the last child finishes.

Key parameter: tasks (required — an array of {mode, message, todos?}).

Tool aliases

Some models reach for a familiar name for a tool that exists here under a different one. Rather than fail the call, the agent resolves the alias to the real tool and runs it — write_file resolves to write_to_file.

The alias is preserved in the conversation history — the transcript shows the name the model used, while execution follows the canonical tool. You never configure this; it just removes a class of avoidable failures.

Disabling tools

Individual tools can be switched off globally (disabledTools). A disabled tool is dropped from the system prompt so the model never sees it, and rejected at execution time if a model asks for it anyway — belt and braces, so a cached prompt can’t smuggle it back. Use it to take a capability off the table permanently rather than declining it repeatedly.

Experimental tools

These appear only when the matching toggle in Settings → Experimental is on (all are off by default):

• generate_image (edit group, imageGeneration experiment) — generates or edits an image via image-capable models through OpenRouter and saves it into the workspace. Parameters: prompt, path (both required), image (optional input image to transform; PNG/JPG/JPEG/GIF/WEBP).
• run_slash_command (runSlashCommand experiment) — lets the agent invoke your slash commands itself.
• Custom tools (customTools experiment) — TypeScript/JavaScript tool definitions loaded from .nexgile/tools/ in your project and ~/.nexgile/tools/ globally become real callable tools with their own schemas. Treat this as advanced, at-your-own-risk extensibility: the code runs locally with your privileges.

Related

• How Tools Work — groups, gating, and the approval flow
• Auto-Approving Actions — every toggle referenced above
• Command Guardrails & Limits — allow/deny lists and caps
• Using MCP Tools — external tools in practice
• Settings Reference — the toggles in one table