Skip to main content
Glama
Sign In
@mgcrea/mcp-ios-simulator

@mgcrea/mcp-ios-simulator

by mgcrea
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

iOS Simulator: Wait For Element

ios_simulator_wait_for_element
Read-only

Pauses until a specified UI element appears or disappears in an iOS Simulator, so you can verify loading, network, or import steps instead of relying on short animation pauses.

Instructions

Poll until an element appears, or until it goes away. This is the tool for a screen that loads: a generation step, a network round trip, a long import. settle_ms on the action tools is a pause for an animation and caps at ten seconds — it is not a wait, and using it as one is how you end up verifying a server instead of the screen. Give exactly one of id, label or predicate, the same way ios_simulator_tap_element takes them. Your MCP client may have a request timeout of its own, commonly 60 seconds, and it will cut this call off before timeout_ms does — for a longer wait, raise it there too or call this twice.

Input Schema

NameRequiredDescriptionDefault
idNoAccessibility identifier — the `id` field from ios_simulator_ui_tree.
labelNoExact accessibility label, i.e. the visible text. Matched against controls first, as in ios_simulator_tap_element, then against any element that is not a container (text, images, spinners), never a navigation bar or a wrapper repeating the label.
absentNoWait for the element to *stop* matching instead of to start. This is how you wait out a spinner, a progress view or a placeholder, which is the same wait from the other side.
deviceNoWhich simulator: its UDID or its name as shown by ios_simulator_list. Omit it when exactly one is booted — that is the normal case, and IOS_SIMULATOR_ID pins it when it is not. Unlike simctl's own `booted`, this never picks arbitrarily between two.
poll_msNoHow long to wait between polls. Each poll is one query to the device, so a long wait costs less at 2000 than at 250 and arrives at almost the same moment.
predicateNoA raw NSPredicate, e.g. `type == "XCUIElementTypeButton" AND label BEGINSWITH "Add"`.
screenshotNoReturn a screenshot of the resulting screen. On by default, and worth leaving on: it is how you find out that the action landed where you meant it to. Turn it off only for a sequence whose intermediate states you do not need to see.
timeout_msNoHow long to keep polling before giving up. Read the note about your client's own request timeout in this tool's description before setting it above 60000.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv0.4.1
    • changedInput schema / properties / label / description
      Previous value: -"Exact accessibility label, i.e. the visible text. Matched against controls first, as in ios_simulator_tap_element."New value: +"Exact accessibility label, i.e. the visible text. Matched against controls first, as in ios_simulator_tap_element, then against any element that is not a container (text, images, spinners), never a navigation bar or a wrapper repeating the label."
  2. First observedv0.2.0

TDQS

A4.5/5.0
Behavior4/5

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

With readOnlyHint=true already covering safety, the description still adds real operational context: the client's own request timeout (commonly 60s) can cut the call off before `timeout_ms`, and the workaround is to raise it or call twice. It also explains that each poll is a device query, so long waits cost less at higher `poll_ms`. It does not say what the tool returns or raises when the timeout expires, which is the remaining behavioral gap.

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?

Front-loaded with the core purpose, then guidance, then the constraint, then the timeout warning — a sensible order. Some phrasing is conversational ("how you end up verifying a server instead of the screen"), which adds motivation but slightly inflates length for a tool whose schema is already well documented.

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 an 8-parameter polling tool with no output schema, the description covers selection of the match criterion, the negative-wait mode, cost tradeoffs, and the dominant failure mode (client-side timeout). The only thing an agent might still want — whether a timed-out poll raises an error or returns a negative result, and whether the screenshot is still returned — is unstated.

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 baseline is 3, but the description adds a constraint the schema cannot express: "Give exactly one of `id`, `label` or `predicate`" — there is no oneOf/enum in the schema enforcing this. It also cross-references the `timeout_ms` client-timeout caveat. The `absent` flag and screenshot default are left to the schema descriptions.

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?

"Poll until an element appears, or until it goes away" gives a specific verb (poll/wait) and resource (element) with the two directions of the wait stated up front. It also distinguishes itself from the near-sibling behavior (`settle_ms` on the action tools) so an agent can tell which mechanism applies to a real load versus an animation.

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?

Explicit when-to-use cases are enumerated (generation step, network round trip, long import) and an explicit when-not-to-use case is given: `settle_ms` caps at ten seconds and is for animations, not waits. It also routes matching semantics to `ios_simulator_tap_element` so the agent knows where the identifier conventions are defined.

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