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

Annotations already declare readOnlyHint=true, so no safety contradiction. The description adds valuable behavioral context beyond annotations: boxes 'can drift' and the user should 'inspect action results', plus the error condition 'without a tree'. This informs the agent about reliability and failure modes.

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 tightly packed sentences: the core action, the intended usage of results, and a caveat plus alternative. Every sentence earns its place, and the most critical 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 zero-parameter, read-only tool with no output schema, the description tells the agent what the tool produces, how to consume the result, what can go wrong, and which sibling to fall back to. Nothing essential for correct invocation 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 tool has zero parameters, so schema coverage is trivially 100% and the baseline is 4. The description adds no parameter syntax, but none is needed; it instead clarifies that the produced IDs are output artifacts, not inputs, which is relevant for post-processing.

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: 'Capture a screenshot with numbered accessibility boxes and a text legend.' This clearly distinguishes it from siblings like glass_screenshot (plain screenshot) and glass_a11y_snapshot (accessibility tree), and it adds the distinctive detail that the boxes carry numbers usable with click_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?

The description gives explicit when-to-use and when-not-to-use guidance: 'Use the IDs with a click_element action' names the downstream interaction pattern, and 'Errors without a tree; use glass_screenshot' explicitly tells the agent to fall back to another tool when the accessibility tree is unavailable.

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 convey readOnlyHint=true; the description adds substantial behavioral context: values can be absent/redacted/truncated, IDs renumber on each snapshot, a childless Document notice requires one fresh read followed by pixels, and errors without an accessibility tree should fall back to glass_screenshot. These are exactly the failure modes and re-read behaviors an agent cannot infer from annotations or 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?

Five dense sentences, each carrying distinct information, with the core purpose front-loaded in the first clause. The collapsed workflow quirk sentence ('A childless Document notice... an unpublished-content placeholder') is terse to the point of requiring careful parsing, but 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?

With no output schema, the description fully covers return contents (IDs, roles, names, values, bounds, states), value fidelity caveats, ID refresh behavior, error conditions and their fallback, and batching guidance. For a read-only snapshot tool whose safety profile is already covered by annotations, 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 coverage is 100%: the schema for max_nodes already documents the node cap, server default, 0-for-unlimited behavior, and the ID-renumbering consequence of changing the cap. The description itself adds no parameter detail, but with the schema carrying the full burden, the baseline 3 is correct.

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 opening sentence names a specific verb ('Read') and a specific resource (the current semantic state), then enumerates exactly what is returned: IDs, roles, name/description, bounded editable value, bounds, and states. This makes it immediately distinguishable from siblings like glass_screenshot (pixels), glass_wait_for_element (exact verification), and glass_a11y_marks.

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 names three explicit alternatives with the conditions that select them: wait_for_element when exact verification is needed (values may be absent/redacted/truncated), glass_screenshot when there is no accessibility tree or content is image-based (childless Document notice, unpublished-content placeholder), and glass_do for batching known actions and checks. This is textbook when-to-use-vs-alternatives 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?

Annotations are thin (only safety hints), so the description carries the behavioral burden — and it delivers: silent replacement of existing names, persistence across glass_stop, and expiry at server exit are all explicitly disclosed. 'Settle first if animating' also pre-announces a likely failure mode for unstable windows.

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 terse sentences, each carrying distinct information: the core action, the animation prerequisite, replacement behavior, and lifecycle semantics. Primary purpose is front-loaded with zero 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 single-parameter save operation with no output schema, the description covers action, prerequisite, side effects, and lifecycle. The only unaddressed gap is the success/return signal, which is minor for a tool this simple.

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% — the schema already documents the ASCII character restriction, silent replacement, and downstream consumers for the name parameter. The description repeats the consumers rather than adding new parameter-specific meaning, matching the baseline baseline of 3.

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 + resource ('Save the whole current window as a named pixel baseline') and names the downstream consumers (glass_diff, glass_wait_for_region), differentiating it from capture-only siblings like glass_screenshot. The 'whole current window' scope makes the action precise and immediately actionable.

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 clear usage context by naming the two tools that consume baselines and gives a concrete prerequisite ('Settle first if animating') that ties into sibling tools like glass_wait_stable. It doesn't explicitly state when-not-to-use or name an alternative, 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 adds useful behavioral context beyond the readOnlyHint/openWorldHint annotations: no session required, default backend behavior, status semantics, and the caveat that profile membership does not imply backend support. It does not contradict annotations and gives an agent realistic expectations about tool 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 compact and front-loaded with the core purpose, then efficiently adds status categories, notes, session requirements, and caveats. Every sentence contributes distinct information with no filler or redundancy.

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 tool with one optional parameter and no output schema, the description explains what will be reported (status per tool, tool_profile, notes) and key call semantics like default backend and session requirements. It is complete enough for correct invocation, though it could be slightly more explicit about the response shape.

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 already provides 100% coverage for the single backend parameter, including valid values and default behavior, so the description does not need to compensate. It adds the profile-membership caveat, but much of the backend defaulting information repeats 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 uses a specific verb ('Report') and identifies the resource: live backend operation status, affected exposed tools, and tool_profile. It also enumerates the status categories, which clarifies scope. However, it does not differentiate from sibling tools such as glass_doctor, so it falls short of full sibling distinction.

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 implies the tool is used to check backend capability/status and notes that no session is required and the default backend is used. It does not explicitly say when to prefer this over sibling diagnostic tools or provide when-not conditions, leaving usage selection partly 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 convey readOnlyHint=false and destructiveHint=false. The description adds the useful window-relative coordinate context, but it does not disclose further behavioral details beyond what a click operation implies, and the optional button/count/modifiers mostly restate schema properties.

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 two sentences with no filler: the primary action is front-loaded, optional parameters are summarized in one clause, and the alternative tool is routed in the second sentence. 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?

