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

With no annotations, the description carries the full burden and it discloses the most important behavior: focus is verified and failure produces an error rather than a false success. It does not describe effects on window stacking or minimized windows, but the core activation guarantee is explicit.

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

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

Two short sentences with no filler; the main action and the error guarantee are front-loaded. Every clause adds 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 simple activation tool with fully documented parameters, the description plus schema gives enough to call it correctly. It lacks an explicit success return contract, and there is no output schema, but the error-on-failed-focus statement covers the most important outcome.

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 description does not need to restate parameters. It adds no parameter-level detail, but every parameter is already well documented in the input schema, meeting 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 uses a specific verb and resource ('focus and raise a window') and adds a verifiable success criterion ('confirm focus actually landed'), which distinguishes it from inspection tools like list_windows or window_at. It is immediately clear what the tool does.

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

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

The description does not state when to choose this tool over siblings such as window_manage or list_windows, nor does it mention prerequisites or exclusions. The only hint that it belongs before input actions is in the target parameter schema, not in the tool description.

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

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

Beyond the readOnlyHint annotation, the description discloses two decisive behaviors: assertions 'come back passed/failed with what was actually observed' (return semantics), and 'a false assertion is a result, not an error' — telling the agent a failed check is a normal outcome, not a thrown error. The 'honest/evidence' framing adds integrity context no annotation carries. No conflict with readOnlyHint; asserting is a read-only operation.

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

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

Three sentences of roughly 50 words, purpose front-loaded in the first clause. Sentence 2 delivers the load-bearing result-vs-error semantic; sentence 3 enumerates the argument options. Every sentence earns its place and adds new information — no padding or restatement of the name.

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 moderate-complexity read-only tool (5 optional nested parameters, no output schema), the description covers what an agent needs: when to call (task end), what to pass (one of the five), and what happens (passed/failed with observed evidence, never an error). It compensates for the missing output schema with clear return semantics. Minor gaps remain — exact multi-parameter behavior and precise response shape — but the routing and invocation choices are adequately covered given the sibling set.

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

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

Schema coverage is 100% — the schema already documents each parameter (e.g., text_present requires OCR visibility, widget_exist targets AT-SPI). The description adds the key semantic beyond the schema: 'Give any of: ...' clarifies these are alternative single assertions, a constraint the all-optional schema leaves implicit. It does not say what happens when multiple are passed at once, but the schema carries the per-parameter detail.

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: 'Prove the desktop is in a state' — an assertion/verification tool over desktop state. The five assertion types are enumerated (window_exists, window_focused, text_present, widget_exist, clipboard_contains), and 'the honest way to END a task' positions it against action/search siblings like wait_for and ui_find. An agent can tell what this tool is for without ambiguity.

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

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

Provides a clear usage context — use at the end of a task to verify the final state with evidence, and a failed assertion is a valid result. However, it does not explicitly name alternatives (e.g., wait_for for polling until a condition becomes true) or state when not to use it, so the routing guidance is context-only, not exclusion-based.

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

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

Annotations already declare readOnlyHint=true, and the description adds valuable behavioral edge cases beyond that: an empty clipboard is a clean result rather than an error, and a non-serving clipboard owner is reported after a short deadline instead of hanging. These details prevent an agent from misinterpreting empty output as failure and reassure about timeout behavior. No contradiction exits with the read-only annotation.

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

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

The description is three compact sentences with no filler: the first establishes the core purpose, the second explains the only parameter, and the third covers important edge-case behavior. Each sentence adds distinct value and the most important information is front-loaded. It is an example of efficient, well-structured documentation.

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

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

For a simple single-parameter read tool, the description is complete: it explains the default return, the alternative mimetype mode, and the two non-obvious edge cases (empty clipboard and hanging clipboard owners). There is no output schema, so the description appropriately covers return semantics. No prerequisites or additional failure modes are needed for correct invocation.

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

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

Schema coverage is 100%, and the schema already describes types as 'List offered mimetypes instead of reading text.' The description reinforces this by stating 'Text by default; types:true lists the offered mimetypes instead,' which clarifies the default but adds little beyond the schema. This matches the baseline where the schema carries the parameter semantics.

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

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

The description clearly identifies the resource (clipboard) and the read operation, with 'What is on the clipboard' immediately conveying purpose. It also distinguishes two modes—reading text by default and listing mimetypes with types:true—so an agent knows exactly what the tool returns. The read intent is obvious even without an explicit imperative verb, and it is clearly differentiated from the sibling clipboard_write.

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

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

The description provides clear context for when to use this tool: whenever clipboard contents are needed, with the types parameter for inspecting offered mimetypes. It does not explicitly reference alternatives or exclusion conditions, but the sibling list makes the read-vs-write distinction apparent. The default behavior and parameter switch are stated precisely enough for an agent to choose the correct invocation.

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

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

With no annotations, the description carries the full behavioral burden. It discloses that the tool will write and then read back to verify, that it goes through gnome-shell/mutter rather than an external client, why that matters (bug S-018), and that the wl-copy fallback says when it is used. This is unusually transparent about side effects and implementation 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 the core action and verification guarantee, followed by a concise rationale for the implementation choice. The mutter bug detail earns its place by explaining why the fallback exists and why the extension path is preferred.

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

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

The description explains purpose, mechanism, verification, and fallback behavior, and the schema completes parameter semantics. The main gap is that without an output schema, return/error behavior is only implicit ('prove it landed' and the fallback 'says so'), so an agent might not know exactly what to expect on success or failure.

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

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

The input schema already documents all three parameters with 100% coverage, including the 'text OR path+mimetype' constraint and the role of mimetype. The description adds only the high-level 'text or a file's bytes' framing, which does not materially deepen parameter understanding beyond the schema.

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

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

