Skip to main content
Glama

glass_find_elements

Read-only

Find ranked accessibility candidates from one fresh read when a target is approximate, duplicated, or unidentified. Search by role, query, and states within a scope for actionable IDs and context.

Instructions

Find ranked accessibility candidates from one fresh read when the target is approximate, duplicated, or not yet identified. Query matches name, description and non-secure value; within must match one semantic scope. max_results defaults to 10, capped at 20; timeout_ms optionally waits. Returns actionable IDs, compact context and explicit truncation in an untrusted match array. subject_mismatch flags a different app, named by subject in that block. Total text is capped at 8 KiB.

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": "glass_find_elements"
  }
}

Input Schema

NameRequiredDescriptionDefault
roleNoNormalized target role.
queryNoApproximate case-insensitive semantic text. Optional when role or states are supplied.
statesNoTarget state predicates combined with AND.
withinNoOptional unique semantic scope resolved in the same fresh tree.
max_nodesNoExisting accessibility walk limit semantics; 0 removes the node-count limit.
timeout_msNoOptional wait for at least one match; default 0 performs one fresh read.
max_resultsNoMaximum ranked matches before the byte budget; default 10, range 1 through 20.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Addedv1.5.1

TDQS

A4.2/5.0
Behavior5/5

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

Beyond the readOnlyHint/openWorldHint annotations, the description discloses substantial behavior: a single fresh read, timeout_ms waiting semantics, ranking, a default of 10 results capped at 20, an 8 KiB total text budget, explicit truncation, an untrusted match array, and a subject_mismatch block naming a different app. These are exactly the operational traits an agent needs and that annotations do not cover.

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 text is front-loaded with the purpose and use condition before falling back to defaults, caps and return shape, and nearly every clause carries a distinct fact. It is dense to the point of being terse, packing limits, return shape and error flags into short clauses that take a second read to parse.

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 a 7-parameter, all-optional search tool with no output schema, the description covers return contents (IDs, compact context, truncation marker, subject_mismatch) and budget behavior, which is the bulk of what matters. It leaves max_nodes semantics entirely to the schema, which is acceptable but is the one remaining gap.

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?

With 100% schema description coverage the baseline is 3, but the description adds real meaning: query is confined to name/description/non-secure value (implying secure text is excluded), and `within` must resolve to exactly one semantic scope in the same fresh tree. It also restates the max_results default and cap, which is redundant with the schema.

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 specific verb and resource ('Find ranked accessibility candidates') and scopes it to a fresh tree read over name, description and non-secure value. The phrase 'when the target is approximate, duplicated, or not yet identified' implicitly separates it from exact-target siblings like click_element or a11y_snapshot, but no sibling is ever named, keeping it just short of the top band.

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 a clear triggering condition: use this when the target is approximate, duplicated, or not yet identified. There is no explicit when-not guidance and no named alternative for the exact-match case, so the agent must infer that routing itself.

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