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

Annotations already declare destructiveHint=true, idempotentHint=false and openWorldHint=true, so the risk profile is largely carried structurally. The description usefully adds a failure condition (only works when the app exposes a menu model), but omits the high-risk confirmation flow and what activation actually triggers upstream.

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

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

Two tight sentences, no filler, with the action and its data source front-loaded before the mechanism caveat. Every clause carries information.

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

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

No output schema exists, so the description should carry more burden for this destructive mutation. It covers mechanism and the app-menu-model precondition, but leaves the confirmation_token requirement and the likely effect of activation unexplained for an agent deciding how to call it.

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 all three parameters are already documented, including app selectors and the menu:12 id format. The description only reinforces the provenance of menu_index and adds nothing about the confirmation_token beyond what the schema states.

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 ('activate a global app-menu item') and names get_app_state as the source of the item id, plus the underlying mechanism (DBusMenu/GMenu). It clarifies it is not the AT-SPI menu path, though it does not contrast itself against a specific sibling tool by name.

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?

Usage is implied through the dependency on get_app_state ('menu item id from get_app_state'), so an agent can infer the intended workflow. There is no explicit when-to-use/when-not guidance, and no mention of when the confirmation_token path is required.

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 destructiveHint=true, openWorldHint=true and idempotentHint=false, so the safety profile is covered. The description usefully adds that entries are filtered by identity and policy validation and that only safe entries are replayed, but it omits what gets destroyed, that a confirmation token is required, and whether the preflight itself is harmless.

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?

A single front-loaded sentence with no filler, leading with the dry-run action before the optional mutation. The density of undefined jargon costs it a point, but every clause does work.

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 destructive, non-idempotent, open-world tool with no output schema and half-documented parameters, the description should at minimum explain the preflight/replay distinction and the confirmation requirement. It does not, leaving an agent unable to call it safely with confidence.

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 only 50%; only confirmation_token and max_record_age_seconds carry descriptions. The description adds no semantics for 'execute' or 'allow_clipboard', does not explain that execute toggles the replay hinted at by 'optionally', and leaves the 300s default age window unexplained in prose, so it fails to compensate for the coverage 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?

States a specific verb pair ('preflight' the redacted audit journal, 'optionally replay') and a specific resource, which clearly separates it from the UI-automation siblings. However 'preflight' and 'replay' are nonstandard jargon that the description never defines, leaving some ambiguity about what is actually read versus written.

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 word 'optionally' implies a mode switch but never says when to actually enable replay, when to stay in preflight, or what the conditions are that make an entry 'safe'. No prerequisites, no mention of the confirmation flow, and no alternatives are named.

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

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

Annotations already declare destructiveHint=true, readOnlyHint=false, and non-idempotency, so the safety profile is covered. The description adds one genuine behavioral nuance beyond that: element clicks use the native pointer path so the visible cursor overlay appears. It does not, however, surface the confirmation_token/high-risk gating that the schema implies, so it is adequate but not rich.

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 tightly written sentences with the core capability front-loaded and no filler. Both sentences earn their place: the first defines targeting modes, the second adds the pointer-path 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 an 11-parameter mutating tool with no output schema, the description covers targeting and pointer behavior but omits the confirmation flow for high-risk actions and any relationship to the numerous sibling click tools. It is minimally complete but leaves real gaps for selection and risk handling.

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 91%, so the schema documents nearly all 11 parameters in detail. The description only summarizes the three targeting modes (index, name/text, coordinates) that map to element_index/name/coordinate, adding little beyond the schema. Baseline 3 is appropriate when the schema does the heavy lifting.

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 (Click) and resource (visible element) and enumerates three targeting modes: element index, accessible name/text, and coordinates. The purpose is unambiguous, but it does not distinguish itself from the many sibling click tools (left_click, right_click, double_click, click_text, click_mark), so an agent cannot tell from the description alone why it should pick this over those.

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 multiple targeting approaches but gives no when-to-use guidance, prerequisites, or named alternatives among the dense click-tool siblings. There is no statement of when NOT to use it or how it relates to left_click/click_text, leaving selection entirely to inference.

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

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

Annotations already declare destructiveHint=true, idempotentHint=false, openWorldHint=true, and readOnlyHint=false. The description adds useful precondition context ('live identity, geometry, and screenshot-hash validation'), but does not mention the confirmation_token/request_confirmation flow for high-risk actions, which is left to the schema.

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

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

A single front-loaded sentence with zero wasted words. The core action and validation condition are stated immediately.

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 destructive, non-idempotent click tool with six parameters and no output schema, one sentence is insufficient. It lacks usage routing and parameter semantics, leaving the agent without enough textual guidance to invoke it correctly alongside the many click-related siblings.

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%. The description adds no parameter semantics beyond vaguely implying a single bound mark id; app, marks_id, mark_id, click_count, and mouse_button are not explained in text, so it fails to compensate for the low schema coverage.

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: 'Click one bound Set-of-Marks id'. The Set-of-Marks framing implicitly distinguishes it from generic click siblings, but it does not explicitly name when to use this over click, left_click, or get_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 implies usage by requiring a bound Set-of-Marks id and validation, but gives no explicit when-to-use, when-not-to-use, or alternative-tool guidance. The agent must infer that get_marks is a prerequisite and that generic click tools are 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?

Annotations already declare destructive/openWorld/non-idempotent, and the description adds genuine value beyond them by disclosing the pre-input revalidation of screenshot hash, process identity, and geometry (i.e., a stale ocr_id will fail rather than misclick). It omits the high-risk confirmation flow that the confirmation_token parameter implies, and says nothing about failure behavior when revalidation fails.

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 action and target, with no filler. Every clause adds information about what is clicked and what guards the input.

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 destructive, 9-parameter input tool with no output schema and very low schema coverage, the description is too thin: it omits the confirmation-token prerequisite for high-risk clicks, the meaning of match/nth/casefold/click_count, and any error semantics. The revalidation sentence is valuable but does not close the gap.

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

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

Schema description coverage is only 22% across 9 parameters, so the description must compensate and largely does not. Beyond ocr_id and text it explains nothing about match, nth, casefold, click_count, mouse_button, or the confirmation_token needed for high-risk actions, leaving most call-shaping choices undocumented.

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 (click) plus the resource and selection basis (OCR text identified by a current ocr_id), which distinguishes it from coordinate-based siblings like click/left_click and from click_mark. It does not, however, name those siblings or explain how an ocr_id is obtained, so differentiation is inferred rather than stated.

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?

There is no explicit when-to-use or when-not-to-use guidance and no alternatives named, despite a crowded sibling set (click, click_mark, left_click, right_click, activate_menu_item). The phrase 'current ocr_id' faintly implies a prior OCR call but never tells the agent to run `ocr` first or what to do when the ocr_id is stale.

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, destructiveHint=true, openWorldHint=true, so the agent knows this mutates the desktop; the description adds the coordinate-space preference and fallback behavior. However, it says nothing about the high-risk confirmation flow (confirmation_token, request_confirmation sibling), clipboard side effects, or that many actions move/close windows — meaningful behavioral gaps for a destructive 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 with no padding, and the purpose statement leads. But the terminology is confusing ('brand', 'hyprcum namespace') and the ordering buries the fallback rule after an unexplained product name, so the agent must parse awkward phrasing to extract the operational guidance.

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

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

