[BUG] Documentation not up-to-date

Environment

• Platform (select one):
• [x] Anthropic API
• [ ] AWS Bedrock
• [ ] Google Vertex AI
• [ ] Other: <!-- specify -->
• Claude CLI version: 0.2.67 (Claude Code)
• Operating System: ubuntu-24
• Terminal: Terminal App

Bug Description

using 'claude -p' and Claude runs into permissions issues:

content": [
{
"type": "tool_result",
"content": "Claude requested permissions to use Replace, but you haven't granted it yet.",
"is_error": true,
"tool_use_id": "toolu_014sFdBK2QB3jBFJj5yu1Nmv"
}
]

There is not Replace listed in the documentation...

Steps to Reproduce

Do something that requires Claude to use the Replace tool...

Expected Behavior

The tool is documented so I can properly grant permission.
If the permission is not granted Claude should fail gracefully with an appropriate and understandable message to the user - instead Claude keeps going and just writes what would have been replaced into the conversation. This is another example of Anthropic just ringing the cash register with Claude chewing up tokens doing actions that do not satisfy the prompt ot the user expectation - which, obviously, needed to replace something. As a user how am I supposed to know any such permission is needed if it is not documented.

Actual Behavior

Claude tries to perform the action but fails and just keeps going..

Additional Context

Claude admitted that the Replace command was know to it from the system message.

you gave me this message - Claude requested permissions to use Replace, but you haven't granted it yet. What tool exactly is this?

● Read(CLAUDE.md)…
⎿  Read 98 lines (ctrl+r to expand)

● The Replace tool is used to completely overwrite the contents of a file. It takes two parameters:

• file_path: The absolute path to the file you want to write
• content: The new content to write to the file

This is different from the Edit tool, which makes specific changes within a file. Replace is useful when you need to create a new file or completely rewrite an existing one.

how do I grant permission?

● When you see the permission request in Claude Code, you need to respond with a command that grants the permission:

For example, use:
<command-name>grant-tool-permission</command-name><command-message>grant-tool-permission Replace</command-message>

This grants permission for Claude to use the Replace tool. You can similarly grant permissions for other tools when requested.

no, I mean what is it called? It isn't documented. I know about FileReadTool and FileWriteTool for example, but is it just ReplaceTool?

● I see the confusion. The tool is simply called "Replace", not "ReplaceTool".

In Claude Code, the official tool names are:

• View (for reading files)
• Edit (for making specific changes to files)
• Replace (for completely overwriting files)
• Bash (for running shell commands)
• GlobTool (for finding files by pattern)
• GrepTool (for searching file contents)
• LS (for listing directory contents)

When you need to grant permission, you would use:
<command-name>grant-tool-permission</command-name><command-message>grant-tool-permission Replace</command-message>

/allowed-tools

where did you find that help? it is not on the official docs page at https://docs.anthropic.com/en/docs/agents-and-tools/claude-code/overview