For a simple click tool, the description plus full parameter schema covers the coordinate space, optional arguments, and multi-step routing via glass_do. No output schema exists, but a return-value explanation is not essential for a click operation.

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%, with each parameter already described in the input schema. The description's mention of button, click count, and modifiers adds no new meaning beyond those schema descriptions, 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 uses a specific verb ('Click') and a clear resource ('a window-relative point'), and it lists the optional inputs. It also distinguishes itself from glass_do, which is the main sibling an agent might confuse it with.

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 states a routing rule: 'For 2+ known steps, use glass_do.' This tells the agent when to choose an alternative, leaving the single-click case clearly as the context for this tool.

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 set readOnlyHint=false, destructiveHint=false, leaving the description to carry the full behavioral burden. The description does this well: it discloses that native actions may bypass occlusion or focus text editors, that pointer waits for stability and reports actionability, that method/native_fallback/actuated_id disclose the path, that popover actions restore the prior window, and that Glass never retries after possible dispatch. These are rich behavioral traits beyond what annotations offer.

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 and then provides a dense set of behavioral notes. Every sentence contributes new information without redundancy, though the density may require careful parsing. It is appropriately sized for a tool with complex behavior.

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 6 parameters, no output schema, and minimal annotations, the description covers many critical aspects: target resolution, timeout, modes, retry behavior, and fallback mechanics. It does not detail max_nodes or return behavior, but those are partially covered by schema descriptions. The description is complete enough for an agent to call the tool correctly in most scenarios.

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 only 33%, so the description must compensate. It explains timeout_ms (10 seconds default) and mode (auto/native/pointer semantics), which adds value. However, it does not explain max_nodes or the exact use of target/id beyond the exclusivity mention, leaving some parameters under-specified. The description adds meaningful but incomplete parameter context, warranting a score above baseline but not high.

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 'Click exactly one id or target,' which clearly states the verb (click), the resource (one element identified by id or target), and the constraint of exactly one. It also names a sibling alternative, glass_do, for multi-step actions, helping distinguish the tool's purpose.

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 for when to use this tool vs glass_do ('For 2+ known steps, use glass_do') and explains the mode selection logic (auto/native/pointer). It does not mention the simpler glass_click sibling, but the core usage context is clear enough for an agent to decide when to invoke this tool.

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 declare readOnlyHint=true, and the description adds behavioral context beyond that: it notes that include_image:true returns the changed crop only when pixels differ, and that a single comparison is insufficient for quiescence. It doesn't detail return stats format, but the read-only nature is covered by annotations and the description adds meaningful caveats.

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 waste. The core function is front-loaded, the critical caveat about quiescence follows immediately, and the include_image behavior is stated precisely. 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?