For a tool with 50 enumerated actions, 88 parameters, nested objects, and no output schema, the description explains almost none of the surface: the action enum is described in the schema only as 'Computer use action to perform.' It omits how to sequence a typical session (screenshot/get_app_state to click via app or coordinates), return shapes, and per-action prerequisites, leaving the most complex tool in the set under-documented.

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?

With 88 parameters and only 51% schema description coverage, the description arguably should compensate, yet it only clarifies the app vs. target/global coordinate precedence. That single clarification is genuinely useful for choosing between app, target, x/y, and coordinate_space, but the remaining undocumented parameters (nth, snapshot_id, element_index, etc.) get no help 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 labels this as a compatibility tool for Hyprland background Computer Use with browser/Chromium control, which is a specific domain, but the opaque term 'brand' carries no meaning and the description never says this is a consolidated, multi-action computer-control surface. It only distinguishes itself from siblings implicitly by name-dropping get_app_state and screenshot, despite the schema containing ~50 actions that overlap tools like click, scroll, drag, type, and manage_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?

It gives real routing guidance: prefer app plus get_app_state/screenshot coordinates, treat target/x/y global coordinates as a low-level fallback, and do not use Browser MCP or the obsolete namespace. That is clear when-and-when-not direction, though it omits the condition choosing this mega-tool over the many single-purpose siblings (click, scroll, press_key, etc.).

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 destructive=true, idempotent=false, and openWorld=true, so the safety profile is covered. The description adds only that it is a compatibility alias, which is a weak hint about deprecation/legacy status but discloses nothing about the double-click mechanics, target resolution order (name vs coordinates vs element_index), or confirmation requirements.

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?

One short sentence with no filler and the action front-loaded. It is efficiently sized, though the terseness is a symptom of under-specification rather than deliberate economy.

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 9-parameter mutation tool with no output schema, destructive and non-idempotent annotations, and a confirmation-token flow, a single sentence is far too thin. It omits the target-resolution strategy and any return/failure behavior the agent needs to call it reliably.

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% across all 9 parameters, so the schema fully documents coordinates, selectors, and the confirmation token. The description contributes no additional parameter meaning, which lands at the baseline for high coverage.

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 phrase 'double left click' names a specific action, but 'Compatibility alias' is ambiguous about what it aliases, and the description never distinguishes it from siblings like left_click, click, or triple_click beyond the implicit click count.

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?

No guidance on when to use this versus left_click or click, no mention of the confirmation_token workflow that the schema implies for high-risk actions, and no prerequisites stated.

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 destructiveHint=true, idempotentHint=false and openWorldHint=true, so the safety profile is covered structurally. The description adds the useful distinction that coordinates are screenshot- or window-relative, but stays silent on the confirmation workflow, reversibility, and any side effects of a drag on the target app.

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?

A single front-loaded sentence with zero filler. It is efficient, though arguably terse for a 10-parameter tool with a confirmation workflow that goes unmentioned.

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?

Parameter documentation and annotations are rich, and no output schema is needed. The missing piece is behavioral context around the required confirmation_token for high-risk drags and how this tool relates to left_click_drag, which matters 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 both coordinates, duration, app selector, and coordinate_space are fully documented in the schema itself. The description only loosely ties 'screenshot/window-relative coordinate' to the coordinate_space enum, adding no syntax or format detail beyond the schema baseline.

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

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

Specific verb (drag) plus resource (coordinates) with scope clarification that both start and end points are involved. However, it does not distinguish itself from the highly similar sibling left_click_drag, leaving the agent to guess which of the two drag tools to invoke.

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?

No when-to-use guidance, no exclusions, and no mention of when this differs from left_click_drag or hover. It also fails to state that a confirmation_token may be required before a high-risk drag.

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 cover the safety profile (readOnly, idempotent, non-destructive), and the description adds real value on top: it discloses the three return components and warns about uiHints semantics ('separates AT-SPI menu entries from tab/ribbon/toolbar controls; do not substitute a same-named menu'). It stops short of describing coordinate conventions or pagination/size 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?

Three tight sentences, front-loaded with the return contents followed by sequencing and the uiHints caveat. Every clause carries actionable information with no filler.

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

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

With no output schema, the description correctly compensates by naming what is returned and how element_index/coordinates are consumed downstream, and it flags the menu-vs-tab pitfall. The one missing piece is disambiguation from the similarly named read_app_state sibling.

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?

One parameter with 100% schema description coverage; the schema already documents the app selector formats (name, class/title, pid, address:0x...). The description adds no selector syntax or matching behavior beyond that, so the baseline of 3 is appropriate.

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

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

Names a specific verb and resource and enumerates exactly what the state bundle contains: screenshot, accessibility tree, and uiHints. An agent knows this is a state-acquisition tool distinct from the primitive siblings like screenshot or click without opening the schema.

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

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

Explicitly states sequencing ('Call this before action tools') and the follow-up usage ('then use element_index or screenshot/window-relative coordinates'). It does not, however, differentiate itself from the near-identically named sibling read_app_state, which is the most likely routing ambiguity here.

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, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds the useful fact that coordinates can be expressed in monitor/screenshot/window-relative frames, but says nothing about return shape or any side conditions (e.g. what happens if the pointer is on another output).

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?

A single front-loaded sentence with no filler, and the coordinate-frame detail is placed where it matters. It is efficient, though arguably too terse for the parameter surface it must support.

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-required-parameter read tool with annotations covering safety and no output schema, the description is close to adequate. However, with three parameters at 33% schema coverage, the ambiguity around source and include_global is left unresolved, so it is only minimally sufficient.

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

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

Schema description coverage is only 33%, and the description adds no parameter meaning at all. The enum values auto/hyprland/agent for source and the purpose of include_global are left unexplained in both the schema and the description, which is a real gap an agent cannot resolve.

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 pairs a specific verb ("Return") with a specific resource ("current cursor position") and even names the coordinate frames, which cleanly separates it from write-oriented siblings like move_mouse or click. It never names a sibling explicitly, so it stops short of a 5.

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?

There is no statement of when to call this versus alternatives such as screenshot, get_screenshot, or the move/click family, and no prerequisites or exclusions. The agent must infer usage entirely from the name and context.

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, destructiveHint=false, idempotentHint=true and openWorldHint=false, so the safety profile is covered without the description. The description adds only marginal value beyond that: 'non-destructive' restates destructiveHint=false, while 'opaque marks_id mapping' is genuinely new but leaves open whether marks_id expires, is reusable, or how it relates to snapshot_id.

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?

A single front-loaded sentence with no filler, and the outcome (marks_id) is stated at the end. It is efficient but arguably too terse for an 11-parameter tool, so the economy is not fully earned.

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 an 11-parameter tool with a nested region object, 18% schema coverage, and no output schema, the description is far too thin. It does not explain the marks overlay contents, the marks_id lifecycle, or any of the rendering parameters, so an agent cannot confidently invoke it beyond the required app argument.

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 only 18% (just app and coordinate_space are documented), leaving 9 of 11 parameters undocumented. The description says nothing about zoom, scale, region, quality, format, ocr_id, snapshot_id, max_dimension, or include_elements, and 'bound target screenshot' only loosely implies how app binds the target. Description fails to compensate for the large coverage 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?

