Tool Use & Sandboxing

How AI Coding Agents Interact With Your System — Safely

A large language model, on its own, can only produce text. To become a useful coding assistant, it needs tools — structured interfaces that let it read files, search codebases, run terminal commands, and edit source code. But giving an AI access to your filesystem and shell introduces real risk. The architecture of tool use in agentic systems is fundamentally a trust and safety engineering problem: how do you grant enough capability to be productive while preventing catastrophic mistakes?

This page explores the general design patterns behind tool systems in coding agents — the taxonomy of tools, how they are defined and invoked, permission models that gate dangerous operations, sandboxing techniques that contain blast radius, and strategies for handling the massive outputs that tools can produce.

Tool Execution Flow

Every tool call follows the same lifecycle: the model generates a structured JSON request, the harness checks permissions, the sandbox executes the operation, and the result flows back into the model's context. Click through each stage to see the details.

Step 1 / 5

Click "Next" or "Auto-Play" to walk through the tool execution pipeline.

Tool Taxonomy

Coding agents typically have access to five broad categories of tools, each with different risk profiles. Click any tool category below to explore what it does, why it exists, and what could go wrong.

Select a tool category above to see details.

How Tools Are Defined: JSON Schema

The model does not have hardcoded knowledge of what tools exist. Instead, each tool is described by a schema definition included in the system prompt — a name, a natural-language description, and a formal parameter schema. When the model wants to use a tool, it generates a JSON object that conforms to that schema. The harness parses this output, validates the parameters, and routes the call to the right implementation.

Tool Definition (what the model sees)

{
  "name": "ReadFile",
  "description": "Read contents of a file at the given path",
  "parameters": {
    "type": "object",
    "properties": {
      "file_path": {
        "type": "string",
        "description": "Absolute path to the file"
      },
      "offset": {
        "type": "integer",
        "description": "Line number to start reading from"
      },
      "limit": {
        "type": "integer",
        "description": "Max lines to return"
      }
    },
    "required": ["file_path"]
  }
}

Generated Tool Call (model output)

{
  "tool": "ReadFile",
  "arguments": {
    "file_path": "/src/auth/login.ts",
    "offset": 42,
    "limit": 30
  }
}

The harness validates this JSON against the schema, then executes it.

Try another tool:

Permission Tiers

Not every tool call is equally dangerous. Reading a file is harmless; executing rm -rf / is catastrophic. Agentic systems implement layered permissions to balance autonomy with safety. Some operations auto-execute silently, some require explicit user approval, and some are blocked outright.

Permission Simulator

Choose a tool call to see how the permission system would handle it:

Click a scenario above to simulate the permission check.

Sandboxing Approaches

Even with permissions, you need a containment boundary around command execution. If the model decides to run a shell command, what prevents it from accessing files outside the project, calling the network, or modifying system configuration? Different sandboxing strategies offer different trade-offs between security, performance, and compatibility.

Tool Result Handling

Tool outputs can be enormous — a file might be 5,000 lines, a grep might match hundreds of results, a build command might produce megabytes of logs. Since every token of tool output consumes context window space, agents need strategies to keep results manageable without losing critical information.

Scenario: Reading a Large File

Strategies

Parallel Tool Calls

When the model needs to gather information from multiple independent sources — say, reading three files and running a grep — it can issue those tool calls simultaneously rather than sequentially. This requires the model to reason about dependencies: if reading file B depends on knowing which file to read from the result of grep A, they cannot run in parallel. But if the calls are truly independent, parallelism saves significant wall-clock time.

Sequential time: --

Parallel time: --

Speedup: --

Frequently Asked Questions

Can an AI coding agent accidentally delete important files?

In theory, yes — any tool with write access to the filesystem could cause damage. In practice, well-designed agents implement multiple safeguards: permission tiers that require explicit user approval for destructive operations, sandboxing that restricts filesystem access to the project directory, and pattern-matching rules that flag dangerous commands like rm -rf, git push --force, or anything touching system paths. The key insight is defense in depth — no single layer is relied upon exclusively. Even if the model generates a dangerous command, the permission gate and the sandbox each independently prevent execution.

Why use JSON schema for tool definitions instead of function signatures?

JSON Schema provides several advantages for LLM-based tool calling. First, it is language-agnostic — the schema works regardless of whether the harness is written in TypeScript, Python, or Rust. Second, it supports rich validation: types, required fields, enums, string patterns, and nested objects can all be expressed declaratively. Third, schemas are self-describing — the model can read the schema and understand what parameters are expected without needing examples. Finally, JSON is the format the model already generates naturally, so there is no serialization mismatch between the schema definition and the generated call.

What happens when tool output exceeds the context window?

This is one of the hardest practical challenges in agentic systems. When a tool returns more data than can fit in the remaining context, agents use several strategies: truncation (keeping the first N and last M lines, with a note about what was omitted), pagination (reading a file in chunks using offset and limit parameters), summarization (having the model or a separate summarizer condense the output), and selective retrieval (using grep or search to find only the relevant portions instead of reading the whole file). The choice of strategy depends on the type of output — error messages are best kept verbatim, while large data dumps can often be summarized.

How does sandboxing affect performance?

There is an inherent trade-off between isolation strength and execution speed. Lightweight approaches like OS-level policy profiles (macOS Seatbelt, Linux seccomp) add negligible overhead because they operate at the kernel level — the process runs natively but with restricted syscalls. Container-based isolation (Docker, Podman) adds a small startup cost but near-native runtime performance. Full VM isolation offers the strongest guarantees but introduces noticeable latency for every command due to VM boot time and I/O overhead. Most agentic coding tools choose the lightest viable option: kernel-level restrictions for local use, containers for CI environments, and VMs only for untrusted code execution scenarios.

Can the model decide on its own which tools to call in parallel?

Yes — this is a form of planning that the model performs during generation. When the model recognizes that multiple pieces of information are needed and none depend on each other, it can emit multiple tool calls in a single response turn. The harness then executes all of them concurrently and returns all results together in the next turn. The model must reason correctly about dependencies: if it needs file A's contents to know which function to search for in file B, those calls are sequential. But if it needs to read three independent configuration files, all three can go in parallel. Getting this wrong wastes time (sequential when parallel was possible) or causes errors (parallel when there was a real dependency).