Local MCP

Ui Find Element

ui_find_element

Read-only

GUI automation — control a native app's interface. Finds an element (button, field, menu…) in an app's accessibility tree by role and/or label. Scope with app_bundle_id or window_id. Returns an opaque element_ref (usable by ui_click / ui_get_element this session) plus role, label, bounds, focused, and enabled only when the app publishes AXEnabled (otherwise enabled_unknown: true, which does NOT mean disabled). An element with no position and no press action (a label inside a web page) gets the ref of the pressable link or button that contains it (ref_via:"ancestor"), or no element_ref and clickable:false when there is none: click it by coords. found=false when the app is reachable but no element matches; app_not_found is an explicit error. Requires Accessibility permission.

Input Schema

Name	Required	Description
`role`	No	AX role, e.g. AXButton, AXMenuItem, AXTextField.
`index`	No	Which match to return if several (default 0), counted after the exact-first ordering.
`label`	No	AX title/description to match.
`match`	No	Default contains. With contains, a label that equals the query (ignoring case and spacing) is preferred over longer labels that merely contain it (label "Reply" returns "Reply", not "Reply All"). When several elements match equally well the response has ambiguous: true and the candidates; the first is still returned.
`window_id`	No	Alternatively scope by a window_id from list_windows.
`app_bundle_id`	No	Scope the search to this app.

Output Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

Changed3 schema fields changedOct 10, 2026

changedInput schema / properties / index / description

Previous value: -"Which match to return if several (default 0)."New value: +"Which match to return if several (default 0), counted after the exact-first ordering."

changedInput schema / properties / match / description

Previous value: -"Default contains."New value: +"Default contains. With contains, a label that equals the query (ignoring case and spacing) is preferred over longer labels that merely contain it (label \"Reply\" returns \"Reply\", not \"Reply All\"). When several elements match equally well the response has ambiguous: true and the candidates; the first is still returned."

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "additionalProperties": true,
+  "type": "object"
+}

AddedJul 10, 2026

TDQS

A4.5/5.0

Behavior5/5

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

Adds substantial context beyond the annotations: the returned ref is session-scoped, enabled is only present when AXEnabled is published, enabled_unknown true does NOT mean disabled, ancestor fallback assigns the containing pressable element's ref with ref_via:'ancestor', and found=false versus app_not_found are distinguished as outcomes. It also states the Accessibility permission requirement.

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?

Front-loads the core action and scope before enumerating return values and edge cases. Despite being dense, every clause—element_ref lifetime, enabled semantics, ancestor fallback, found/app_not_found error distinction—carries necessary operational detail.

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?

Although an output schema exists, the description still covers the key return contract, including the opaque element_ref and its session lifetime, the enabled vs enabled_unknown distinction, ancestor fallback, and the found=false versus app_not_found error boundary. With annotations and schema already in place, this is complete enough for correct invocation.

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

Parameters3/5

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

Schema description coverage is 100%, so role, index, label, match, window_id, and app_bundle_id are already fully documented, including exact-first ordering and ambiguity behavior. The description only adds 'by role and/or label' and the scoping choice between app_bundle_id and window_id, which is a marginal restatement rather than new parameter meaning.

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?

States a specific verb and resource: finds an element in an app's accessibility tree by role and/or label, scoped by app_bundle_id or window_id. This is distinct from sibling tools like ui_read_tree (whole tree) and ui_click (act on a found element), and the relationship to ui_click / ui_get_element is made explicit.

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?

Gives clear context for when to use it: obtaining an opaque element_ref for ui_click or ui_get_element, with a fallback instruction to click by coordinates when clickable is false. It does not explicitly compare against alternatives like ui_wait_for_element or ui_read_tree, so it falls short of a full when/when-not routing guide.

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

All Local MCP tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.