States a specific verb (render) and resource (numbered Set-of-Marks overlay) plus the returned artifact (marks_id), which is more precise than a generic 'get'. It does not differentiate itself from siblings such as click_mark or ocr, which are the natural upstream/downstream partners, so an agent must infer the relationship.

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?

There is no explicit when-to-use guidance and no mention of alternatives. The obvious workflow (call get_marks, then click_mark with the resulting marks_id) is never stated, nor is it explained when to prefer this over screenshot or ocr. Usage is only implied by the noun 'marks_id'.

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, idempotentHint, and destructiveHint=false, so the safety profile is covered. Beyond that the description discloses nothing: no indication of what the capture returns, whether it writes files, or how it interacts with the 11 parameters.

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 single sentence is short but that is under-specification rather than conciseness — it spends its only clause pointing at a sibling instead of conveying any actionable information.

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 an 11-parameter tool with a nested region object, three enums, 27% schema coverage, and no output schema, one sentence of alias text is completely inadequate to let an agent 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 description coverage is only 27% across 11 parameters (including an enum-heavy cursor_source, coordinate_space, and a nested region object), and the description adds zero parameter guidance. With low coverage the description must compensate, and it does nothing.

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 only says it is a 'compatibility alias for screenshot' — it never states that it captures a screenshot, what it captures it of, or how it differs from the sibling tool `screenshot`. This is close to restating the name/redirecting rather than defining the tool's actual 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?

Calling it an 'alias' weakly implies it is redundant with `screenshot`, but there is no explicit when-to-use, when-not-to-use, or instruction to prefer `screenshot`. An agent has to guess whether this is deprecated, identical, or subtly different.

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 supply the risk profile (destructiveHint=true, idempotentHint=false, openWorldHint=true), so the bar is lower. The description contributes the useful "compatibility alias" framing (implying a preferred canonical tool) and clarifies no click event fires, but it omits any mention of the confirmation_token / high-risk approval flow that its own schema exposes.

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?

A single front-loaded sentence with no wasted words; the non-clicking constraint appears immediately. It is perhaps too terse for a nine-parameter tool, but nothing is padded.

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 nine-parameter, open-world, destructive-flagged tool with no output schema, one sentence is thin. It says nothing about the required app selector, coordinate-space defaults, element resolution order, or when the confirmation_token flow is triggered, all of which an agent needs 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 nine parameters, including the coordinate_space enum and element_click_mode enum, are fully documented in the schema itself. The description adds no targeting precedence (element_index vs name vs coordinate) or app-selector guidance, so the 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+resource ("move the background pointer to an element or coordinate") and adds a distinguishing scope note ("without clicking"), which separates it from the many click* siblings. However, "Compatibility alias" never says what this aliases (presumably move_mouse), leaving the relationship to siblings ambiguous.

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?

There is no explicit when-to-use guidance. The "without clicking" clause hints at a non-clicking alternative to click/move_mouse but never names those siblings or states a condition for choosing hover over them, despite ~40 sibling tools including move_mouse, click, and click_text.

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 destructiveHint=true, idempotentHint=false, and openWorldHint=true, so the safety profile is covered structurally. The description adds the alias equivalence and accepted input flexibility, but says nothing about the confirmation_token / high-risk approval flow or the effect on the target app, leaving behavioral context thin.

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 clauses, front-loaded with the alias relationship, and zero filler. Every word earns its place and nothing is buried.

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 and a fully described input schema, the description covers the alias role adequately, but for an 8-parameter mutating tool it omits the confirmation_token workflow and how the multiple key-input parameters relate, which an agent needs 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 every one of the 8 parameters is already documented in the schema. The description merely lists the same parameter names without adding format, precedence, or mutual-exclusivity rules (e.g., how key vs keys vs keycode interact), so the 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?

States it is a compatibility alias for press_key and enumerates the input forms it accepts, so an agent can infer the resource (a key press) and its relationship to the press_key sibling. However, it never uses a direct verb like 'presses a key' and depends on the agent already understanding press_key's behavior.

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?

Calling it a 'compatibility alias' implies it should be used when the alias-style inputs (key, keys, modifiers, keycode, text) are needed instead of press_key, but the description never states when to prefer this over press_key or any of the many sibling input tools (type_text, type, sequence). Usage is left to inference.

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

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

Annotations already declare destructive/openWorld/non-idempotent/not-readOnly, so the safety profile is covered. The description adds value beyond that: it discloses the default window-reuse behavior and that the call returns a window selector. It still doesn't explain the high-risk confirmation_token flow that the schema hints at.

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 dense sentences with no filler, and the primary action plus default behavior are front-loaded. Every sentence carries operational content, though the Browser MCP sentence could be tightened.

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 8 parameters and no output schema, the description correctly surfaces the return value ('return a window selector') and the key default. Given full schema coverage, most parameter detail is handled structurally; the main remaining gap is sibling differentiation from open_app.

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% across 8 parameters, so the schema already carries parameter meaning. The description largely restates the reuse_existing/new_window semantics that the schema already documents, adding little parameter-level meaning beyond baseline.

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

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

States a specific verb and resource ('Open or launch an app through Hyprland and return a window selector'), so the agent knows exactly what it does. It does not distinguish itself from the sibling open_app, which appears to overlap, leaving some ambiguity about which launch-family tool to pick.

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

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

Gives explicit conditional guidance: reuse is the default, and reuse_existing=false is only for an explicit new-instance request. It also carves out the Browser MCP boundary ('use this instead of Browser MCP only when an app launch/open is requested'). It omits any guidance relative to the sibling open_app.

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 destructiveHint=true, idempotentHint=false, readOnlyHint=false and openWorldHint=true, so the safety profile is covered. The description adds nothing beyond that — it does not mention that clicks mutate UI state irreversibly, nor that high-risk actions may require the confirmation_token parameter, nor any rate/permission constraints.

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?

A single short sentence with the key qualifier ('left button') front-loaded and zero filler. It is efficiently sized, though so terse that the alias/compatibility semantics are left unexplained.

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 9-parameter, non-idempotent, destructive, open-world interaction tool with no output schema, the description does not say whether it behaves identically to `click`, how element_index vs coordinate targeting resolves, or when confirmation tokens are needed. The schema covers parameters, but the alias/routing semantics an agent needs are absent.

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 all nine parameters (coordinate spaces, element_index, element_click_mode, confirmation_token) are already documented in the schema. The description contributes no additional parameter meaning, so the baseline of 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 names a concrete action (left-button click) and explicitly frames the tool as a compatibility alias for the sibling `click`, which lets an agent tell it apart from right_click/middle_click/double_click without opening a schema. It is clear, but it never explains what 'compatibility alias' means operationally (identical behavior? legacy only?).

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?