● Fetch(https://docs.anthropic.com/en/docs/agents-and-tools/claude-code/overview)…
  ⎿  Request failed with status code 403

● You're right - I apologize for the confusion. The tool information I provided comes from my understanding of the available tools in this conversation, not from the official documentation. I was looking at the functions available to me in this
environment as shown in my system instructions, not from the public documentation.

The tool names I listed are the ones I can actually invoke in this session (View, Edit, Replace, Bash, GlobTool, GrepTool, LS, etc.). These may differ from what's documented in the official Claude Code documentation.

well, since all the tools do not seem to be documented can you help me by showing all the tools you do have in case there is one or more I need to grant permission for?

● I can show you all the tools I have available in this environment. Here's the complete list:

1. dispatch_agent - Launches a new agent with basic tools for searching/exploration
2. Bash - Executes bash commands in a shell session
3. BatchTool - Runs multiple tool invocations in parallel
4. GlobTool - Finds files matching patterns
5. GrepTool - Searches file contents using regex
6. LS - Lists files and directories
7. View - Reads files from the filesystem
8. Edit - Makes specific changes to files
9. Replace - Completely overwrites files
10. ReadNotebook - Reads Jupyter notebooks
11. NotebookEditCell - Edits cells in Jupyter notebooks
12. WebFetchTool - Fetches and processes content from URLs

These are the tools I can use in this conversation if granted permission. If you need me to use any specific tool that requires permission, you can grant it using the grant-tool-permission command.

There are ohter undocumented tools listed, such as WebFetchTool and I note that the tools LS is shown but in documentation it is listed as LSTool and other tools are not named exaclty the same as the documentation.

Tool | Description | Permission Required
-- | -- | --
AgentTool | Runs a sub-agent to handle complex, multi-step tasks | No
BashTool | Executes shell commands in your environment | Yes
GlobTool | Finds files based on pattern matching | No
GrepTool | Searches for patterns in file contents | No
LSTool | Lists files and directories | No
FileReadTool | Reads the contents of files | No
FileEditTool | Makes targeted edits to specific files | Yes
FileWriteTool | Creates or overwrites files | Yes
NotebookReadTool | Reads and displays Jupyter notebook contents | No
NotebookEditTool | Modifies Jupyter notebook cells | Yes

It seems maybe dispatch_agent (internal) is AgentTool (documentation) - that's even more confusing that Anthropic does not maintain a 1-1 mapping on internal to external tool names which means Claude cannot actually give advice on the topic. You can see that there is a tool (according to Claude) 7. View - Reads files from the filesystem but in the docs it is FileReadTool. So I am still left wondering - how do I enable the Replace tool?

Further - Claude tells me: When you need to grant permission, you would use:
<command-name>grant-tool-permission</command-name><command-message>grant-tool-permission Replace</command-message>

I will also note that just to learn all this from Claude comes at a cost TO ME of 18cents:

Total cost: $0.1830
Total duration (API): 1m 2.6s
Total duration (wall): 32m 34.9s
Total code changes: 0 lines added, 0 lines removed

And to run my prompt only to discover that the 'Replace' tool is not enabled cost me about 30 cents.

Hello Anthropic - this all ADDS UP! The use of the help system and asking Claude itself for clarification of poor documentation should not be a cost to the user. Maybe if poor documentation was a cost to Anthropic and note revenue for Anthropic the documentation would be better? Just sayin....

Interestingly - there's a (very small and hard to notice) hint in the --help:

--allowedTools <tools...> Comma or space-separated list of tool names to allow (e.g. "Bash(git*) Edit Replace")

Here I see Edit and Replace but they are not the same exact name as in the documentation - FileEditTool not Edit in the docs. Are these the same tools? Why does the CLI use different tool names that names that are documented? Why are the tools inside Claude (using /allowedTools) named differently than tool names used from the CLI? All very confusing...

And a last bit of feedback - running: claude --help shows:
claude --help
Usage: claude [options] [command] [prompt]

Claude Code - starts an interactive session by default, use -p/--print for non-interactive output

Arguments:
prompt Your prompt

Options:
-d, --debug Enable debug mode
--verbose Override verbose mode setting from config
-p, --print Print response and exit (useful for pipes)
--output-format <format> Output format (only works with --print): "text" (default), "json" (single result), or "stream-json" (realtime streaming)
--json [Deprecated: Use --output-format json instead] Output JSON in the shape {cost_usd: number, duration_ms: number, duration_api_ms: number, result: string} (only works with --print)
--mcp-debug Enable MCP debug mode (shows MCP server errors)
--dangerously-skip-permissions Bypass all permission checks. Only works in Docker containers with no internet access.
--allowedTools <tools...> Comma or space-separated list of tool names to allow (e.g. "Bash(git*) Edit Replace")
-v, --version output the version number
-h, --help display help for command

Commands:
config Manage configuration (eg. claude config set -g theme dark)
mcp Configure and manage MCP servers
migrate-installer Migrate from global npm installation to local installation
doctor Check the health of your Claude Code auto-updater
update Check for updates and install if available

Running claude --allowedTools Replace doesn't just add the tool to the allowed list - it puts me into a claude session, which is certainly not what the user expects.

And, please improve the --help command itself while you are at it. Good CLI software will provide extended or full help, so --help gets me the list of commands but then for more detail --help allowedTools should get me the actual list of allowed tools. i.e full extended help for the allowedTools command. Really that's something so trivial to implement it's a head scratcher why it isn't already available.