fix: validate Cua window discovery filters and guide recovery

plugins/cua-driver/tools.json

@@ -1,21 +1,29 @@
 [
   {
     "name": "list_windows",
-    "description": "List visible application windows with exact pid/window_id and physical bounds. Pick only the user-authorized target.",
+    "description": "Find the authorized application window. If its PID is unknown, call with app only, e.g. {\"app\":\"Brave\",\"on_screen_only\":true}; omit pid or use null, never 0. Use the returned matching pid/window_id for later actions. Empty filtered results are not proof that the app is unavailable; follow lookup.suggested_arguments when present.",
     "inputSchema": {
       "additionalProperties": false,
       "properties": {
         "app": {
-          "description": "Only windows of apps whose name contains this text (case-insensitive), or whose bundle id equals it. Prefer this or `pid` over an unfiltered call, which returns every window on the host.",
-          "type": "string"
+          "description": "Application name substring (case-insensitive). Start with this when the target PID is unknown. app and a non-null pid are combined filters; do not copy the PID of an unrelated foreground app.",
+          "type": [
+            "string",
+            "null"
+          ]
         },
         "on_screen_only": {
           "description": "When true, drop windows that aren't currently on-screen. Default false.",
           "type": "boolean"
         },
         "pid": {
-          "description": "Optional pid filter. When set, only this pid's windows are returned.",
-          "type": "integer"
+          "description": "Known positive Windows process ID from a matching list_windows result. Unknown: omit or null; never 0. With app, both filters must match the same window.",
+          "type": [
+            "integer",
+            "null"
+          ],
+          "minimum": 1,
+          "maximum": 4294967295
         }
       },
       "type": "object",
@@ -43,7 +51,7 @@
           "type": "integer"
         },
         "pid": {
-          "description": "Process ID from `list_apps`.",
+          "description": "Positive process ID returned for the target app by list_windows; never guess or use another app foreground PID.",
           "type": "integer"
         },
         "query": {
@@ -170,7 +178,7 @@
           "type": "boolean"
         },
         "pid": {
-          "description": "Exact process whose window may be observed.",
+          "description": "Positive process ID returned for the target app by list_windows; never guess or use another app foreground PID.",
           "minimum": 1,
           "type": "integer"
         },
@@ -240,7 +248,7 @@
           "type": "string"
         },
         "pid": {
-          "description": "Target process ID for window scope. Optional with element_token (the token carries the pid). Omit with scope=desktop for screen-absolute coordinates from get_desktop_state.",
+          "description": "Positive process ID returned for the target app by list_windows; never guess or use another app foreground PID.",
           "type": "integer"
         },
         "window_id": {
@@ -289,7 +297,7 @@
           "type": "number"
         },
         "pid": {
-          "description": "Target process ID.",
+          "description": "Positive process ID returned for the target app by list_windows; never guess or use another app foreground PID.",
           "type": "integer"
         },
         "to_x": {
@@ -340,7 +348,7 @@
           "type": "string"
         },
         "pid": {
-          "description": "Target process ID.",
+          "description": "Positive process ID returned for the target app by list_windows; never guess or use another app foreground PID.",
           "type": "integer"
         },
         "text": {
@@ -403,7 +411,7 @@
           "type": "array"
         },
         "pid": {
-          "description": "Target process ID.",
+          "description": "Positive process ID returned for the target app by list_windows; never guess or use another app foreground PID.",
           "type": "integer"
         },
         "window_id": {
@@ -451,7 +459,7 @@
           "type": "string"
         },
         "pid": {
-          "description": "Target process ID. Optional with element_token (the token carries the pid).",
+          "description": "Positive process ID returned for the target app by list_windows; never guess or use another app foreground PID.",
           "type": "integer"
         },
         "value": {
@@ -519,7 +527,7 @@
           "type": "string"
         },
         "pid": {
-          "description": "Target process ID for window scope. Optional with element_token (the token carries the pid). Omit with scope=desktop for screen-absolute coordinates from get_desktop_state.",
+          "description": "Positive process ID returned for the target app by list_windows; never guess or use another app foreground PID.",
           "type": "integer"
         },
         "window_id": {
@@ -556,7 +564,8 @@
       "properties": {
         "pid": {
           "type": "integer",
-          "minimum": 1
+          "minimum": 1,
+          "description": "Positive process ID returned for the target app by list_windows; never guess or use another app foreground PID."
         },
         "window_id": {
           "type": "integer",
@@ -612,7 +621,7 @@
           "type": "string"
         },
         "pid": {
-          "description": "Target process ID for window scope. Optional with element_token (the token carries the pid). Omit with scope=desktop for screen-absolute coordinates from get_desktop_state.",
+          "description": "Positive process ID returned for the target app by list_windows; never guess or use another app foreground PID.",
           "type": "integer"
         },
         "window_id": {
@@ -642,4 +651,4 @@
       "idempotentHint": false
     }
   }
-]
+]