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

Goes well beyond the destructiveHint/openWorldHint annotations: batch halts on ~ or ✗ with nothing more sent and no replay, ambiguous labels are refused, outward actions need `confirm: true` plus an `accord` token from a prior refusal, and local destruction needs `confirm: true` alone. The confirm-vs-accord split and the 'no replay after unknown outcome' rule are exactly the operational facts an agent needs to avoid causing damage.

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?

Front-loaded and information-dense, but written in a compressed shorthand that costs parseability: 'Steps ✓ = ~ ✗, status = the worst' and 'follow `next`' require inference, and the action list runs as an unpunctuated stream. Nothing is redundant, but several lines do not earn their place because they cannot be decoded on first read.

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 non-idempotent, open-world actuator with no output schema and no schema descriptions, this covers safety gating, failure semantics, and targeting comprehensively. The remaining gap is the return value: step statuses and `next` are alluded to but never characterized, and three parameters are left dangling.

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 0% schema description coverage the description must carry all parameter meaning. It covers hwnd, steps (with a full action vocabulary and example), accord, and foreground well, but `then`, `repeat`, and `time_budget` receive no explanation at all, and the referenced `next` is not even a declared parameter. Partial compensation only.

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

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

Opens with a specific verb and scope: 'Act in ONE batch, in the background, on a NAMED window (hwnd), without reading the code.' That phrasing directly separates it from `look` (which reads the UI) and gives an agent a one-line mental model of what the tool is for.

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 the essentials for choosing this tool: batch-only, hwnd-targeted, `foreground=True` reserved as a fallback, and a hard precondition that a batch without a prior look is refused. It stops short of naming `look` explicitly as the required prior step, so the alternative is implied rather than 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?

Adds substantial context beyond annotations: the opening is read back, settings pages open behind the user's window, web URLs are refused, paths with spaces are not split, and Chromium/Electron apps accept files only. These constraints materially affect invocation and are not covered by 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?

Front-loaded and dense with useful constraints, with a concrete example. However, the phrasing is compressed and somewhat run-on, making it slower to parse than ideal.

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, but the description explains the read-back behavior. It covers the main invocation modes, exclusions, argument semantics, special settings behavior, and app-specific restrictions, leaving little an agent would need to 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?

Schema description coverage is 0%, so the description must compensate, and it does: `app` accepts executable names, paths, or protocol URIs, while `args` is restricted to .exe arguments, never documents/folders/addresses, and can also follow the program inside `app`.

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: opens an application, folder, or document like a double-click. It also clearly distinguishes the tool from web-opening alternatives by explicitly refusing http/https/ftp and pointing to nexus-browser.

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

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

Provides explicit when-to-use examples, including a settings URI case, and explicit exclusions for web addresses. It also gives detailed guidance on when to use `args` and when not to, plus Chromium/Electron restrictions.

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 readOnly/idempotent/non-destructive, so the description earns credit for adding behavior beyond them: it operates on covered/background windows without raising them, falls back to an image only if the tree is too thin, and notably does not re-attach the image if the screen matches the last one sent. That image-dedup rule is genuine behavioral context an agent could not infer from structured fields.

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 critical rule is front-loaded and every clause carries information, but the prose is over-compressed into semicolon run-ons and fragments ('Unlocks a batch.'), which costs parseability for an agent reading the definition cold. It earns its length but not its density.

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, zero-annotation-coverage tool with no output schema, the description is largely sufficient: it explains the return format (one line per element, image fallback, compact JSON shape) and the main parameter semantics. The unexplained max_depth/max_elements/output_path leave a residual gap that keeps it from a 5.

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 0%, so the description carries the full burden and largely does: hwnd accepts an id, a window title, or a process name (much richer than the bare anyOf), query filters, format="json" yields compact JSON with box_2d in 0-1000, annotate draws numbers, zoom=box_2d enlarges an area, capture_screenshot forces the image, WebP capped at 2000px. max_depth, max_elements, and output_path are never explained, which keeps it off a 5.

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 and resource: see a NAMED window (hwnd, title, or process) without bringing it to the front, emitting one line per element with role/name/value/states/coordinates. It is specific enough to distinguish from 'act' (which it feeds) and from 'windows' (which presumably lists rather than inspects), though it never explicitly contrasts with 'window' or 'windows'.

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 front-loaded 'GOLDEN RULE: look → act in one batch, targets by label; never resend a batch without looking' gives an explicit workflow and names the sibling it precedes ('act'), and 'Unlocks a batch' reinforces the sequencing. What is missing is a when-not condition or guidance on choosing 'look' over the 'window'/'windows' siblings.

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

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

Adds substantial behavior beyond annotations: it names the close sequence (UI Automation, then WM_CLOSE), states the closing is read back (verification), and clarifies a 'Save?' prompt is reported but never answered, which is key context given destructiveHint=false. Still silent on what other action values do and on side effects beyond closing.

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?

Front-loads the resource and target identification, then the action semantics, then a compact JSON example. Dense but each clause carries information; nothing is wasted.

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

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

For a 2-parameter mutation tool with no output schema, the close path is well covered including verification and prompt handling. However, the free-form 'action' parameter's other possible values and their behavior are entirely undocumented, which is a meaningful 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 0%, so the description carries the burden. It adds real meaning for 'hwnd' (accepts a number, a title, or a process), but 'action' is an unconstrained string documented only with the single value 'close', leaving the valid action vocabulary ambiguous.

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 ('manage a NAMED window') and identifies targets by hwnd, title, or process, which distinguishes it from the sibling 'windows' that presumably lists them. However, only the 'close' action is spelled out, so the full scope of 'manage' is not clear.

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

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

The description implies usage (obtain/identify a window by hwnd, number, title, or process), but never explicitly says when to use this over 'windows' or 'act'. With sibling 'windows' present, an explicit 'call windows first to get the hwnd' instruction would have made this a 4-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 non-destructive, so safety is covered and the description is not required to restate it. The description does add genuine value by enumerating the returned fields and clarifying that "process" is the real owning application for UWP apps — a non-obvious detail. It says nothing about ordering, snapshotting, or how many windows to expect.

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?

It is short and front-loaded with the purpose and return fields, which is good. But the 'Example: {"by_app": false}' line is a wasted, ambiguous fragment that contradicts the by_app=true sentence above it.

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, listing the returned fields is necessary and partially done, but the visible_only parameter and the difference from the sibling "window" tool remain unexplained. For a simple two-parameter read tool this is passable but leaves real gaps an agent would hit on first call.

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. It explains by_app (grouped by application) but never mentions visible_only, which defaults to true and materially changes the result set. Half the parameters are effectively 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?

The opening clause gives a specific verb plus resource ("List open windows") and even enumerates the returned fields (hwnd, title, process, position, foreground), so the agent knows exactly what it gets. It does not, however, distinguish itself from the sibling tool named "window", which sounds adjacent enough to require a disambiguation sentence.

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 only usage signal is the by_app toggle behavior; there is no statement of when to use this versus siblings like "window" or "look", and no exclusions or preconditions. The trailing example {"by_app": false} is also at odds with the preceding by_app=true explanation, adding confusion rather than guidance.

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