Skip to main content
Glama

Wait for Screen Change

wait_for_change
Read-onlyIdempotent

Wait until part of the screen changes, settles, or shows (or loses) some text, instead of guessing a sleep. Returns the elapsed time, changed regions (screenshot pixels; add origin for desktop), and the final state.

Instructions

Wait until part of the screen changes, settles, or shows (or loses) some text, instead of guessing a sleep. Returns the elapsed time, changed regions (screenshot pixels; add origin for desktop), and the final state.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "target": "<target>"
    },
    "name": "wait_for_change"
  }
}

Input Schema

NameRequiredDescriptionDefault
goneNoMode text: wait until it disappears instead.
keepNoKeep the final screenshot on disk and return its path (default false).
modeNochange (default): return once it differs from the start. settle: once it has been still for settleSec. text: once text appears (OCR, re-read only after a change).
textNoMode text: what to wait for; tolerates OCR misreads.
regexNoMode text: text is a regex.
targetYesWhat to watch: full | monitor:<i> | window:<title> (or exe=/hwnd=) | region:<x>,<y>,<w>,<h>.
backendNowgc: watch a window even when covered (window: targets; 1-2 s per check).
settleSecNoMode settle: seconds of stillness (default 1).
exactTitleNowindow: targets match the whole title only (default false).
intervalMsNoPause between checks in ms (default 250; 1000 with wgc).
timeoutSecNoGive up after this many seconds (default 30; a timeout is a result, not an error).
returnImageNoReturn the final state inline (default true).
pixelThresholdNoMean 0-255 difference for a ~32x32 cell to count as changed (default 12).

Output Schema