For a read-only comparison tool with 100% schema coverage and no output schema, the description covers the essential behavioral caveats: single comparison is not quiescence, use wait_for_region for waiting, and image return behavior. It could mention what 'change stats' includes, but the schema and read-only annotation carry much of the burden.

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 9 parameters. The description adds value by explaining the include_image behavior (crop only when pixels differ) and the mode semantics, but most parameter meaning is already in the schema. 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 ('Compare current pixels with a named baseline') and resource ('named baseline'), and distinguishes itself from siblings by naming glass_wait_for_region as the tool to use for waiting. It clearly identifies the tool's core function: returning change stats and bbox.

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 a single comparison does not establish transition completion or quiescence, and directs the agent to use glass_wait_for_region to wait. This provides clear when-to-use and when-not-to-use guidance, differentiating it from the waiting tool.

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, which only declare readOnlyHint=false, destructiveHint=false, openWorldHint=false. It discloses fail-fast behavior, the shared deadline semantics, default timeout and range, what 'ok:true means', the structure of success vs. failure returns, terminal settle/diff/screenshot behavior, preflight invalid_sequence behavior, semantic target freshness, and a critical warning: 'Never replay completed or possibly dispatched mutations; observe after uncertainty.' This is precisely the kind of behavioral context 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 and packs a lot of information, but every sentence contributes a distinct fact: limits, defaults, failure modes, terminal observation, and restrictions. It is front-loaded with the core purpose and the accepted action list. It is not padded, though it is a long wall of text for a tool definition; a slightly more structured layout (e.g., headings) could improve scanability.

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 batching tool with no output schema, the description covers all the essentials an agent needs to call it correctly: the action vocabulary, size limits, timeout behavior, success/failure return structures, terminal observation semantics, and critical caveats about mutations and semantic targets. It even explains what happens on preflight invalid_sequence. Nothing critical is missing given the schema already documents individual action arguments.

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 covers 100% of parameters with descriptions, the tool description adds operational meaning not present in the schema: 'Maximum 64 actions and 65536 compact argument bytes,' the default timeout (30000ms) and range, the single shared deadline for all actions and observations, and the return contract ('ordered steps with result and content_blocks'). It also clarifies the semantics of `then` ordering (settle → diff → screenshot) and how failures retain `completed, failed, unexecuted` steps. This is substantial additional meaning, not mere repetition.

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 opening sentence states a specific verb and resource: 'Batch 2+ known actions or waits here; observe before choosing dependent steps.' It distinguishes itself from the 30 sibling tools by positioning glass_do as the batching/sequencing tool, and enumerates the exact action types it accepts (click, move, drag, scroll, type, key, settle, etc.), leaving no ambiguity about what it 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 clearly implies when to use it: when you have multiple known actions or waits that should run as an ordered sequence, with observation between batches. It also states what it cannot do ('No branching, bindings, loops, retries or generated steps'), which helps an agent avoid misusing it. It doesn't explicitly say 'use this instead of calling standalone sibling tools individually,' but the context of batching makes that evident.

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 important behavior beyond the annotations: returns structured report sections and an overall verdict, reports statuses such as ok/warn/fail/skip, and warns that non-default backend failures only affect the overall verdict as warnings. It also explicitly notes that deep starts and tears down the default display, which is a useful side-effect disclosure.

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 information-dense: three sentences cover purpose, return shape, statuses, backend-failure nuance, and the deep flag's side effect. It is appropriately sized for the tool's behavior, though the output-structure explanation could be slightly more 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?

With only one parameter and no output schema, the description covers the important return fields, overall verdict, status values, and deep behavior. It also gives enough context for branching on 'overall.' It does not explain the exact values of 'overall' or when 'deep' should be used, but these are minor gaps.

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 'deep' parameter with 100% coverage. The description adds only the phrase 'deep also starts and tears down the default display,' which largely mirrors the schema's own description, so the parameter semantics do not get much additional value from the 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 uses a specific verb and resource: 'Diagnose setup or launch failures' and explains the return format. It is clear, but it does not explicitly distinguish this tool from diagnostic-looking siblings such as glass_logs or glass_capabilities.

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 clear context for when to use the tool: when diagnosing setup or launch failures. It does not mention alternatives or exclusion criteria, but it does explain the optional 'deep' mode and its effect, giving the agent enough context to decide.

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 (readOnlyHint=false, destructiveHint=false, openWorldHint=false), so the description must carry the behavioral burden. It does well by disclosing the holding of the button/modifiers, the duration control, and the endpoint refusal condition. It also notes in the parameter description that faster motion gives the app fewer sampled frames, which is valuable. It does not disclose side effects (e.g., whether this triggers navigation or state changes) but for a drag tool the key behaviors are covered.

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 succinct - three sentences that cover the core action, a key constraint, and routing to alternatives. It is front-loaded with the primary action and immediately provides differentiation. Every sentence earns its place, with no redundancy.

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 no output schema and the complexity is moderate, the description covers the core action, constraints, and sibling routing. It does not specify the return value or error behavior, but that is often implicit. The guidance on duration effects and endpoint refusal is sufficient for an agent to call it correctly. Missing a brief note on the default button and modifier behavior is negligible because the schema covers those defaults.

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 description coverage is 100%, so the schema already documents all parameters clearly. The description adds minimal extra semantic value: it explains the holding behavior and the effect of duration on sampling, but the parameter details are already comprehensive. Thus a 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 clearly states the action (drag one pointer from (x1,y1) to (x2,y2)) and the resource (a pointer in a window), with specific details about holding the button and modifiers. It explicitly differentiates from siblings by naming glass_gesture for multi-touch and glass_do for 2+ known steps, which are the primary alternatives.

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 explicit usage guidance: for multi-touch use glass_gesture, for 2+ known steps use glass_do. It also mentions the constraint that either endpoint outside the window is refused, which sets expectations for when the tool cannot be used. This is thorough and specific.

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 readOnly/openWorld annotations, the description discloses matching fields, default and cap for max_results, timeout behavior, the return shape ('actionable IDs, compact context and explicit truncation'), the 'untrusted' nature of matches, and the 8 KiB total-text cap. This is rich behavioral context that annotations alone do not provide.

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 three dense sentences with no filler: purpose and trigger come first, then matching semantics and parameter limits, then return behavior. Every sentence earns its place, and key operational constraints are packed efficiently.

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 there is no output schema, the description does a good job of describing what the caller gets back: ranked IDs, compact context, explicit truncation, and a bounded result set. It could be clearer about what 'ranked' means and the exact structure of the returned matches, but it is sufficient for selecting and invoking the 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 coverage is 100%, so the baseline is 3; the input schema already documents query matching, within's semantic scope, max_results range, and timeout semantics. The description largely restates these facts ('max_results defaults to 10, capped at 20') and adds only minor gloss such as 'within must match one semantic scope.'

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 resource ('accessibility candidates') with a concrete verb ('Find') and ties it to a clear triggering condition: 'when the target is approximate, duplicated, or not yet identified.' It does not explicitly name or contrast sibling tools such as glass_wait_for_element or glass_a11y_snapshot, so it stops short of full sibling differentiation.

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 a clear use context: this is the one-shot ranked search for ambiguous or unknown targets, and it clarifies the single-read timing model. It does not state exclusions or explicitly point to alternatives, but the 'one fresh read' phrase distinguishes it from wait/snapshot-style tools without naming them.

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 (readOnlyHint=false, destructiveHint=false, openWorldHint=false), the description reveals important behavioral traits: all pointers go down simultaneously at t=0 and up at duration_ms, a from==to pointer is held, and multi-touch may return an Unsupported error depending on backend. 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?

