Tool Use and Actions

Overview

AI coding agents do not write code by magic. They interact with your codebase through a defined set of tools -- structured functions the agent can invoke to read files, make edits, run commands, and search for information.

Understanding these tools is not just academic curiosity. When you know exactly how an agent reads your file, what it sees when it searches, and how it applies edits, you can structure your code to make every tool invocation more effective.

How Tool Use Works

At the LLM level, tools are function calls. The model does not execute anything directly. Instead, it generates a structured request that says "I want to call this tool with these arguments." The agent framework receives that request, executes the actual operation, and sends the result back to the model.

Sequence diagram showing tool execution flow: the LLM sends a Read tool call to the framework, which reads from disk and returns file contents. The LLM reasons, then sends an Edit tool call, which the framework applies. Finally, the LLM sends a Bash tool call to run tests, and the framework returns the test results. The LLM reasons and decides, but the framework executes.

This separation is critical to understand. The LLM is a reasoning engine that decides what to do. The framework is the execution engine that does it. The LLM never touches your files directly.

The Core Tool Set

While different agent platforms name and organize tools differently, most provide the same fundamental capabilities. Here are the core tools that most coding agents share.

Read: Loading Files into Context

The Read tool loads a file's contents into the conversation so the agent can reason about it. This is the most frequently used tool in a typical agent session -- in practice, a large share of tool calls are reads.

Key behaviors of the Read tool:

• Returns the entire file by default (some tools support line ranges)
• Each line is prefixed with its line number, which is essential for the Edit tool
• The full contents go into the context window, consuming tokens proportional to file size
• Reading a file the agent has already read wastes tokens (the same content appears twice in the history)

Why this matters for your codebase: Every file the agent reads costs tokens. A 500-line file costs 3x the tokens of a 150-line file. If the agent only needs one function from that file, the extra lines are pure waste.

Edit: Modifying Existing Code

The Edit tool modifies an existing file by replacing a specific string with a new string. It is a search-and-replace operation, not a line-number-based edit.

Key behaviors of the Edit tool:

• The old_string must exactly match the text in the file, including whitespace and indentation
• If the old string appears multiple times, the edit fails (the match must be unique)
• The agent must have previously read the file to know the exact text to replace
• Failed edits return an error, and the agent must retry with the correct text

This is why consistent formatting matters. If your codebase has inconsistent indentation (tabs vs. spaces, 2-space vs. 4-space), the agent's edits are more likely to fail because the string match will not work. Linters and formatters that enforce consistency directly improve agent reliability.

Write: Creating or Replacing Files

The Write tool creates a new file or completely replaces an existing file's contents. Unlike Edit (which modifies a specific part), Write replaces everything.

Agents use Write for:

• Creating new files that do not exist yet
• Replacing files that need major rewrites (when Edit would require too many changes)
• Generating configuration files, test files, or boilerplate

Bash: Running Commands

The Bash tool executes shell commands and returns the output. This is how agents run tests, check build output, inspect the filesystem, and execute any command-line operation.

Key behaviors of Bash:

• Returns stdout and stderr combined, all of which enters the context window
• Long outputs consume large amounts of tokens (a verbose test suite output can be thousands of tokens)
• Commands have timeouts -- long-running processes may be killed before completion
• The agent can chain commands with && and ;
• Each Bash invocation starts in a fresh shell (environment variables do not persist)

Practical tip: Configure your test runner to produce concise output. Verbose test logs that print every assertion consume agent context without adding value.

Search: Finding Code Across the Codebase

Many agents have dedicated search tools (like grep, ripgrep, or AST-based search) that find patterns across the codebase without reading every file.

Search is the most token-efficient way for agents to navigate code. A search returns just the matching lines and locations, consuming far fewer tokens than reading every file in a directory.

The Tool Call Lifecycle

Every tool call follows a lifecycle with multiple points where things can go right or wrong:

Tool call lifecycle: the agent decides to call a tool, which goes through a permission check (denied returns an error to the agent; allowed proceeds to execution). Execution either succeeds (result returned) or errors (error message returned). The agent processes the result and decides if more work is needed, looping back or responding to the user.

The permission check is an important step. Many agent frameworks ask the user to approve certain actions (especially edits and command execution). This is a safety mechanism, but it also means the agent's flow can be interrupted by permission prompts.

How Tool Choice Affects Quality

The order and selection of tools matters enormously. Compare these two approaches to the same task:

Approach A (Poor tool use):

1. Read a file that might contain the target function
2. It is not there. Read another file
3. Not there either. Read a third file
4. Found it. Make the edit
5. Do not run tests

Approach B (Good tool use):

1. Search for the function name across the codebase
2. Read the specific file where the function lives
3. Read the test file for that function
4. Make the edit
5. Run the relevant tests
6. Confirm tests pass

Approach B uses search before read (saving tokens), reads the test file (understanding expectations), and verifies with tests (catching regressions). The total token cost is lower, and the result is better.

Key insight: Agents that search before they read, read before they edit, and test after they edit tend to produce better results. This is a useful default sequence, and you can encourage it through good code organization and documentation.

What Agents Cannot Do

Understanding tool limitations is as important as understanding capabilities:

• Agents cannot see images in your codebase (diagrams, screenshots) through file reading alone
• Agents cannot interact with GUIs -- they work through text-based tools only
• Agents cannot access external services unless given explicit tools for it (database queries, API calls)
• Agents cannot run indefinitely -- timeouts, token limits, and rate limits all constrain execution
• Agents cannot undo -- there is no built-in rollback. If an edit breaks something, the agent must fix it forward

Summary

Tools are the hands and eyes of an AI coding agent. Understanding how they work reveals actionable ways to make your codebase more agent-friendly:

• Read is the dominant tool: Structure code so agents load less to understand more
• Edit uses exact string matching: Consistent formatting improves edit reliability
• Bash output fills context: Keep test and build output concise
• Search is the most efficient navigator: Consistent naming patterns make search effective
• A useful default sequence is search, read, edit, test: Good code organization encourages this flow
• Tools have limitations: Design workflows with tool constraints in mind

Next, we will explore how agents decide which tool to call and what strategy to follow -- the decision-making process that turns tool capabilities into coherent actions.