diff --git a/docs/tools/shell.md b/docs/tools/shell.md
index 34fd7c8490..f31f571eca 100644
--- a/docs/tools/shell.md
+++ b/docs/tools/shell.md
@@ -120,6 +120,14 @@ tools to detect if they are being run from within the Gemini CLI.
 
 ## Command restrictions
 
+<!-- prettier-ignore -->
+> [!WARNING]
+> The `tools.core` setting is an **allowlist for _all_ built-in
+> tools**, not just shell commands. When you set `tools.core` to any value,
+> _only_ the tools explicitly listed will be enabled. This includes all built-in
+> tools like `read_file`, `write_file`, `glob`, `grep_search`, `list_directory`,
+> `replace`, etc.
+
 You can restrict the commands that can be executed by the `run_shell_command`
 tool by using the `tools.core` and `tools.exclude` settings in your
 configuration file.