Skip to main content
Glama
software-mansion

Argent

Official
by software-mansion
OverviewSchemaRelated ServersScoreDiscussions
TypeScript
Local

await-ui-element

Wait until a UI element exists, becomes visible, hides, or shows expected text, returning a clear cause if the timeout elapses.

Instructions

Block until a UI element reaches an expected state or a timeout elapses, so you don't have to poll screenshot/describe yourself.

Conditions: exists — the selector matches an element anywhere in the tree. visible — the selector matches an element with a non-zero on-screen frame. hidden — the selector matches nothing, or only a zero-area element (e.g. a spinner that disappeared). text — the first VISIBLE match in reading order (topmost, then leftmost; falling back to the first match overall if none is visible) contains expectedText (case-insensitive substring), or exactly matches it when textMatch is equals. A loose selector can match several elements; only that one is inspected, so if a different match is the one holding the text the wait still reports failure — narrow the selector to target it.

The selector is { text?, identifier?, role? }; every provided field must match. text and role match as case-insensitive substrings of the element's label/value and role; identifier matches exactly (case-insensitive), also accepting the unqualified Android resource-id name ('submit' matches 'com.example.app:id/submit'). It polls the same accessibility / DOM tree as describe (iOS simulator AXRuntime, physical-iOS runner snapshot, Android uiautomator, Chromium CDP, Vega automation toolkit) every pollIntervalMs (default 400ms) until timeoutMs (default 5000ms).

Returns { success: boolean, elapsed: number, note?, cause? } — success=false means the wait ended without the condition holding, which is not always a verdict on the condition: cause says which it was — unmet (the tree was read and the condition was false there), unreadable (no trustworthy read, so nothing was judged) or cancelled — and note describes what was seen. Only unmet licenses rewriting the check. Use this after a tap/navigation to wait for the next screen, or before tapping an element that appears asynchronously.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
udidYesTarget device id from `list-devices` (iOS UDID, Android serial, or Chromium id).
bundleIdNoOptional iOS app bundle id, passed to the describe fallback (see `describe`). Ignored on Android / Chromium, and on physical iOS.
selectorYesElement to match (text / identifier / role).
conditionYesWhat to wait for. `exists`: selector is anywhere in the tree. `visible`: selector is present with a non-zero on-screen frame. `hidden`: selector is absent or zero-area. `text`: the first visible match in reading order (topmost), falling back to the first match overall if none is visible, contains (or, with textMatch `equals`, exactly matches) expectedText — if a loose selector hits several elements, only that one is checked, so narrow it to target the intended element.
textMatchNoFor condition `text`: how expectedText is compared. `contains` (default) is a case-insensitive substring; `equals` is a case-insensitive full-string match.
timeoutMsNoMax time to wait for the condition before giving up (default 5000).
expectedTextNoFor condition `text`: the string the first visible matched element (topmost in reading order; the first match overall if none is visible) must contain (default) or equal — see `textMatch`. Case-insensitive.
pollIntervalMsNoHow often to re-check the tree (default 400).

Schema Changelog

Changes observed during successful MCP inspections. Dates show when Glama detected each change.

  1. Changed1 schema field changedv0.24.0
    • changedInput schema / properties / bundleId / description
      Previous value: -"Optional iOS app bundle id, passed to the describe fallback (see `describe`). Ignored on Android / Chromium."New value: +"Optional iOS app bundle id, passed to the describe fallback (see `describe`). Ignored on Android / Chromium, and on physical iOS."
  2. Changed5 schema fields changedv0.16.0
    • changedInput schema / properties / condition / description
      Previous value: -"What to wait for. `exists`: selector is anywhere in the tree. `visible`: selector is present with a non-zero on-screen frame. `hidden`: selector is absent or zero-area. `text`: the first match in reading order (topmost) contains expectedText — if a loose selector hits several elements, only that topmost one is checked, so narrow it to target the intended element."New value: +"What to wait for. `exists`: selector is anywhere in the tree. `visible`: selector is present with a non-zero on-screen frame. `hidden`: selector is absent or zero-area. `text`: the first visible match in reading order (topmost), falling back to the first match overall if none is visible, contains (or, with textMatch `equals`, exactly matches) expectedText — if a loose selector hits several elements, only that one is checked, so narrow it to target the intended element."
    • changedInput schema / properties / expectedText / description
      Previous value: -"For condition `text`: case-insensitive substring the first matched element (topmost in reading order) must contain."New value: +"For condition `text`: the string the first visible matched element (topmost in reading order; the first match overall if none is visible) must contain (default) or equal — see `textMatch`. Case-insensitive."
    • addedInput schema / properties / selector / additionalProperties
      Added value: +false
    • changedInput schema / properties / selector / properties / identifier / description
      Previous value: -"Case-insensitive substring of the element's identifier (accessibilityIdentifier / resource-id / testid)."New value: +"The element's identifier (accessibilityIdentifier / resource-id / testid), matched case-insensitively as the exact identifier or the unqualified resource-id name ('submit' matches 'com.example.app:id/submit')."
    • addedInput schema / properties / textMatch
      Added value: +{
+  "description": "For condition `text`: how expectedText is compared. `contains` (default) is a case-insensitive substring; `equals` is a case-insensitive full-string match.",
+  "enum": [
+    "contains",
+    "equals"
+  ],
+  "type": "string"
+}
  3. First observedv0.15.0

TDQS

A4.7/5.0
Behavior5/5

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

With no annotations, the description carries the full burden, and it delivers: it explains polling intervals, defaults, return shape, and the crucial nuance that success=false is not always a verdict on the condition, with cause values of unmet, unreadable, and cancelled. It also discloses selector matching pitfalls, reading order, hidden zero-area semantics, and the underlying accessibility/DOM sources. This is exemplary behavioral disclosure.

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?

The description is long but well-structured with headings and front-loaded purpose. Some condition details are repeated from the schema, which adds length, but the additional context about selector resolution, failure causes, and polling justifies most of the content. It is dense but organized enough for an agent to scan.

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?

Given 8 parameters, a nested selector object, multiple conditions, and no output schema or annotations, the description is remarkably complete. It explains the return value shape, failure semantics, when a failure licenses rewriting the check, and even the environmental tree types. There are no critical gaps that would prevent correct use.

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

Parameters5/5

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

Although schema coverage is 100%, the description adds substantial meaning beyond the schema: it explains reading order for visible text matches, the loose-selector trap, the unqualified Android resource-id matching behavior, and the exact meaning of each condition. It clarifies expectedText and textMatch behavior contextually rather than merely restating 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 opens with a specific verb and resource: 'Block until a UI element reaches an expected state or a timeout elapses.' It clearly distinguishes itself from polling screenshot/describe by stating it removes that need, and the conditions section further defines exact behavioral scope. This is much more than a tautology and stands apart from sibling tools like describe and await-screen-idle.

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?

The final sentence gives explicit usage guidance: 'Use this after a tap/navigation to wait for the next screen, or before tapping an element that appears asynchronously.' It also explicitly contrasts with polling screenshot/describe yourself. It does not formally enumerate when not to use it or name all sibling alternatives like await-screen-idle, so it stops short of a 5.

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

Install Server

Other Tools

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/software-mansion/argent'

If you have feedback or need assistance with the MCP directory API, please join our Discord server