The description opens with a specific verb and resource: 'Put text or a file's bytes on the clipboard.' It also explains the mechanism (gnome-shell extension) and distinctly implies the inverse operation of the sibling clipboard_read, so an agent can tell it apart without opening schemas.

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

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

It gives context about when the extension path is used and mentions wl-copy as a fallback that identifies itself when used, but it does not explicitly state when to prefer this tool over clipboard_read or any alternative. The usage guidance is mostly implied by the tool name and action, not stated as routing rules.

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

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

Beyond the readOnlyHint annotation, the description adds valuable behavioral detail: it reports live state of the running shell, calls out the edited-extension-not-loading-until-login caveat, and exposes specifics like XTEST trap and AT-SPI counts. This gives the agent a concrete mental model of what the tool reveals without an output 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 opens with the core question ('whether each mechanism is usable right now') and then delivers a compact, comma-separated list of specifics. Every clause earns its place, and the parenthetical about edited extensions is high-value nuance rather than padding.

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 parameterless tool with no output schema, the description is complete: it names the mechanisms covered, explains the kind of information returned, flags an important reload caveat, and even gives call-order guidance. An agent has everything needed to select and invoke it correctly.

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

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

The tool takes zero parameters and the schema is empty, so there is no parameter meaning to add. Per the zero-param baseline this is a non-issue; the description spends no unnecessary words on parameters.

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

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

The description states exactly what the tool reports: whether each desktop-automation mechanism is usable right now and what it will do, enumerating extension state, running shell methods, pointer control, counts, keyboard layout, and the XTEST trap. This clearly identifies a diagnostic resource and sets it apart from the sibling action tools like pointer_click or ui_find by framing it as an environment health check.

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

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

It gives an explicit trigger: 'Call this first when something behaves oddly.' That tells an agent when to invoke it, but it does not spell out when not to use it or name alternatives, so it stops just short of full routing guidance.

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

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

With no annotations, the description carries the behavioral burden. It discloses that steps run with their own look off, the picture is taken after the last step or the failing step, and the sequence is validated up front so a call that cannot finish never starts. This is useful, non-obvious execution behavior.

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

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

The description is front-loaded with the core purpose, then explains the cost rationale, the alternative case, and the up-front validation guarantee. Every sentence contributes and no space 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 complex tool with no output schema, the description covers the critical context: when to batch, when not to, how look behaves, and how failures are handled. A formal return description is absent, but the observable outcomes are clearly implied.

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?

Input schema coverage is 100%, and the schema already documents steps, look, look_at, settle_max_s, and stop_on_error in detail. The description adds selection context but does not need to repeat parameter syntax; it correctly leaves parameter semantics to the schema.

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

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

The first sentence clearly states the tool's purpose: run a short sequence of actions in one call and look once at the end. It also names typical verbs and explicitly contrasts with making four separate calls, making it distinguishable from the single-action sibling tools.

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

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

The description gives explicit when-to-use guidance: batch known sequences because separate calls cost round trips, and use single tools when the next action depends on what the last one revealed. This directly tells an agent when to choose do_steps versus 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?

The description adds substantial behavioral context beyond the readOnlyHint annotation: it reads pixels with OCR, takes about 1.5 seconds per window, is cheaper and more exact than estimating from a screenshot, and is blind to icon-only buttons. No contradiction with annotations.

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

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

Four concise sentences with no filler. The core purpose and clickable-coordinate outcome are front-loaded, followed by the comparison to ui_find, performance characteristics, and the key limitation.

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 tool with no output schema, the description covers purpose, alternative routing, performance, and limitations well. It implies a coordinate result but does not explicitly describe the return format or how limit/min_confidence affect results, which is a minor 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?

The description enriches parameter understanding by explaining how text phrases are matched across consecutive words on one line and by giving the default PSM modes for window vs whole-screen searches. The schema already covers most parameters; min_confidence and limit lack schema descriptions, but the description provides enough context for typical use.

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: locating visible on-screen text and returning clickable coordinates via OCR. It also distinguishes itself from ui_find by naming the exact gap it fills (OCR-based pixel reading for Chrome/Electron/Qt apps).

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 instructs the agent to try ui_find first and only fall back to find_text when ui_find returns nothing, with a clear rationale. Also notes the limitation with icon-only buttons, so the agent knows when this tool is unsuitable.

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 carry the safety profile (readOnlyHint=true), and the description adds substantial behavior beyond that: the output is exactly ONE tiled image with frame-number and timestamp stamps, per-frame change is measured, and duplicate frames are reported to catch stutter and frozen output. It also discloses how compare stacks a second sheet underneath in the same image, a non-obvious behavioral trait. No contradiction with the read-only annotation.

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

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

Five sentences, each earning its place: core purpose, why the tool exists (models cannot decode mp4), extra detection behavior, parameter workflow, and scope clarification. The core verb-and-output is front-loaded in the first sentence, and no wording is redundant.

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 tool with no output schema, the description covers the output artifact, the overview-then-zoom workflow, the compare layout, and the duplicate-detection behavior. The only notable omission is the return value, an agent is not told what the function returns after writing the sheet, though the outdir parameter provides the artifact location.

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 57% schema coverage, the description compensates for the real gaps: to_frame has no schema description at all, and the description explains its purpose alongside from_frame as a zoom into a fraction of a second. It also enriches compare's rationale (before/after needs both sheets in ONE image). However, cols and rows are left to inference from the 'tiled into a contact sheet' context rather than being explained.

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 first sentence states a specific verb-plus-resource: turn a video into ONE image, with N evenly spaced frames stamped with frame number and timestamp, tiled into a contact sheet. It explicitly positions this against the sibling screencast as the other half of screencast, so an agent can distinguish it from the other 32 tools 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?