NameRequiredDescriptionDefault
modeYes
originYes
outcomeYes
regionsYes
elapsedSecYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed7 schema fields changedv0.51.1
    • addedInput schema / properties / backend
      Added value: +{
      +  "description": "wgc: watch a window even when covered (window: targets; 1-2 s per check).",
      +  "enum": [
      +    "gdigrab",
      +    "wgc"
      +  ],
      +  "type": "string"
      +}
    • addedInput schema / properties / gone
      Added value: +{
      +  "description": "Mode text: wait until it disappears instead.",
      +  "type": "boolean"
      +}
    • changedInput schema / properties / intervalMs / description
      Previous value: -"Pause between checks in ms (default 250)."New value: +"Pause between checks in ms (default 250; 1000 with wgc)."
    • changedInput schema / properties / mode / description
      Previous value: -"change (default): return once it differs from the start. settle: once it has been still for settleSec."New value: +"change (default): return once it differs from the start. settle: once it has been still for settleSec. text: once text appears (OCR, re-read only after a change)."
    • changedInput schema / properties / mode / enum
      Previous value: -[
      -  "change",
      -  "settle"
      -]New value: +[
      +  "change",
      +  "settle",
      +  "text"
      +]
    • addedInput schema / properties / regex
      Added value: +{
      +  "description": "Mode text: text is a regex.",
      +  "type": "boolean"
      +}
    • addedInput schema / properties / text
      Added value: +{
      +  "description": "Mode text: what to wait for; tolerates OCR misreads.",
      +  "maxLength": 500,
      +  "minLength": 1,
      +  "type": "string"
      +}
  2. Changed10 schema fields changedv0.47.0
    • changedInput schema / properties / exactTitle / description
      Previous value: -"For window: targets, match the title exactly (default false)."New value: +"window: targets match the whole title only (default false)."
    • changedInput schema / properties / intervalMs / description
      Previous value: -"Pause between checks in ms (default 250); each check itself takes ~0.2 s."New value: +"Pause between checks in ms (default 250)."
    • changedInput schema / properties / keep / description
      Previous value: -"Keep the final screenshot on disk and return its path (default false: it is only returned inline)."New value: +"Keep the final screenshot on disk and return its path (default false)."
    • changedInput schema / properties / mode / description
      Previous value: -"'change' (default) returns as soon as the target differs from when the call started (a dialog opened, a page responded). 'settle' returns once the target has stopped changing for settleSec (a build finished, a page finished loading)."New value: +"change (default): return once it differs from the start. settle: once it has been still for settleSec."
    • changedInput schema / properties / pixelThreshold / description
      Previous value: -"How different (0-255 mean) a cell of about 32x32 screen pixels must be to count as changed (default 12: catches a changed label or a toast)."New value: +"Mean 0-255 difference for a ~32x32 cell to count as changed (default 12)."
    • changedInput schema / properties / returnImage / description
      Previous value: -"Also return a screenshot of the final state inline (default true)."New value: +"Return the final state inline (default true)."
    • changedInput schema / properties / settleSec / description
      Previous value: -"Mode 'settle': how long the screen must stay still (default 1)."New value: +"Mode settle: seconds of stillness (default 1)."
    • changedInput schema / properties / target / description
      Previous value: -"What to watch: 'full' | 'monitor:<index>' | 'window:<title>' (or window:exe=<app.exe> / window:hwnd=<handle>) | 'region:<x>,<y>,<w>,<h>'."New value: +"What to watch: full | monitor:<i> | window:<title> (or exe=/hwnd=) | region:<x>,<y>,<w>,<h>."
    • changedInput schema / properties / timeoutSec / description
      Previous value: -"Give up after this many seconds (default 30). A timeout is a normal result, not an error."New value: +"Give up after this many seconds (default 30; a timeout is a result, not an error)."
    • changedOutput schema / (root)
      Previous value: -nullNew value: +{
      +  "$schema": "http://json-schema.org/draft-07/schema#",
      +  "additionalProperties": {},
      +  "properties": {
      +    "elapsedSec": {
      +      "type": "number"
      +    },
      +    "mode": {
      +      "type": "string"
      +    },
      +    "origin": {
      +      "additionalProperties": {},
      +      "properties": {
      +        "x": {
      +          "type": "number"
      +        },
      +        "y": {
      +          "type": "number"
      +        }
      +      },
      +      "required": [
      +        "x",
      +        "y"
      +      ],
      +      "type": "object"
      +    },
      +    "outcome": {
      +      "type": "string"
      +    },
      +    "regions": {
      +      "items": {},
      +      "type": "array"
      +    }
      +  },
      +  "required": [
      +    "outcome",
      +    "mode",
      +    "elapsedSec",
      +    "regions",
      +    "origin"
      +  ],
      +  "type": "object"
      +}
  3. Changed2 schema fields changedv0.39.0
    • addedInput schema / properties / keep
      Added value: +{
      +  "description": "Keep the final screenshot on disk and return its path (default false: it is only returned inline).",
      +  "type": "boolean"
      +}
    • changedInput schema / properties / pixelThreshold / description
      Previous value: -"How different an 8 px cell must be to count as changed (default 12)."New value: +"How different (0-255 mean) a cell of about 32x32 screen pixels must be to count as changed (default 12: catches a changed label or a toast)."
  4. First observedv0.32.0

TDQS

A4.1/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds real value beyond that by stating what comes back (elapsed time, changed regions, final state) and noting the desktop `origin` variant, though it omits the notable non-error timeout behavior that only appears in the schema.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

One dense sentence that front-loads the purpose and then summarizes outputs; no filler. The parenthetical about `origin` is the only piece that reads as noise given it is not a declared parameter.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With 13 parameters, full schema descriptions, rich annotations, and an output schema, the description only needs to convey purpose and return shape, which it does. The missing piece is guidance on mode selection trade-offs (e.g. wgc cost, timeout semantics) that would help an agent call it correctly the first time.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% and every parameter carries a description with defaults and bounds, so the baseline is 3. The description adds little parameter meaning and even references an `origin` option that does not exist in the schema, which slightly muddies rather than clarifies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (wait) plus the exact conditions it can wait on (change, settle, text appear/disappear) and the resource (part of the screen). The phrase 'instead of guessing a sleep' frames the tool's role so an agent can immediately tell it apart from screenshot/screen_diff style tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives a clear selection context: use this when you would otherwise sleep-poll, and the mode enum in the schema encodes the three when-to-use cases. It stops short of naming exclusions or pointing to siblings like screen_diff or screenshot for one-shot captures.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.