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

No annotations are provided, so the description carries the full burden of behavioral disclosure — and it goes far beyond basic mutation info. It discloses read-only status ('no input injection, no focus change'), explains the JPEG-vs-PNG size tradeoff relative to the 32 MiB provider cap, quantifies token costs (~12,500 vs ~50 tokens), and warns about the dpi_verified=false pairing hazard. This is exemplary behavioral transparency with zero annotation support.

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

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

The description is long but every clause earns its place — the coordinate alignment, file/scale/bounds return contract, size rationale, and token economics all carry operational value. It's front-loaded with the primary purpose and cropped-client-area detail. Slightly essay-like ('which is what keeps a long session's request body under the provider's 32 MiB cap') but purposeful; each sentence advances understanding.

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

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

For an 8-parameter tool with no annotations and zero schema coverage, this description is remarkably complete: it explains the return contract (bounds, scale, dpi_verified) even though an output schema exists, covers file-saving semantics, and anticipates the exact failure mode an agent would hit (huge base64 payloads). Nothing critical an agent needs to invoke it correctly or interpret its output is missing.

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

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

Schema description coverage is 0%, so the description must compensate — and it does, covering nearly every parameter in prose: hwnd/title (provide either), client_only (client area cropping), max_dim (downscaling), quality (JPEG q80 default), include_data_uri (token cost and base64 inlining), and save_path (read with read_image). A minor gap is that image_format is never explicitly named, and some parameters aren't labeled by their schema property names, but the intent is conveyed well.

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

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

States a specific verb and resource ('Capture a window screenshot and SAVE IT TO A FILE') and adds a distinguishing detail — cropping to the client area with aligned coordinate systems — that differentiates it from siblings like tool_skyshot. The purpose is unambiguous and the resource (window) is 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?

Gives explicit input guidance ('Provide hwnd or title substring') and a conditional rule for when to pass include_data_uri ('only when a caller genuinely cannot read a file'), plus a recommended alternative (read_image). However, it never names sibling tools as explicit exclusions (e.g., when to prefer tool_skyshot or tool_get_window_rect over this), so it lacks direct when-not 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?

No annotations are present, so the description carries the full burden. It discloses mutation, serialization, user yielding for the raw path, z-order/focus dependencies, window ownership verification, and dry_run side-effect-free behavior. This is unusually rich and goes well beyond a simple 'click'.

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

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

The description is long but front-loaded with the core purpose and every sentence adds a distinct behavioral fact. The MUTATING and dry_run sentences are dense but necessary; could be slightly tightened but overall well structured.

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 6-param tool with no annotations and no schema descriptions, the description covers most behavioral context but leaves title and full prefer semantics undocumented. It is close to complete but not fully sufficient for all invocation decisions.

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

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

With 0% schema coverage, the description must document parameters. It explains x/y are client-area coordinates, dry_run prevents effects, prefer relates to element vs raw, and hwnd as 'addressed window'. Title is not documented, and prefer values beyond default 'element' are unstated, so compensation is strong but 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?

States a specific action ('Click at client-area coordinates within a window') and gives coordinate meaning. It explains internal click paths but does not explicitly differentiate from sibling tools like tool_element_action_at or tool_send_keys, so it lacks direct sibling contrast.

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 how the tool behaves (element first, raw fallback, dry_run) and when it is safe to use, but it never tells the agent which sibling to choose instead. No exclusions or comparisons to alternatives are given, so usage guidance is implied by the action itself.

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 key behavioral trait: non-text clipboard content reports empty text rather than failing. This goes beyond the basic read-only annotation and helps the agent anticipate edge cases. However, it does not mention potential side effects (e.g., clipboard access permissions) or whether the clipboard is cleared after reading, but for a read operation this is minor.

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 short sentences with no wasted words. It front-loads the core action ('Read the current clipboard text'), then adds the read-only note and the edge-case behavior. 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 zero-parameter read tool, the description is nearly complete. It states what it does, the read-only nature, and the behavior for non-text content. The only minor gap is not describing the exact return format (e.g., whether it returns a string or an object), but the output schema exists and likely covers that. The description is sufficient for an agent to call it correctly.

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

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

The tool has zero parameters, so the description does not need to explain parameter semantics. The schema is empty and coverage is 100%, meaning there is nothing undocumented. The description adds value by clarifying the return behavior for non-text content, which is more useful than parameter details.

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

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