The description names screencast as the complementary sibling and states the trigger condition: a model cannot decode an mp4, so a recording is useless until converted to stills. It also prescribes a workflow, use from_frame/to_frame to zoom into a fraction of a second once the overview shows the interesting moment, and scopes applicability with Works on any video, not just screencast output.

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

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

With no annotations provided, the description carries the full burden and discloses important behavior: it is a real press with a separate release, not a tap, and blocks for the duration. This adds meaningful behavioral context beyond 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?

Two sentences with no waste. The core behavior is front-loaded, followed by use cases, the blocking caveat, and the sibling alternative that should be used instead.

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

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

The combination of the description and the rich input schema covers the high-level behavior, blocking semantics, target focus guarantee, and visual feedback options. No output schema exists, but the tool's primary semantics are clearly 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 description coverage is 100%, so the baseline is 3. The description does not add parameter-specific detail beyond what the schema already provides, but the schema fully documents key, seconds, look, target, look_at, and settle_max_s.

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

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

The description uses a specific verb and resource: 'Hold ONE key down for a duration, then release it'. It clearly distinguishes this from a tap and from press_keys for combinations, so an agent can tell it apart from sibling tools 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?

The description states explicit use cases ('shift-selection, held-key scrolling and games') and names the alternative tool ('press_keys is the tool for combinations'). It also warns that the call blocks for the whole duration, giving clear when-to-use guidance.

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

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

With readOnlyHint=true, the safe-read nature is already annotated. The description adds meaningful context about what the journal contains, what it excludes, and the audit/replay use case, going beyond the annotation's bare safety signal.

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

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

The description is two tight sentences: the first states the core function and contents, the second gives usage guidance and an exclusion. Every sentence earns its place with no filler.

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

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

The tool is simple, the schema is complete, and the read-only annotation covers safety. The description explains the return content, use cases, and exclusions, so an agent has enough context to select and invoke the tool correctly without an output schema.

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

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

The schema describes both parameters fully, including default values, constraints, and field-specific semantics, so schema coverage is 100%. The description adds no additional parameter-level detail, which fits the baseline 3 for high 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?

The description states a specific verb and resource: 'Read back the trail of acted tool calls.' It also clarifies scope and content by listing what is journaled (arguments, outcome, hit/miss verdict, screenshot hash) and distinguishes itself from sibling tools with 'Reading tools are not in it.'

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

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

The description gives explicit use cases: reconstruct past context after loss and review an unattended run. It also provides a when-not-to-use signal by stating that reading tools are not included, though it does not name specific alternative sibling 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?

With no annotations, the description carries the behavioral burden, and it does disclose substantial behavior: launch confirmation is actually verified, the result carries the NEW window dict, and the screen-locked fallback returns a new AT-SPI app while naming the confirming mechanism. It could add failure behavior, but the core side effects and return semantics are clear.

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

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

The description is only two sentences. The first sentence leads with the action and immediately gives the confirmation contract; the second gives the use-case context. Every clause carries useful information, with no padding.

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 lack of an output schema, the description usefully describes result contents, including the locked-screen behavior. It also signals the protocol-native intent. It does not detail failure/timeout behavior, but the schema's timeout min/max/default partially fills that gap, so overall the tool is usable for first-step launch tasks.

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 at 80%, and the schema already explains file, command, desktop_id, and wait_window, including the exact-one constraint between desktop_id/command. The tool description adds no per-parameter meaning beyond that, so the agent has adequate but not enriched parameter semantics.

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: 'Start an application and confirm it actually arrived.' It also clarifies what makes this tool distinct from listing or activating apps: it handles the case where the app is not running yet, and it reports the NEW window or AT-SPI app that confirms launch.

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 clear context: 'Every real task starts with an app that is not running yet; this is that step.' The phrase also positions launch_app as the protocol-native replacement for shell-launching, so an agent knows when to reach for it. It does not explicitly name sibling alternatives, but the use-case signal is strong.

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?

readOnlyHint is true, and the description adds behavioral context beyond it: it returns the focused window, ids are consumed by type_text and press_keys, and ids change when a dialog is recreated while a wm_class/title fragment does not. The HOW TO DRIVE section also frames cost expectations by noting the round trip is expensive while actions take milliseconds. There is no contradiction with the read-only annotation.

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 first two sentences are front-loaded and high-value, but a long general desktop-driving primer follows, covering ui_find, find_text, do_steps, and screenshot policy. This material is only loosely about list_windows and would be better placed in a shared system prompt. The description is overlong for a zero-parameter, read-only tool, even though it is structured as a numbered list.

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 explains the return content ('id, wm_class, title, geometry, pid and which one has focus') and how the ids should be used, which is enough to call the tool correctly. It also covers the dynamic nature of ids and the recommended order of operations. It is functionally complete despite the extraneous driving advice.

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

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

The input schema is empty and schema description coverage is 100%, so there are no parameter semantics for the description to clarify. Baseline 4 applies because zero parameters mean the description has no burden to explain parameter meaning. The description appropriately focuses on outputs and usage instead.

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 resource ('every open window') with an explicit verb ('list') and enumerates the returned fields: id, wm_class, title, geometry, pid, and focus. It positions the tool as the entry point for obtaining window ids, which clearly separates its role from action tools like type_text and press_keys. An agent can tell exactly what this tool does without inspecting 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?

The description explicitly says 'Start here' for targeting type_text and press_keys and explains that ids from this list are what those tools consume. It also gives broader routing guidance for driving the desktop and says a full screenshot is the last resort. It does not explicitly contrast list_windows with sibling window-related tools such as window_at or ui_apps, so the when-not guidance is incomplete.

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

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

