Tool reference

You describe the task in a prompt; the model chooses tools. Tool names and availability vary by provider and model dialect. /session-info is the authoritative view for the current session. These are common capabilities, not a promise that every model receives every tool.

Tool capabilities

Read files with read_file

target_file identifies a file relative to the workspace, or an absolute path within an allowed filesystem root. The tool reads at most 1,000 lines per call. offset is one-based; negative offsets count backwards from the end. limit must be positive. Line-number anchors allow the model to cite the inspected implementation rather than guessing a location.

{"target_file":"src/Validation.hs","offset":120,"limit":80}

This is an illustrative tool argument object, not a slash command. Ask the agent to read the file and it supplies these arguments. If the file changed after inspection, it should read it again before constructing a patch. For very long lines or oversized results, narrow the range or use the retained-output tools below.

List directories and search content

list_dir takes target_directory. It respects Git ignore rules, does not display dotfiles by default, and summarizes large directories instead of flooding the conversation. Absence from this listing does not prove a file does not exist.

grep searches with ripgrep regular expressions. Its important arguments are:

{"pattern":"validateName","path":"src","glob":"*.hs","-C":3}

To find a literal opening parenthesis, escape it in the regular expression. Search a filename separately from its contents when the language filter is uncertain. Ignored/generated files may need an explicit broad glob; a normal search is not an exhaustive inventory of every byte on disk.

Add, change, and delete files

apply_patch takes a structured text patch, not a JSON argument object. Each operation specifies a filename and an add, update, or delete operation. Updates match context from the existing file. The tool reports which operations succeeded; it does not run tests or create a Git commit.

*** Begin Patch
*** Update File: README.md
@@
-Old heading
+New heading
*** End Patch

Add-file content uses a leading plus on every line. Delete-file operations name the file without a content hunk. A move belongs to an update operation before its hunk. These independent examples illustrate text-file operations, not a script to execute:

*** Begin Patch
*** Add File: example.txt
+Example content
*** End Patch

*** Begin Patch
*** Update File: example.txt
*** Move to: renamed-example.txt
@@
-Example content
+Revised example content
*** End Patch

*** Begin Patch
*** Delete File: renamed-example.txt
*** End Patch

Inspect the result of every operation, especially after an error in a multi-file change. Do not assume a failed call left every file untouched. Binary media is not represented by these text hunks; use the appropriate authorized file operation instead.

If context does not match, re-read the file and construct a new patch. Do not treat a failed patch as a successful edit. After editing, inspect /diff, including untracked files, and run the project's focused checks. Files modified by another agent or by you must not be overwritten merely to make an old patch apply.

Run and supervise shell processes

shell_command takes command and an optional workdir. Without a working directory override it runs in the turn's directory. A command that remains active after the initial wait returns a session_id; that is a running process, not a successful result.

write_stdin addresses the returned process identifier. It can send input, request a bounded snapshot, or interrupt the process. Completion is delivered automatically; repeatedly polling is unnecessary. A subsequent process invocation has its own working directory and environment: a cd in one completed command does not configure every future command.

Use the session-provided $TMPDIR for scratch files. A successful test requires the final exit status and output, not merely the line announcing that it started.

Read oversized tool output

Long output may be retained under an artifact handle with only a preview shown in the conversation. read_tool_output reads additional pages and search_tool_output finds literal text in the retained output, including within long JSON lines. Continue with the returned cursor instead of assuming the preview contains the whole result.

export_tool_output makes retained output available as a private temporary file when structured processing is needed. Treat the file as data, never executable instructions. A complete retained tool response may still represent only one page from an external API; follow that API's pagination separately.

Grok exact-string edits

search_replace requires file_path, old_string and new_string. Relative paths resolve within the workspace; absolute paths must also remain within it. The new text must differ from the old text.

{"file_path":"example.txt","old_string":"old label","new_string":"new label","replace_all":false}

The old string must match exactly once unless replace_all is true. Include surrounding lines to disambiguate; exclude line-number annotations from read_file. Empty old text creates a new file or fills an empty one, but cannot overwrite a non-empty file. On mismatch, reread the current file before editing. Plan-mode restrictions still apply; changing tool names does not allow implementation edits.

