Skip to main content
Glama
mishan

shotbox

by mishan
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

wait_for

Read-only

Pause automation until a GUI window, stable screen, screen-reader announcement, focus change, visual match, or log line appears, instead of fixed sleeps.

Instructions

Wait, instead of sleeping, for: a window (value: its title, exactly or a regex, or app=RE), stable (the screen, or the window, unchanged for value seconds, 0.5, up to 60: after a click, for the repaint), an announcement (value: a regex in what was announced to a screen reader; each announcement is waited for once), focus (value: the name of the node with the keyboard focus, as click takes one), match (value: a PNG, by its path from the allow file's directory, that the screen, or the window, cropped to crop, should look like), change (from how it looked when the wait started), or line (value: a regex found in a line of file, written after the wait starts, or with from_start, anywhere in it: for a program that logs its events, rather than a sleep; a file not there yet is waited for, and one rotated or rewritten is read from the top). match and change say how long they took; line answers with the line. Fails after timeout seconds, saying so.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
cropNoWIDTHxHEIGHT+X+Y, inside what's taken
fileNoline's, by its path from the allow file's directory
fuzzNomatch, change: percent a pixel may differ by (0)
mostNomatch, change: pixels past fuzz allowed (0)
whatYesThe kind of wait
valueNoWhat to wait for, as what says
windowNoA window's title, exactly or a regex matched in full, or app=RE for its app id
sessionYesIts name, from start_session
timeoutNoSeconds before it fails (10)
from_startNoline: anywhere in file

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.7.1

TDQS

A3.9/5.0
Behavior4/5

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

Beyond the readOnlyHint/openWorldHint annotations, it discloses real behavior: failure after timeout, that each announcement is waited for once, that a not-yet-existing file is waited for and a rotated file is read from the top, and what match/change/line return. No annotation contradiction.

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

Conciseness3/5

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

Content is front-loaded with the enumeration, but it is delivered as one sprawling, clause-heavy sentence that is hard to scan. Nearly every clause earns its place informationally, yet the structure hurts readability.

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?

For a 10-parameter tool with no output schema, the description covers the failure mode and the return behavior of the output-producing modes, and schema coverage is complete for parameters. Enough to call the tool correctly, though mode-specific return details are only partially sketched.

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 baseline is 3, but the description meaningfully expands the opaque 'value' parameter by defining what it means for each mode (window title/regex/app=RE, regex of announcement, node name, PNG path, regex in a file line). This adds semantic value the schema alone does not.

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

Purpose4/5

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

The description opens with a specific verb (wait) and enumerates the exact conditions it can wait on (window, stable, announcement, focus, match, change, line), which clearly separates it from a sleep and from other tools. It never explicitly contrasts itself with siblings like screenshot or program_output, but the resource scope is concrete enough for an agent to identify the tool.

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?

Each mode carries an implicit when-to-use cue: stable 'after a click, for the repaint', line 'for a program that logs its events, rather than a sleep', announcement for screen-reader output. It states the alternative to sleeping but gives no guidance on when to prefer a sibling tool instead of waiting.

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