Skip to main content
Glama

owa_find_ui

Locate a UI control by visible text or tooltip, report its screen location and panel, then optionally highlight it or search all open windows.

Instructions

Find a control in the app by its visible text or tooltip, and say where it is on screen (plus which component renders it, in dev). Matching is tolerant -- exact words first, then looser fits -- and a zero answer comes back with the closest labels that ARE on screen, so retry with one of those instead of a new guess. Write "Panel > Control" when the same words appear in more than one panel ("Background > Videos"), and say "the X panel" to mean the panel itself; each answer names the panel it is in. highlight outlines it in the real window for four seconds, so the user can be pointed at it. anyPage searches every open window and says which one each match lives in. A match marked showsOnHover is one the app only paints while the mouse is over that part of the window, so tell the user to move the mouse there; highlight holds it up meanwhile.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "text": "<text>"
    },
    "name": "owa_find_ui"
  }
}

Input Schema

NameRequiredDescriptionDefault
pageNoPart of the window URL, e.g. "reader.html"; default the main window.
textYes
anyPageNoSearch every open window, not just one, and tag each match with the window it is in. Use when the control could be in either half of the app.
highlightNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv2026.11.15

TDQS

A3.9/5.0
Behavior3/5

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

With no annotations at all, the description carries the safety and behavior burden and does well on matching semantics: exact-first-then-loose tolerance, zero-hit fallback returning nearby on-screen labels, and the showsOnHover restriction. What it omits is whether this is purely read-only or has side effects, and how expensive a multi-window search is, so an agent cannot fully assess cost or safety. Strong behavioral detail, but not complete coverage for an unannotated tool.

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 core purpose and the retry advice are front-loaded, and nearly every sentence adds operational detail. The prose is dense with nested clauses and parenthetical examples, though, so the highlight and showsOnHover behavior arrive late and are harder to scan than they need to be.

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?

No output schema exists, so the description must describe returns, and it does: location on screen, panel attribution, rendering component in dev, window tagging under anyPage, and the closest-labels payload on a miss. Hover-only matches are flagged too. The main remaining gap is that side effects and search cost are never stated.

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?

With 50% schema coverage, the two documented parameters (page, anyPage) are already handled by the schema, and the description re-explains anyPage rather than adding much. It does add value for the undocumented `text` (visible text or tooltip) and `highlight` (four-second outline in the real window, and that it holds a hover-only control up). That is meaningful compensation, but coverage is uneven.

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: find a control by its visible text or tooltip, and return its on-screen location plus the rendering component in dev. That is enough to separate it from generic siblings such as owa_pick_element or owa_list_ui, which do not describe text-based lookup with location reporting.

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?

It gives real conditional guidance: use 'Panel > Control' when the same words appear in more than one panel, use 'the X panel' to target the panel itself, and use anyPage when the control could be in either half of the app. It stops short of naming competing tools or stating hard exclusions, so the agent still has to infer when to prefer this over a picker-style tool.

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