The description is information-dense with no wasted words. It front-loads the core purpose ('multi-touch gesture'), packs constraints into the first sentence, and uses the second sentence for examples and a backend caveat. Every clause 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?

For a tool with no output schema and only two parameters, the description covers what an agent needs: the gesture model, pointer count range, timing behavior, held-pointer semantics, and the backend limitation. Together with the fully described schema, this is sufficient 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 description coverage is 100%, so the schema already documents the pointers array and duration_ms. The description adds value by describing gesture patterns (pinch, rotate, swipe) and clarifying that all pointers are synchronized, but most parameter meaning is already present in the schema, so the additional contribution is moderate.

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') and resource ('multi-touch gesture') with precise scope: 2–10 pointers, each a straight from→to segment in window-relative px, all down together at t=0 and up at duration_ms. This clearly differentiates it from single-pointer siblings like glass_drag, glass_click, and glass_scroll.

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 use cases: pinch, rotate, two-finger swipe, and held pointers. It clearly implies this tool is for multi-touch gestures rather than simple single-pointer interactions, though it does not explicitly name when-not-to-use it or point to specific sibling tools for single-pointer alternatives.

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?

Adds behavioral detail beyond annotations: 'releasing modifiers afterwards' and 'Unknown keys/modifiers fail before input'. These are not present in the minimal annotations and help the agent predict side effects and failure modes.

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 tight sentences with no filler. The main action is front-loaded, followed by key behavioral notes and sibling routing. 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?

For a simple single-parameter tool, the description adequately covers purpose, usage, and behavior. It does not mention return values, but the absence of an output schema and the tool's nature make this less critical. Minor gap, not a major omission.

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%, fully describing the 'chord' parameter with modifier list and examples. The tool description adds no new semantic information about the parameter beyond what the schema provides, so baseline 3 applies.

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: 'Press a key chord' with examples. It distinguishes itself from glass_type ('Use type for literal text') and glass_do ('For 2+ known steps'), clearly differentiating 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?

Explicitly tells when to use alternatives: use glass_type for literal text, use glass_do for sequences. It also clarifies that this tool handles shortcuts, which is a clear usage condition.

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?

Annotation Contradiction: the description instructs agents to re-list after windows open/close, implying the output changes with external world events, but the annotation openWorldHint=false explicitly declares the tool's output is not affected by world changes. This is a direct contradiction with the description's stated 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?

Two sentences with no filler. The first sentence names the action and output fields; the second gives a critical caching caveat. Information density is high and the key behavioral note is placed at the end without burying the purpose.

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 list tool with no output schema, the description adequately enumerates the returned fields and warns about ID stability. However, the contradiction with openWorldHint leaves the expectations about world dynamics ambiguous, preventing a perfect score.

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 100%, so the schema already fully describes the input. The description need not add parameter detail; the baseline of 4 applies because there is nothing missing.

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 'List app windows' – a specific verb and resource – and enumerates the returned fields (id, title, class, geometry, active state). This clearly differentiates it from siblings like glass_select_window (which selects) and glass_a11y_snapshot (which captures accessibility data) without needing to open 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 provides actionable guidance: 'Re-list after windows open/close; do not cache IDs.' This tells the agent when to invoke the tool again and warns against reusing stale window IDs. It does not explicitly name alternatives or exclusion cases, but the context for correct usage is 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?

