diff --git a/docs/docs.json b/docs/docs.json
index 121125c6b98..2ae489a38b0 100644
--- a/docs/docs.json
+++ b/docs/docs.json
@@ -1030,12 +1030,12 @@
                 "pages": [
                   "tools/plugin",
                   "plugins/building-plugins",
-                  "plugins/sdk-migration",
-                  "plugins/architecture",
                   "plugins/community",
                   "plugins/bundles",
                   "plugins/manifest",
                   "plugins/agent-tools",
+                  "plugins/sdk-migration",
+                  "plugins/architecture",
                   "tools/capability-cookbook"
                 ]
               },
@@ -1071,11 +1071,25 @@
                   "tools/exec-approvals",
                   "tools/elevated",
                   "tools/apply-patch",
-                  "tools/web",
-                  "tools/brave-search",
-                  "tools/firecrawl",
-                  "tools/tavily",
-                  "tools/perplexity-search",
+                  {
+                    "group": "Browser",
+                    "pages": [
+                      "tools/browser",
+                      "tools/browser-login",
+                      "tools/browser-linux-troubleshooting",
+                      "tools/browser-wsl2-windows-remote-cdp-troubleshooting"
+                    ]
+                  },
+                  {
+                    "group": "Web and search",
+                    "pages": [
+                      "tools/web",
+                      "tools/brave-search",
+                      "tools/firecrawl",
+                      "tools/tavily",
+                      "tools/perplexity-search"
+                    ]
+                  },
                   "tools/pdf",
                   "tools/diffs",
                   "tools/llm-task",
@@ -1086,15 +1100,6 @@
                   "tools/btw"
                 ]
               },
-              {
-                "group": "Browser",
-                "pages": [
-                  "tools/browser",
-                  "tools/browser-login",
-                  "tools/browser-linux-troubleshooting",
-                  "tools/browser-wsl2-windows-remote-cdp-troubleshooting"
-                ]
-              },
               {
                 "group": "Agent coordination",
                 "pages": [
diff --git a/docs/plugins/agent-tools.md b/docs/plugins/agent-tools.md
index 8740fd51fa4..ea3cd7e231d 100644
--- a/docs/plugins/agent-tools.md
+++ b/docs/plugins/agent-tools.md
@@ -1,16 +1,20 @@
 ---
-summary: "Write agent tools in a plugin (schemas, optional tools, allowlists)"
+summary: "Register custom agent tools in a plugin with schemas, optional opt-in, and allowlists"
 read_when:
   - You want to add a new agent tool in a plugin
   - You need to make a tool opt-in via allowlists
-title: "Plugin Agent Tools"
+title: "Registering Tools in Plugins"
+sidebarTitle: "Registering Tools"
 ---
 
-# Plugin agent tools
+# Registering Tools in Plugins
 
-OpenClaw 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).
+Plugins can register **agent tools** — typed functions that the LLM can call
+during agent runs. Tools can be **required** (always available) or
+**optional** (users opt in via allowlists).
+
+See [Building Plugins](/plugins/building-plugins) for the full plugin creation
+guide. This page focuses on the tool registration API.
 
 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
diff --git a/docs/plugins/architecture.md b/docs/plugins/architecture.md
index 4ffdeb29125..90070dae177 100644
--- a/docs/plugins/architecture.md
+++ b/docs/plugins/architecture.md
@@ -1,17 +1,23 @@
 ---
-summary: "Plugin architecture internals: capability model, ownership, contracts, load pipeline, runtime helpers"
+summary: "Plugin internals: capability model, ownership, contracts, load pipeline, and runtime helpers"
 read_when:
   - Building or debugging native OpenClaw plugins
   - Understanding the plugin capability model or ownership boundaries
   - Working on the plugin load pipeline or registry
   - Implementing provider runtime hooks or channel plugins
-title: "Plugin Architecture"
+title: "Plugin Internals"
+sidebarTitle: "Internals"
 ---
 
-# Plugin Architecture
+# Plugin Internals
 
-This page covers the internal architecture of the OpenClaw plugin system. For
-user-facing setup, discovery, and configuration, see [Plugins](/tools/plugin).
+<Info>
+  This page is for **plugin developers and contributors**. If you just want to
+  install and use plugins, see [Plugins](/tools/plugin). If you want to build
+  a plugin, see [Building Plugins](/plugins/building-plugins).
+</Info>
+
+This page covers the internal architecture of the OpenClaw plugin system.
 
 ## Public capability model
 
diff --git a/docs/tools/capability-cookbook.md b/docs/tools/capability-cookbook.md
index f439c362e89..7a5ab50611a 100644
--- a/docs/tools/capability-cookbook.md
+++ b/docs/tools/capability-cookbook.md
@@ -1,13 +1,20 @@
 ---
-summary: "Cookbook for adding a new shared capability to OpenClaw"
+summary: "Contributor guide for adding a new shared capability to the OpenClaw plugin system"
 read_when:
   - Adding a new core capability and plugin registration surface
   - Deciding whether code belongs in core, a vendor plugin, or a feature plugin
   - Wiring a new runtime helper for channels or tools
-title: "Capability Cookbook"
+title: "Adding Capabilities (Contributor Guide)"
+sidebarTitle: "Adding Capabilities"
 ---
 
-# Capability Cookbook
+# Adding Capabilities
+
+<Info>
+  This is a **contributor guide** for OpenClaw core developers. If you are
+  building an external plugin, see [Building Plugins](/plugins/building-plugins)
+  instead.
+</Info>
 
 Use this when OpenClaw needs a new domain such as image generation, video
 generation, or some future vendor-backed feature area.