The description clearly states the tool reads the current clipboard text, using a specific verb ('Read') and resource ('current clipboard text'). It also distinguishes itself from the sibling tool_clipboard_write by focusing on reading rather than writing. The behavior for non-text content is explicitly described, which further clarifies its purpose.

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

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

The description implies when to use this tool: whenever an agent needs to retrieve the current clipboard text. It does not explicitly name alternatives or exclusions, but the sibling list includes tool_clipboard_write, and the read-only nature is clear. The context is sufficient for an agent to select this tool over writing to the clipboard.

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 fully carries the behavioral burden. It explicitly labels the tool as MUTATING, warns that it DESTROYS the user's last copied content, mentions serialization across sessions, and instructs the agent to announce the action. This exceeds typical 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 two sentences with no fluff. The primary action is front-loaded, and the critical warnings are placed immediately after, making the most important information easy to scan.

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

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

For a simple one-parameter write tool, the description covers the action, destructive consequences, persistence behavior, and usage caution. The presence of an output schema means return-value details are unnecessary here, so the description is complete 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 schema has no descriptions for the single 'text' parameter, and the description only vaguely maps to it via 'with text.' This provides basic meaning but does not fully compensate for the 0% schema coverage, so it lands at an adequate but not exceptional level.

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 'Replace the clipboard contents with text,' which is a specific verb and resource. It clearly identifies the tool as the write counterpart to clipboard_read and leaves no ambiguity about its function.

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

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

The description advises against casual use and instructs the agent to announce the action, giving clear context for safe usage. It does not explicitly name an alternative tool or state when not to use it beyond the strong caution, so it falls just short of a 5.

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

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

With no annotations provided, the description carries the full burden and does disclose the key behavioral trait: 'Read-only.' It also sets expectations about the returned data by listing tunables, health, and timing information. It does not cover access prerequisites or failure behavior, but those are less critical for a stateless status report.

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

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

A single dense sentence with the core purpose front-loaded before a colon-delimited list of report contents. Every phrase earns its place, and the description avoids padding while remaining technically precise.

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 status tool with an output schema, the description provides both when to invoke it and what data to expect. The output schema covers the return structure, so nothing an agent needs to call this tool correctly is missing.

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

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

The tool has zero parameters, so there is no schema description to compensate for; the 0-param baseline is 4. The description still adds semantic context by enumerating what the caller receives, which is useful even though there are no inputs 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?

States a specific verb ('Report') and resource ('coexistence policy in force'), then enumerates exact contents such as the admission gate, tunables, named-mutex health, and last physical input. This clearly distinguishes it from sibling action tools like tool_click_at and tool_send_keys, which perform UI operations rather than report policy state.

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

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

Explicitly states when to call it: 'call it when an action was refused with user-active or arbiter-busy and you want the numbers behind the refusal.' It also frames the tool as read-only, making it clear this is a diagnostic fallback rather than a routine action; no alternative tool is needed because no sibling offers this state.

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 of behavioral disclosure. It explicitly states 'Read-only', indicating no side effects, and specifies that values are in physical pixels, which is critical for coordinate interpretation. This provides meaningful transparency beyond a bare 'returns position' statement.

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

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

The description is a single, front-loaded sentence that conveys the primary purpose (cursor position and screen size) and a key qualifier (physical pixels), followed by the 'Read-only' trait. There is no wasted prose, and the most important information appears first.

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 (no parameters) and an output schema exists (not shown but indicated), so the description need not explain return types. It covers purpose, units, and side-effect nature. Minor details like multi-monitor behavior are not addressed, but for a basic read tool this is adequate. The presence of an output schema reduces the burden further.

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

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

The tool has zero parameters, so the baseline is 4 per the rubric. The description adds no parameter semantics (there are none to explain), but it does clarify the output semantics (position and screen size), which is useful context. No gaps exist since there are no parameters 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 states the tool returns the current cursor position and screen size in physical pixels, which is a specific purpose distinct from sibling tools like tool_click_at (which manipulates coordinates) or tool_get_window_rect (which returns window bounds). The 'Read-only' phrase further disambiguates it as a query operation.

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

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

The description implies usage when an agent needs the cursor position or screen dimensions, but it does not explicitly mention when to choose this tool over alternatives or list exclusions. Since the purpose is self-contained and no alternative is cited, the guidance is implied rather than explicit.

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

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

With no annotations provided, the description carries full behavioral burden and does so thoroughly. It discloses mutation ('MUTATING (soft)'), serialization across sessions, lack of physical input injection, the ability to run during user typing, and refusal behavior with the supported action list. This is far beyond the minimal.

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

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

