Skip to main content
Glama

desktop_find

Searches desktop UI elements by role, name, value, or text and filters by app, window, surface, or state to locate specific controls for inspection and action.

Instructions

agent-desktop find: Search elements by role, name, value, or text content

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "desktop_find"
  }
}

Input Schema

NameRequiredDescriptionDefault
appNoFilter to application by name
nthNoReturn Nth match (0-indexed)
lastNoReturn last match only
nameNoMatch by accessible name or label
roleNoMatch by accessibility role (button, textfield, checkbox ...)
rootNoSearch only inside this ref's subtree, not the whole window
textNoMatch by text in name, value, title, or description
countNoReturn match count only
exactNoRequire exact (case-insensitive) name/description/value matches
firstNoReturn first match only
limitNoReturn at most N matches; defaults to 50 when omitted, use 0 for all
valueNoMatch by current value
statesNoFilter by state token (repeatable); append =true or =false
surfaceNoSurface to search (menubar, menu, sheet ...) instead of the windowwindow
native_idNoMatch by native automation id (AXIdentifier)
window_idNoScope to a single window ID (from list-windows)
timeout_msNoTraversal deadline in milliseconds (default 5000; raise for a large tree such as a shell file dialog)
descriptionNoMatch by accessible description

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.4.0

TDQS

C2.9/5.0
Behavior2/5

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

No annotations are supplied, so the description carries the full burden, yet it only implies read-only behavior via the word 'Search'. It says nothing about result shape (refs), default truncation at 50 matches, or that this walks the accessibility tree and can time out on large trees — all behavior the agent must know before relying on it, even though some of it appears in the schema.

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?

A single short sentence with the core purpose front-loaded — efficient and easy to scan. The leading 'agent-desktop find:' token is redundant with the tool name and slightly dilutes an otherwise waste-free line.

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

Completeness2/5

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

For an 18-parameter traversal tool with no annotations and no output schema, a one-line description is thin: the return value (refs usable by other desktop tools), result ordering, and the performance caveat implied by timeout_ms are never addressed. The rich schema compensates for parameter semantics but not for behavioral or workflow context.

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%, and every one of the 18 parameters carries a clear inline description, so the schema does the heavy lifting. The description echoes only four of those parameters (role, name, value, text) and adds no combination or matching-precedence semantics beyond what the schema states.

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

Purpose4/5

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

The description states a concrete verb and resource ('Search elements') plus the four matching criteria (role, name, value, text), which is enough to distinguish it from siblings like desktop_click or desktop_get. It does not explicitly contrast itself with desktop_get or desktop_is, and the 'agent-desktop find:' prefix duplicates the tool name rather than adding meaning.

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

Usage Guidelines2/5

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

There is no guidance on when to use this versus desktop_get, desktop_check, or desktop_is, and no mention of the common workflow where a find result's ref is then passed to desktop_click or desktop_focus. The agent must infer the entire usage pattern from parameter names alone.

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