[DOCS] Inconsistent Edit vs Write tool usage in Agent SDK examples

Documentation Type

Unclear/confusing documentation

Documentation Location

• https://platform.claude.com/docs/en/agent-sdk/overview - https://platform.claude.com/docs/en/agent-sdk/python - https://platform.claude.com/docs/en/agent-sdk/quickstart - https://platform.claude.com/docs/en/agent-sdk/skills - https://platform.claude.com/docs/en/agent-sdk/sessions

Section/Topic

The allowed_tools / allowedTools arrays in code examples across Agent SDK documentation.

Current Documentation

Examples show inconsistent tool selection for file operations:

overview.md (line 21) - Bug fixing task uses Edit:

async for message in query(
    prompt="Find and fix the bug in auth.py",
    options=ClaudeAgentOptions(allowed_tools=["Read", "Edit", "Bash"])
):

quickstart.md - All examples consistently use Edit:

allowed_tools=["Read", "Edit", "Glob"],  # Tools Claude can use

python.md (line 651) - Feature addition uses Write instead of Edit:

async for message in query(
    prompt="Add a new feature following project conventions",
    options=ClaudeAgentOptions(
        setting_sources=["project"],
        allowed_tools=["Read", "Write", "Edit"]  # Includes both
    )
):

python.md (lines 1929, 2021, 2090) - Multiple examples use Write without Edit:

allowed_tools=["Read", "Write", "Bash"],

skills.md (line 48) - Uses Write without Edit:

allowed_tools=["Skill", "Read", "Write", "Bash"]  # Enable Skill tool

What's Wrong or Missing?

The documentation shows three different patterns without explaining when to use which:

| Pattern | Files | Guidance Provided |
|---------|-------|-------------------|
| Edit only | overview.md, quickstart.md | None |
| Write only | python.md (advanced examples), skills.md | None |
| Both Edit and Write | python.md, sessions.md | None |

This creates confusion because:

1. Edit is more efficient for modifications - The Edit tool performs surgical string replacements, using fewer tokens than Write (which replaces entire files)

1. Different tools for different operations - Edit modifies existing files; Write creates or overwrites files. The docs don't explain when each is appropriate.

1. Examples don't match their tasks:

• "Add a new feature following project conventions" (python.md:651) likely involves modifying existing code, but uses Write
• "Find and fix the bug in auth.py" (overview.md:21) correctly uses Edit

1. Users copying examples get inconsistent guidance - Depending on which doc they read first, they'll adopt different patterns without understanding why.

Suggested Improvement

Add a brief explanation near the first allowed_tools example (in overview.md or quickstart.md):

### Choosing file tools

| Tool | Use When | Token Efficiency |
|------|----------|------------------|
| `Read` | Reading file contents | - |
| `Edit` | Modifying existing files (preferred for code changes) | High |
| `Write` | Creating new files or complete rewrites | Lower |

For agents that modify existing code, prefer `Edit` over `Write`. Include both when the agent may need to create new files AND modify existing ones.

Then standardize examples:

• Modification tasks (bug fixes, refactoring, adding features to existing code): Use Edit
• Creation tasks (scaffolding, generating new files): Use Write
• Mixed tasks (general development): Use both Edit and Write

Example fix for python.md line 651:

# Before (unclear):
allowed_tools=["Read", "Write", "Edit"]

# After (with comment explaining why both):
allowed_tools=["Read", "Edit", "Write"]  # Edit for modifications, Write for new files

Impact

High - Prevents users from using a feature

Additional Context

Affected files (platform-claude mirror)

| File | Lines | Current Pattern | Suggested Fix |
|------|-------|-----------------|---------------|
| agent-sdk/overview.md | 21, 33 | ["Read", "Edit", "Bash"] | ✓ Correct for bug-fix task |
| agent-sdk/quickstart.md | 137, 161, 243, 250, 261, 269, 281, 288 | ["Read", "Edit", "Glob"] variants | ✓ Correct |
| agent-sdk/python.md | 414, 651 | ["Read", "Write", "Edit"] | Add comment explaining why both |
| agent-sdk/python.md | 1929, 2021, 2090 | ["Read", "Write", "Bash"] | ✓ Correct for file creation tasks |
| agent-sdk/python.md | 2049 | ["Write", "Bash"] | ✓ Correct for file creation |
| agent-sdk/skills.md | 48, 68 | ["Skill", "Read", "Write", "Bash"] | Consider adding Edit for modification tasks |
| agent-sdk/sessions.md | 102, 121 | ["Read", "Edit", "Write", "Glob", "Grep", "Bash"] | Add comment explaining comprehensive toolset |

Summary of findings

After investigation, many examples ARE correctly matched to their tasks:

• File creation tasks correctly use Write
• Bug fixing/modification tasks correctly use Edit

However, the documentation lacks guidance explaining why different examples use different tools. Adding a brief explanation would help users understand the distinction and choose appropriately for their use cases.

Mirror locations:

• platform-claude/docs/en/agent-sdk/overview.md
• platform-claude/docs/en/agent-sdk/python.md
• platform-claude/docs/en/agent-sdk/quickstart.md
• platform-claude/docs/en/agent-sdk/skills.md
• platform-claude/docs/en/agent-sdk/sessions.md

Reference: Claude Code tool documentation distinguishes Edit (surgical modifications) from Write (file creation/overwrite).