With no annotations, the description carries the full burden of behavioral disclosure. It does well by explaining that the screen is compared before and after, that clicks into dead space are reported as such, that the result is shown without a separate screenshot, and that keyboard movement is reported. It also discloses the refusal behavior when expect_window is not matched. It does not fully specify side effects or exact response shape, but it covers the key behavior strongly.

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

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

The description is front-loaded with the core action and includes several valuable behavioral notes without being bloated. It is slightly conversational and could be tightened, but every sentence contributes useful information about what the tool does and how to use it safely.

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 no output schema and no annotations, the description gives important behavioral context but does not fully cover the tool's usage space. It explains click landing, expect_window, and result presentation, but does not address choosing between ref and x/y, the meaning of other parameters, or the exact structure of the returned result. The rich schema descriptions compensate partially, leaving the description adequate but not complete.

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 73%, so the schema already documents most parameters. The description adds meaningful nuance for expect_window, explaining the difference between a missed click and clicking in someone else's window, but it does not add extra semantics for the other parameters, such as ref, button, count, or look_at. Overall it provides modest added value over the schema.

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

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

The description opens with a specific verb and resource: 'Click at an absolute screen position.' This clearly distinguishes the tool from siblings like pointer_move, pointer_drag, and pointer_scroll by establishing that it performs a click and reports outcomes. The additional details about landing detection and expect_window further clarify its role.

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 useful context, especially 'PASS expect_window' to avoid clicking in the wrong window, and notes it needs no consent dialog unlike xdotool. However, it does not explicitly say when to use pointer_click versus sibling input tools like pointer_move or pointer_drag, so usage guidance is implied rather than fully articulated.

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?

No annotations are present, so the description must shoulder the behavioral burden. It does disclose the crucial non-obvious trait that the travel is real intermediate motion, not a teleport. However, it omits other meaningful behaviors such as the default left button, step count, and how look/settle affect results.

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 action and then a discriminating behavioral caveat. No wasted words.

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

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

With 11 parameters, no annotations, and no output schema, the description is too thin to be complete. It covers the drag concept but not the parameter landscape, expected outcomes, or failure modes.

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 36%, so the description needs to compensate for undocumented parameters like steps, button, and expect_window. It only loosely covers from/to coordinates and says nothing about the other parameters, leaving the agent undersupplied.

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

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

The description clearly defines the action: press at one point, travel, release at another. It is specific about being a real drag with intermediate motion, distinguishing it from pointer_move and similar siblings.

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

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

Implied usage is clear – use for actual drag gestures where toolkits need real motion. But it does not explicitly name alternatives or state when not to use it, leaving the routing partly to inference.

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

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

With no annotations, the description carries the behavioral disclosure burden. It reveals a meaningful implementation detail: the move goes through org.gnome.Mutter.RemoteDesktop rather than ydotool, resulting in no acceleration curve and no closed loop. This is genuinely useful beyond 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?

Three sentences, no filler. The core action is front-loaded, then the exact execution path and coordinate semantics are added without redundancy. Every sentence earns its place.

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

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

For a simple pointer-move action, the description covers the essential behavioral context: absolute coordinates, coordinate origin, and the compositor path. While it does not describe return values or failure modes, the schema handles the look/settling parameters, making the overall package sufficient.

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

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

The schema has 67% coverage, leaving x and y undocumented. The description compensates by defining them as absolute screen coordinates consistent with list_windows and screen_map. Other parameters already have thorough schema descriptions, so the added coordinate context is the key contribution.

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 precise verb and resource: 'Move the pointer to an absolute screen position.' It also separates itself from pointer_drag, pointer_scroll, and pointer_click by emphasizing absolute positioning, and clarifies the coordinate convention shared with list_windows and screen_map.

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

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

The description implies when to use it: whenever an absolute pointer move is needed using the same coordinate space as list_windows and screen_map. However, it does not explicitly contrast with sibling tools like pointer_drag or pointer_position, nor does it state when not to use it.

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

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

Beyond the readOnlyHint annotation, the description adds meaningful behavioral detail: it may answer from the compositor or from the last server-set position, it explicitly says which source was used, and it never guesses from X due to staleness over Wayland surfaces. This is rich, non-obvious behavior disclosure.

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

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

The description is three short sentences, front-loaded with the core purpose, and every sentence adds necessary caveats about source reliability and staleness. There is no filler or redundant restatement of the tool name.

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 getter with no output schema, the description covers the key behavioral context: data source, fallback, and reliability. It could explicitly state the coordinate system or return format, but the semantics of 'pointer position' are sufficiently clear 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?

The tool has zero parameters and an empty input schema, so there are no parameter semantics for the description to clarify. The baseline of 4 applies because there is no parameter surface to document.

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

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

The description clearly identifies the tool as a pointer-position getter ('Where the pointer is'), which distinguishes it from pointer-mutation siblings like pointer_move and pointer_drag. It lacks an explicit verb like 'get' or 'read,' but the meaning is unambiguous.

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

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

The description explains when the compositor source is used and when the server-derived last position is used, which gives useful selection context. It does not name alternative tools or state when not to use it, but for a zero-parameter read-only getter the context is sufficient.

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

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

With no annotations, the description carries the full burden of behavioral disclosure. It adds a useful detail beyond the schema: the sign convention for dx and dy. However, it does not state whether the pointer is moved to the point first, what units dx/dy use, or whether any settling or screenshot behavior occurs. This is a meaningful but partial disclosure.

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

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

