diff --git a/.openclaw-sync/source.json b/.openclaw-sync/source.json
index bd62813ea..4b469b33b 100644
--- a/.openclaw-sync/source.json
+++ b/.openclaw-sync/source.json
@@ -1,5 +1,5 @@
 {
   "repository": "openclaw/openclaw",
-  "sha": "392897304cc57b96c74e52b0457d141332037948",
-  "syncedAt": "2026-05-03T23:23:41.597Z"
+  "sha": "baadd74b6bb515f4a20aadf10ccadbec156e4f28",
+  "syncedAt": "2026-05-03T23:42:43.411Z"
 }
diff --git a/docs/plugins/building-plugins.md b/docs/plugins/building-plugins.md
index 32ff2b425..0cd7b6467 100644
--- a/docs/plugins/building-plugins.md
+++ b/docs/plugins/building-plugins.md
@@ -252,6 +252,11 @@ plugin manifest:
 {
   "contracts": {
     "tools": ["my_tool", "workflow_tool"]
+  },
+  "toolMetadata": {
+    "workflow_tool": {
+      "optional": true
+    }
   }
 }
 ```
@@ -260,6 +265,9 @@ OpenClaw captures and caches the validated descriptor from the registered tool,
 so plugins do not duplicate `description` or schema data in the manifest. The
 manifest contract only declares ownership and discovery; execution still calls
 the live registered tool implementation.
+Set `toolMetadata.<tool>.optional: true` for tools registered with
+`api.registerTool(..., { optional: true })` so OpenClaw can avoid loading that
+plugin runtime until the tool is explicitly allowlisted.
 
 Users enable optional tools in config: