Claude Code's Tool API Details Revealed

Claude Code's Tool API Structure

A Reddit user documented their conversation with Claude Code about its internal tool API. The AI assistant revealed specific details about how it interacts with the environment.

Tool Categories and Functions

File System Tools:

• Read — reads files by absolute path, returns content with line numbers (cat -n style). Supports images, PDFs, Jupyter notebooks.
• Write — overwrites or creates files. Must Read first before Writing to existing files.
• Edit — performs surgical string replacement. Requires the old_string to be unique in the file, otherwise it fails. Must Read first.
• Glob — finds files by pattern (e.g., *.py), sorted by modification time.
• Grep — ripgrep-based content search. Supports regex, file type filters, and context lines.

Execution Tools:

• Bash — runs shell commands with a 2-minute default timeout (up to 10 minutes). Working directory persists between calls, but shell state doesn't carry over (no environment variables, aliases, etc.). Has a run_in_background option.

Web Tools:

• WebFetch — fetches URL content.
• WebSearch — searches the web.

AI Agents:

• Agent — spawns subagents (general-purpose, Explore, Plan, etc.) with their own tool access and context. Can run in background. Returns a single message when done.

Special Tools:

• Skill — invokes named "skills" (slash commands like /commit) that expand into full prompts.
• ToolSearch — fetches schemas for "deferred tools" (tools known by name but can't be called until their schema is fetched).

Key Implementation Details

Tool Call Structure: Claude Code doesn't use special tokens to trigger tools — it's a standard function-calling API. The response includes structured tool call blocks, and results come back as tool result messages.

Tool Call Format: The blocks use XML-like syntax with an antml:function_calls wrapper containing one or more antml:invoke elements with the tool name as an attribute. Each parameter is an antml:parameter element with a name attribute and the value as text content.

Example structure for a Bash call:

• Outer tag: antml:function_calls
• Inner tag: antml:invoke with attribute name="Bash"
• Parameter tag: antml:parameter with name="command" containing the command text

Operational Behaviors

• Linter interactions: When editing files, git hooks or configured "hooks" can run automatically after tool calls and modify files further. The tool result indicates "file was modified by another process," requiring re-reading before editing again.
• Tool call visibility: Every tool call appears in the terminal for user approval (depending on permission mode). Users can deny any tool call.
• Parallel execution: Multiple tool calls can be issued in a single response and execute concurrently, useful for reading several files at once.
• Context management: Long conversations get compressed automatically — earlier messages get summarized to free up context. Memory persistence occurs through a directory structure: /home/tpreal/.claude/projects/...