The description is short and front-loaded: the action is stated first, followed by the most important parameter semantics. There is no filler or redundant wording. It is appropriately concise, though it could be slightly expanded without becoming bloated.

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, no annotations, and no output schema, this description is too sparse to be complete. It leaves key invocation details to the schema or agent inference, such as what x/y actually represent, how dx/dy are interpreted, what expect_window does, and what happens after the scroll. The richer schema descriptions for look and settle_max_s help, but the overall tool context remains under-specified.

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 low (38%), so the description must compensate. It does add meaning for dx and dy by specifying scroll direction, and 'at a point' implies x and y are the target coordinates. However, it does not explain expect_window, the meaning or units of dx/dy values, or other parameters, so compensation is incomplete.

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 operation as a wheel-based action at a point, which distinguishes it from pointer_click and pointer_move siblings. The direction semantics ('dy positive scrolls down, dx positive scrolls right') further clarify what the tool does. It could be stronger by explicitly saying 'scrolls' rather than 'wheel clicks', but the meaning is reasonably clear.

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

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

There is no guidance about when to use pointer_scroll versus alternatives like pointer_click, pointer_drag, or pointer_move. No context is given for scrolling behavior, prerequisites, or situations where this tool is preferable. The agent is left to infer usage from the tool name and minimal description.

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

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

With no annotations, the description carries the transparency burden and does meaningful work: it discloses that focus is confirmed before any key is sent, that nothing is typed if focus fails, and that Ctrl+Alt+F1-F12 is deliberately refused because it can look like a frozen machine. It falls short of full transparency because it says nothing about return behavior or other side effects.

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 short sentences, each earning its place: the core action with an example, the batching guidance, and a critical safety warning. There is no filler or redundant restatement of 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?

Given no output schema and no annotations, the description covers the essential selection and safety context: focus confirmation, fail-safe behavior, the do_steps alternative, and the dangerous combo. The schema covers the look and settle parameters, making this complete enough to invoke correctly, though a one-line statement of what the tool returns would make it fully self-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 83%, so the schema already documents most parameters. The description adds an extra combo example and reinforces the focus-confirmation behavior for target, but the optional 'via' parameter remains undocumented and the description does not compensate for that 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 states a specific verb ('Send') and a well-defined resource ('a key combination to a named window'), with a concrete example ('ctrl+s'). It also distinguishes itself from do_steps by advising chaining, so an agent can tell when this tool is the right one.

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

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

It gives an explicit routing rule: chain several key combinations with do_steps instead of calling this tool once per combo, which is actionable guidance. It also warns against the dangerous Ctrl+Alt+F1-F12 combination, but it does not compare press_keys with closely related keyboard siblings like ui_press, hold_key, or type_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?

The description adds meaningful behavioral context beyond the readOnlyHint annotation: it explicitly says the tool 'Polls pixels', 'returns as soon as it changes', and waits. This tells the agent the tool is a polling/observation primitive, not an immediate action. No contradiction with annotations and no misleading claims.

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 behavior, then enriched with relevant use cases and mechanism. Every sentence adds value: one states purpose, one gives when-to-use, one explains the polling approach. No fluff 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?

The description covers overall purpose, polling behavior, return timing, and main inputs, but no output schema leaves 'show it' somewhat ambiguous. It also does not address what happens when neither window nor region is provided, or how the tool signals a timeout. Given 5 params and low schema coverage, the description is solid but not fully complete.

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 40%, with window, timeout, and poll_seconds lacking schema descriptions. The description partially compensates by mentioning 'window or rectangle' and 'Polls pixels', which maps to window vs region and poll_seconds. However, it does not explain timeout semantics, defaults, units, or how window vs region interact, leaving an agent with meaningful gaps.

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 ('Wait until a window or rectangle CHANGES, then show it') and clearly identifies the resource. It also differentiates itself from the sibling wait_for by saying 'For anything wait_for cannot express', so an agent can tell this tool apart from the most similar alternative.

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

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

The description gives concrete use cases ('a reply arriving, a spinner finishing, a download completing') and contrasts itself with taking blind screenshots, implicitly directing the agent away from screenshot-based polling. It does not explicitly name exclusions, but the context is clear enough for an agent to select this tool over wait_for or screenshot.

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

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

Annotations already declare readOnlyHint=true, and the description does not contradict that. It adds valuable behavioral context beyond the annotation: it uses the xdg portal to org.gnome.Mutter.ScreenCast, skips the consent dialog, encodes on the iGPU, and suggests reading frames back with ffmpeg. This is useful implementation-level transparency.

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

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

The description is compact and front-loaded: purpose first, then the key usage decision, then brief implementation detail, then the outcome-readback hint. No sentence is redundant, and the structure makes the most decision-relevant information appear early.

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 screen-recording tool with no output schema, the description sufficiently covers what the output is (h264 mp4), how to consume it (ffmpeg), and the key behavior (no consent dialog, iGPU encoding). It does not detail return values or consequences of optional parameters, but those are secondary and partly covered by the input schema defaults.

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

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

Schema description coverage is only 40%, with fps, seconds, and include_cursor lacking schema descriptions. The tool description mentions screen vs. one window, which relates to target, but does not explain the semantics of fps, seconds, or include_cursor. With low schema coverage, the description needed to compensate for those parameters but did 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?

The description starts with a specific verb and resource: 'Record the screen, or one window, to an h264 mp4.' It clearly differentiates itself from screenshot by stating when motion capture is needed, naming the sibling tool explicitly and explaining why stills are insufficient.

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

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

It explicitly says to use this tool 'instead of screenshot whenever the thing being judged MOVES' and gives concrete examples: animation, transition, scroll, stutter, hover state. It also explains the limitation of the alternative ('Stills cannot show motion and bursting them tops out near 5 fps'), so an agent can choose confidently.

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 readOnlyHint annotation already marks the call as non-mutating, and the description adds genuinely useful behavioral detail a caller could not infer: refs are valid until the next screen_map call, refs_generation identifies the issuing call, and windows are ordered with the topmost first. This materially reduces the risk of stale-ref mistakes.

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?

