Skip to main content
Glama

observe

Read a macOS app's window as a one-line-per-element outline with action refs; later calls return only changes, and focus opens a folded part.

Instructions

Outline of an app's window: one line per element, each with a ref like b3 or t1 for act. Later calls return only what changed. Long parts are folded; pass focus to open one. In apps that draw their own interface, labels read from the pixels appear as seen (v refs): click or drag them.

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": {
      "app": "<app>"
    },
    "name": "observe"
  }
}

Input Schema

NameRequiredDescriptionDefault
appYesApp name, bundle id or pid
fullNoThe whole outline instead of changes
focusNoA ref: show only this part, unfolded
menusNoInstead: every menu command with its shortcut
windowNoPart of a window title (default: main window)

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.1.0

TDQS

A3.8/5.0
Behavior4/5

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

With no annotations, the description carries the full load and does disclose real behavior beyond the schema: incremental diffing on repeat calls, folding of long sections, and the existence of 'seen' v-refs for canvas-drawn apps that can be clicked or dragged. It leaves out failure modes (app not running, permissions, frontmost requirements) and does not state read-only-ness explicitly, which keeps it from a 5.

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?

Four short sentences, front-loaded with what the output looks like, then behavior, then the edge case for pixel-drawn apps. Every sentence carries new information; the terseness ('t1 for act') is dense but not wasteful.

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?

With no output schema and no annotations, the description does the important work of describing the return shape (one line per element, ref tokens) and the diffing semantics. It is nearly complete for a five-parameter inspection tool, missing only error/precondition behavior and a clear statement of how 'seen' refs differ from normal refs when passed to 'act'.

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 all five parameters; baseline is 3. The description adds meaning only for 'focus' ('long parts are folded; pass focus to open one') and implicitly for 'full' (diff vs whole outline), but never addresses 'menus' or 'window', so the added value is partial.

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?

Opens with a concrete noun+format ('Outline of an app's window: one line per element') and explains the ref scheme (b3, t1) that makes the output usable. It does not distinguish itself from the sibling 'see' tool, so an agent must infer that boundary, but the returned artifact is unmistakable.

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

Usage Guidelines3/5

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

Usage is implied rather than stated: 'Later calls return only what changed' tells the agent this is a polling/inspection tool, and 'pass focus to open one' routes to a parameter. There is no explicit when-to-use-it-instead-of-X guidance and no mention of the 'see', 'timeline', or 'act' siblings as alternatives.

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

Deploy Server

Other Tools