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

Annotations provide readOnlyHint=true, and the description aligns with that by describing a read-only operation. It adds context about the precision of bounding boxes (~10-20px drift), how clicks are actuated (native accessibility action vs center), and error behavior. The only minor gap is not detailing what the legend format is for elements with both a name and description, but the overall transparency is strong.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is dense but perfectly scannable: it opens with what the tool does, explains the legend format, then covers precision, click mechanism, and error handling. Every sentence adds unique information with no fluff.

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

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

Despite being a zero-parameter tool, it fully explains the output format, error conditions, precision limitations, and how to use the output. The error fallback to glass_screenshot is a nice operational detail.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has 0 parameters, and schema coverage is 100%. The description doesn't need to add parameter info since there are none. It adds value by explaining the return format (image + legend) which goes beyond parameters.

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

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

The description clearly states the tool takes a screenshot of the active window with numbered boxes on interactable elements (Set-of-Mark) and returns the image plus a text legend. It distinguishes itself from siblings by using the phrase 'Pick an element visually, then click it with glass_click_element using its #id', and mentions it returns errors differently than glass_screenshot.

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

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

It explicitly says when to use it: 'Pick an element visually, then click it with glass_click_element using its #id', and when it's not appropriate: 'Errors if no accessibility tree is available — use glass_screenshot then.' It also clarifies the relationship with glass_click_element and glass_a11y_snapshot.

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

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

The annotations only provide readOnlyHint=true; the description goes far beyond that by disclosing the compact-text line format, stable id-based addressing, redaction/truncation of the compact value, error behavior when no accessibility tree exists, the Document wrapper for web content, placeholder notices, and the max_nodes token-budget cap. There is no contradiction with the annotations, and the extra behavior detail is exactly what an agent needs to interpret results safely.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is long but front-loaded with the core purpose and each sentence carries a distinct operational fact: output format, sibling routing, value redaction, error fallback, Document behavior, placeholder noticess, and cap behavior. It could be improved with structured bullets or shorter sections, but no sentence is filler for a tool this behaviorally rich.

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

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

No output schema exists, so the description correctly carries the burden of explaining return values; it gives the exact line grammar `#<id> <Role> "<name>" desc="<description>" (x,y wxh) [states]` and explains how desc, ids, and states are used. It also covers error cases, web-content structure, placeholder notices, the single optional parameter, and explicit fallback tools, making the definition complete for a one-optional-param read-only tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, and the schema already fully documents max_nodes: omit for default cap, pass a larger number to raise it, pass 0 for no limit, and re-read ids because snapshots renumber them. The description's max_nodes sentence mostly paraphrases the schema ('raise the element cap', '0 to remove the element-count limit', 'default caps protect the token budget'), so it adds no material new parameter meaning beyond the schema. The baseline of 3 for high schema coverage is appropriate.

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

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

The description opens with a specific action and resource: 'Capture the active window's current semantic state as a compact accessibility tree' and enumerates exactly what the tree contains (role, name, description, bounded editable value, window-relative bounds, and states). It also distinguishes itself from glass_wait_for_element and glass_screenshot by explicitly labeling itself as one observation, not proof of transition completion or visual appearance.

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

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

The description gives explicit when-to-use and when-not-to-use guidance: call glass_wait_for_element for exact runtime verification, use value/value_contains for editable values, and prefer the wait over repeated snapshots when the full queryable value matters. It also names concrete fallback paths, such as using glass_screenshot when no accessibility tree exists and taking a fresh snapshot before pixels for a childless Document.

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

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

The description discloses several important behaviors beyond the annotations: capturing the whole window at call time rather than a saved region, silent replacement on overwrite, storage outside the app in a per-server directory, and persistence until server exit. These are exactly the kind of behavioral details an agent needs.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is dense but every sentence contributes: it defines the baseline, explains the capture scope, discloses replacement and lifetime semantics, and routes to alternatives. The most important purpose is front-loaded.

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

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

For a single-parameter tool with no output schema, the description is complete. It covers what the tool does, how it behaves, what conditions matter, and which sibling to choose instead. Nothing an agent needs to decide whether to invoke it is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema already fully describes the single `name` parameter, including allowed characters and overwrite behavior. The description adds baseline semantics and capture scope, but not additional parameter-level detail, so the high-coverage baseline of 3 is appropriate.

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

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

States a specific verb and resource: 'Save the current frame as a named visual baseline.' It clearly distinguishes the tool from siblings by explaining what glass_diff and glass_wait_for_region use it for and explicitly contrasts it with glass_screenshot.

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

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

Gives explicit when-to-use guidance: use this with glass_diff to detect change, and use glass_screenshot when you need to inspect pixels. Also provides a timing constraint—settle the UI first if it is still animating—which is practical usage advice.

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

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

Annotations already declare readOnlyHint=true, so the description doesn't need to repeat that. It adds valuable behavioral context: the tool is static (no session required), reports live status with specific enum values, and explains what each status implies (e.g., degraded means reduced fidelity, requires_setup means a setup step is missing). This goes beyond the annotations by detailing the response semantics.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is dense but well-structured, front-loading the purpose and then explaining the status values and parameter usage. It's a bit long but every sentence adds value, explaining the status enum and the `tools` field. The structure is logical: purpose, status explanation, parameter guidance.

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

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

For a read-only capability check tool with a single optional parameter and no output schema, the description is quite complete. It explains the status values, what they mean, and how to use the parameter. The only minor gap is that it doesn't explicitly state the return format beyond the status and tools fields, but given the tool's simplicity and the annotations, this is sufficient.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema already provides 100% coverage of the `backend` parameter, including valid values and the behavior for omitted vs. invalid names. The description adds a brief note about omitting for the active backend, but the schema already covers this. Since schema coverage is high, the baseline of 3 is appropriate.

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

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

