Core Concepts6 min read

How Tools Work

Tool groups, mode gating, and the approval flow

Tools are the agent’s hands. Nexgile Code never edits a file or runs a command “directly” — every action on your system is a discrete, typed tool call that you can see, approve, or deny. Understanding the tool system explains both what the agent can do in any given mode and where your control points are.

Tool groups

Tools are organized into four groups, plus a set that is always available:

Group	Tools	What they do
read	`read_file`, `search_files`, `list_files`, `codebase_search`	Read file contents (with line ranges), search by regex, list directories, and — with indexing enabled — search the codebase by meaning.
edit	`apply_diff`, `write_to_file`, `generate_image`*, plus per-model editors†	Modify files. `apply_diff` applies targeted SEARCH/REPLACE blocks; `write_to_file` writes complete files.
command	`execute_command`, `read_command_output`	Run terminal commands (with optional working directory and timeout) and fetch persisted output from long-running commands by artifact id.
mcp	`use_mcp_tool`, `access_mcp_resource`	Call tools and read resources from connected MCP servers.

* generate_image only appears when the image-generation experiment is enabled in Settings → Experimental.

† The edit toolset varies by model. Most models get apply_diff and write_to_file. OpenAI’s GPT-5.x and GPT-4.1 families and the Codex models instead get apply_patch alone — both defaults are removed for them — and xAI Grok models get search_replace and write_to_file. Each family edits more reliably with the convention it was trained on. See the Tool Reference.

Always available in every mode: ask_followup_question (ask you a question with clickable suggested answers), attempt_completion (finish the task), switch_mode (request a mode change — you approve), new_task (spawn a subtask), new_parallel_tasks (delegate a batch of subtasks in one approval), update_todo_list (maintain the task’s plan), skill (load a skill package on demand), and run_slash_command (invoke a slash command — experimental, off by default).

Modes gate the groups

The active mode decides which groups are exposed to the model at all. Code mode has all four; Ask mode has only read and mcp; Orchestrator has none (it works purely through the always-available delegation tools). A mode can also attach a file restriction to its edit group — Architect’s edit tools accept only .md paths, and the Spec modes only their documentation subtrees. Calls outside the restriction fail as tool errors naming the allowed pattern; they are not silently ignored.

This gating happens at the tool-definition level: in Ask mode the model doesn’t refuse to edit — it has no edit tools to call. That is why picking the right mode is a hard guarantee, not a suggestion.

Here is the full map for the ten core modes:

Mode	read	edit	command	mcp
🏗️ Architect	✓	`.md` files only	—	✓
💻 Code	✓	✓	✓	✓
❓ Ask	✓	—	—	✓
🪲 Debug	✓	✓	✓	✓
📚 Spec Bootstrap	✓	spec subtrees only	✓	✓
🔄 Spec Sync	✓	spec subtrees only	✓	✓
🪃 Orchestrator	—	—	—	—
🔬 Tester	✓	—	✓	—
🔍 Reviewer	✓	—	✓	—
🚀 Shipper	—	—	✓	—

Specialist modes and custom modes declare their groups the same way — a custom mode’s YAML groups: list is exactly this mechanism in your hands.

The approval flow

Each consequential tool call pauses the task and renders an approval card in chat:

File edits show a full diff of the proposed change. Approve with Save (or Save All for a batch), or Deny. Review the diff like a micro code review — it is exactly what will land on disk, and once saved it is also captured as a checkpoint.
Commands show the exact command line. Approve with Run or Deny. Output streams back into the chat as the command executes; very long output spills to disk and the agent retrieves it with read_command_output.
Reads, MCP calls, mode switches, subtasks each show what is being requested — file path, server and tool name with arguments, target mode — with the same Approve/Deny choice.

Two refinements make the flow more useful than a plain yes/no:

Feedback with your decision. You can attach text when approving or denying. A denial with “wrong file — the config lives in config/app.ts” turns a dead end into a course correction.
Denial is informative, not fatal. The agent receives a structured denied result and re-plans. Deny an edit and it will propose a different approach — or ask you what you’d prefer.

When approval prompts become friction rather than signal, move trusted categories to auto-approval — most people start with read-only operations and keep edits and commands manual. Command execution additionally respects the allow/deny lists described in Command Guardrails & Limits. Two housekeeping tools — update_todo_list and skill — are always auto-approved, since they change nothing outside the conversation.

Native structured tool calling

Nexgile Code uses the model’s native tool-calling interface: every tool is defined by a typed schema (name, parameters, constraints), and the model emits structured calls against those schemas rather than describing actions in prose that must be parsed. You’ll notice the benefits indirectly — malformed calls are rejected with precise errors the model can correct (a missing required parameter comes straight back as “missing value for required parameter”), arguments arrive intact, and approval cards can render exactly what was requested.

A brief tour of the tools you’ll see most

Tool	What the approval card shows	Notes
`read_file`	The file path (and line range, if partial)	Reads one file per call — the agent issues several reads in parallel when it needs more. Returns numbered lines; supports PDF and DOCX text extraction, and images where the model accepts them.
`apply_diff`	A diff of targeted SEARCH/REPLACE changes	The workhorse editor for surgical, multi-spot changes in one file.
`write_to_file`	A diff against the current file (or new-file content)	Used for new files and full rewrites.
`execute_command`	The exact command line	Runs in your workspace; obeys allow/deny lists and the execution timeout.
`codebase_search`	The semantic query	Only useful once the index is built.
`use_mcp_tool`	Server name, tool name, JSON arguments	Per-server allowlists can auto-approve specific tools.
`new_task`	The child task’s mode and instructions	Runs a subtask; results return to the parent when it finishes.
`new_parallel_tasks`	Every child in the batch, with its mode and instructions	Up to five siblings approved together, then run in sequence.
`attempt_completion`	The final result summary	Ends the task — the only thing that does.

Full parameter-level detail for every tool lives in the Tool Reference.

Errors and retries

Tool failures are returned to the agent as structured error results — The tool execution failed, plus specifics — and the loop continues:

Edits that don’t match (the file changed since it was read, or the SEARCH block was wrong) fail with similarity details; the agent re-reads the file and retries with corrected content. The environment snapshot also flags files modified outside the agent since its last read, prompting a re-read before the failure happens.
New problems caused by an edit — compile errors, lint warnings — are diffed from the editor’s diagnostics and reported to the agent immediately after the save, so it fixes its own breakage in the next step.
Blocked paths return explicit access-denied results: .nexgileignored files, and protected files which always require your explicit approval regardless of auto-approve settings.
Circuit breakers: after three consecutive tool failures the task stops and asks you for guidance rather than burning budget on the same broken approach; identical repeated calls trip the same breaker. The threshold is consecutiveMistakeLimit, set per API profile (0 disables it). Per-task cost and request caps are separate hard stops — see guardrails.