The description is dense but every sentence earns its place. It front-loads the core purpose, then adds constraints, safety context, and parameter semantics in a logical order. No filler or tautology.

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 3 parameters and an output schema, the description is complete. It covers action constraints, the source of ref, the mutating behavior, safety implications, and refusal behavior. Return values are not explained, but the output schema already handles that.

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

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

Schema coverage is 0%, so the description must compensate. It explains ref as coming from element_at_point, enumerates valid action values, and explicitly ties text to set_value. This adds substantial meaning to all three parameters, including the optional text parameter.

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 ('Perform an action'), a precise resource ('a UI element by the ref from element_at_point'), and a distinguishing property ('focus-free path'). The description clearly differentiates this from coordinate-based or physical-input tools like tool_click_at and tool_element_action_at.

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

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

Provides clear context: use this path when you have a ref from element_at_point and want a focus-free action. It also gives a concrete usage caveat ('do not operate the very window the user is working in') and notes it can run while the user types. It does not explicitly name alternatives or exclusions, but the guidance is strong enough to infer appropriate use.

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. It discloses that the tool is 'MUTATING (soft)', is serialized across agent sessions, injects no physical input, never raises the window, and refuses stale indexes rather than acting on them. These are all meaningful behavioral traits that an agent needs to know.

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

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

Three sentences pack in the core action, the differentiator, behavioral caveats, parameter options, and freshness guidance. Nothing is redundant, and the most important information (what the tool does and when to use it) 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 mutation tool with four parameters and an output schema, the description covers the essential decision points: what index means, what actions are available, the soft-mutation semantics, and the stale-index safeguard. It doesn't detail every possible error or the return format, but the output schema presumably handles that. The description is nearly 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 0%, so the description must explain the parameters. It does: it enumerates the valid action values, notes that set_value additionally requires text, and explains that index refers to a line in the last skyshot. It does not elaborate on hwnd or the exact meaning of each action, but the critical disambiguation is provided.

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 ('Act on') and resource ('element that line index of the last skyshot'), and immediately distinguishes itself from a sibling tool by calling itself the 'focus-free path' for elements element_at_point cannot reach. The list of possible actions further clarifies its scope.

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 sibling alternative (element_at_point) and gives a concrete condition for when to use this tool instead: 'for elements element_at_point cannot reach'. It also advises taking a fresh skyshot when the UI changes, which is a clear operational rule. No other alternatives are mentioned, but the primary decision point is covered.

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

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

With no annotations, the description carries the full burden. It explicitly states 'Read-only — moves no cursor and changes no focus', which is a key behavioral disclosure. It also mentions the return of an opaque ref. It doesn't cover error conditions or edge cases like no element at the point, but for a read-only query the main behavioral trait is 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?

The description is compact, with no filler. The core purpose is front-loaded, followed by return values and the crucial coordinate-space clarification, and ends with a safety note. 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?

The tool has only two parameters and an output schema, so the description doesn't need to explain return values. It covers the use case, coordinate space, and read-only behavior. The only minor gap is not addressing the case where no element exists at the point, but the output schema likely handles that. Overall it is complete enough for correct invocation.

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

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

Schema coverage is 0%, so the description must compensate. It explains that x and y are physical pixel coordinates in the same space as capture bounds, which is critical for correct usage. It also emphasizes 'PHYSICAL screen point' to avoid coordinate-space ambiguity. This adds meaning well beyond the bare integer type in 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 ('Identify') and resource ('UI element at a PHYSICAL screen point via Windows UI Automation'), then lists exactly what is returned (name, role, rect, supported actions, opaque ref). It also distinguishes itself from siblings by framing it as the way to turn a screenshot point into an addressable element without clicking, clearly separating it from click_at and read_element.

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

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

The description states when to use it: when you have a physical screen coordinate from a screenshot and want to address the element without clicking. It notes the coordinate space matches capture bounds. It does not explicitly name alternatives or state when not to use it, but the purpose is clear enough that an agent can infer it is the right tool for point-based element lookup.

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, and it does disclose useful behavior: 'Read-only', the minimum-one-filter constraint, that results are refs actionable via element_action, and the important caveat that a zero/minimized result is not proof of no match. It still omits behaviors such as what hwnd=0 means, how include_offscreen and max_results affect results, or ordering/truncation of output.

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

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

Front-loads the purpose and constraint, then adds caveats; every clause is relevant. Slightly verbose in the middle ('the point of naming it is that you no longer need a pixel'), but no sentence is wasted.

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

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