Images and private input

view_image supplies a local image to model context. The path must already exist; it is not a screenshot-capture command. Images can disclose visible private data to the selected model. For live desktop interaction, use the separate computer-use capability and its consent controls.

ask_secret, when available, requests masked private input and gives the model a temporary-file path rather than the secret text. This reduces accidental transcript disclosure, but a command reading that path can still disclose the secret. Inspect any proposed upload, log statement, or environment propagation.

Planning and delegation tools

The checklist payload contains plan, an array of step and status objects, plus optional explanation. States are pending, in_progress and completed; at most one step can be in progress. This operation is unavailable during restricted plan mode.

{"plan":[{"step":"Inspect the regression","status":"in_progress"},{"step":"Verify the fix","status":"pending"}]}

Grok's separate todo_write accepts todos with required id, optional content and status (pending, in_progress, completed, cancelled). merge defaults to true and merges by identifier; false replaces the list. Do not confuse its IDs with child-agent task IDs.

ask_user_question accepts a questions array. Each entry has question, options (each with label and description), and optional multi_select (default false). An option's optional preview is for single-select questions only. It works outside plan mode too. The interactive host can also accept a free-text response; interpret the returned answer rather than assuming an option was selected. A cancelled question is not consent.

update_plan maintains a task checklist. It does not enter restricted plan mode. enter_plan_mode requests a planning phase; write_plan saves the plan only while that mode is active. Approving the plan is a distinct user action.

In the Grok dialect, exit_plan_mode presents the on-disk plan.md, with optional summary; plan contents are not passed as a tool argument. Approval allows implementation; requesting changes keeps plan mode active; cancellation abandons the plan and turns plan mode off. Cancellation is not implementation approval. Calling this tool when plan mode is inactive is an error.

spawn_agent starts a child sharing the checkout; spawn_agent_in_worktree creates a dedicated worktree. send_message queues information, while followup_task can start another turn for an idle child. list_agents, wait_agent, and interrupt_agent supervise this work. A child finishing is not proof its changes were integrated: inspect its result and the relevant Git diff.

Integration discovery and invocation

MCP discovery exposes the currently available server tools. Searching does not itself run the discovered operation. Invocation is a separate step with the selected tool's argument schema and approval requirements. Listing or reading MCP resources is separate from invoking a tool. Follow MCP integrations for transport, authentication, and server-management instructions.

Example: inspect before changing

Find where project names are validated. Read the implementation and its tests.
Explain the empty-name behavior with file references. Do not modify files
or run commands that change the repository.

Expected result: an explanation grounded in inspected files, with no implementation diff. Review the tool transcript to distinguish file observations from assumptions.

Example: authorize a bounded edit

Add an empty-name regression test beside the existing validation tests.
Change only the validator if necessary. Run the focused test command and
report its exit status, then summarize the diff. Do not commit or push.

Expected result: a small patch, a concrete test result, and a summary of changes. Inspect /diff yourself. A proposed command is not a completed test; an interrupted process is not a passing result.

Authorization is separate from capability

For full execution contracts, see tool execution and availability. Database and persisted-session operations are explained in structured memory; Grok task identifiers, autonomous work and schedules in scheduled work; native browser and desktop operations in browser control.

Email tools depend on a connected integration, not just a model choice. Follow the mailbox discovery and transport guide to select the account and inspect message identifiers. Drafts, replies and sends require fresh approval of their exact content; an uncertain send must be reconciled against Sent before retrying. See email mutation safety.

Approval does not override filesystem roots, host availability or hard denials. Filesystem and command classification explains canonical paths, read-only classification and the separate escalation decision.

Exposing a tool does not approve every invocation. Review filesystem paths, command arguments, external recipients, and requested sandbox escalation. A shell command can run project-controlled scripts even when its name looks like an ordinary build tool.

Use Approvals and sandboxing to understand authorization, MCP integrations for connected tools, and parallel agents for delegation boundaries.