docs: clarify browser wait guidance

CHANGELOG.md

@@ -7,6 +7,7 @@
 - UI: add optional `ui.seamColor` accent to tint the Talk Mode side bubble (macOS/iOS/Android).
 
 ### Fixes
+- Docs/agent tools: clarify that browser `wait` should be avoided by default and used only in exceptional cases.
 - macOS: Voice Wake now fully tears down the Speech pipeline when disabled (cancel pending restarts, drop stale callbacks) to avoid high CPU in the background.
 - macOS menu: add a Talk Mode action alongside the Open Dashboard/Chat/Canvas entries.
 - macOS Debug: hide “Restart Gateway” when the app won’t start a local gateway (remote mode / attach-only).

docs/browser.md

@@ -193,6 +193,7 @@ Notes:
 - The arm default timeout is **2 minutes** (clamped to max 2 minutes); pass `timeoutMs` if you need shorter.
 - `snapshot` defaults to `ai`; `aria` returns an accessibility tree for debugging.
 - `click`/`type` require `ref` from `snapshot --format ai`; use `evaluate` for rare CSS selector one-offs.
+- Avoid `wait` by default; use it only in exceptional cases when there is no reliable UI state to wait on.
 
 ## Security & privacy notes
 

docs/tools.md

@@ -51,6 +51,7 @@ Notes:
 - Uses `browser.controlUrl` unless `controlUrl` is passed explicitly.
 - `snapshot` defaults to `ai`; use `aria` for the accessibility tree.
 - `act` requires `ref` from `snapshot --format ai`; use `evaluate` for rare CSS selector needs.
+- Avoid `act` → `wait` by default; use it only in exceptional cases (no reliable UI state to wait on).
 
 ### `clawdis_canvas`
 Drive the node Canvas (present, eval, snapshot, A2UI).

src/agents/clawdis-tools.ts

@@ -506,7 +506,7 @@ function createBrowserTool(): AnyAgentTool {
     label: "Clawdis Browser",
     name: "clawdis_browser",
     description:
-      "Control clawd's dedicated browser (status/start/stop/tabs/open/snapshot/screenshot/actions). Use snapshot+act for UI automation.",
+      "Control clawd's dedicated browser (status/start/stop/tabs/open/snapshot/screenshot/actions). Use snapshot+act for UI automation. Avoid act:wait by default; use only in exceptional cases when no reliable UI state exists.",
     parameters: BrowserToolSchema,
     execute: async (_toolCallId, args) => {
       const params = args as Record<string, unknown>;