diff --git a/CHANGELOG.md b/CHANGELOG.md
index 839716f3a..842c02545 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -21,6 +21,7 @@ Docs: https://docs.clawd.bot
 - CLI: surface FTS + embedding cache state in `clawdbot memory status`.
 - Plugins: allow optional agent tools with explicit allowlists and add plugin tool authoring guide. https://docs.clawd.bot/plugins/agent-tools
 - Tools: centralize plugin tool policy helpers.
+- Docs: clarify plugin agent tool configuration. https://docs.clawd.bot/plugins/agent-tools
 
 ### Fixes
 - Voice call: include request query in Twilio webhook verification when publicUrl is set. (#864)
diff --git a/docs/plugins/agent-tools.md b/docs/plugins/agent-tools.md
index af74ec90b..71d44d155 100644
--- a/docs/plugins/agent-tools.md
+++ b/docs/plugins/agent-tools.md
@@ -6,8 +6,13 @@ read_when:
 ---
 # Plugin agent tools
 
-Clawdbot plugins can register agent tools (JSON‑schema functions) that appear in the
-agent tool list. Tools can be **required** (always available) or **optional** (opt‑in).
+Clawdbot plugins can register **agent tools** (JSON‑schema functions) that are exposed
+to the LLM during agent runs. Tools can be **required** (always available) or
+**optional** (opt‑in).
+
+Agent tools are configured under `tools` in the main config, or per‑agent under
+`agents.list[].tools`. The allowlist/denylist policy controls which tools the agent
+can call.
 
 ## Basic tool
 
@@ -55,7 +60,7 @@ export default function (api) {
 }
 ```
 
-Enable optional tools in `agents.list[].tools.allow`:
+Enable optional tools in `agents.list[].tools.allow` (or global `tools.allow`):
 
 ```json5
 {
@@ -76,6 +81,11 @@ Enable optional tools in `agents.list[].tools.allow`:
 }
 ```
 
+Other config knobs that affect tool availability:
+- `tools.profile` / `agents.list[].tools.profile` (base allowlist)
+- `tools.byProvider` / `agents.list[].tools.byProvider` (provider‑specific allow/deny)
+- `tools.sandbox.tools.*` (sandbox tool policy when sandboxed)
+
 ## Rules + tips
 
 - Tool names must **not** clash with core tool names; conflicting tools are skipped.