SCREENCAST-MCP / TOOLS / WATCH
Wait for Screen Change
wait_for_change
Wait until part of the screen changes or settles, instead of guessing a sleep. Returns the elapsed time, changed regions (screenshot pixels; add origin for desktop), and the final state.
watchread-onlyidempotentsince v0.18.0
00:00PARAMETERS
| Name | Type | Description |
|---|---|---|
target required | string | What to watch: full | monitor:<i> | window:<title> (or exe=/hwnd=) | region:<x>,<y>,<w>,<h>. |
exactTitle | boolean | window: targets match the whole title only (default false). |
mode | "change" | "settle" | change (default): return once it differs from the start. settle: once it has been still for settleSec. |
timeoutSec | number | Give up after this many seconds (default 30; a timeout is a result, not an error). > 0, ≤ 600 |
settleSec | number | Mode settle: seconds of stillness (default 1). > 0, ≤ 60 |
intervalMs | integer | Pause between checks in ms (default 250). ≥ 100, ≤ 5000 |
pixelThreshold | number | Mean 0-255 difference for a ~32x32 cell to count as changed (default 12). ≥ 0, ≤ 255 |
returnImage | boolean | Return the final state inline (default true). |
keep | boolean | Keep the final screenshot on disk and return its path (default false). |
00:05A MINIMAL CALL
wait_for_change { "target": "window:Notepad" }The required arguments only, with placeholder values. Everything else takes its default.
00:10WHAT COMES BACK
Structured content (structuredContent), alongside a text summary:
| Field | Type |
|---|---|
outcome always | string |
mode always | string |
elapsedSec always | number |
regions always | any[] |
origin always | object |
origin.x always | number |
origin.y always | number |
00:15SEEN IN