The annotation readOnlyHint=true already covers the non-destructive nature, but the description adds valuable operational details: buffered lines age out, cursor-based resumption, filtering, and that app text is untrusted. These behaviors are not available from the annotations alone and materially affect how an agent should use 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?

Four short sentences cover purpose, filtering, cursor semantics, workflow integration, retention behavior, and a trust warning. The most important information is front-loaded and every sentence contributes new value.

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 tool with four optional parameters and no output schema, the description provides sufficient context: how to start reading, resume with a cursor, filter, and prepare for waiting. It does not fully spell out the return payload shape, but the cursor-resumption language and pointer to glass_wait_for_log make the main workflow clear without an output 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%, so the structured definitions already explain cursor, stream, contains, and max_lines. The description reinforces the cursor/filter concepts and adds workflow context around cursors, but it does not materially enrich parameter meaning beyond what the schema 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 names a specific verb ('Read'), resource ('buffered stdout/stderr'), and immediate purpose ('verify completed actions'), making the tool's role unmistakable. The phrase 'now' and the reference to glass_wait_for_log help distinguish it from the waiting-oriented sibling.

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 concrete workflow guidance: drain logs before an action, save the final cursor, and use that cursor with glass_wait_for_log. It clearly frames when to read logs ('now to verify completed actions'), though it does not explicitly enumerate when not to use this tool or name direct alternatives beyond glass_wait_for_log.

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 states the core behavioral trait: moving the pointer without clicking or dragging. It also clarifies the window-relative coordinate semantics, which is useful context even though the schema already mentions it. With readOnlyHint=false and destructiveHint=false, the mutation semantics are consistent and adequately disclosed.

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 core action comes first and the alternative-tool routing is appended as a single conditional clause. Every word contributes.

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 two-parameter pointer-move tool, the description plus full schema coverage is sufficient. No output schema is needed for a side-effect operation, and the sibling guidance covers the main ambiguity.

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%, with x and y each described as 'Destination ... in window-relative pixels'. The description adds no new parameter-level detail beyond the schema, so a 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 uses a specific verb ('Move') and resource ('the pointer') plus a precise coordinate space ('window-relative point'). It clearly distinguishes this from sibling tools like glass_click or glass_drag by framing it as a pure pointer move.

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 names the alternative glass_do and gives the condition for choosing it ('For 2+ known steps'). This gives the agent actionable routing guidance beyond what the schema or tool name provides.

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, and the description adds significant behavioral context beyond that: output format (lossless WebP), clipping behavior for off-display captures, error conditions for fully off-screen surfaces, and the non-intrusive nature of window_id. No contradictions 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?

Three sentences with zero waste. The core purpose is front-loaded, followed by two high-value behavioral notes. Every sentence earns its place, and the structure is highly scannable.

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 is complete for a screenshot tool with no output schema. It covers output format, clipping and error behavior, and window selection semantics. An agent has everything needed to invoke it correctly and interpret results. No gaps that would cause mis-calls.

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 each parameter (region, max_width, window_id, max_height) is already documented. The description adds minimal extra parameter-specific meaning—the window_id observation behavior is already in the schema. It does clarify overall output behavior (dimensions disclosure) but that is not parameter semantics. 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 action ('Capture current visual evidence as lossless WebP') and clearly distinguishes it from 'semantic state or transition completion', which sets it apart from sibling tools like glass_a11y_snapshot or glass_wait_for_region. This is a precise verb+resource statement that leaves no ambiguity about the tool's function.

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 implies when to use it ('when you need visual evidence') and explicitly contrasts it with semantic state checks. It also provides guidance on window_id usage ('observes without switching the active window'). However, it does not name specific alternative tools or explicit exclusion conditions, so it falls short of a perfect 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?