Calling itself a 'compatibility alias' weakly signals that `click` is the preferred tool and this exists for backward compatibility, but there is no explicit when-to-use/when-not rule or stated condition that selects this over `click` or `left_click_drag`. Usage is only implied.

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

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

Annotations already declare destructiveHint=true, readOnlyHint=false, and openWorldHint=true, so the safety profile is covered. The description adds nothing beyond that — it doesn't mention a confirmation step (though a confirmation_token param exists) or how the drag interacts with the target app. It merely restates two parameter names.

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?

A single short, front-loaded sentence with no wasted words. It is appropriately sized for a compatibility alias, though the phrase 'using start_coordinate and coordinate' is largely redundant with the 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?

For a destructive, non-idempotent input tool with 100% schema coverage and no output schema, the schema carries most of the burden. The description is minimal but adequate to identify the tool; it omits any note on the confirmation_token high-risk flow, which would have added real value.

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 start_coordinate, coordinate, coordinate_space, and duration are already fully documented in the schema. The description names two parameters but adds no syntax, format, or defaulting detail 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+resource — a drag operation — and names the sibling it duplicates ('alias for drag'), which helps an agent tell it apart from 'drag'. However, calling it a 'compatibility alias' rather than describing the drag itself makes the purpose slightly indirect.

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 implies this exists for backward compatibility but never states when to use it versus the 'drag' sibling or 'left_click'. No prerequisites or selection conditions are given, leaving the agent to infer whether to prefer the canonical 'drag'.

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, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds the useful context that it enumerates currently running windows rather than all installed apps, but says nothing about return shape, ordering, or freshness.

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, front-loaded with the action and then the routing condition; every clause carries weight. The awkward 'available to brand' phrasing is the only blemish.

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 and no parameters, the description should ideally hint at what a listed app entry looks like (name, id, handle) so the agent can chain into target selection. Safety and usage are complete, but the return contract is left implicit.

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 takes zero parameters, so the schema imposes no semantic burden and the baseline of 4 applies. Nothing in the description misleads 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?

States a specific verb and resource ('List running Hyprland apps/windows'), which clearly separates it from launch_app/open_app siblings. The trailing phrase 'available to brand' is garbled and slightly muddies what the list actually returns, keeping it short of a 5.

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

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

Gives an explicit trigger ('Start here before choosing a target app') plus an exclusion ('unless the user explicitly asks to launch a new app/window'), which effectively routes the agent between this tool and the launch tools. It stops short of naming the sibling alternatives directly.

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, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered externally. The description's only behavioral contribution is the legacy/compatibility status, which is useful but thin; it says nothing about return shape or whether output matches list_apps exactly.

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?

A single short sentence with no filler, and the key fact (it is an alias, and of what) is front-loaded. Nothing could be trimmed without losing the only information it carries.

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 whose annotations fully cover the safety profile and whose schema is empty, the description supplies everything needed to invoke it. The only residual gap is whether it returns identical results to list_apps, which the agent must infer.

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 takes zero parameters, so there is no parameter semantics to document and the baseline is 4. Schema coverage is 100% and additionalProperties is false, leaving nothing for the description to compensate for.

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 identifies the tool only by reference: it is a 'Compatibility alias for list_apps.' The agent must open the sibling to learn what the tool actually does, and the name 'list_windows' pointing at an app-listing tool is potentially confusing rather than self-describing. It does at least pin the tool to a specific sibling, so it is not a tautology.

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?

Calling it a 'compatibility alias' implicitly tells the agent this exists for backward compatibility and that list_apps is the canonical choice, which effectively routes usage. It never explicitly says 'prefer list_apps' or states a when-not condition, so it falls short of the fully explicit 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, idempotentHint and destructiveHint=false, so the safety profile is fully covered. The description adds a genuine behavioral detail — special workspaces are included by default and are explicitly tagged — which is useful and not derivable from 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?

A single tight sentence with the resource front-loaded and no filler. It is efficient, though the trailing clause about Hyprland's identification is slightly vague.

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 trivial read-only listing tool with no output schema and full annotation coverage, a single sentence plus the special-workspace note is close to sufficient. The only minor gap is that the shape of returned items (names, IDs) is not hinted at beyond the special-workspace marker.

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 0%, so the description must compensate for the lone include_special parameter. It partially does: "special workspaces are included by default" explains the default value and observable effect, but it never names the parameter or states what setting it to false does.

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: "List Hyprland workspaces." The Hyprland-workspace scope distinguishes it from siblings like list_windows or manage_workspace, though the description never names those alternatives explicitly.

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?

There is no guidance on when to use this tool versus manage_workspace (for switching/creating) or the other list_* tools. The only conditional information is the default behavior of special workspaces, which is about output rather than usage.

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

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

Annotations already declare destructiveHint=true, idempotentHint=false, and openWorldHint=true, so the safety profile is largely covered. The description adds only the vague qualifiers 'Targeted, verified' and says nothing about the confirmation_token/request_confirmation flow that high-risk actions apparently require, nor what state changes are irreversible.

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?

A single dense sentence, front-loaded with the tool's domain and scope, with no filler sentences. It is efficient, though the enumerated action list is largely redundant with the enum in the 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?

For a 14-parameter, destructive, 15-action tool with no output schema and low schema description coverage, this one-liner is far too sparse. It leaves the agent without guidance on parameter combinations, the confirmation workflow, or the effect of each action.

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 only 21%, so the description should compensate and does not. The action list merely restates the action enum verbatim, and the other 13 parameters (x, y, width, height, target, address, follow, workspace, restore_workspace, minimized_workspace, etc.) receive no semantic explanation anywhere.

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 (window management) and enumerates the exact action set, so an agent immediately knows this operates on windows rather than workspaces or apps. It lacks explicit differentiation from siblings like manage_workspace or list_windows, but the action list implicitly makes the scope clear.

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

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

There is no when-to-use guidance, no conditions that select this tool over list_windows, wait_for_window, or manage_workspace, and no mention of prerequisites. The 'Targeted, verified' framing hints at intent but names no alternatives or exclusions.

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

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

Annotations already declare destructiveHint=true, openWorldHint=true, idempotentHint=false, so the safety profile is covered structurally. The description adds little beyond annotations: 'Verified' is opaque, and the 'special-workspace semantics' note is a minor behavioral hint. For a destructive tool that can rename workspaces and move windows, it never discloses what state is altered or lost, nor the role of confirmation_token.

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

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

Two tight sentences with no filler, and the primary purpose is front-loaded. The density comes at some cost to readability, but every clause carries intended meaning.

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 8 parameters, a 10-way action enum, and destructive semantics, a two-sentence description with no output schema is materially incomplete. An agent cannot determine which action/parameter combination to use or what destruction means without opening the 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 only 25% across 8 params, so the description must compensate but does not. It loosely gestures at actions (switch/create-or-activate/rename/move) but never explains the 10-value action enum, nor workspace, target, follow, address, or new_name. Only the schema-described confirmation_token carries meaning.

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 (Hyprland workspaces) and enumerates operations: switch, create-or-activate, rename, and targeted window move. This is clearly distinguishable from a generic tool, though it never contrasts itself with siblings like manage_window or list_workspaces. The compressed phrasing ('Verified Hyprland workspace...') is understandable but not maximally crisp.

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?