For a 7-param read tool with an output schema, the description covers purpose, precondition, alternative, and even one return field ('minimized'), which is a helpful bonus since output schemas don't explain semantics. The remaining gap is the undocumented non-filter parameters, which is a parameter-semantics issue more than a completeness one.

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% across 7 parameters, so the description must compensate — it explains role (lowercase skyshot roles, with examples) and effectively name_contains ('name substring'). However hwnd, title, max_results, automation_id, and include_offscreen receive no meaning beyond their names, so the compensation is only partial.

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 ('Find UI elements by role and/or name substring') and names the downstream consumer (element_action), which makes the tool's output role unambiguous. It also explicitly separates itself from tool_skyshot and explains the hit-testing use case, so an agent can distinguish it from siblings without opening the schema.

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

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

Gives an explicit when-to-use ('reach an element that cannot be hit-tested'), an explicit when-not ('an unfiltered call would be a tree dump, so use skyshot for that'), and names the follow-up tool (element_action). It even states a hard precondition — at least one filter is required.

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

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

No annotations are provided, so the description carries the full burden. It discloses the tool is read-only, which is a key behavioral trait, and states the return content (hwnd and geometry). However, it does not mention behavior when no match is found, case sensitivity, or whether multiple matches are possible. This is minimal but not absent.

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

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

The description is a single, front-loaded sentence that states purpose and read-only nature efficiently. It could include a bit more detail without losing conciseness, but it is appropriately brief and wastes no 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?

Given an output schema exists, return values are covered. The tool is simple with one parameter. Missing details include behavior on no match, multiple matches, and case sensitivity, which could affect an agent's interpretation. The description is adequate but not fully complete for all potential edge cases.

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

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

Schema description coverage is 0%, so the description must explain the parameter. It states the 'title' is used for substring matching, which adds meaning beyond the schema's bare type and default. It does not clarify edge cases like empty string behavior, but the core semantic is conveyed.

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 ('Find'), a specific resource ('window'), and the distinguishing mechanism ('by title substring'), and specifies the returned data ('hwnd and geometry'). This clearly differentiates it from sibling tools like tool_list_windows and tool_get_window_rect, which have different purposes.

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 a clear use case: given a title substring, find a window. However, it does not explicitly mention alternatives or when not to use this tool (e.g., when listing all windows or retrieving geometry of an already known window). The usage guidance is adequate but not explicit.

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 provided, so the description carries the full burden. It states 'Read-only,' which is a key safety trait, but it does not disclose other behaviors: what happens if the window is not found, whether hwnd or title is used preferentially, whether the window must be visible, or any error conditions. For a tool with two optional parameters, this is a significant gap.

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

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

The description is a single, well-structured sentence that front-loads the core purpose and includes the read-only safety note. Every word earns its place; there is no fluff 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?

While the output schema exists to explain return values, the description does not cover essential context: how to choose between hwnd and title, what happens if neither is provided (since both have defaults), or whether the tool requires a valid window handle. For a tool with two optional parameters, this is incomplete and could lead to incorrect invocations.

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% and the description does not explain the parameters at all. It does not clarify that hwnd and title are alternative identifiers, which one takes precedence, or how they interact. The description's mention of 'absolute position, dimensions, and client area size' describes the output, not the input. This leaves the agent guessing how to specify the target window.

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

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

The description clearly states the tool's purpose: getting detailed position and size info for a window, including absolute position, dimensions, and client area size. This is a specific verb (get) and resource (window), and it distinguishes from siblings like tool_find_window (which likely finds handles) and tool_capture_window (which captures images). It 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?

No guidance is provided on when to use this tool versus alternatives. It does not mention prerequisites (e.g., need a window handle first) or scenarios where this should be preferred over tool_list_windows or tool_find_window. The description is purely declarative without any contextual direction.

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 behavioral burden. It explicitly says 'Read-only', which communicates non-mutating safety, and specifies the exact information returned, including the physical-pixel coordinate context. This is adequate for a simple list 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?

A single dense sentence front-loads the action and resource, then lists the output fields in a readable sequence. Every phrase earns its place, and the read-only note is a useful signal.

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 takes no parameters, has an output schema, and the description adds semantic meaning about the returned items (work-area rectangles, physical pixels, primary flag). An agent has everything it needs to select and invoke this tool correctly.

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

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