Annotations already declare readOnlyHint=false and destructiveHint=false, indicating a mutating but non-destructive operation. The description adds that scrolling uses wheel notches rather than pixels, which clarifies the effect. It does not describe potential side effects or error conditions, but given the annotations cover the safety profile, the added context is sufficient.

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 purpose and key parameters, the second clarifies units and provides the alternative. No wasted words, and the critical scoping 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-scroll action with no output schema, the description covers the purpose, the alternative for multi-step sequences, and the unit semantics. Nothing essential is missing for an agent to invoke it 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%, so the schema already documents all parameters including dx/dy as notches. The description reinforces the 'not pixels' distinction, which adds a critical clarification beyond the schema's 'wheel notches' wording. This adds value 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 clearly states the action ('Scroll the container under (x,y)') with a specific verb and resource, and distinguishes itself from the sibling glass_do by explicitly noting when to use that alternative. It also clarifies the unit of measurement (notches vs pixels), which is essential for correct usage.

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 guidance on when to use an alternative: 'For 2+ known steps, use glass_do.' This directly informs the agent of the boundary between this tool and a related sibling. It also clarifies the notches unit, which is a usage constraint.

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 sweep-then-reverse behavior, return fields, timeout and end-of-scroll failure modes, the absence of tree errors, and batched sequence failure semantics. The annotations are sparse, so this description carries the behavioral burden effectively.

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?

Roughly sixty words, front-loaded with the core action, followed by return values, failure modes, batched behavior, and a routing note. Every sentence contributes information without redundancy.

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?

Covers action, return fields, direction handling, timeout behavior, failure semantics, and sibling routing despite having no output schema. Minor gaps remain around what 'on-screen' means exactly and the shape of the returned element, but the context is strong for a complex automation 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 coverage is 100%, so the baseline is 3 and the description need not re-explain parameters. It adds useful context about direction sweeping and timeout behavior, but no per-parameter semantics 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?

States a specific verb and resource: 'Scroll until a semantic element is actually on-screen'. It clearly distinguishes the tool from glass_do by naming the alternative, and the unique role is evident from the description alone.

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 clear context for when to use the tool and explicitly routes the user to glass_do for '2+ known steps'. It could more fully contrast with sibling scroll/find tools, but the main alternative is covered.

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, the description discloses a meaningful behavioral trait: selection is stateful and influences all later actions and observations, including coordinate interpretation. This is useful context that annotations alone do not provide.

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 deliver the core purpose and the key behavioral consequence with no filler. 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 one-parameter selection tool with rich annotations and full schema coverage, the description covers what selection does, how it affects subsequent operations, and how coordinates are interpreted. No critical operational detail 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 documents the single 'id' parameter, including that it comes from glass_list_windows and should be re-listed after window changes. With 100% schema coverage, the description does not need to add parameter details, and its 'current ID' mention is consistent but not additive.

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 ('Select a window'), a specific resource ('window'), and the key qualifier ('by current ID'). It also explains the consequence of selection, which distinguishes this from listing or inspecting windows among the 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 clearly indicates when the tool matters: before subsequent actions and observations, and when input coordinates should be interpreted relative to the selected window. It does not explicitly name alternatives or exclusions, but the usage context is 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?

Beyond the minimal false hints, it discloses backend confirmation, fresh target resolution, immediate ID behavior, supported write modes, read-back behavior, and terminal post-write uncertainty. 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?

Every sentence carries operational weight, from the core contract to recovery guidance and the sibling reference. It is dense but not bloated, with the most important constraints 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?

It covers the tool's core behavior, error taxonomy, and recovery policy, making the mutation tool much safer to invoke. The main gap is the absence of exact output/error shape, which matters more given there is no output 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?

The schema covers id, text, and return, but leaves target, max_nodes, and timeout_ms largely undocumented. The description adds value by explaining target resolution freshness/uniqueness and ID immediacy, though it does not clarify max_nodes or timeout_ms.

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 ('Set...') with a bounded scope: exactly one editable id or target. It also distinguishes itself from the multi-step sibling by explicitly naming glass_do as the alternative.

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 'For 2+ known steps, use glass_do,' giving a clear routing rule. It also provides when-not-to guidance by warning not to write again on uncertainty and to observe first before recovery.

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 accessibility is enabled by default and that window_hint can locate handoffs—not obvious from the schema alone. It also notes that backend and containment choices are in the parameters, which adds behavioral context. The annotations (readOnlyHint=false, openWorldHint=true, destructiveHint=false) are not contradicted; the tool performs actions but is not destructive. The description adds useful nuance 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 three sentences and front-loaded with the core action (build, launch, locate) and return value (window geometry). It avoids unnecessary fluff. The only minor deduction is that the last sentence is somewhat vague ('See parameters for backend and containment choices') rather than giving specific guidance, but it's still efficient overall.

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 9 parameters, a nested object, and no output schema, the description does not detail return format, error cases, or platform specifics beyond its brief mention. However, the schema carries most of the parameter documentation, and the description covers the high-level workflow. It could be more complete by explaining what 'returns window geometry' implies in practice (e.g., coordinates, size), but given the schema's richness, this is adequate.

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 schema coverage is 100%, the description adds meaning by summarizing how window_hint works (select among windows or locate a handoff) and pointing to backend and containment choices. It does not enumerate each parameter, but it gives a high-level semantic framework that helps agents understand the tool's logic without reading every schema detail. Given the schema is already thorough, this adds value 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 clearly states the tool's purpose: 'Build, launch and locate an app; returns window geometry.' It uses specific verbs and a clear resource (an app), and mentions returning window geometry. It also distinguishes itself from siblings like glass_select_window and glass_window by focusing on the full build/launch/locate workflow.

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 context on when to use this tool (to build, launch, and locate an app) and hints at alternatives via window_hint for selecting windows or handoffs. However, it does not explicitly state when not to use it or name specific sibling tools as alternatives, such as glass_select_window for pure window 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?