There is no statement of when to use this tool versus alternatives such as manage_window, list_workspaces, or activate. No prerequisites, ordering, or action-selection guidance is given beyond the bare operation names. The 'special' clause describes semantics but not when 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 already declare destructiveHint=true, openWorldHint=true, idempotentHint=false and readOnlyHint=false, so the safety profile is covered by structured data. The description only adds the button identity (middle) and the alias relationship; it says nothing about side effects like paste, autoscroll, or new-tab behavior that a middle-click can trigger, nor about the confirmation flow.

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?

A single, front-loaded sentence with no filler. It is efficient, though the alias framing is slightly vague and could be tightened to state the equivalence more decisively.

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 9-parameter, destructive UI-interaction tool with no output schema, the description is very thin: it omits how clicks resolve (element_index vs coordinates), the coordinate_space semantics, and the confirmation_token flow for high-risk actions. Rich schema coverage mitigates this somewhat, but the interaction model an agent needs is largely absent.

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, including coordinate_space and element_click_mode enums. The description adds no parameter-level meaning beyond the button identity, so the 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 action (a middle-button click) and clarifies it is an alias equivalent to click with the middle button, which separates it from left_click/right_click/double_click in the sibling set. It is clear but relies on the reader knowing what the referenced 'click' tool does.

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

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

No when-to-use guidance is given. Calling it a 'compatibility alias' hints that the primary click tool may be preferred, but the description never says when to choose middle_click over click, nor any prerequisites or exclusions.

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

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

Annotations already declare destructiveHint=true, openWorldHint=true, and non-idempotent, which is a surprising profile for a pointer move and deserves explanation. The description adds nothing about the confirmation_token, element-click semantics, or why a mouse move is flagged destructive; with annotations carrying the (opaque) safety signals, the description leaves the behavioral picture unexplained.

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?

A single front-loaded sentence with zero filler, but for a 9-parameter, destructive-flagged tool this is under-specification rather than true conciseness. The size is efficient but inadequate to the tool's complexity.

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?

This is a complex, 9-parameter pointer/element tool with destructive annotations and no output schema, yet the description covers only its alias status. It omits how element targeting works, the confirmation flow for high-risk actions, and coordinate-space behavior, leaving the agent to derive all of it from the 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% across all 9 parameters, so the schema documents coordinates, app selector, coordinate_space, element_index, and confirmation_token in detail. The description adds no parameter meaning, which is acceptable given full schema coverage but earns only the baseline.

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

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

The description identifies the tool only by reference to a sibling ('Compatibility alias for hover'), which lets an agent infer it moves the pointer to hover over a target but never states the verb+resource directly. It succeeds at distinguishing itself from the real 'hover' tool, but the purpose is left implicit rather than described.

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?

Calling it a 'compatibility alias' implies the preferred path is the 'hover' tool and this exists only for backward compatibility, which is useful routing information. However, it never explicitly says when to prefer one over the other or whether behavior differs.

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 cover read-only, idempotent, non-destructive safety. The description adds meaningful context beyond them: the capture is 'privacy-filtered', confidence is normalized 0..1, and the ocr_id is 'short-lived', which signals result caching/expiry behavior. It omits cost/privacy details and error 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, front-loaded with purpose then return shape, with zero filler. 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?

With no output schema, the description usefully discloses the return values (confidence, pixel boxes, short-lived ocr_id), which is exactly the burden it must carry. The remaining gap is underexplained input parameters for a 7-param, nested-schema tool.

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

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

Schema description coverage is only 43% (app, timeout, coordinate_space are documented; region, backend, language, page_segmentation_mode are not), and the description says nothing about any of the seven parameters. It fully fails to compensate for the coverage 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?

The description gives a specific verb+resource: running a local OCR backend against a newly captured target screenshot, which is clearly distinct from the accessibility-based siblings like read_app_state. It does not explicitly name or contrast the nearest siblings (screenshot, get_screenshot), so it stops short of full 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?

Usage is implied - extract text from a captured screenshot via OCR - but there is no explicit when-to-use guidance or comparison against alternatives such as read_app_state or click_text. The agent must infer that this is the OCR path versus the accessibility-tree path.

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 destructiveHint=true, openWorldHint=true and non-idempotent behavior, so a lower bar applies, yet the description adds nothing beyond them – no note on the high-risk confirmation flow that the `confirmation_token` parameter implies, no statement about side effects of launching processes, and no duplication/instance semantics tied to `reuse_existing`.

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?

A single short sentence with zero padding and no ambiguity about being secondary to `launch_app`. It is efficient, though its extreme brevity means it carries no useful information beyond the aliasing relationship.

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 an 8-parameter, destructive, open-world launch tool with no output schema and a confirmation-token workflow in its schema, a one-line alias note is not sufficient context. An agent gets no warning about risk, confirmation gating, or what happens on failure/timeout, all of which matter for this 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 description coverage is 100%, so the schema already documents all eight parameters (including defaults, ranges, and the 'prefer app' guidance for `command`). The description contributes no additional parameter meaning, which is the expected baseline when the schema does the heavy lifting.

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 identifies the tool as a 'Compatibility alias for launch_app', which tells an agent both the underlying capability (launching apps, inferred from the `app`/`command`/`new_window` params and the sibling `launch_app`) and its status as a legacy alias. That distinguishes it from the primary sibling, though it never states the action in its own words.

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?

'Compatibility alias' implicitly signals that `launch_app` is the preferred entry point for new work, but this is left to inference rather than stated. There is no explicit when-to-use/when-not-to-use guidance, nor any mention of when the alias is actually required.

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 destructive/non-idempotent/openWorld, but the description adds real state-machine context beyond them: panic latches writes off, cancel is one-shot, resume clears the latch, status is read-only. It does not mention that high-risk modes require the confirmation_token, which the schema covers but the description leaves silent.

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?

Semicolon-delimited clauses with the primary action front-loaded; every clause carries distinct information about a mode and there is no filler.

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

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

For a mode-switching control tool with no output schema, the entry points, latch behavior, and reset path are all covered. The main gap is not tying the destructive modes to the confirmation_token gate, which an agent must infer from the 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 coverage is 50% (the mode enum has no schema description), so the description has to carry mode meaning — and it does, explaining the latch/one-shot/clear/read-only semantics of each value. It adds genuine meaning the enum alone does not.

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 ('cancel active background operations') and then disambiguates each of the four modes with distinct behavior. This is enough for an agent to tell it apart from the GUI-automation siblings, though the tool name 'panic' is only one of four modes and the headline verb matches just the 'cancel' 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?

The mode clauses imply when each mode applies (resume to clear the latch, status to inspect), but there is no explicit when-to-use/when-not or routing against alternatives such as request_confirmation. Usage must largely be inferred from the enum semantics.

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 destructiveHint=true, openWorldHint=true, and readOnlyHint=false, so the agent knows this mutates external state. The description adds the clipboard-mediated mechanism and the speed rationale, but does not itself disclose the clipboard-clobbering risk or the confirmation/permission requirements (those live in the schema). With annotations carrying the safety profile, a 3 is appropriate.

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, zero filler: the action is front-loaded, the routing rationale follows. Nothing is redundant with the title or 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?