The description clearly states the tool reports which operations can be performed on a backend, listing specific operations (input, multi-touch, clipboard, accessibility, window move/resize) and the purpose (check before acting to avoid Unsupported errors). It distinguishes itself from siblings by focusing on capability reporting rather than performing actions.

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

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

The description explicitly says to use this tool to check capabilities before acting, and explains the status values and what they mean for subsequent tool calls. It also specifies when to pass the `backend` parameter and when to omit it, providing clear guidance on usage.

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

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

Annotations already indicate readOnlyHint=false and destructiveHint=false, so the click is known to be an input action rather than a read-only or outright destructive operation. The description adds the modifier-held-during-action behavior and coordinate-relative semantics, but it does not disclose potential side effects, focus requirements, or failure modes. This is adequate but not highly transparent given the action-oriented nature of the tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is compact and front-loaded with the core action. Every sentence serves a purpose: the coordinate mechanism, the parameter variants, the modifier behavior, and the batching alternative via glass_do. There is no filler or redundant elaboration.

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

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

For a five-parameter tool with full schema coverage and no output schema, the description covers the essential call context: coordinate frame, click variants, modifier usage, and an alternative for batching. It could mention window focus or the need to select a target window beforehand, but that is likely handled by the surrounding workflow and sibling tools. Overall, an agent has enough to invoke this tool correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema fully documents x, y, count, button, and modifiers. The description largely restates these values ('button: left|right|middle; count for multi-click') and gives examples already present in the schema. It adds little meaning beyond what the schema provides, so the baseline score of 3 is appropriate.

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

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

The description opens with a specific verb and resource: 'Click at window-relative coordinates.' This clearly identifies the tool's action and distinguishes it from element-based siblings like glass_click_element, since it works from raw coordinates rather than UI elements. The button/count/modifiers details further pin down the operation.

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

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

The description gives explicit routing guidance: when at least two subsequent actions or waits are known, use glass_do instead of issuing separate calls. This is a concrete alternative with a clear condition. It does not explicitly contrast with glass_click_element, but the 'window-relative coordinates' language makes the coordinate-based use case reasonably clear.

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

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

Beyond annotations (readOnlyHint=false, destructiveHint=false), the description richly discloses fallback behavior (native action vs. pointer click), result fields that reveal which path ran ('method', 'native_fallback', 'actuated_id'), popover routing with window restoration, and default observation behavior ('none'). It also warns about snapshot invalidation and text editors focus behavior. This is substantial behavioral context far beyond the annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is long but every clause carries operational weight, and the most important behavioral facts (native-action-first, fallback, result fields) are front-loaded. It is not wastefully wordy, but it is a dense single paragraph that could be slightly more scannable with sentence breaks or bullets.

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

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

For a 2-parameter tool with no output schema, the description is complete: it explains why the tool exists, what happens when native actions are unavailable, how popover routing works, when to re-snapshot, what the optional return parameter does, and when to prefer glass_do. Nothing needed to invoke it correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents both parameters well. The main description adds only modest extra value by naming the optional return values and their effects ('snapshot', 'settle', 'none'), but it does clarify the default. Since the schema is already strong, this is a solid 4, losing a point because the description itself doesn't add much beyond what the schema already says.

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

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

The description names a specific verb ('Click'), a precise resource ('an element by its #id from glass_a11y_snapshot'), and immediately distinguishes the primary native accessibility action from the synthetic pointer fallback. This clearly separates it from sibling tools like glass_click (generic click) and glass_click_element is scoped to a11y snapshot ids.

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

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

The description explicitly tells the agent when to use it (element from latest snapshot, even occluded/off-screen), when to re-run glass_a11y_snapshot, and when to prefer glass_do instead ('If at least two next actions or waits are known'). It also discloses automatic routing for popover-owned targets, which prevents misuse.

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

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

Annotations already mark readOnlyHint=true, so the description adds value beyond that by disclosing edge cases: "" if empty and "Unsupported where the backend can't provide clipboard access." It also explains the ctrl+a/c Ctrl+c workflow as an implementation detail. No contradiction with readOnlyHint.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, front-loaded with the primary purpose, then the secondary use case. Every clause contributes information: return value, empty-handling, workflow hint, OCR comparison, and failure mode. No waste.

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

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

For a zero-parameter read-only tool with no output schema, the description covers the essential behavioral contract: what it returns (text), empty case, and the Unsupported state. It also ties into the broader tool ecosystem with the glass_do reference, making it complete for an agent to call correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has zero parameters, and schema coverage is trivially 100%. The description cannot add parameter-level meaning, but it does not need to. The baseline for 0-param tools is 4, and the description doesn't introduce any ambiguity about inputs.

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

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

The description states a clear verb ("Read") and resource ("the app's clipboard"), and specifies the return type (text) and empty-string behavior. It also differentiates from siblings like glass_clipboard_set by framing itself as the read counterpart and adding a specific text-extraction use case.

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

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

It provides a concrete usage scenario: "the cheap text-extraction path" using glass_do ctrl+a then ctrl+c, and explicitly compares to OCR ("beats OCR for selectable text"). It lacks explicit exclusion criteria or when-not-to-use guidance, hence not a 5, but the context is clear enough for an agent to select correctly.

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

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