Annotations already indicate destructiveHint=true and idempotentHint=true, but the description adds valuable behavioral context: it requests app close first, then terminates if necessary, and clarifies that logs and element IDs are discarded while baselines survive. It also notes that errors occur without an active session. This 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 and front-loaded with the core action ('End the session'), followed by essential behavioral details. Every sentence adds value, and there is no redundancy or 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 zero-parameter tool with no output schema, the description covers the key aspects: what it does, side effects, prerequisites, and error conditions. It could potentially mention what the return value looks like, but the absence of an output schema makes that less critical. The description is complete enough for an agent to invoke it 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, so the description doesn't need to explain parameter semantics. The baseline for 0 params is 4, and the description appropriately focuses on behavior rather than 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's purpose: ending the session by requesting app close and terminating if necessary. It distinguishes itself from siblings like glass_start by explicitly noting that glass_start creates a fresh session and there is no resume.

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 explicit guidance on when to use this tool: at the end of a session. It also gives important context about prerequisites (read logs first) and what happens to data (logs and element IDs are discarded, baselines survive until server exit). This helps the agent decide when to invoke 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?

Despite annotations providing only readOnly/destructive hints, the description discloses key behavioral traits: single dispatch only, unconfirmed focus never types, fresh-element target resolution, no value confirmation, and no replay after uncertain dispatch. This gives the agent a clear safety model for a write-like operation.

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 action ('Type text once') and then delivers a dense set of caveats in compact, purposeful sentences. Every sentence either clarifies behavior, prevents a misuse, or routes to an alternative.

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 write-like tool with no output schema, the description covers the most important behavioral constraints and alternatives. It does not explain the return/snapshot semantics or the undocumented timeout/max_nodes parameters, though the schema partially covers return and the parameter names are suggestive.

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 33%, so the description must compensate. It adds meaningful semantics for text, target, and focus_mode, including the 'one fresh unique element' behavior and the three focus modes. However, max_nodes and timeout_ms receive no added explanation in either schema or description, leaving a partial gap.

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?

'Type text once' is a specific verb+resource statement that immediately establishes the tool's core behavior. It also distinguishes itself from siblings by explicitly routing multi-step work to glass_do and newline handling to a key action.

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 context: type once into current focus or a resolved target, and never replay after uncertain dispatch. It also names an alternative ('use glass_do' for 2+ steps) and a fallback for newlines ('use a key action'), which is strong usage 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?

Beyond the readOnlyHint annotation, it discloses timeout behavior (matched:false), batched-sequence failure, error when no accessibility tree appears, and the exact return fields (matched, elapsed_ms, and the element). These are meaningful behavioral details not present in the annotations, and there is 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?

Purpose is front-loaded, and each sentence covers a distinct concern: scope, selectors, matching semantics, conditions, return values, edge cases, and the sibling alternative. There is no filler, and the brief redundancy with schema timeout descriptions is acceptable given the absence of an output schema.

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 having no output schema, it explicitly states what is returned and how timeout is represented. Together with the fully documented input schema and read-only annotations, an agent has enough information to invoke the tool correctly, understand failure modes, and distinguish it from related tools.

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 already documents all 8 parameters at 100% coverage, so the baseline is 3. The description adds useful selection semantics by stating that name, description, and/or role can be used as selectors and by clarifying exact-value versus substring matching for value and value_contains, which goes slightly beyond the schema's individual property 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 states a precise verb and resource: wait for an element's semantic transition, explicitly contrasted with pixel/stability waiting. It enumerates selection fields and supported conditions, and its scope is clearly distinct from sibling tools like glass_find_elements, glass_wait_stable, and 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?