For a high-risk mutation tool with full schema coverage and annotations, the description supplies the missing purpose and selection guidance. It could go slightly further on failure behavior or clipboard side effects, but the essential call-time information is present.

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 every parameter (app selector, text, restore_delay, restore_clipboard, prefer_related, confirmation_token) is already documented in the input schema. The description adds no parameter-level syntax or format detail, so the 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?

States a specific verb+resource ("Paste text through the clipboard into the target app") and immediately distinguishes itself from the key-by-key typing siblings. An agent can select it correctly without opening any schema.

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

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

Explicitly enumerates when to prefer this tool (multiline, tabular, CSV/TSV, Unicode-heavy, long text) and names the tradeoff against the alternative ("much faster than key-by-key typing"). This is a clear when-to-use rule that routes the agent away from type_text/type/key.

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 destructiveHint=true, readOnlyHint=false, idempotentHint=false and openWorldHint=true, so the safety profile is covered by structured data. The description adds only 'secondary AT-SPI action' domain framing and does not explain that high-risk actions require a token from request_confirmation, nor what side effects an invoked action may have.

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?

A single front-loaded sentence with no filler or redundancy. It is efficient, though that brevity is partly under-specification rather than disciplined conciseness.

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 destructive, open-world tool with no output schema, the description omits critical context: how the confirmation_token/request_confirmation flow works, that element_index must come from a prior get_app_state call, and what a 'secondary action' actually is. It is not sufficient on its own 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 all four parameters are already documented in the schema, and the description adds no syntax, format, or semantics beyond them. Baseline of 3 applies when the schema carries the parameter burden.

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 gives a specific verb (invoke) and resource (a secondary AT-SPI action exposed by an element), so an agent knows this triggers an accessibility action rather than a synthesized input event. However, 'secondary action' is jargon that is never contrasted with any primary-action sibling (click, activate_menu_item, set_value), leaving some ambiguity about which tool to pick.

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?

There is no statement of when to use this over click, activate_menu_item, or set_value, nor any precondition such as requiring a prior get_app_state call to obtain element_index. The existence of a confirmation_token parameter strongly implies a high-risk approval flow, but the description never says when that flow is required.

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 destructiveHint=true, idempotentHint=false, and openWorldHint=true, so the safety profile is covered. The description adds nothing about the required 'app' targeting, that keystrokes are delivered asynchronously, or that high-risk presses may need the confirmation_token flow via request_confirmation — meaningful context that is absent.

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?

A single front-loaded sentence with a clear verb and inline examples; 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 7-parameter, destructive, no-output-schema tool the description is thin: it omits the mandatory app-targeting semantics and the high-risk confirmation path, though the schema's field-level descriptions carry much of the remaining 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 coverage is 100%, so the baseline is 3, but the description genuinely adds value by showing the xdotool-style syntax (ctrl+v, Return, alt+left, super+c) that the bare schema text 'Key or key-combination to press' does not convey. It still says nothing about the precedence between key/keys/keycode/modifiers.

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 (press) and resource (key or key-combination) with concrete syntax examples. However, it does not distinguish itself from the sibling tool 'key', which appears to be the same or a very similar operation, nor from type_text/type.

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

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

No guidance on when to use this versus the near-identical sibling 'key', nor when a full text-entry tool (type_text, paste_text) would be preferable. The agent is left to guess between overlapping keypress tools.

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 already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint=false. The description adds only that it is an alias, with no additional behavioral context such as expected output shape, compatibility caveats, or deprecation guidance.

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 single sentence is maximally concise and front-loaded. It avoids filler, though it is so terse that it leaves important routing context unstated.

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 alias with full annotation coverage and a fully documented schema, the description is minimally adequate. It identifies the canonical sibling but does not explain why or when the alias should be preferred or avoided, which is the main contextual gap.

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

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

There is one required parameter and schema description coverage is 100%, so the schema fully documents the app selector syntax. The description adds no parameter meaning beyond what the schema already provides, making the baseline 3 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 identifies the tool only as a compatibility alias for get_app_state; it does not state what state is read or what resource is involved. It does distinguish the tool from its canonical sibling, but the functional purpose must be inferred from get_app_state.

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?

Calling it a 'compatibility alias' implies it should normally be avoided in favor of get_app_state, but the description never explicitly says when to use this tool versus the canonical one. The guidance is only implied.

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

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

Annotations already declare destructiveHint=true, readOnlyHint=false and non-idempotency; the description usefully adds that the challenge is pending, one-time in nature, and requires approval from an independent local TTY before authorizing. It does not cover expiration, rejection handling, or what the challenge returns, so it stops short of full 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?

Two tight sentences that front-load the core action and follow with the governing constraint. 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?

Given the mutation semantics and 100% schema coverage, the description is nearly sufficient; however, with no output schema, it never says what is returned (presumably the challenge ID later passed as confirmation_token), leaving a small gap in the end-to-end flow.

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 all three parameters (arguments, tool_name, confirmation_token) are already documented, including the 'excluding confirmation_token' and 'one-time challenge ID' details that live in the schema. The description adds only the framing that arguments must match the high-risk call exactly, which is a marginal gain over structured data.

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 ('Create') and resource ('pending challenge bound to an exact high-risk call'), plus the approval mechanism. An agent can immediately tell this is a human-in-the-loop confirmation gate, distinguishable from every other sibling tool.

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

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

Usage is implied – it is for high-risk calls needing human approval – but the description never states the workflow explicitly (call this first, then re-invoke the target tool with the resulting confirmation_token) or when confirmation is required versus optional. No alternatives or exclusions are named.

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

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

The annotations already declare destructiveHint=true, openWorldHint=true, readOnlyHint=false, and idempotentHint=false, so the agent knows this is an unsafe, non-idempotent, open-world mutation. The description adds no behavioral context beyond those annotations, such as whether the action needs confirmation or how the pointer is positioned.

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?

A single sentence with no wasted words, front-loading the core fact that it is an alias for a right-button click. It is appropriately sized for an alias tool, though the term 'compatibility' could be clearer.

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 rich schema and annotations, the description covers the essential action but omits any usage context for a 9-parameter, destructive tool. It is minimally adequate as an alias pointer but leaves the agent to rely entirely on the schema and annotations for safe 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 fully documents all 9 parameters. The description mentions no parameters, which is acceptable given the schema's completeness, but it adds no extra semantics such as default coordinate space or the meaning of confirmation_token.

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: a right-button click implemented as a compatibility alias for click. It distinguishes itself from siblings like left_click and middle_click by naming the button, though 'compatibility alias' adds slight ambiguity about whether it is the preferred or legacy tool.

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

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

