[DOCS] Built-in "Edit" tool naming conflict between Agent SDK and API Tool Use guides

Documentation Type

Unclear/confusing documentation

Documentation Location

• https://platform.claude.com/docs/en/agent-sdk/overview - https://platform.claude.com/docs/en/agents-and-tools/tool-use/text-editor-tool

Section/Topic

The "Built-in tools" summary table in the Agent SDK documentation and the "Model compatibility/Use the text editor tool" sections in the Text Editor Tool documentation.

Current Documentation

In Agent SDK Overview:

| Tool | What it does | |------|--------------| | Edit | Make precise edits to existing files |

In Text editor tool (API reference):

"Provide the text editor tool (named str_replace_based_edit_tool) to Claude using the Messages API." "Claude 4.x models: text_editor_20250728"

What's Wrong or Missing?

There is a naming discrepancy that creates friction for developers moving between the direct Messages API and the Agent SDK.

• The Agent SDK documentation uses the simplified name Edit in all code examples and tables (e.g., allowed_tools=["Read", "Edit", "Bash"]).
• The primary tool documentation for the same functionality describes it as str_replace_based_edit_tool (for Claude 4) or str_replace_editor (for Claude 3.7).

A developer following the "Text editor tool" guide while using the Agent SDK might attempt to use the long-form string in their allowed_tools list, which would result in a configuration mismatch or failure, as the SDK expects the abstracted name Edit.

Suggested Improvement

Add a "Note for SDK users" section or a footnote to the Text editor tool page explaining that the Agent SDK simplifies these versioned tool names.

Suggested text for docs/en/agents-and-tools/tool-use/text-editor-tool.md:

Note for Agent SDK Users: If you are using the [Claude Agent SDK](/docs/en/agent-sdk/overview), you should use the simplified name "Edit" in your allowed_tools configuration. The SDK automatically maps this to the correct versioned tool (e.g., str_replace_based_edit_tool) based on the model you are using.

Impact

High - Prevents users from using a feature

Additional Context

• Links to related documentation: This discrepancy is also present in docs/en/agent-sdk/python.md and docs/en/agent-sdk/typescript.md, where the tool is exclusively referred to as Edit.
• Examples from other projects: Most SDKs that wrap complex APIs (like AWS or Stripe) include a "Usage in SDK" callout on the main API feature pages to prevent users from trying to use raw API strings that the SDK has abstracted.