Skip to main content
Glama

Find elements by name

browser_find

Find interactive elements by case-insensitive name match anywhere on a page, including off-screen areas, and tag them with refs for targeted clicks or form actions.

Instructions

Find interactive elements by case-insensitive name match anywhere on the page — including beyond the observe window on huge pages — and tag them with refs (f1, f2, ...). Free — no model call. The targeted way to act on dense pages: browser_find "Philips", then browser_click the returned ref. Works for links, buttons, and form fields. Returns {match_count, matches:[{ref, kind, role, name, value?, inViewport}]}.

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": {
      "query": "<query>"
    },
    "name": "browser_find"
  }
}

Input Schema

NameRequiredDescriptionDefault
exactNoRequire the name to equal the query (case-insensitive) instead of substring matching. Default false.
queryYesText to match against element names/labels, e.g. "Philips" or "Sign in".
max_resultsNoMax matches (default 10); increase if the first result is not the one you want.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.1.0

TDQS

A4.3/5.0
Behavior4/5

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

With no annotations, the description carries the burden and does well: it discloses cost ('Free — no model call'), the side effect of tagging elements with refs, that matching extends beyond the observe window on large pages, and the exact return shape. It is silent on whether refs persist or are invalidated after a subsequent action, and whether the page is scrolled or visually marked.

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 definition, then the cost, then the workflow, then the return shape — a logical progression in a few dense sentences with no filler. Every clause contributes information an agent would otherwise have to guess.

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?

There is no output schema, so the description supplies the return shape itself (match_count plus matches with ref, kind, role, name, value, inViewport). Combined with the cost note and the follow-up action, an agent has everything needed to call this correctly and use the result.

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 coverage is 100%, so the schema already defines query, exact, and max_results with defaults. The description reinforces the matching semantics (case-insensitive name match) and adds a small operational hint for max_results, but does not explain 'exact' or the 50-result cap beyond what the schema says.

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 ('Find interactive elements by case-insensitive name match') plus the side effect ('tag them with refs f1, f2'), which is exactly what a find-then-ref workflow needs. The scope note ('anywhere on the page — including beyond the observe window') distinguishes it from the observation-based siblings.

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 explicit when-to-use guidance ('The targeted way to act on dense pages') and a concrete sequence (browser_find "Philips", then browser_click the returned ref), plus a fallback for too-few results (increase max_results). It doesn't state when NOT to use it or name browser_observe as the alternative for broad inspection, so it stops short of a full routing rule.

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