The tool has zero parameters, so the description does not need to explain parameter semantics. The base baseline of 4 applies; there is nothing missing and the description adds no irrelevant parameter information.

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 ('List monitors') and resource ('monitors') and enumerates the exact fields returned (index, primary flag, device name, monitor and work-area rectangles in physical pixels). It clearly distinguishes from display-related siblings by scope and output details.

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 this tool versus alternatives like tool_get_window_rect or tool_cursor_position. The description implies a read-only enumeration use case but does not state exclusions or conditions that would route an agent to this tool.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It clearly states the tool is read-only and safe while the user works, and it discloses the sorting behavior and scope ('visible top-level windows'). This goes beyond the schema and gives an agent confidence about 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?

The description is a single, well-structured sentence that front-loads the action and resource, then packs in the key output fields and ordering. Every clause earns its place with no filler or redundancy.

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

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

The output schema exists, so return values are presumably covered elsewhere. The description covers purpose, scope, sorting, and safety, but it omits filter_title semantics and does not provide guidance on when to prefer this over sibling tools. For a simple list tool this is acceptable 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?

The only parameter, filter_title, is not mentioned in the description. Since schema description coverage is 0%, the description should explain what filtering means (e.g., substring match, case sensitivity), but it does not. The parameter name and default empty string imply optionality, but no semantic detail is provided.

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 ('List'), a precise resource ('all visible top-level windows'), and the exact fields returned (title, hwnd, PID, position, size). It also mentions sorting behavior, which distinguishes it from sibling tools like tool_find_window or tool_get_window_rect.

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 the tool: when you need an overview of visible top-level windows. It also notes the operation is read-only and safe while the user works, which is useful context. However, it does not explicitly contrast this tool with alternatives or 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?

With no annotations, the description carries the full burden, and it discloses important behavioral traits: it is labeled MUTATING (soft), serialized across agent sessions, and may take focus. This goes beyond a bare 'open' statement. The term 'soft' is somewhat informal, but the sentence adds genuinely useful side-effect context.

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

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

Two compact sentences with no filler: the first establishes the operation and examples, the second adds critical behavioral caveats. Every clause earns its place, and the key purpose is front-loaded.

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

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

The tool is simple (one required parameter) and has an output schema, so the description does not need to explain return values. It covers what is opened, how, and the relevant side effects (session serialization, focus stealing), making the definition complete for an agent deciding whether and how to call it.

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

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

Schema coverage is 0%, so the description must compensate for the single 'target' parameter. It does so by defining target as a file, folder, or URI and giving examples (.exe path, document, URL). It could add path-format or URI-scheme details, but the required meaning is clear enough for correct invocation.

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 ('Open') and a precise resource class ('a file, folder, or URI') via the shell's default handler, with concrete examples like .exe paths, documents, and URLs. This clearly distinguishes it from the UI-automation siblings, none of which launch external default-handler targets.

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 a clear mental model — same as double-clicking in Explorer — so an agent knows to use it when it wants OS-level default handling rather than window/element manipulation. It does not explicitly name alternatives or exclusion conditions, but the sibling tools are sufficiently distinct that no close alternative needs to be ruled out.

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 burden. It discloses that the tool is read-only and explains that stale refs are reported rather than guessed. It doesn't detail error handling or output format, but these are likely covered by the output schema. The key behavioral trait of staleness reporting is clearly communicated.

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

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

The description is two sentences, with the core action and source stated first, followed by the usage scenario and staleness behavior. Every word earns its place; there is no redundancy or filler.

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

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

For a single-parameter read tool with an output schema (even though not shown), the description covers purpose, usage, and the key behavioral nuance of staleness. The agent has enough to decide when to call it and what to expect, and the output schema presumably covers return values.

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

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

Schema coverage is 0%, so the description must compensate. It explains that 'ref' is a reference returned by element_at_point and clarifies that it can become stale. This adds meaning beyond the bare 'string' type, giving the agent enough context to use the parameter correctly.

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 ('re-read') and resource ('UI element'), and clarifies the ref comes from element_at_point. It distinguishes itself by focusing on re-reading a specific element rather than performing actions on it, making its purpose clear and unique among siblings.

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

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

It provides explicit guidance on when to use it ('Use this to check whether an element is still there before acting on it') and explains the stale ref scenario. It doesn't name alternative tools explicitly, but the context implies its role in the verification step. A slight gap is the lack of explicit '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?

Annotations are absent, so the description carries the full burden and it delivers: it discloses that the tool is mutating, serialized via admission gate, that global hotkeys yield to the user and refuse with reason user-active, and that it refuses when the target window is not the foreground window. That is rich behavioral disclosure beyond a bare 'send keys' statement. A 5 would require even more, like what exactly happens on failure, but this is substantial.

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

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

