The text edit tool

So far every tool in this module is one you wrote yourself — function, schema, dispatch. Claude also ships with built-in tools where the schema is owned by Anthropic and the model has specialised training for how to use them. The first of those is the text editor tool, which turns Claude into something close to a command-line AI pair programmer. This lesson explains how the built-in tools differ from your custom ones and shows you how to wire the text editor into your conversation loop.

What the text editor tool can do

The text editor tool gives Claude a concrete set of file manipulation operations:

• View a file or directory listing
• View a specific line range of a file
• Replace text in a file — find a string, substitute it
• Create a new file with given content
• Insert text at a specific line number
• Undo the most recent edit

These operations, taken together, are essentially what you'd need to implement a command-line editor. Chaining them is what lets Claude act as a software engineer inside your application — browse a codebase, read a file, modify it, add a test file, run through the results, and roll back if something's wrong.

The built-in-tool contract

Built-in tools split the responsibility differently from custom tools. On your custom tools, you write the schema and the function that does the work. With the text editor tool:

• Claude (Anthropic) owns the schema. You don't write out all the operations and their arguments — Claude already knows them through specialised training.
• You own the implementation. When Claude decides to call "view this file" or "replace this string," you still have to run the actual filesystem operations and return the results.

Think of it this way: Claude knows how to ask for file operations in a standardised way, but your server still has to do the filesystem work and return the results. The tool result loop is identical to custom tools — Claude emits tool_use, you run the operation, you return tool_result — only the schema comes from Claude's side.

The schema stub

You still have to tell the API you're enabling the tool. The declaration is much shorter than a custom schema — just a type string and a name:

def get_text_edit_schema(model):
    if model.startswith("claude-3-7-sonnet"):
        return {
            "type": "text_editor_20250124",
            "name": "str_replace_editor",
        }
    elif model.startswith("claude-3-5-sonnet"):
        return {
            "type": "text_editor_20241022",
            "name": "str_replace_editor",
        }
    # ... extend as new versions release

Claude sees this small declaration and expands it internally into the full tool specification. All you have to do is include the schema stub in your tools=[...] list, exactly like a custom schema.

The type version string is pinned to a specific tool version. New versions of the text editor tool ship with new version strings. When you upgrade to a newer Claude model, check the docs for the corresponding text editor tool version — they're listed on Anthropic's tool-use documentation pages. A helper function like get_text_edit_schema(model) centralises the lookup so you only have to update one place.

Implementing the handlers

Because you still own the implementation, your run_tool function needs branches that actually perform the file operations Claude requests. The shape of tool_input matches the text editor tool's operation schema — a command field identifying which operation (view, create, str_replace, insert, undo_edit), plus operation-specific arguments.

Sketch of what handlers look like:

def run_text_editor_tool(tool_input):
    command = tool_input["command"]
    path = tool_input["path"]

    if command == "view":
        # Read the file and return its content
        with open(path, "r") as f:
            return f.read()

    if command == "create":
        content = tool_input["file_text"]
        with open(path, "w") as f:
            f.write(content)
        return f"Created {path}"

    if command == "str_replace":
        old_str = tool_input["old_str"]
        new_str = tool_input["new_str"]
        # Read, replace, write back
        ...

    # ... and so on for insert and undo_edit

In production you'd add safety: sandboxing the allowed paths, permissioning against a user's workspace, and careful error handling when a file doesn't exist or a replacement is ambiguous. The schema lets Claude request operations; you decide which operations are actually allowed to run.

A practical example

Drop the text editor schema into a conversation and ask:

"Open ./main.py and summarise its contents."

Claude will:

1. Emit a tool_use with command="view" and path="./main.py".
2. Receive back the file contents as a tool_result.
3. Respond with a natural-language summary.

Ask for something more ambitious:

"Open ./main.py and add a function that calculates pi to the 5th digit. Then create ./test.py with a unit test for it."

Claude will:

1. view main.py to see what's already there.
2. str_replace to add the new function while preserving the existing code.
3. create test.py with a pytest-style test for the new function.

Three tool calls, all handled by your run_tool implementation, all chained automatically by the conversation loop you built in the previous lessons.

When to use the text editor tool

You might reasonably wonder why this tool exists when every modern code editor already has an AI assistant. The value lands in specific use cases:

• Programmatic file editing as part of an application, not a human editing session — think batch-fixing a large codebase, automated migration scripts, or generating a project skeleton.
• Environments without a full editor — remote machines, sandboxed execution environments, server-side file manipulation.
• Custom Claude-powered developer tools where you want file editing integrated into your own UI rather than a third-party IDE.

The text editor tool lets you embed much of the functionality of a fancy AI-powered code editor directly inside your own application, with fine-grained control over what Claude can touch, which directories are visible, and how changes are committed back to disk.

One important habit: never run a text editor tool against a path Claude shouldn't be able to touch. Enforce path whitelisting, sandbox the working directory, and audit every change before it hits a real codebase. The tool is powerful, which means it's also exactly as powerful as your handlers make it.