The description gives no explicit guidance on when to use this tool versus click or the other button-specific siblings. 'Compatibility alias' weakly implies a legacy alternative, but the agent is left to infer whether right_click or click should be preferred.

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 readOnly, idempotent and non-destructive, so the safety profile is covered. The description adds genuinely useful behavior ('unoccluded' capture, compositor fallback when no app is passed) but says nothing about what is returned (image data vs. path) or how failures are surfaced.

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, front-loaded sentences with no filler; the primary capability leads and the scoping caveat follows. Slightly terse at the cost of completeness, and 'low-level target' is vague jargon.

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 11 parameters, a nested region object, three enums, no required params and no output schema, the description is thin. It omits return-value expectations and the interaction between region, coordinate_space and the app/window selection, leaving the agent to guess on most of the surface.

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 only 27% across 11 parameters, so the description must compensate but does not. Only the app/target precedence is clarified; zoom, scale, region, format, quality, max_dimension, show_cursor and cursor_source are undocumented in both description and 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?

States a specific verb and resource ('Capture ... screenshot') plus the scope rule (app/window, else the visible compositor). However, it gives no differentiation from the near-identically-named sibling get_screenshot, which an agent could easily confuse with this tool.

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

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

'Prefer app over low-level target' gives one concrete selection rule between two of its own parameters, and the fallback to the compositor when no app is passed is implied. There is no guidance on when to choose this tool over get_screenshot or ocr, so routing among siblings is left 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 declare destructiveHint=true, idempotentHint=false, and openWorldHint=true, but the description says nothing about the high-risk confirmation flow the schema hints at (confirmation_token) or what happens to the target. It adds essentially no behavioral context 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?

A single front-loaded sentence with no filler. Efficient, though perhaps too terse given the tool's complexity.

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 an 11-parameter, non-idempotent, potentially destructive tool with no output schema, a one-line description is inadequate. It never explains the element_index/coordinate alternatives, the coordinate_space semantics, or the confirmation workflow, leaving the agent to rely entirely on the 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 91%, so the schema already documents all 11 parameters including coordinate_space, element_index, and confirmation_token. The description adds no extra syntax or semantics beyond what the schema provides, so the 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?

States a specific verb (scroll), the target (an element or coordinate), and the method (by pages in a direction). Clear enough for an agent to understand what the tool does, but it offers no differentiation from siblings like drag or key that could also move viewport content.

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?

There is no guidance on when to use scroll versus alternatives such as drag, press_key (PageDown), or move_mouse. No mention of prerequisites like obtaining an element_index from get_app_state or when a confirmation_token is required.

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, idempotentHint, and destructiveHint=false, so the safety profile is covered structurally. The description adds a non-obvious behavioral guarantee that annotations cannot express: the response will not leak secrets, which matters for a security-policy read.

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?

A single front-loaded sentence with no filler. The noun phrase names both the primary payload (security policy) and secondary payload (readiness diagnostics) plus the redaction caveat, all in one pass.

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 no-parameter, read-only tool with no output schema, the description tells the agent what it gets back at a high level and guarantees no secret leakage. It stops short of describing the shape or granularity of the diagnostics, but the core need is met.

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 takes zero parameters, so there is no parameter semantics to document; the 100% coverage is vacuous. Baseline 4 applies and nothing in the description misleads 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?

States a specific verb ('Return') and a specific resource ('the active desktop-control security policy and readiness diagnostics'). No sibling tool covers security posture, so there is no ambiguity to resolve, though it never spells out what the policy fields or diagnostics actually contain.

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?

There is no statement of when to call this versus the many action-oriented siblings (computer, launch_app, screenshot), nor whether it should be checked before attempting desktop control. The only implicit cue is 'readiness diagnostics', which an agent must infer means a pre-flight check.

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 destructiveHint=true, idempotentHint=false, and openWorldHint=true, so the safety profile is covered. The description adds real behavioral context beyond that: each step re-enters the policy, confirmation, confinement, lease, and audit gateway, and nesting is rejected. But the jargon (confinement, lease) is undefined and it says nothing about error handling or what happens on partial failure.

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 core action and followed by the governance constraint; no filler. Dense internal terminology slightly reduces immediate comprehension but the structure is efficient.

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?

This is a complex orchestration tool accepting up to 128 steps with dry-run and stop-on-error semantics, no output schema, and near-empty parameter documentation. The description leaves critical gaps: return shape, per-step failure behavior, and the meaning of most parameters.

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 only 20%, with just confirmation_token documented. The description never mentions steps, dry_run, max_steps, or stop_on_error, so four of five parameters have no semantics anywhere, and the low coverage is not compensated for.

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 ('Run an ordered action sequence'), which clearly identifies this as a meta-orchestration tool distinct from the single-action siblings like click or type_text. It stops short of naming a sibling or contrasting with calling those tools one by one, so it misses the top band.

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 usage (batch several actions with per-step governance) and gives one exclusion ('nested sequences are rejected'), which is useful. However it never says when an agent should choose sequence over issuing the individual tools directly, nor any prerequisite beyond confirmation.

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, destructiveHint=true, idempotentHint=false, and openWorldHint=true, so the safety profile is covered structurally. The description adds nothing beyond this—it doesn't explain what happens to the prior value, whether confirmation is required, or any 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?

A single front-loaded sentence with no wasted words, but it is under-specified rather than genuinely concise for a destructive mutation tool. It is minimal without being information-dense.

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 destructive, non-idempotent mutation with a confirmation_token in the schema, the description omits the confirmation/approval workflow and any context about which elements are 'settable'. No output schema exists, so the description could have carried more of this 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 all four parameters (including the confirmation_token) are already documented in the schema. The description adds no parameter meaning, which is acceptable given the baseline-3 rule for high coverage.

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+resource ('Set the value of a settable accessibility element'), so an agent knows it mutates an existing element's value. However, it offers no differentiation from siblings like type_into, type_text, or click_text, which could also write values into UI elements.

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?

No guidance on when to use this versus type_into or type_text, no prerequisites, and no mention that a high-risk action may require a confirmation token. The agent must infer usage entirely from the terse statement.

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 destructiveHint=true, idempotentHint=false, and openWorldHint=true, so the safety profile is covered downstream. The description adds only that the gesture is a triple left click, with no mention of the high-risk confirmation_token flow referenced in the schema or any side effects. Minimal added context.

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?

A single front-loaded sentence with zero filler, so nothing is wasted. But for a 9-parameter, destructive, non-idempotent interaction tool, this level of brevity leaves the definition under-specified rather than efficient.

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 9 parameters, a destructive write profile, a confirmation-token mechanism, and no output schema, the description omits prerequisites, high-risk confirmation behavior, and any routing to alternatives. It is not complete enough for an agent to call this confidently versus its many click-family siblings.

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% across all 9 parameters, so the schema fully documents coordinates, app selectors, element targeting, coordinate spaces, and the confirmation token. The description adds nothing about parameters, which is acceptable given the coverage but earns no credit above the baseline.

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

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

Names a specific action (triple left click) and flags it as a compatibility alias, which tells the agent it's a legacy entry point. However, it doesn't distinguish itself from the obvious siblings (click, double_click, left_click) or explain why a distinct triple-click tool exists. A vague but minimally informative 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 phrase 'compatibility alias' hints that this exists for backward compatibility, implying new callers should prefer a canonical tool, but no explicit when-to-use, when-not-to-use, or named alternative is given. The agent must guess between this and click/double_click.

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 destructiveHint=true, readOnlyHint=false, openWorldHint=true, and idempotentHint=false, so the safety profile is covered structurally. The description adds nothing beyond that: no mention that typing can destroy/overwrite focus content, no note on the confirmation flow for high-risk actions, no rate or focus prerequisites.

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?