Each sentence is information-dense and earns its place: the first defines the output, the second gives the decision-relevant purpose, the third explains ref lifecycle and use. It is front-loaded with the core 'coordinates to reach it' idea and contains no fluff.

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

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

With no output schema, the description does a good job of explaining return content and ref validity, and the generation marker closes an important ambiguity. However, it stays silent on the limit and widgets parameters, so an agent cannot predict truncation or reduction of the widget list without guessing.

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

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

Schema description coverage is only 33%: app is described in the schema, but limit and widgets are bare. The description does not compensate by explaining what limit controls, what widgets=false does, or how app scopes the operation to a non-focused application.

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 an exact deliverable: screen coordinates for the desktop, windows, pointer, and pressable widgets, and frames the tool as the one that turns 'click the Save button' into a number without looking at an image. This clearly distinguishes it from visual/coordiate tools like screenshot and from ref-consuming tools like ui_press/pointer_click.

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 strongly implies when to use it: any time you need exact pixel/ref coordinates or need to convert a semantic widget into an actionable ref. It even tells the caller what to do with refs, but it does not explicitly name alternatives such as ui_find or screenshot or say when not to use this call.

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

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

Beyond the readOnlyHint annotation, the description discloses important behaviors: the image is returned inline with nothing to Read afterwards, window captures reflect whatever is on screen including occluding content, annotate labels are in SCREEN coordinates, and scale below 1 harms readability. These are genuinely useful behavioral details not present in the 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 description is longer than average but every sentence earns its place: primary behavior, token costs, crop advice, combination semantics, coordinate labeling, and alternatives. It is front-loaded with the core outcome before diving into tradeoffs.

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 properly explains return behavior. It covers capture targets, inline vs file-only behavior, scaling pitfalls, occlusion semantics, coordinate conventions, and alternative tools. For an 8-parameter screenshot tool, this is sufficiently complete.

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 high (88%), so the baseline is 3, and the description adds real value beyond the schema: scale cost/readability tradeoffs, window+region composition, and annotate's coordinate purpose. However, include_cursor has no schema description and is not mentioned in the description, leaving one parameter fully 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 description opens with a specific verb and resource: 'Look at the screen, one window, or one rectangle,' and clarifies the immediate return behavior ('image comes back in this reply'). It also differentiates from siblings by naming ui_find and find_text as non-image alternatives and noting that acting tools already show results.

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

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

It gives explicit when-not-to-use guidance: ui_find and find_text answer 'where is X' without an image, and every acting tool already shows the result. It also gives concrete crop-vs-shrink guidance with token cost comparisons and explains the window+region combination semantics, so an agent can choose the right capture mode.

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

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

With no annotations, the description carries the full disclosure burden. It reveals that focus is confirmed before typing, nothing is typed if confirmation fails, the widget is read back for verification, and keysyms avoid keyboard-layout transposition. It stops short of explaining what happens if the read-back verification fails, but this is otherwise strong behavioral disclosure.

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

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

The description is three sentences, each adding distinct value: the verification workflow, the keysym technical property, and the alternative tool. There is no filler, and the most important behavioral guarantee is front-loaded.

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

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

For a tool with 8 parameters, no annotations, and no output schema, the description covers the core workflow, a critical safety property, and the main alternative. The only notable gap is the absence of an explicit statement about what happens when post-type verification fails or what the tool returns.

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 88%, with detailed descriptions for via, look, target, look_at, verify_app, and settle_max_s. The description itself adds no per-parameter semantics, only global context about keysym delivery and verification, so the baseline for high schema coverage 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 opens with 'Type into a named window,' giving a specific verb and resource. It also distinguishes itself from ui_set_text by explaining that ui_set_text hands text directly to the widget and requires no focus, making the tool's unique 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?

The description explicitly names ui_set_text as the preferred alternative when it works, giving the agent a clear routing condition. It also explains type_text's focus-confirmation guarantee, which helps the agent decide when this tool is appropriate.

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

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

The readOnlyHint annotation already declares that the tool is read-only, and the description adds value by indicating the result is a live snapshot of the AT-SPI bus ('currently') and that the returned values are directly consumable by sibling tools. No side effects are implied and no contradiction exists.

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 main object and followed by a targeted note about how the result is used. Every word earns its place.

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

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

For a zero-argument, read-only enumerator, this description is sufficient: it defines the output and explains its relationship to ui_tree and ui_find. It does not cover empty-bus edge cases or output formatting, but those are minor gaps given the tool's low complexity.

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

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

The tool has zero parameters and an empty input schema, so there is nothing for the description to add. The baseline of 4 for zero-parameter tools 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 clearly states that the tool provides applications currently on the AT-SPI bus, and it distinguishes itself from sibling tools by noting that these names are what ui_tree and ui_find accept as input. The verb 'list' is implicit, but the meaning is unmistakable.

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

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

The description gives clear usage context: use this tool to obtain valid app names for ui_tree and ui_find. It does not explicitly mention alternatives or when not to use it, but the integration hint is actionable and specific enough.

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 provide readOnlyHint=true, and the description adds valuable behavioral context: returned paths are only valid while the accessibility tree is unchanged, and lookup works through AT-SPI independent of window position. This goes beyond the annotation without contradicting it.

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, each earning its place: the first states what the tool does, the second explains why it is the reliable way to act, and the third gives a critical freshness caveat. It is front-loaded and free of fluff.

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

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

The description covers purpose, mechanism, and a key validity constraint, and 100% param schema coverage fills in the parameter details. There is no output schema, so it would be helpful to describe the exact return format more explicitly, but 'Paths returned here' already indicates the return value and its intended downstream 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?

