qt_wait_for

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

No annotations are provided, so the description carries the full behavioral burden, and it omits the most important trait for a wait tool: what happens on timeout (error vs. returning a negative result), whether the call blocks the UI thread, and whether the operation is purely observational. It does disclose the default timeout of 5000 ms, which is useful, but that is the only behavioral detail.

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

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

The one-line purpose is front-loaded and the arg block is a scannable per-parameter list with no filler. The only structural weakness is that the conditions and their required companion parameters are spread across separate lines rather than grouped, forcing the agent to reconstruct which args pair with which condition.

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

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

An output schema exists, so return-value explanation is rightly omitted, and the condition vocabulary is covered. However, for a 7-parameter tool with zero annotation and zero schema-description coverage, leaving 'instance' undocumented and the timeout/failure contract unstated leaves real gaps for correct invocation.

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

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

Schema description coverage is 0%, so the description must compensate, and it largely does: it documents condition, timeout_ms, object_name, ref, property_name, and value, and crucially enumerates the three legal condition strings that the schema does not constrain with an enum. The gap is that the seventh parameter, 'instance', is never mentioned, and there is no explanation of the ref-vs-object_name distinction beyond their condition pairing.

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

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

States a specific verb and resource ('Wait for a UI state change') and the arg list enumerates the three concrete conditions, so the agent knows exactly what kinds of state it can wait on. It is clearly differentiated from action siblings like qt_click or qt_type, though it doesn't distinguish itself from read-only inspection siblings such as qt_snapshot that could also reveal state.

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

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

Usage is only implicit: the tool is obviously for synchronizing on asynchronous UI changes before inspecting or asserting. There is no explicit 'use this instead of polling / instead of qt_snapshot' guidance, no mention of when a wait is the wrong tool, and no prerequisites about the target instance needing to be selected.

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