A single short sentence with no filler, front-loaded and easy to scan. It is not padded, though it is arguably too terse rather than maximally economical per unit of information.

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 destructive, open-world input-injection tool with no output schema, the description omits the essentials an agent needs: confirmation_token usage, target-app focus requirements, and any relation to paste_text/type_into. Only the alias relationship to type_text is conveyed.

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 75%, near the high-coverage baseline where 3 is standard, but the description supplies zero parameter meaning. In particular the enum'd `method` parameter has no schema description and is not compensated for in the description, and the app-addressing/confirmation-token semantics are left to the schema alone.

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?

"Compatibility alias for type_text" identifies the tool only by reference to a sibling rather than stating verb+resource itself. An agent can infer it types text, but the definition never says what the alias actually does or how (if at all) it differs from type_text at runtime.

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?

No when-to-use, when-not-to-use, or preference guidance is given. Saying it is an alias leaves open whether the agent should prefer type_text or this tool, and no condition or alternative routing is stated.

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, destructiveHint=true, idempotentHint=false and openWorldHint=true, so the safety profile is covered structurally. The description usefully adds the atomic sequence (resolve, verify, focus, refresh state) that precedes input, but it says nothing about the confirmation_token approval workflow, permission needs, or what state the typing mutates.

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?

A single dense sentence that front-loads the action and its resolution sequence with no filler. It is compact but packs several loosely-defined terms ("refresh state", "verify") without explaining them.

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 destructive, non-idempotent tool with 15 parameters at 20% coverage, no output schema, and a confirmation-token flow, the description leaves large gaps: it never signals the destructive nature, the approval requirement, or which of the many targeting parameters to 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?

With 15 parameters and only 20% schema description coverage, the description would need to carry the parameter burden, but it mentions only the input method values (auto/AT-SPI/paste/keys) that the enum already lists. Target-resolution parameters (locator, mark_id, snapshot_id, element_index, accessible_name, target_text, nth, match) are undocumented in both places.

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 concrete verb (input text) and resource (an editable target), plus the resolution/focus sequence that precedes the write. However, it does not distinguish itself from the many text-entry siblings (type, type_text, paste_text, set_value), so an agent cannot tell from the text alone which entry tool to pick.

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?

There is no when-to-use or when-not-to-use guidance, and no mention of alternatives despite four closely related text-input siblings. The only hints are the method enum values, which are already in the schema rather than framed as selection criteria.

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 destructiveHint=true, idempotentHint=false, and openWorldHint=true, so the risk profile is partly covered. The description adds real behavioral context about the method fallback chain (AT-SPI editable control first, then isolated background key/paste input), though it never mentions the confirmation_token / high-risk approval flow or that input cannot be undone.

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, front-loaded with the core action, then the routing alternative, then the method semantics. No filler and every clause carries information.

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 4-param mutation tool with no output schema and full annotation coverage, the description covers the key decision (this tool vs paste_text) and the method behavior. It does not explain the confirmation_token requirement or the two remaining method values, which would be needed for fully confident invocation.

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

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

Schema coverage is 75% and the enum values have no per-value descriptions in the schema, so the description's explanation of method=auto and method=atspi adds genuine meaning beyond structured data. It leaves method=paste and method=keys unexplained, which is the only 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?

States a specific verb+resource ('Type literal text into the target app') and immediately distinguishes itself from the closest sibling, paste_text, by naming the cases that belong to paste_text instead.

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

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

Gives an explicit routing rule: use paste_text for multiline, tabular, CSV/TSV, Unicode-heavy, or long text. It also explains which method the agent will get implicitly via method=auto, so the caller knows what happens when they don't specify anything.

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 already declare this as a safe, idempotent, non-open-world read (readOnlyHint=true, idempotentHint=true, destructiveHint=false), so the safety profile is covered. The description adds that it blocks for a 'short duration' and is a compatibility alias, but does not disclose that it pauses execution or what the alias replaces.

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?

A single tight sentence with the alias status front-loaded. No waste, though it is arguably too terse to route the agent correctly.

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, zero-required, fully annotated tool this is minimally adequate, but 'compatibility alias' is left unexplained (alias for what, and should it be avoided?), which is a real gap for correct tool selection.

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 the single 'duration' parameter is fully documented in the schema with its default. The description's 'short duration' phrase adds only mild corroboration and no syntax or unit detail beyond the schema's 'Seconds to wait. Defaults to 1.'

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 verb (wait) and a scope (a short duration), and the 'compatibility alias' label hints at its legacy status, but it does not differentiate itself from the more specific siblings wait_for_window and wait_for_close, which an agent could easily 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?

There is no explicit when-to-use or when-not-to-use guidance. 'Compatibility alias' implies a preferred modern alternative exists but never names it, leaving the agent to guess whether to use this or a sibling.

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, idempotentHint, and destructiveHint=false, so the safety/idempotency profile is covered. The description adds useful behavioral context: the conditional behavior of 'related_to' returning surviving root app state. It does not explain default return values or the blocking nature when the target never closes.

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 tightly written sentences that front-load the core action before the conditional behavior. 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?

There is no output schema, so the description carries the burden of explaining returns; it covers the related_to case but is silent on what is returned when related_to is omitted, and on what happens on timeout. Adequate but with a clear gap for a wait tool.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description adds meaning beyond the schema for 'related_to' by explaining its conditional effect on the return value (surviving related/root app state), which the schema text alone does not convey.

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 ('wait for') and resource ('target window/dialog to close'), which distinguishes it from the sibling 'wait_for_window' (appearance) by implication. It is clear what the tool does, though it never explicitly names the sibling it contrasts 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?

No statement of when to use this versus 'wait', 'wait_for_window', or 'get_app_state'. The only conditional mentioned (related_to) describes behavior, not a usage decision, so the agent must infer the context from the name alone.

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, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds useful behavior beyond that: it blocks until a window/popup appears and returns app state, clarifying this is a blocking poll rather than a fire-and-forget call.

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

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

Two tight sentences, front-loaded with the core purpose and followed by the usage trigger. No filler or repetition.

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-required-parameter read-only wait tool with no output schema, the description adequately covers purpose, trigger, and that app state is returned. Only minor gaps remain, such as whether it fails or returns empty on timeout.

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 of the five optional parameters (app, class, title, timeout, related_to) is already documented in the schema, including the timeout cap. The description adds no syntax or selector-format detail beyond what is provided, so the 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?

States a specific verb ('Wait for') and resource ('Hyprland window or same-process related popup/dialog') plus the post-condition ('then return its app state'). An agent can immediately tell this blocks until a window appears rather than performing an 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?

'Use after actions expected to open dialogs or new windows' gives a clear triggering condition. It does not, however, name alternatives such as wait_for_close or generic wait, leaving the agent to infer which wait variant to pick.

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