[DOCS] `--tools` docs omit native-build `Grep`/`Glob` behavior with embedded search

Documentation Type

Missing documentation (feature not documented)

Documentation Location

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

Section/Topic

The --tools CLI flag, especially how Grep and Glob behave on native macOS/Linux builds that use embedded search

Current Documentation

The CLI reference currently says:

--tools — Restrict which built-in tools Claude can use. Use "" to disable all, "default" for all, or tool names like "Bash,Edit,Read"

The tools reference also says:

Claude Code has access to a set of built-in tools that help it understand and modify your codebase. The tool names are the exact strings you use in permission rules, subagent tool lists, and hook matchers.

and it still lists:

Glob — Finds files based on pattern matching. Grep — Searches for patterns in file contents.

What's Wrong or Missing?

As of v2.1.162, explicitly listing Grep and Glob in --tools on native builds with embedded search now provides the dedicated search tools. Before this change, those names were silently ignored in that configuration.

The current docs do not explain that platform-specific --tools behavior at all.

That creates one root-cause documentation gap:

A. --tools does not document the native-build exception

Readers are told that --tools accepts built-in tool names, but they are not told that native macOS/Linux builds with embedded search treat explicit Grep/Glob entries specially.

B. Tool naming guidance leaves the embedded-search case ambiguous

Because the docs say Grep and Glob are tool names while other release notes describe native builds as using embedded search through Bash, users cannot tell from the reference docs whether --tools "...,Grep,Glob" is meaningful, ignored, or mapped differently on native builds.

Suggested Improvement

Update the --tools documentation to call out the embedded-search behavior explicitly.

Before:

--tools — Restrict which built-in tools Claude can use. Use "" to disable all, "default" for all, or tool names like "Bash,Edit,Read"

After:

--tools — Restrict which built-in tools Claude can use. Use "" to disable all, "default" for all, or tool names like "Bash,Edit,Read". On native macOS/Linux builds that use embedded search, explicitly listing Grep and Glob also enables the dedicated search tools; these names are not ignored.

If there are limits or differences by install type (for example Windows or npm-installed builds), document those in the same note so readers know when this behavior applies.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

| Page | Line(s) | Context |
|------|---------|---------|
| https://code.claude.com/docs/en/cli-reference | 113 | --tools describes generic tool-name syntax but not the native-build embedded-search behavior for Grep/Glob |
| https://code.claude.com/docs/en/tools-reference | 9, 26-27 | Tool naming guidance and the Glob/Grep entries do not explain how explicit --tools values interact with embedded search on native builds |

Total scope: 2 pages affected

Version context: The v2.1.162 changelog says: --tools: explicitly listing Grep/Glob now provides the dedicated search tools on native builds with embedded search (previously these names were silently ignored). This is especially important because the docs already discuss Grep and Glob as tool names, while earlier release notes also described native macOS/Linux builds as using embedded search.