Every sentence earns its place: the example, the Alt-navigation tip, the serialization/yield-to-user behavior, and the foreground-window precondition. No filler and information-dense.

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

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

Given a 4-parameter tool with no annotations but a present output schema and 18 siblings, the description is complete enough to invoke correctly: window targeting (hwnd/title), shortcut syntax, Alt-key mode, and two refusal conditions are all covered. The output schema exists to explain return values, so that is not a gap.

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

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

Schema description coverage is 0%, so the description must compensate, and it does for the key parameters: keys get the example ['ctrl','s'], use_alt_key gets the 'alt as first key' guidance, and title/hwnd are the window-targeting pair. It doesn't explain the hwnd=0 default or the title fallback relationship explicitly, but it covers the two non-obvious parameters. Baseline would be 3 at 100% coverage; with 0% coverage and this much guidance, a 4 is appropriate.

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

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

States a specific verb and resource: send keyboard shortcut to a window. Not fully differentiated from sibling tool_type_text, but it names the target and the key-list mechanism clearly, and the title is null so the description carries the load.

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 gives when-to-use guidance: use for shortcuts like ctrl+s, use 'alt' first key for menu navigation. It also gives a when-not-to-use and an alternative: switch to element actions, or retry later, when user is active. This clearly routes the agent compared with siblings like tool_click_at, tool_type_text, and tool_element_action.

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 and does so unusually well: read-only with no input injection or focus change, server-side diff baseline that outlives the session, positional indexes valid only against the shot that printed them, and the minimized-window caveat (measured behavior on Edge/Explorer). It even warns the text may contain whatever is on screen.

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?

Long (~300 words) but front-loaded with the core purpose and diff semantics, and nearly every sentence carries non-derivable information given zero annotations and zero schema docs. The index-validity point is stated twice, which is the main redundancy.

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

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

For a tool with an output schema, the description needn't restate return shape, yet it usefully explains the line format, shot_key, minimized, and diff markers. Combined with the schema and output schema, an agent has everything needed to call it correctly and interpret the result.

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% across 7 parameters, so the description must compensate: it explains disable_diff (full render), include_offscreen (scrolled-out/hidden elements and its limits), and include_values implicitly via the VALUES note. hwnd, title, max_depth, and max_nodes remain undefined anywhere, which keeps this below 5, but the added meaning for the behaviorally tricky flags is substantial.

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 ('Read a window's UI as a compact TEXT tree') and immediately differentiates it from tool_capture_window by contrast with 'a screenshot' and from element_at_point by naming what a hit-test cannot reach. An agent can place this tool among its 18 siblings without opening the schema.

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

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

Explicitly routes against alternatives: use this instead of an image because it is cheaper, and it reaches elements that element_at_point reports only as the enclosing 'document'. It also states the condition selecting disable_diff=true and tells the agent to re-check with a fresh shot before acting when the window may have changed.

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 supplied, the description carries the full burden and does so well: it discloses the PostMessage mechanism, automatic child-control resolution, the effect_verified read-back, that it is MUTATING (soft) and serialized across agent sessions, no physical input injection, and the side effect that the window may be raised to foreground. This is exactly the behavioral detail an agent needs.

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

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

One dense paragraph, front-loaded with the action and mechanism before the behavioral caveats. Every sentence carries information, though the parenthetical asides make it denser than it needs to be for quick scanning.

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 mutation tool with an output schema (covering the effect_verified return value) and no annotations, the description supplies the mechanism, verification path, concurrency behavior, and the key safety caveat. Only the two secondary parameters remain undocumented, which is a minor gap against an otherwise complete picture.

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% across four parameters, so the description must compensate and largely does not. It clarifies hwnd semantics indirectly ('passing a window handle alone used to post into nothing') and implies text is the payload, but the roles of `title` (selector vs. fallback for hwnd) and `delay_ms` (inter-character timing?) are never addressed.

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

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

States a specific verb+resource ('Type a text string into a window character-by-character') and immediately scopes the mechanism ('window-targeted PostMessage, not global keystrokes'), which distinguishes it from the sibling tool_send_keys. An agent can identify the operation without opening the schema.

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

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

Gives clear situational context: it can run while the user types because no physical input is injected, and it warns to avoid typing into a window the user is actively working in. It does not explicitly name an alternative (e.g. send_keys) or state when that alternative should be preferred, so it stops 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.