[DOCS] Document the mapping between TUI display labels and canonical tool names (e.g. "Update" → Edit)

Documentation Type

Missing documentation (feature not documented)

Documentation Location

https://code.claude.com/docs/en/tools-reference

Section/Topic

Tools reference — built-in tool names vs. TUI display labels (e.g. "Update" vs Edit)

Current Documentation

The tools table lists every built-in tool by canonical name and states: "The tool names are the exact strings you use in permission rules, subagent tool lists, and hook matchers." The Edit tool is described as "Makes targeted edits to specific files." Nothing on this page (or elsewhere in the docs) mentions that the TUI renders Edit tool calls with the display label "Update(<path>)". The word "Update" does not appear as a tool anywhere in the reference.

What's Wrong or Missing?

The TUI shows friendly display labels that differ from canonical tool names — most notably, Edit renders as "Update(<path>)" in the transcript and in approval cards. Every configuration surface (permission rules, hook matchers, subagent tool lists, --allowedTools/--disallowedTools) requires the canonical names, but the docs never state the mapping. Consequences: (1) users write rules against the label they see (e.g. Update(**/pom.xml)), which silently matches nothing, and debugging is painful because the transcript keeps saying "Update"; (2) users conclude Update and Edit are two different tools — see #25161, where a user reported Claude Code "switching between the Update and Edit tools" and asked to enforce one, closed as not planned because the premise is a rendering artifact; (3) verifying the mapping currently requires inspecting the session JSONL or writing a PostToolUse hook.

Suggested Improvement

Add a "Display label" column (or a short mapping table) to the tools reference covering every tool whose TUI label differs from its canonical name, plus a one-line note that permission rules, hooks, and tool lists must always use the canonical name, never the on-screen label.

Impact

Low - Minor confusion or inconvenience

Additional Context

#25161 — user believed Update and Edit were separate tools. #85648 — desktop app approval cards also render "Update(path)" for Edit calls, so the label spans surfaces. Confirmed via session transcript JSONL that the tool_use block for an "Update(...)" transcript entry is named "Edit".