Skip to main content
Glama
Sign In
Handy

Handy

by miisodev
OverviewSchemaSourceRelated ServersDiscussionsAdmin
JavaScript
Local

List or Focus Desktop Windows

handy_windows
Idempotent

List visible desktop windows with titles, owning apps, screen bounds, and focus state, or bring a chosen window to the foreground for desktop automation.

Instructions

List visible desktop windows with their titles, owning apps, screen bounds { x, y, width, height }, and focused state (action: 'list'), or bring a specific window to the foreground (action: 'focus').

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": {
      "action": "<action>"
    },
    "name": "handy_windows"
  }
}

Input Schema

NameRequiredDescriptionDefault
idNoExact window ID from handy_windows list
appNoCase-insensitive application name substring when focusing
titleNoCase-insensitive window title substring when focusing
actionYes'list' to inspect visible windows or 'focus' to activate one

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv1.3.0

TDQS

A3.8/5.0
Behavior3/5

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

Annotations already declare destructiveHint=false, idempotentHint=true, and readOnlyHint=false; the description is consistent with that by showing focus changes foreground state. It adds no context on what happens when no window matches the filter, how multiple matches are resolved, or whether focusing requires permission/accessibility grants — a meaningful gap given the handy_permission sibling.

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?

A single dense sentence that front-loads the resource and enumerates the two action modes with their return payload. No filler, nothing repeated from the schema, no trailing caveats.

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, the description correctly takes on the burden of describing return values (titles, apps, bounds, focused state) — a strong choice. Remaining gaps are secondary: no mention of empty/multi-match behavior for focus or permission prerequisites.

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%, so id, app, title, and the action enum are already fully documented in structured form. The description adds only the framing that focus targets 'a specific window'; it says nothing about precedence when id and app/title are supplied together, so the baseline 3 holds.

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 two specific verbs (list, focus) against a concrete resource (visible desktop windows) and even enumerates the returned fields: titles, owning apps, screen bounds, focused state. An agent can tell exactly what this tool does and what it yields without opening the schema.

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?

The description distinguishes the two modes' intent ('list to inspect', 'focus to activate'), which is implicit when-to-use guidance. It stops short of naming any alternative or exclusion (e.g., how this relates to handy_see or handy_act for interacting with a window), so the agent must infer routing.

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