Skip to main content
Glama
fixed-width

glass

by fixed-width
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Rust

glass_wait_for_region

Read-only

Wait until a pixel region changes or matches a saved baseline, returning match status, change percentage, and bounds. Use it to confirm the UI reached an approved visual state without vision tokens.

Instructions

Wait for pixel transition completion: block until a visual region changes (diverges from a reference) or matches (converges to a saved baseline), then return text metrics (no image unless include_image:true). until: "changes" (default) or "matches" (needs baseline); optional window-relative region; mode perceptual|exact with threshold/tolerance. Returns {matched,changed_pct,bbox,elapsed_ms}. Use "matches" to confirm the UI reached an approved design without spending vision tokens. This verifies pixels, not semantic state or subsequent stability; use glass_wait_for_element for accessible conditions/values and glass_wait_stable when animation completion means visual quiescence.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
modeNo"perceptual" (default) or "exact".
untilNo"changes" (default; diverge from reference) or "matches" (converge to baseline).
ignoreNoWindow-relative rectangles to exclude from the comparison. Use for perpetually animating content — a blinking text caret, a clock, a spinner — which otherwise keeps `changed_pct` permanently non-zero. `changed_pct` is measured over the pixels that remain. Combines with `region`: rects are always window-relative and are intersected with it. A rect that falls partially or entirely outside the compared area — the frame, or the `region` sub-rectangle when one is set — is silently clamped or dropped, masking less than requested or nothing at all; the excluded count is reported as `ignored_pixels`, so a smaller-than- expected value flags a misplaced rect.
regionNoWindow-relative sub-rectangle to watch; omit for the whole window.
baselineNoSaved baseline name to compare against; omit to use the frame at call start.
thresholdNoPerceptual sensitivity (default 0.1; smaller = stricter).
toleranceNoExact per-channel tolerance (default 0).
window_idNoCapture/observe this window (id from `glass_list_windows`) instead of the active one, without changing which window subsequent ops target. Omit for the active window.
timeout_msNoGive up after this long (default 10000ms); returns `{matched:false}`.
interval_msNoPoll interval (default 100ms).
include_imageNoOn match, also return the watched region as an image (default false).

Schema Changelog

Changes observed during successful MCP inspections.

  1. Addedv1.2.0
  2. Removedv1.1.0
  3. Addedv1.0.3

TDQS

A4.9/5.0
Behavior5/5

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

With readOnlyHint=true already present, the description adds meaningful behavioral context: blocking semantics, default until='changes', matches requiring a baseline, no image unless include_image:true, and the important caveat that this verifies pixels, not semantic state or subsequent stability. It goes beyond annotations and does not contradict them.

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

Conciseness5/5

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

Dense but efficient: the first sentence establishes the blocking behavior and return shape, later sentences cover parameter modes, the primary use case, and the critical exclusion from semantic/stability checks. Every sentence earns its place with no filler.

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

Completeness5/5

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

Despite 11 parameters and no output schema, the description covers the essential output structure, key parameter relationships, the main use case, and the alternatives. The remaining parameters (timeout_ms, interval_ms, ignore, window_id) are fully described in the 100%-coverage schema, so nothing critical is missing.

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

Parameters4/5

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

Schema coverage is 100%, so the schema carries the parameter details; the description still adds cross-parameter relationships not obvious from the schema alone — 'matches' needs a baseline, 'mode' pairs with threshold/tolerance, and include_image gates image output. This is useful but not a full re-derivation of the schema.

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?

The description names a specific verb ('wait'), resource ('visual region'), and the two conditions (change or match) with return value details. It also explicitly distinguishes itself from glass_wait_for_element and glass_wait_stable, so an agent can tell them apart without opening schemas.

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

Usage Guidelines5/5

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

It gives explicit when-to-use guidance ('Use matches to confirm the UI reached an approved design without spending vision tokens') and explicit when-not-to-use guidance with named alternatives ('use glass_wait_for_element for accessible conditions/values and glass_wait_stable when animation completion means visual quiescence').

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

Deploy Server

Other Tools