Schema description coverage is 100%, so the schema already documents all five parameters in detail. The description adds little parameter-specific meaning beyond the schema, only framing the tool's purpose rather than elaborating on app, role, text, depth, or actionable_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?

The description states a specific verb and resource ('Find widgets by visible text') and positions itself as 'THE way to locate something to act on', which conveys its role among the broader toolset. It does not explicitly name sibling tools like ui_tree or find_text to differentiate itself, so it falls just 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?

The description gives clear usage context: use this when you want to locate a real widget to act on, and it emphasizes robustness ('cannot miss and does not care where the window moved to'). It also provides a strong sequencing guideline ('find, then act') and warns about tree changes. It does not explicitly state exclusions or when to prefer alternatives.

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

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

With no annotations, the description carries the behavioral burden and does well: it explains that the tool acts through the widget's own AT-SPI action and adds a meaningful safety detail — it refuses when the path no longer matches the expected widget, preventing accidental presses on the wrong element. It does not detail side effects or failure output, but the core behavior is clearly disclosed.

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

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

Two sentences, both informative: the first states purpose and preference, the second states the critical safety constraint. No filler, no repetition of schema content, and the most decision-relevant information is front-loaded.

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

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

For an 8-parameter tool with no annotations and no output schema, the description covers the essential selection and safety context. It could go further by describing what the action actually returns or how failures surface, but the parameter schema covers the remaining operational details well.

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 high at 88%, so the schema already documents most parameters. The description adds genuinely non-schema value by stating that expect_name or expect_role is required at runtime, despite the schema's required list being empty, and by explaining the safety consequence of these guards.

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 (invoke a widget's own action) and the mechanism (AT-SPI), making clear this is not a coordinate click like pointer_click or a key press like press_keys. Calling it 'the preferred way to act on this desktop' further distinguishes it from sibling tools.

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

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

Explicitly frames the tool as the preferred way to act on the desktop, which tells the agent when to reach for it over pointer-based alternatives. It does not spell out when to avoid it or explicitly name alternatives, so it falls short of a full 5.

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

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

The description adds behavior beyond the readOnlyHint annotation by specifying that the content is read 'straight out of the accessibility tree' and frames it as a verification step. This gives insight into how the value is obtained and why it is authoritative, without contradicting the annotation.

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, no wordiness. The first sentence states the operation, the second communicates the intended use case. Every sentence earns its place and the key concept is front-loaded.

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

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

For a simple read tool with readOnlyHint and a fully documented schema, the description is complete: it states what is returned (content), where it comes from (accessibility tree), and when to use it (verify something landed). No critical gap remains.

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

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

Schema description coverage is 100%, so the baseline is 3. The description itself adds no parameter-specific meaning; the detailed guidance about `app`, `path`, and the focused text widget lives in the input schema rather than in the description.

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

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

The description uses a specific verb ('Read') with a clear resource ('content of a text widget') and source ('accessibility tree'). It also states the intent: verification that something landed, which distinguishes it from sibling tools that send keystrokes or search for text.

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

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

It explicitly frames when this tool is appropriate: to VERIFY that something landed after input, rather than trusting a keystroke arrived. It does not name a specific sibling alternative, but the context is clear enough for an agent to select it for read-verification tasks.

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

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

With no annotations, the description carries the behavioral disclosure burden and does it well: it reveals that no focus is needed, that it works on a locked screen, that it does not rely on ydotool, and that it verifies the text landed by reading the widget back. It does not mention what happens with existing text when replace is false, but the schema covers the replace parameter.

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

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

The description is concise, front-loaded, and every sentence earns its place. It states the core purpose, the key behavioral advantages, and the sibling fallback condition without adding redundant details.

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

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

For a 7-parameter tool with no output schema, the description gives enough decision-relevant context: what the tool does, how it works, and when not to use it. It does not fully spell out able default insertion behavior or return-value shape, but the schema's rich parameter descriptions compensate for those gaps.

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

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

Schema description coverage is 100%, so the schema already fully documents all seven parameters. The description adds useful context about the overall mechanism and verification behavior, but does not add much per-parameter meaning beyond what the schema provides. This matches the baseline for full 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?

The description opens with 'PREFERRED way to enter text' and states it writes through AT-SPI EditableText, giving a specific verb, resource, and mechanism. It also explicitly distinguishes itself from the sibling type_text by naming it and explaining the boundary.

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

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

It clearly states when to use this tool: for entering text into AT-SPI-editable widgets, including when focus is unavailable or the screen is locked. It also gives an explicit exclusion: 'Use type_text only when a widget is not AT-SPI-editable,' which tells the agent when to choose the alternative.

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 readOnlyHint annotation already indicates a safe read operation, and the description adds meaningful behavioral context by specifying what the tree exposes. It also signals that ui_find is likely the better default, which is useful beyond the annotation, though it does not mention performance or failure behavior when the app is not available.

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, both purposeful: the first defines the tool's output and the second gives routing guidance. 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?

The description covers the tool's scope, output contents, and relationship to ui_find, which is most of what an agent needs for a simple read-only tool. However, with no output schema and an undocumented optional 'depth' parameter, the definition is not fully complete.

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

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

The schema describes the 'app' parameter as 'Application name from ui_apps', but the 'depth' parameter has no schema description. The tool description adds no parameter-level guidance, leaving the meaning and effect of 'depth' unclear to an agent.

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

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

The description clearly identifies the tool as retrieving an accessibility tree for a single application and lists the key data it contains (roles, names, screen bounds, actionable nodes). It also implicitly distinguishes itself from the sibling ui_find by framing this as the whole-window tree option.

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

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

The description explicitly says 'Prefer ui_find unless you genuinely need the shape of the whole window,' which gives the agent a concrete rule for choosing between this tool and a sibling. This is clear when-to-use and when-not-to-use guidance.

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

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

Beyond the readOnlyHint annotation, the description reveals how the tool behaves: it polls OCR, AT-SPI widgets, clipboard, or timers; it returns as soon as the condition is true; it honestly reports timeouts; and it clamps timeouts over 300s. This gives the agent a clear mental model of polling semantics.

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

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

The description is dense and every sentence carries information, but the long run-on structure could be easier to parse. The core purpose is front-loaded, and the condition list is compact, so it remains effective.

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

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

For a tool with 6 parameters and no output schema, the description explains the major behavioral modes and timeout handling well. However, it omits a precise definition of target for several conditions and does not clarify the exact return value on success or timeout, which an agent would need for reliable downstream 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?

The description adds useful meaning for condition values and timeout behavior, but it never clearly binds the target parameter to conditions such as window_exists or text_appears, despite schema coverage being only 50%. The parameter semantics are partially compensated, not fully.

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

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

The description opens with a specific verb and resource: 'Wait until the desktop reaches a state.' It then enumerates all supported condition types, making the tool's scope immediately identifiable and distinguishing it from a simple sleep or blind wait.

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 practical guidance for when to use specific conditions, such as using text_appears to detect a reply or build finishing and using elapsed when there is nothing to poll. It also contrasts this tool with sleeping a guessed number of seconds. It does not explicitly compare against sibling tools like assert_state, but the condition-level guidance is substantial.

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 readOnlyHint annotation already signals safety, and the description adds meaningful behavior: the compositor pick respects input shapes, sees through click-through overlays, and the result includes every window whose rectangle covers the point. This is beyond what annotations convey.

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 deliver the purpose, the usage trigger, and the key output distinction, front-loading the main idea. 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?

With no output schema, the description still explains what the tool reports: the compositor's pick and all covering windows. The only notable gap is the undocumented coordinate system, but for a simple read-only hit-test tool it is otherwise 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 0%, so the description carries the burden for x and y. It only refers to 'this point' and does not specify coordinate space, units, or whether coordinates are screen-relative vs image-relative, which is essential for correct use with screenshots.

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 operation: determine what a click at a coordinate would hit. It disambiguates from sibling tools by promising both the compositor's input-shape-aware pick and all covering windows, which no sibling name suggests.

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

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

Explicitly tells the agent when to use it: before clicking a location inferred from a screenshot. It does not spell out exclusions or alternatives, but the use-before-clicking context is clear.

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

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

The description discloses a genuinely useful behavioral trait: the result reports the window's post-operation state, not merely that the call was sent. It also explains that a close that leaves the window standing names the likely reason, such as an unsaved-changes dialog. With no annotations provided, this is meaningful transparency, though it stops short of covering side effects, reversibility, or permissions.

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

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

The description is compact and front-loaded with the action list, then result semantics, then the close-failure behavior. The last sentence is grammatically awkward and 'where these are ordinary calls' is slightly extraneous, but overall every sentence contributes useful information without padding.

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 mutation tool with no annotations and no output schema, this description covers purpose and one error mode but lacks parameter semantics, when-to-use guidance, and broader behavioral outcomes. An agent would likely need additional information to invoke it reliably, especially for workspace and geometry 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 description coverage is only 38%, so the description must compensate. It loosely connects actions to parameters (pin to 'above', workspace to 'index', geometry to x/y/width/height), but it does not clarify coordinate origin, units, workspace indexing, or valid ranges. Several parameters remain effectively undocumented, so the description is too thin to bridge the schema 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 names a specific resource (windows) and a clear set of verbs: move, resize, close, minimize, maximize, re-workspace, pin. It distinguishes itself from read-only window tools like list_windows or window_at by emphasizing mutation/manipulation through the compositor. Minor ambiguity from 're-workspace' and typos in the enum values keep it from 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 explicit guidance on when to use this tool versus siblings such as activate_window, list_windows, or window_at. The phrase 'through the compositor, where these are ordinary calls' hints at context but does not define selection criteria or exclusions. Usage is only implied by the operation list.

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

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

Annotations carry readOnlyHint, and the descrption's observe/capture framing is consistent with it — no contradiction. It adds genuinely useful behavioral traits beyond the annotation: never-scaled full-resolution capture, and the refusal error when the region exceeds half the desktop, which an agent must know before invoking. It stops short of disclosing what the tool returns or how the PNG result is consumed, which would have made it fully transparent.

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 compact sentences and front-loaded: the core purpose and sibling contrast land in sentence one, with use cases and the size cap following in order of importance. The final clause 'zoom exists to spend tokens on FEW pixels' is mildly redundant with the refusal statement, but costs little and reinforces intent.

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

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

For a read-only capture tool with full schema param coverage, the descrption covers purpose, alternative, use cases, and the key failure mode. The one substantive gap is the return value — with no output schema, the agent is left to infer from the path parameter that a PNG path is what comes back.

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

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

Schema coverage is 100%, so the schema documents all four parameters and the baseline is 3. The descrption adds one meaningful param-level constraint the schema lacks — 'Refuses more than half the desktop' caps the region size — and the 'small area' framing ties the region parameter to the tool's intended use. That value above baseline justifies a 4.

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

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

States a specific action and resource — 'Look closer at a small area at FULL resolution' — and immediately differentiates itself from the screenshot sibling by the scaling contrast. Names concrete use cases (tiny glyph, hairline border, icon) and a precise size constraint. An agent can select this over screenshot without opening either 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 names the alternative (screenshot) and the decisive differentiator (the model's 1568px ceiling vs full-resolution capture). The 'For a tiny glyph, a hairline border, an icon' list gives concrete when-to-use guidance, and 'Refuses more than half the desktop' supplies the when-not boundary.

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