It gives an explicit exclusion ('not pixels/stability') and a direct alternative for multi-step flows ('For 2+ known steps, use glass_do'). However, it does not explicitly compare against related sibling wait tools such as glass_wait_stable, glass_wait_for_log, or glass_wait_for_region, leaving some routing implicit.

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 surfaces important behavioral details beyond the readOnlyHint: cursor semantics, the need to drain glass_logs in repeated-event scenarios, substring matching behavior, timeout results (`matched:false`), and resuming from a returned cursor. These are non-obvious traits that materially affect invocation.

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 short sentences deliver dense operational guidance with no filler. The most important usage decision (cursor:0 for buffered logs) is front-loaded, and each sentence covers a distinct necessary behavior.

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 covers the key waiting, cursor, timeout, and resume behaviors, and the schema fills parameter details. With no output schema, it could more explicitly define the success return shape, but the mention of `matched:false` and 'returned cursor' gives enough guidance for correct use.

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 documents all five parameters, so the description is not the primary source of parameter meaning. However, the description adds workflow context around cursor: 'for repeated events drain glass_logs before acting and pass its final cursor' and 'Resume from returned cursor,' extending the schema's definitions.

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 implies the tool waits for a log line matching a substring, and it clearly associates cursor behavior with log positions. It references glass_logs, which helps distinguish it from the related log-reading sibling, though it never states 'wait for a log' as an explicit verb+resource declaration.

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, scenario-based usage instructions: use cursor:0 for buffered logs, drain glass_logs before repeated actions and pass its final cursor, and omit cursor to wait only for future lines. This is explicit operational guidance that lets an agent decide exactly how to invoke the tool.

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 declare readOnlyHint=true, so the agent knows this is a safe read operation. The description adds valuable behavioral context beyond that: it explains the return values (matched, changed_pct, bbox, elapsed_ms), the timeout behavior (returns matched:false), the include_image opt-in, and the limitation that it does not prove semantics or quiescence. This is rich, honest behavioral disclosure.

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 purpose is in the first sentence, followed by return values, opt-in behavior, timeout behavior, and a clear limitation with an alternative. Every sentence earns its place; 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 13-parameter tool with no output schema, the description covers the key behavioral aspects: what it returns, timeout semantics, the baseline requirement, and the limitation. It doesn't enumerate every parameter, but the schema already does that. The only minor gap is that it doesn't explain the difference between 'perceptual' and 'exact' modes, but the schema covers that. Overall, complete enough for an agent to call it 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 already documents all 13 parameters. The description adds some semantic context (e.g., 'changes from the initial frame or matches a saved baseline', 'include_image opts into an image on match', 'Timeout returns matched:false'), but it does not systematically explain each parameter's meaning beyond the schema. 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 ('wait for'), a precise resource ('pixel transition completion'), and the two modes ('changes' vs 'matches'). It also names the sibling it is not ('use a settle action for the latter'), which distinguishes it from glass_wait_stable. This is a clear, specific definition.

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 when to use this tool: wait for pixel transition completion, and when not: 'Does not prove semantics or subsequent quiescence; use a settle action for the latter.' It also explains the 'matches' mode requires a saved baseline. This gives the agent clear routing guidance relative to alternatives.

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 and openWorldHint=false already in annotations, the description adds important behavioral nuance: it returns the last frame rather than confirming a semantic state, a timeout returns settled:false, and window_id observes without selecting. These go beyond what annotations and schema already state.

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?

Five short sentences, front-loaded with core purpose, and each sentence contributes either a key distinction, a parameter usage tip, or alternative routing. 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 complex 11-parameter tool with no output schema, the description covers core purpose, timeout behavior, window_id semantics, and routing to glass_do. It does not enumerate all return metadata fields, but those are documented in the schema's include_image parameter.

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 each parameter already has a thorough description. The description re-states some parameter behaviors (include_image, window_id, timeout) but adds no new meaning beyond the schema, so baseline 3 applies.

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 ('wait') and resource ('visual quiescence'), clarifies it returns the last frame, and explicitly contrasts with waiting for semantic state or pixel design, distinguishing it from siblings like glass_wait_for_element and glass_wait_for_region.

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 an explicit alternative condition ('For 2+ known active-window steps, use glass_do') and advises on include_image:false for text-only metadata. It doesn't enumerate all sibling comparisons, but provides clear context for when the tool is appropriate.

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 mark the tool as not read-only, and the description reinforces that by listing mutating operations (focus, resize, move) alongside read-only geometry. However, it doesn't disclose side effects, window targeting assumptions, or what the geometry operation returns.

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 concise sentence with the key verb and resource front-loaded, followed by a compact op enumeration. The second sentence is slightly redundant but serves as a useful quick reference.

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 is workable for a four-operation dispatcher with a well-covered schema, but it omits important context such as which window is affected and how geometry results are returned. Since there is no output schema, this leaves some ambiguity for the agent.

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%, with each parameter already described including conditional requirements like 'required only for move' and 'required only for resize'. The description's op list adds little beyond what the schema already 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 clearly identifies the resource (window) and the specific operations it supports (focus, resize, move, geometry) with a compact enumeration. It is understandable and distinct from many siblings, though it doesn't explicitly contrast with tools like glass_move or glass_select_window.

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 no explicit guidance on when to choose this tool versus sibling tools such as glass_move or glass_select_window. The operation list implies its intended use, but no exclusions or alternative routing are given.

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