From Pure Text to Taking Action

An AI without tools can only output text. It can tell you “you should modify line 42”, but it cannot actually do it. Tools change everything — they transform me from someone who “only talks” into someone who “can do things”.

In Claude Code, tools are my hands and feet. Through tools, I can read files, edit code, run commands, and search codebases — these are the capabilities that make an AI coding assistant truly useful.

How Tool Calling Works: Function Calling

Tool use (also called function calling) is the standard mechanism for AI to interact with the external world. The core idea is simple:

1. AI is told (via System Prompt) which tools are available, including each tool’s JSON Schema
2. When generating a response, AI can choose to “call a tool” instead of outputting text
3. The client executes the tool call and returns the result to AI
4. AI sees the result and continues reasoning and responding

At the API level, a tool call looks like this:

// AI's response contains a tool_use block
{
"role": "assistant",
"content": [
  {
    "type": "text",
    "text": "Let me read this file to understand its structure."
  },
  {
    "type": "tool_use",
    "id": "toolu_01A2B3C4",
    "name": "Read",
    "input": {
      "file_path": "/src/utils/auth.ts",
      "limit": 100
    }
  }
]
}

// Client executes and returns the result as tool_result
{
"role": "user",
"content": [
  {
    "type": "tool_result",
    "tool_use_id": "toolu_01A2B3C4",
    "content": "1  import { verify } from 'jsonwebtoken';\n2  ..."
  }
]
}

Claude Code’s Built-in Tools

Claude Code provides a complete toolkit covering core software development operations:

File Operations

Read — Read file contents. Supports line ranges, images, and PDFs.

{
"name": "Read",
"input": {
  "file_path": "/absolute/path/to/file.ts",
  "offset": 50,    // start from line 50
  "limit": 100     // read 100 lines
}
}

Write — Create or completely rewrite a file. Used only when creating new files or doing full rewrites.

{
"name": "Write",
"input": {
  "file_path": "/absolute/path/to/new-file.ts",
  "content": "export function hello() {\n  return 'world';\n}"
}
}

Edit — Make precise edits to specific parts of a file. This is the most commonly used file modification tool — it works by exactly matching old_string and replacing it with new_string.

{
"name": "Edit",
"input": {
  "file_path": "/src/utils/auth.ts",
  "old_string": "const EXPIRY = 24 * 60 * 60;",
  "new_string": "const EXPIRY = 1 * 60 * 60;  // 1 hour"
}
}

Search Tools

Grep — Content search powered by ripgrep. Supports regex, file filtering, and context lines.

{
"name": "Grep",
"input": {
  "pattern": "function validateToken",
  "path": "/src",
  "glob": "*.ts",
  "output_mode": "content",
  "-C": 3
}
}

Glob — Find files by name pattern.

{
"name": "Glob",
"input": {
  "pattern": "src/**/*.test.ts",
  "path": "/project"
}
}

Command Execution

Bash — Execute shell commands. This is the most powerful and most dangerous tool — through it I can run anything: git, npm, compilers, test frameworks, etc.

{
"name": "Bash",
"input": {
  "command": "cd /project && npm run test -- --watch=false",
  "description": "Run project tests",
  "timeout": 30000
}
}

Advanced Tools

Agent (Sub-agent) — Spawns an independent child Claude to handle complex subtasks. The sub-agent has its own context window and does not consume the main conversation’s context.

{
"name": "Agent",
"input": {
  "prompt": "Find all usages of deprecated APIs in the project, list file names and line numbers"
}
}

WebSearch — Search the web for up-to-date information.

WebFetch — Fetch content from a specific URL.

Tool Definitions: JSON Schema

Every tool has a JSON Schema definition that tells me the tool’s name, description, parameter structure, and type constraints. These definitions are provided in the System Prompt and are the only way I “know” how to use a tool.

// Simplified tool definition example
{
"name": "Edit",
"description": "Performs exact string replacements in files...",
"parameters": {
  "type": "object",
  "required": ["file_path", "old_string", "new_string"],
  "properties": {
    "file_path": {
      "type": "string",
      "description": "The absolute path to the file to modify"
    },
    "old_string": {
      "type": "string",
      "description": "The text to replace"
    },
    "new_string": {
      "type": "string",
      "description": "The text to replace it with"
    },
    "replace_all": {
      "type": "boolean",
      "default": false,
      "description": "Replace all occurrences"
    }
  }
}
}

Every tool I see follows this format. I do not need to know the implementation details — only the interface. This is just like using an API: you do not need to know the server internals, just the request format and response format.

The Decision Process for Tool Calls

When I receive a message, I need to decide: respond with text directly, or call a tool?

This decision is based on several factors:

// My internal decision logic (simplified)

User says: "What's wrong with this function?"

Thought process:
1. User is asking about code
2. I need to see the code first
3. User didn't paste code → I need to read the file
4. Decision: call Read tool

User says: "Make this function async"

Thought process:
1. User wants code modification
2. I need to see current code (if not already visible)
3. Then make precise edit → use Edit tool
4. After editing, may need to verify → use Bash to run tests
5. Decision: Read → Edit → Bash (chained calls)

User says: "What's new in React 18?"

Thought process:
1. This is a knowledge question
2. My training data covers this
3. No external tools needed
4. Decision: respond with text directly

The Tool Result Feedback Loop

Tool calling is not a one-shot operation — it is a loop. After each tool returns a result, I reassess the situation and decide the next action:

A typical “fix a bug” task might involve 5-10 tool calls:

1. Grep — search for relevant code
2. Read — read the found file
3. Read — read related type definitions
4. Edit — fix the problematic code
5. Bash — run tests to verify the fix
6. Read — tests fail, read test file to understand expected behavior
7. Edit — adjust the fix
8. Bash — rerun tests, they pass

Each step’s result is injected into context, influencing my next decision. This is the core pattern of an AI Agent: Think, Act, Observe, Repeat.

Tools transform AI from an “advisor” into a “doer”. I no longer just tell you what to do — I can do it for you. But every tool call is a decision, and good decisions require good context.