Annotations already indicate this is a write operation (readOnlyHint=false, destructiveHint=false). The description adds a specific error condition ('Returns Unsupported where the backend can't provide clipboard access'), which goes beyond the annotations. This is useful context about a failure mode that an agent would not otherwise know.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short sentences with no filler. The primary action is in the first sentence, and the error condition in the second. Every word contributes to the tool's understanding.

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

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

For a simple one-parameter write operation with no output schema, the description covers the core behavior and the only notable edge case (Unsupported backend). It does not mention return values on success, but that is implied for a write operation and not essential. The absence of output schema means the description isn't required to explain return format.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% for the single 'text' parameter, with a clear description ('The text to write to the clipboard.'). The tool description does not add any additional meaning or nuance beyond the schema's own documentation, so it meets the baseline but adds no extra value.

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

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

The description states a clear verb ('Write') and resource ('text to the app's clipboard'), with an explicit purpose ('so it can paste it'). It is easily distinguishable from its sibling 'glass_clipboard_get' since it names the opposite action (write vs. get).

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

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

The usage context is implied by the tool's name and description (write text to clipboard), but no explicit guidance is given about when to use this versus the sibling 'glass_clipboard_get' or any exclusions. The description does not mention alternatives, so it relies on the agent to infer from the sibling list.

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

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

Annotations already mark the tool as read-only, and the description adds valuable behavioral context: this is a non-waiting, one-shot comparison, and include_image only returns a crop when pixels actually differ. This goes beyond what annotations alone convey, though it does not describe full return-structure details.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences with no filler: the core action and outputs are front-loaded, the distinguishing usage guidance follows, and the optional include_image behavior closes efficiently. Every sentence earns its place.

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

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

Given the tool's moderate complexity, full parameter schema coverage, and readOnly annotation, the description covers purpose, usage boundaries, and the key optional behavior. It does not detail the exact shape of 'change stats' or the bbox, but that is not required without an output schema and does not prevent correct invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents all seven parameters thoroughly. The description only reiterates include_image's effect without adding meaning beyond the schema, which keeps this at the baseline for fully-covered schemas.

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

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

The description uses a specific verb ('Compare'), names the resource ('current visual evidence with a named pixel baseline'), and states the outputs ('change stats and a bounding box'). It also explicitly distinguishes itself from wait-for tools, making its purpose unmistakable among siblings.

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

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

It clearly states when to use this tool ('single current-state comparison') and when not to, naming the alternatives: 'glass_wait_for_region to wait for pixel change/match and glass_wait_stable for quiescence.' It also gives a concrete usage tip for include_image, so an agent knows how to get the changed crop.

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

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

Annotations are minimal (three negative hints), so the description carries the full burden and delivers: fail-fast semantics on action errors, sequence deadline, and unmatched batched predicates; the exact error outcome shapes (completed/failed/unexecuted in the MCP error); the preflight invalid_sequence path; terminal_steps additions; and hard limits (64 actions, 65536 bytes). The explicit 'No variables, result bindings, interpolation…' dislosure prevents false expectations. No contradiction with annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Dense but every sentence carries distinct information, and the most actionable guidance (when to prefer, canonical flow, when not to) is front-loaded. A mild structural ding for presenting this much detail as one unbroken wall of text without bullets or paragraph breaks.

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

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

With no output schema, the description documents result shapes: structured completed outcomes per action on success, and the completed/failed/unexecuted split in MCP errors on mid-sequence failure. Combined with a schema that fully documents every action variant and the then-args, nothing an agent needs to invoke it correctly or recover from failures is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3. The description earns above baseline by adding constraints the schema omits — max 64 actions, 65536 compact argument bytes, and the one shared absolute deadline for timeout_ms — plus fail-fast ordering for the actions array.

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

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

Neames a specific operation — running multiple fixed ordered UI actions (click, set_value, wait_for_element, etc.) in one call — and explicitly contrasts itself with the standalone siblings. The phrase 'Run fixed static ordered actions in one call' plus the enumerated action list make the resource and scope unmistakable.

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

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

Explicitly states when to prefer this tool: 'Prefer glass_do whenever at least two upcoming actions or verification waits are already known.' It also gives the canonical form flow and the exclusion condition — 'Use standalone tools only when the next step depends on newly observed state.' This is textbook when/when-not guidance with alternatives named.

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

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

The description discloses that the deep option spawns and tears down a headless display, implying side effects, which aligns with the annotations. It also details the return structure (sections, checks, statuses, remedies) and overall verdict, providing full transparency about behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured and concise, covering purpose, usage, parameter, and output in a logical flow. It avoids redundancy and each sentence adds value, despite being somewhat detailed for the return structure.

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

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

The description fully explains the tool's functionality, optional deep behavior, and the complete structure of the returned data, including status values and remedy fields. It leaves no ambiguity for an agent using this tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The only parameter 'deep' is fully described: 'Also spawn and tear down the default backend's headless display to verify it actually starts (slower). Default false.' Schema coverage is 100%, so the parameter semantics are complete and clear.

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

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

The description clearly states the tool diagnoses the glass environment and reports per-check status, with a specific verb and resource. It also mentions the self-diagnosis use case, effectively distinguishing it from sibling tools that perform other actions.

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

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

The description explicitly instructs 'Use this to self-diagnose a glass_start failure', providing a precise when-to-use scenario. It also explains the optional deep check, making the tool's intended usage unambiguous.

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

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

Annotations only carry basic hints (readOnly=false, destructive=false), so the description carries the behavioral burden and delivers richly: window-relative vs screen-relative coordinate semantics, the press-move-release lifecycle in steps over duration_ms, default button behavior, modifiers held throughout, and the safety behavior that out-of-window endpoints are refused with an error reporting window size. No contradiction with annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Dense but every sentence earns its place: coordinate semantics, mechanics, defaults, error behavior, use cases, alternatives, and batching guidance. The most decision-relevant fact (window-relative coordinates disambiguating 0,0) is front-loaded, and the sibling routing is compactly appended.

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

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

For a 7-parameter, 4-required tool with no output schema, the description covers the key behavioral surface an agent needs: coordinate frame, execution lifecycle, defaults, modifier handling, out-of-bounds refusal, and alternative-tool routing. No critical call-time decision is left undocumented.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so baseline is 3. The description adds value beyond the schema by explaining how duration_ms shapes motion ('moves across in steps'), the default button behavior, and how modifiers apply ('held throughout'), plus the endpoint-validation constraint tying x1/y1/x2/y2 to the window bounds. This is genuine added meaning, not mere restatement.

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

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

Opens with a specific verb+resource: 'Drag with a button held from (x1,y1) to (x2,y2)'. It explicitly differentiates from siblings — glass_gesture (multi-touch pinch/rotate), glass_click (press-and-release in place), and glass_do (batching). An agent can tell exactly what this tool does and what it is not 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.

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

Gives explicit selection criteria: 'Use this for a single pointer — selecting text, moving an item, resizing a pane', then names the alternatives with their distinguishing conditions (glass_gesture for 2+ pointers, glass_click for in-place press/release, glass_do when two or more next actions are known). The when/when-not/alternatives guidance is complete and leaves nothing to inference.

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

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

Annotations already declare readOnlyHint=true, but the description adds substantial behavioral context: it performs a single fresh read, returns a bounded ranked set, treats query as deterministic, caps max_results at 20, uses snapshot walk-limit semantics for max_nodes, and caps complete output at 8 KiB. It also discloses the trusted/untrusted nature of returned data. No annotation contradiction is present.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is dense but every sentence earns its place: it front-loads the core behavior, immediately gives routing guidance, then compacts parameter semantics, return shape, and error limits. Despite its length, it avoids repetition and stays organized.

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

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 correctly covers return semantics: trusted counts plus one untrusted match array with actionable ids and compact context. It also covers key constraints like the 8 KiB cap. For a tool with seven optional parameters and rich sibling context, this description provides enough for correct invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3, but the description meaningfully extends the schema. It clarifies that query is a deterministic case-insensitive substring over accessible name/description/non-secure value, that within must match one semantic scope, that max_results defaults to 10, that positive timeout_ms waits for a match, and that max_nodes reuses snapshot walk-limit semantics. These details are absent from the schema descriptions.

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

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

The description opens with a specific verb and resource: 'Find a bounded ranked set of accessibility elements from one fresh read.' It clearly differentiates this tool from glass_wait_for_element and glass_a11y_snapshot by naming them as alternatives, so an agent can select the right sibling without opening their schemas.

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

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

The description gives explicit selection criteria: use this when target text is 'approximate, duplicated, or not yet identified,' and use glass_wait_for_element for 'one precise runtime condition' or glass_a11y_snapshot for 'broad tree inspection.' This provides both when-to-use and when-not-to-use guidance.

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

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

The description discloses that multi-touch isn't available on every backend and that it returns a clear Unsupported error where unsupported, which is valuable beyond the annotations (which declare only safety hints). It also explains the timing model (all down at t=0, up at duration_ms) and the 'held pointer' behavior, adding behavioral context that helps the agent anticipate results. The annotations don't specify these runtime behaviors, so the description fills a real gap.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise and information-dense, front-loading the core action and mechanics in the first sentence, then adding gesture examples and a critical limitation note. Every sentence adds non-redundant value; there's no filler or repetition of schema details. It's well-structured for quick scanning by an agent.

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

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

Given no output schema and a moderate-complexity parameter set (only two parameters), the description covers the essential semantics: pointer segments, gesture types, timing, and backend limitations. The only minor gap is that it doesn't explicitly state the default duration_ms, but that's in the schema description. Overall, an agent has enough to call it correctly without missing critical behavior.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema covers the parameters thoroughly, but the description adds glossary-level meaning: it defines what a 'from==to pointer' means (held), and clarifies how the pointer count maps to gesture types. It reinforces window-relative coordinate semantics already in the schema, and explains the duration default implicitly by describing the timeline. Since schema coverage is 100%, the description's additional gestures and examples go beyond repetition, earning a 4.

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

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

The description states a specific verb ('perform'), a precise resource ('multi-touch gesture'), and enumerates pointer count and segment mechanics. It lists concrete gesture patterns (pinch, rotate, swipe, hold), which clearly distinguishes it from single-pointer tools like glass_drag and glass_click, and from other input tools such as glass_key or glass_type.

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

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

The description explains the gesture mechanics and provides examples of when to use each pattern (pinch, rotate, swipe), giving clear context. It doesn't explicitly say when NOT to use this tool versus alternatives, but the detailed gesture-specific guidance implies usage for multi-touch scenarios, leaving no ambiguity for common cases.

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

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

Beyond the sparse annotations, it discloses important runtime behavior: unknown tokens are rejected with a named error, nothing is half-pressed, and modifiers are released on completion. It also explains case-insensitivity and aliases for super, which materially affect how the agent should construct calls.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is long but every sentence earns its place: syntax, accepted values, error behavior, release semantics, and routing to alternatives. It is front-loaded with examples before grammar details, making it easy to scan.

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

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

For a single-parameter keyboard tool with no output schema, the description covers everything needed to invoke it correctly: chord grammar, modifier aliases, key categories, error handling, and alternative tools. There is no critical missing context.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Although the schema provides a simple example, the description substantially expands the meaning of the `chord` parameter: last token is the key, earlier tokens are modifiers, accepted modifier names, key categories, and printable ASCII support. This adds real semantic value beyond the schema's one-line description.

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

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

The description begins with an explicit verb and resource: 'Press a key chord', followed by concrete examples. It clearly differentiates from glass_type ('for literal text') and glass_do ('for batching'), so an agent can distinguish the tool from siblings without inspecting schemas.

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

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

The description gives explicit guidance: use for shortcuts and named keys, glass_type for literal text, and glass_do when batching multiple actions or waits. It also specifies exact chord syntax and accepted modifier forms, leaving little to inference.

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

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

The description adds valuable behavioral context beyond the readOnlyHint and openWorldHint annotations. The note that 'Window ids are not stable across calls' is a critical runtime behavior that agents must know to avoid caching issues, and it explicitly advises re-listing after window changes. This is a significant disclosure that goes beyond the annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is compact—two sentences—with the core action and return format first, followed by the important stability warning. Every sentence earns its place; there is no fluff or redundancy. The structure front-loads the essential information effectively.

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

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

For a zero-parameter tool with no output schema, the description covers the key aspects: what it lists, the fields included, the JSON array format, and a caution about id stability. It does not explicitly mention behavior when no windows are present, but that is not critical. The description is sufficiently complete for an agent to call this tool correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has zero parameters and the schema description coverage is 100% (effectively no parameters to describe). The description does not need to add parameter semantics since there are none. Based on the rubric, with high schema coverage the baseline is 3, and the description does not add any extra parameter-related information because none exists.

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

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

The description clearly states the action: 'List the app's top-level windows' and enumerates the specific fields returned (id, title, class, geometry, and active status). It also specifies the return format as a JSON array. While the verb and resource are specific, it does not explicitly differentiate from sibling tools like glass_select_window or glass_window, though the 'list' action makes the distinction reasonably clear.

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

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

The description does not provide any guidance on when to use this tool versus alternatives. It offers a behavioral warning about id instability, which suggests a usage pattern (re-list instead of caching), but it does not explicitly state when to choose this over related tools like glass_select_window or glass_window. No exclusions or context for selection are given.

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

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

Annotations only declare readOnlyHint=true and openWorldHint=false, but the description adds substantial behavioral context: the resumable cursor semantics, immediate non-blocking return, buffer rotation that can age out unread lines, and the fact that returned lines are marked untrusted. This goes far beyond what annotations provide and contradicts nothing.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Four dense sentences, each earning its place: the core operation, cursor behavior, the blocking alternative, filtering guidance, and the buffer/untrusted caveats. The most important information is front-loaded and no sentence is wasted.

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

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

For a tool with 4 optional parameters, no output schema, and read-only annotations, this description covers everything needed to call it correctly: what it returns, how cursors resume, empty-return behavior, when to choose the waiting sibling, filtering options, and buffer limitations. Nothing essential is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3. The description adds meaning beyond the schema by explaining the cursor's loop-once semantics, why filtering server-side matters, and how the buffer can cause unread lines to be dropped. It doesn't detail every parameter, but the schema already documents them well.

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

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

The description opens with a specific verb and resource: 'Read captured stdout/stderr log lines with a resumable cursor.' It clearly distinguishes this from the sibling glass_wait_for_log by explaining the non-blocking behavior, so an agent can tell which tool to pick without opening schemas.

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

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

The description explicitly says to use glass_wait_for_log when blocking is desired ('it does not wait, so use glass_wait_for_log when you want to block until a line appears'). It also advises server-side filtering with stream and contains instead of reading everything, giving clear guidance on how to use this tool efficiently.

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

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

Annotations already signal readOnlyHint=false and destructiveHint=false, so the mutation aspect is covered. The description adds 'window-relative' coordinate semantics, but it doesn't disclose additional behavior such as hover side effects or whether this moves the OS cursor. No contradiction exists between annotations and description.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two concise sentences: the first states the core action, the second provides routing guidance for an alternative. Every sentence earns its place and there is no filler.

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

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

For a simple pointer-move tool with only two required parameters, full schema coverage, and no output schema, the description is largely complete. It covers the coordinate semantics and the main alternative batching path, though it doesn't mention possible side effects or success criteria.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema fully documents both x and y, including window-relative meaning and edge clarifications. The description echoes 'window-relative coordinates' but adds no extra semantic information beyond the schema, so baseline 3 is appropriate.

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

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

The description states a specific verb ('Move'), a clear resource ('the pointer'), and target coordinates. It also distinguishes itself from related tools by referencing glass_do for batched actions, so an agent can tell what this tool does without ambiguity.

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

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

The description explicitly says to use glass_do instead of separate calls when at least two next actions or waits are known. This provides clear when-not-to-use guidance and names the alternative, which is exactly what an agent needs for tool selection.

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

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

Beyond the readOnlyHint annotation, the description discloses important behaviors: captures are clipped at display edges, the returned width/height reflect the actual captured size, a smaller frame indicates clipping, and only a fully off-screen surface errors. It also clarifies the screenshot's evidential limitation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with the core purpose, then gives usage routing, then covers edge-case behavior. Every sentence earns its place, and there is no filler or repetition of schema boilerplate.

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

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

Coverage is strong for an invoke-time decision: purpose, alternatives, clipping, and error conditions are all present. However, there is no output schema, and the description only mentions returned width/height without stating how the screenshot image itself is returned, which is a minor completeness gap.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% and the schema already explains window_id and region semantics in detail, including window-relative coordinates and optionality. The description mostly restates 'window-relative region' without adding substantial parameter-level meaning beyond the schema.

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

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

The description states a specific verb and resource: 'Capture current visual evidence from the app window' as a 'lossless WebP screenshot.' It also distinguishes itself from sibling wait tools by explicitly saying it proves pixel visibility, not semantic state or transition completion.

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

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

The description gives explicit when-to-use guidance and names specific alternatives: use glass_wait_for_element for accessible conditions, glass_wait_for_region for pixel transition completion, and glass_wait_stable for visual quiescence. This lets an agent route correctly without guessing.

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

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

Annotations already indicate this is not read-only and not destructive. The description adds useful behavioral context: scrolling is measured in wheel steps, modifiers are held during the action, and it names the batching behavior via glass_do when multiple actions are known. This goes beyond the schema but stops short of describing side effects or edge cases in depth.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two tight sentences with no filler. The core action is front-loaded, the modifier behavior is stated briefly, and the batching alternative is placed at the end where it belongs.

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

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

For a simple action tool with 100% schema coverage and no output schema, the description provides all necessary context: what the tool does, coordinate semantics, modifier behavior, and when to route to glass_do. Nothing critical is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema fully documents all five parameters. The description adds a concise restatement of the coordinate model and modifier purpose, but the heavy lifting is already done by the parameter descriptions.

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

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

The description opens with a specific verb and resource: 'Scroll at window-relative coordinates by (dx,dy) wheel steps.' It clearly distinguishes coordinate-based scrolling from the sibling glass_scroll_to_element, and the batching note differentiates it from glass_do.

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

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

Explicitly states when to prefer glass_do instead: 'If at least two next actions or waits are known, use glass_do instead of separate calls.' This gives a concrete condition for choosing an alternative and implies glass_scroll is for single, ad-hoc scroll actions.

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

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

The description goes well beyond the annotations by disclosing the visible-not-merely-present requirement, the sweep-and-reverse search strategy, fallback direction inference, anchoring behavior, text-only return, timeout behavior, and error case. This is exactly the operational context an agent needs and is not available from readOnlyHint/destructiveHint.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is dense but front-loaded with the core purpose, then parameter behavior, then return contract and alternatives. Every sentence carries operational value for a 9-parameter tool, though the single-paragraph format is long and could be improved with clearer structural breaks.

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

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

Given the tool has 9 parameters, no output schema, and no nested objects, the description covers selectors, direction inference, sweep-reversal, anchor defaults, step, timeout, return shape, error conditions, and the glass_do alternative. An agent has enough to decide when to call it and what to expect.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Parameter semantics are already fully documented in the schema (100% coverage), including defaults for `step`, `timeout_ms`, and validation that `value_contains` is not standalone. The description summarizes some of this behavior but does not substantially add new parameter meaning beyond what the schema already provides.

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

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

The description states a specific action (scroll any axis), a resource (container/element), and the outcome (element returned as text-only with usable id for glass_click_element). It clearly distinguishes itself from generic scrolling and clicking siblings by framing the purpose around finding a visible accessibility element.

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

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

It explicitly explains when the tool is appropriate — when an element must actually be visible for a later click — and routes to an alternative: 'If at least two next actions or waits are known, use glass_do instead of separate calls.' It also states a hard failure condition (no accessibility tree), giving agents a clear signal for when not to call it.

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

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

Beyond the annotations (idempotent, non-destructive), the description reveals a key behavioral trait: selecting a window redirects subsequent operations and changes the coordinate system. The schema description also warns that ids are not stable across calls, which is important operational behavior. This adds real value beyond the annotation flags.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is compact and efficient: one sentence that states the action, the id source, and the consequential effect on later operations. Every clause earns its place, and the most important information is front-loaded.

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

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

For a single-parameter tool with no output schema and annotations covering safety, the description is complete. It tells the agent what to pass, where to get it, and what side effects to expect on future calls. Nothing essential is missing for correct invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema already covers the only parameter fully, describing it as a window id from glass_list_windows and noting instability. The main description merely repeats 'by id (from glass_list_windows)', adding no new meaning. With 100% schema coverage, the baseline of 3 is appropriate.

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

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

The description uses a specific verb ('Make a window active') and resource ('window'), and immediately identifies the source of the id ('from glass_list_windows'). This clearly distinguishes the tool from siblings like glass_list_windows, glass_screenshot, or glass_click by explaining that it sets the target for subsequent operations.

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

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

The description provides clear context for when to use the tool: before screenshot/click/type/window operations, since those will target the selected window and interpret coordinates relative to it. It does not explicitly name alternatives or exclusions, but the usage pattern is strongly implied and reinforced by the schema's note about re-listing rather than caching ids.

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

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

The description discloses the underlying mechanism: direct write where possible, otherwise tap-clear-type, up to three a11y reads, and confirmation. It explains error conditions and the meaning of each error variant, including the decision implication ('write again', 'do not write again'). This goes far beyond the annotations, which are all false and offer no behavioral signal.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is very dense and front-loads the core operation well. All sentences carry meaningful information, especially the error-handling guidance. However, the long run-on paragraphs about error variants and next moves are harder to scan, and a bulleted structure would improve readability without losing content.

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

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

For a tool with no output schema, the description is unusually complete: it covers prerequisities, performanc behavior, error conditions, recovery tactics, return modes, and relation to glass_do. It doesn't explicitly state what a successful result looks like when return is omitted, but the confirmation read-back and error semantics make successful invocatoin inferable. This is a small gap in an otherwise thorough definition.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the baseline is 3. The description reinforces that id comes from glass_a11y_snapshot and repeats return option semantics, but it does not add meaningfully new parameter-level detail beyond what the schema already documents. It adds selectively behavioral context, especially around errors, but not enough to raise the score above baseline.

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

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

The description states a specific verb and resource: 'Set an editable element's value' and anchors the target via '#id from glass_a11y_snapshot'. This clearly distinguishes it from sibling tools like glass_type, glass_click, and glass_do. It is not a tautology and names the batching alternary glass_do at the end.

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

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

It tells the agent to pick the element's id from glass_a11y_snapshot, so the intended pre-recondition is clear. It explicitly says to use glass_do when two or more next actions/waits are known, which is useful routing guidance. It does not explicitly contrast with glass_type, but the semantic 'set value' versus raw typing is reasonably implied.

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

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

With annotations only indicating readOnly=false, openWorld=true, and destructive=false, the description carries the burden and handles it well. It discloses that the tool builds and launches processes, may spawn extra accessibility-bus processes, defaults behavior by host, and can follow a window handed off to an unrelated process — all useful behavioral context beyond the raw annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Four dense sentences, with the core purpose and return value front-loaded. Every sentence adds useful guidance: backend choice, a11y behavior, and window_hint semantics. No filler or restatement of schema details.

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

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

For a complex 9-parameter tool with a nested object and no output schema, the description covers the key behavioral decisions, default selections, platform scope, and how to locate the correct window. Combined with the very rich input schema, an agent has enough context to invoke the tool correctly without guessing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the schema already documents every parameter thoroughly. The description adds value by synthesizing the most important defaults and decision points: backend defaults to the host, a11y is on by default, and window_hint disambiguates windows or handles process handoff. This is modest but real added meaning beyond the schema.

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

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

The description opens with a specific verb plus resource ('Build, launch, and locate a native GUI app') and states the return value ('returns its window geometry'). It clearly distinguishes glass_start from the sibling tools by framing it as the app-launch entry point rather than an inspection or interaction tool.

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

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

The description gives concrete usage direction: pick a backend with the `backend` param, pass `a11y:false` for pixel-only apps, and use `window_hint` when multiple windows appear or the process hands off to another process. It does not explicitly name when not to use this tool or contrast it with alternatives, so it stops short of a 5.

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

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

The description goes far beyond the annotations by explaining the graceful shutdown behavior, the slower force-termination fallback, the loss of session-scoped logs and a11y element ids, the persistence of saved baselines, and the no-resume guarantee. This fully discloses the destructive consequences of the call.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is longer than strictly necessary but every sentence carries relevant operational information: shutdown mechanics, session scope, persistence, no-resume, and usage frequency. It is front-loaded with the core action and then builds context logically without unnecessary filler.

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

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

Given the zero-parameter schema and the destructive nature of the operation, the description is complete. It tells the agent exactly what will happen, what will be lost, what will survive, when the tool should be called, when it should not be called, and what happens when no session exists.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has zero parameters and the schema coverage is 100%, so there are no parameter semantics to document. The description appropriately does not invent parameter-related detail, and the baseline for zero-parameter tools is satisfied.

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

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

The description opens with a specific verb and resource: 'Stop the running app and end the session.' It clearly differentiates from glass_start by stating there is no resume and only glass_start runs the app again as a fresh session, so an agent can distinguish this from sibling tools.

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

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

The description is explicit about when to use the tool: it is not needed between steps of a task, one session can be driven for as long as needed, and it errors if no session is running. It also directs the agent to glass_start as the only alternative for starting a fresh session.

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

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

The description discloses key behavioral traits beyond annotations: keystrokes are sent individually, not pasted, so per-key handlers run; newline does not press Return; the tool cannot report where text landed; and return modes ('snapshot', 'settle') are explained. Annotations provide no such detail, so the description carries the full burden and does so thoroughly.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is dense but well-structured: main action first, then focus caveat, keystroke behavior, alternative tool, and return options. Every sentence adds information, though it is longer than strictly necessary and could benefit from bullet-style segmentation for faster parsing.

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

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

Given the tool's interaction complexity—focus dependence, keystroke behavior, return modes, and sibling alternatives—the description covers all essential aspects. It explains prerequisites, side effects, limitations, and fallback tools. No output schema exists, but the return modes are clearly described, making it complete for an agent to invoke correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% and both parameters already have descriptions. The tool description adds value by clarifying the practical implications of 'text' (keystroke-level sending, newline behavior) and the exact semantics of each 'return' option, going beyond the schema's brief wording without redundancy.

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

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

The description opens with a specific verb and resource: 'Type a string of text into the focused window.' It immediately distinguishes itself from siblings by noting it does not focus anything and by naming alternatives like glass_set_value and glass_key, so an agent can tell exactly what this tool does.

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

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

The description gives explicit when-to-use guidance: click the field first, prefer glass_set_value for a11y-exposed fields, send newline via glass_key separately, and use glass_do when multiple actions are known. It also states what happens if prerequisites are ignored ('text goes wherever focus already was'), leaving no ambiguity.

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

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

Annotations only supply readOnlyHint=true; the description alone discloses the blocking behavior, the return contract ({matched,elapsed_ms} plus matched element, and {matched:false} on timeout), the error case ('errors if none appeared before the timeout'), the just-launched-app edge case, and that the returned id is reusable with glass_click_element. This is rich behavioral context well beyond the annotations, with no contradiction.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Purpose is front-loaded and every sentence carries a distinct fact: selector rules, condition enum, return shape, timeout semantics, unready-app handling, and glass_do routing — there is no fluff. It runs long and the condition enum restates the schema, but the density is justified for an 8-parameter wait tool.

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

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

With no output schema, the description carries the full return contract and does so completely: matched/elapsed_ms, element with value, id reuse, timeout shape, and the error case. Combined with 100%-covered parameters and readOnlyHint, nothing an agent needs to invoke it correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema covers 100% of the 8 parameters, so the baseline is 3. The description restates selector semantics (substrings, role filter) and the rule that value/value_contains must combine with a selector, adding only minor nuance such as 'value' requiring an 'exact editable value' — most of this repeats what the schema already documents.

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

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

Opens with a specific verb and resource: 'Wait for semantic transition completion: block until an accessible element reaches a condition and optional value, then return it as text (no image).' It also scopes itself against siblings by asserting it verifies 'runtime semantic state, not pixels or visual stability,' clearly separating it from glass_wait_stable and screenshot-based tools.

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

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

Gives an explicit when-not with a named alternative: 'If at least two next actions or waits are known, use glass_do instead of separate calls,' and frames itself as replacing 'screenshot poll-loops.' However, differentiation from the other wait siblings (glass_wait_for_log, glass_wait_for_region, glass_wait_stable) is only implicit via 'accessible element' and 'not pixels or visual stability,' not stated as explicit exclusions.

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

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

Discloses blocking semantics, timeout behavior returning {matched:false}, the exact return shape, cursor semantics, and the default time window. Annotations mark this as readOnly and non-open-world, and the description adds timing and continuation behavior without contradiction.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is four sentences, dense and front-loaded with the core action. Every sentence contributes essential behavior, and the detailed return-shape note is warranted because no output schema exists. It is slightly longer than minimal but not wasteful.

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

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

For a blocking timeout tool with no output schema, the description fully covers return values, timeout behavior, and cursor continuation. All 5 parameters are documented in the schema, and optional poll/default settings are present. Minor gaps like explicit error cases do not undermine usability.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, but the description adds meaningful semantics beyond the schema: it clarifies that cursor from glass_logs can catch a pre-existing line, explains the resume behavior, and highlights stream optionality. This exceeds the baseline for fully-covered schemas.

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

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

Description states a specific verb ('Block until...'), resource ('log line'), and conditions ('contains', optional 'stream'). It clearly differentiates from sibling tools like glass_logs by emphasizing wait-until behavior and from other wait_* tools by focusing on logs and cursor semantics.

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

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

Description gives practical context: default behavior matches only new lines, pass a cursor from glass_logs to catch an earlier line, and resume from returned cursor. It references glass_logs explicitly, implying a usage sequence, but does not state explicit when-not-to-use or name alternative tools beyond glass_logs.

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

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

With readOnlyHint=true already present, the description adds meaningful behavioral context: blocking semantics, default until='changes', matches requiring a baseline, no image unless include_image:true, and the important caveat that this verifies pixels, not semantic state or subsequent stability. It goes beyond annotations and does not contradict them.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Dense but efficient: the first sentence establishes the blocking behavior and return shape, later sentences cover parameter modes, the primary use case, and the critical exclusion from semantic/stability checks. Every sentence earns its place with no filler.

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

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

Despite 11 parameters and no output schema, the description covers the essential output structure, key parameter relationships, the main use case, and the alternatives. The remaining parameters (timeout_ms, interval_ms, ignore, window_id) are fully described in the 100%-coverage schema, so nothing critical is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the schema carries the parameter details; the description still adds cross-parameter relationships not obvious from the schema alone — 'matches' needs a baseline, 'mode' pairs with threshold/tolerance, and include_image gates image output. This is useful but not a full re-derivation of the schema.

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

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

The description names a specific verb ('wait'), resource ('visual region'), and the two conditions (change or match) with return value details. It also explicitly distinguishes itself from glass_wait_for_element and glass_wait_stable, so an agent can tell them apart without opening schemas.

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

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

It gives explicit when-to-use guidance ('Use matches to confirm the UI reached an approved design without spending vision tokens') and explicit when-not-to-use guidance with named alternatives ('use glass_wait_for_element for accessible conditions/values and glass_wait_stable when animation completion means visual quiescence').

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

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

The description goes beyond the readOnlyHint annotation by clarifying that this tool proves stability, not that a specific semantic state or pixel design was reached — a key behavioral caveat. It also documents the optional include_image:false path for text-only metadata and notes that region only crops the returned frame. It doesn't mention all parameter interactions, but the schema already covers those details.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is compact and front-loaded: the core definition and the semantic distinction from sibling tools appear in the first two sentences. The later sentences about optional parameters and batching are efficient. It earns a 4 rather than 5 because it packs several ideas into a dense paragraph and could be slightly more scannable, but it has no wasted words.

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

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

For a tool with 9 parameters, all documented in the schema, and a readOnlyHint annotation, the description is complete enough. It communicates the tool's guarantee (stability, not semantic state), routes to alternatives, and surfaces the include_image optimization for text-only workflows. An agent can select and invoke this tool correctly without further clarification.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents all parameters thoroughly, including tolerance, stability_region, ignore, window_id, timeout, interval, settle_frames, and include_image. The description adds high-level meaning for stability_region and region and mentions include_image's performance benefit, but the detailed semantics live in the schema, so baseline 3 is appropriate.

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

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

States a specific verb and resource: 'Wait for visual quiescence' and defines the stopping condition as consecutive frames no longer changing, then returning the last frame. The description also clearly distinguishes this from sibling tools glass_wait_for_element and glass_wait_for_region, so an agent can tell them apart without inspecting schemas.

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

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

Provides explicit when-to-use guidance by naming alternatives: use glass_wait_for_element for semantic conditions/values and glass_wait_for_region with a baseline for expected pixels. It also gives a batching direction: use glass_do instead of separate calls when at least two next actions or waits are known.

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

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

Annotations (readOnlyHint: false, destructiveHint: false) already convey that the tool can mutate but is not dangerous. The description adds value by splitting behavior into mutating operations (focus, resize, move) and a read-only one (geometry). It does not, however, disclose consequences such as focus stealing, whether resize/move out-of-bound values are clamped, or whether geometry is returned in window-relative or screen coordinates beyond the x/y note 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.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence with a scannable op list, no filler, and the core action is front-loaded. It earns a 4 rather than 5 because the omitted target-window context and the shorthand 'window' without a definition make the sentence slightly under-specified rather than merely concise.

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

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

For a multi-operation tool with 5 parameters, the description plus schema covers dispatch semantics well, including per-param conditions and coordinates. But there is no output schema, and the description does not state what 'geometry' returns, which window the action applies to, or whether calls are relative to the currently active/selected window. These gaps are meaningful but partially offset by the very detailed schema.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, and each parameter description already explains its meaning, per-op requirements, and coordinate semantics. The tool description itself adds no new semantic detail beyond naming the op values. With full schema coverage, the baseline of 3 is appropriate; the description does not need to compensate.

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

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

The description names concrete verbs (focus, resize, move, read geometry) against a clear resource (the window), so an agent quickly understands what the tool does. It is distinguishable from siblings like glass_select_window and glass_move because the word 'window' anchors the resource. It loses a point for not stating which window is targeted or how that target is established.

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

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

The 'op: focus|resize|move|geometry' list implies usage dispatch, and the schema reinforces per-parameter conditions ('required there and ignored otherwise'), which is decent guidance. However, the description never says when to use this tool instead of related tools — for instance, whether the targeted window must first be selected via glass_select_window, or whether op:"move" is the right path versus the sibling glass_move. The guidance is implied rather than explicit.

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