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

With no annotations provided, the description carries the full burden, and it excels. It discloses the return format (JSON with per-step ok/message), the stop_on_error semantics, the step op types and their optional fields, and the landing-point evidence in click messages. It also reveals performance characteristics (measured round-trip times) and the advice about screenshots, giving an agent a realistic mental model of execution and 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 long but every sentence earns its place. It front-loads the core value proposition and usage rule, then systematically covers step ops, the screenshot tip, stop_on_error, and return details. The bold and star markers guide attention. For a tool with this many op variants and options, the density is appropriate—no filler, all actionable.

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

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

Given the tool's complexity (7 op types with numerous optional fields) and the absence of an output schema, the description covers all critical aspects: op syntax, usage heuristics, error behavior, return structure, and a practical optimization. It even addresses a common failure mode (off-target clicks) and how to verify without extra calls. An agent has everything needed to call it correctly and efficiently.

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%, but the description fully compensates. It enumerates every op (click, type, key, wait, sleep, list_windows, screenshot) with their sub-fields, and explains the stop_on_error parameter's default and effect. This is far richer than the generic 'steps: array of objects' schema, enabling an agent to construct valid step objects without guessing.

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

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

The description states a clear purpose: batch-executing a sequence of actions in one call to save round trips. It distinguishes itself from sibling tools (click, type_text, etc.) by framing it as the aggregation tool, and explicitly names the batching criterion. The verb 'execute' and resource 'a string of actions' are concrete, and it even quantifies the benefit (30–70s per round trip vs. sub-second tool call).

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, actionable usage criteria: submit consecutive actions whose next step doesn't depend on the previous result, and only split when you need to branch on results. It also gives a specific optimization—placing screenshot as the last step to save a round trip—and explains stop_on_error behavior. This directly tells an agent when to use this tool versus individual sibling calls.

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 disclosure burden and discharges it thoroughly. It reveals the three-tier internal execution fallback (element-level do_action → calibrated coordinate click → suggest screenshot), that the return states the effective tier, and the full set of coordinate-click return artifacts: landing evidence, unscaled crosshair snapshot, computed offset from the nearest text block, expect-driven corrective coordinates, and the post-click change percentage as a miss indicator.

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 given the 0% schema coverage and absent annotations, and it is front-loaded with the core purpose and preferred mode before details. The ①②③ fallback chain, bolded key terms, and arrow/percent framing keep the density structured; the crosshair pixel-mapping passage is valuable but could arguably be tightened.

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

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

For a 10-parameter tool with no annotations, no schema descriptions, and no output schema, the description supplies everything an agent needs to call it correctly: targeting modes, fallback mechanics, return artifacts, the expect retry loop, and the preview tradeoff. Remaining gaps are minor: role is undocumented, button is underexplained, and the error-return format beyond the effective-tier indicator is not 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?

With 0% schema description coverage, the description compensates strongly: it explains ref (source tools and precedence), text(+app) first-match semantics, x/y as absolute screen coordinates, expect (enables miss-offset plus suggested retry coordinates), preview (toggles the visual feedback payload), and action via the element-level do_action reference. However, role is never mentioned and button's semantics are left entirely to its default value, so coverage of the 10 parameters is strong but not complete.

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 the purpose immediately and specifically: '点击一个元素' (click an element), a clear verb+resource. It then enumerates the three targeting modes (ref, text+app, bare coordinates), and distinguishes itself from siblings by naming get_ui_tree/find_element/get_screen_text as the sources of ref and screenshot as the fallback path, so an agent can tell it apart from the find/read/keyboard 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?

Gives explicit priority ordering: prefer ref, fall back to text(+app) first-match, and use bare x+y only for gray-zone apps lacking an element tree. It also states when not to use the feedback payload (preview=false to save tokens) and when to abandon the tool (both fallback tiers fail → switch to screenshot), which is explicit when/when-not guidance with named 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. The verb '查看' (view/look up) makes the read-only nature clear, and the list of returned fields tells the agent what to expect. It doesn't discuss invalid/stale refs or error behavior, but for a simple inspection tool this is a minor 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?

Two compact sentences: the first front-loads the purpose and output fields, the second adds the usage context. Every clause carries information and there is no filler.

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

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

For a one-parameter read-only tool with an output schema, the description covers the main need: what the tool returns and when to use it. The main missing piece is the provenance/lifetime of the ref value, but the sibling tool list and simple signature keep this 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?

Schema description coverage is 0%, so the description must explain the ref parameter; it only restates '按 ref' (by ref) as a lookup key. It never says what a ref is, where it comes from (e.g., get_ui_tree/find_element), or that it must be from the current UI snapshot. This leaves the only parameter under-specified.

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 ('view') and names the resource ('single element by ref'), then enumerates exactly what detail fields are returned. This distinguishes it from sibling tools like click/type_text (which perform actions) and get_ui_tree/find_element (which search/collect elements) without needing to open 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?

It gives an explicit usage context: use before click/type to confirm the target element and its available actions. It doesn't name alternative tools or state when not to use it, so it misses the full when/when-not structure, but the 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?

无注解，描述承担全部责任。披露了关键行为：全桌面裸搜慢、遍历大型应用有节点数熔断可能导致结果不全，以及 GTK 输入框 role 为 'text' 而非 'entry' 的细节。这些超出可推断范围，提供了有价值的限制信息。

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?

描述为中文段落，信息密度高，包含用法、性能警示和技术细节，但语句组织有序，无冗余。虽稍长，但每句都提供实用信息，属于效率高的结构。

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?

有输出 schema 因此返回格式有定义，描述已说明返回含 [ref] 的候选列表。参数虽多但主要参数已解释，且提供了使用建议和性能约束，整体足以让代理正确调用。小幅缺失在于未覆盖 limit 和 interactive_only 的细节，但影响有限。

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 描述覆盖率为 0%，描述必须补偿。详细解释了 text（子串匹配）、role（含 GTK 特例）、app（限定应用名）三个参数的含义，但未说明 limit 和 interactive_only 的语义。interactive_only 可从描述中'可交互'推断，但 limit 完全未提，覆盖不完整。

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?

明确说明'按文本/角色/应用搜索可交互元素'，动词（搜索）和资源（可交互元素）清晰，且返回候选列表含 [ref] 的用途明确。虽未直接命名兄弟工具，但'用 ref 配合 click/type_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?

提供了明确的使用条件：至少提供 text 或 role 之一，并强烈建议带 app 或 text 限定，说明全桌面裸搜慢且有熔断风险。虽未明确指向替代工具（如 element_info），但给出了使用时的最佳实践和性能提示，较清晰。

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 full behavioral disclosure. It states what the return contains (click coordinates, computed deviation, suggested coordinates, change percentage), and discloses retention limits (last 8 coordinate clicks) and an exclusion (element-level clicks produce no record).

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: purpose/index, when-to-use, return contents, and retention constraints. It is front-loaded with the core function and uses bold and an emoji for scannability without adding 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?

Since there is no output schema and no annotations, the description must stand alone—and it does. It explains what the tool returns, when to use it, how the index parameter works, and data retention limits. Nothing needed for correct invocation or interpretation is missing.

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

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

The schema provides only a default value of -1 with no description. The tool description adds complete semantic meaning: index=-1 is the most recent click, -2 is the one before that, and records are limited to the last 8 clicks. This fully compensates for the schema's 0% 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 action: review the crosshair image and conclusion of the most recent coordinate click, with index semantics explained. It clearly sets this apart from sibling tools like click or screenshot, which perform actions or capture screens rather than diagnose past clicks.

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 condition: use it when a coordinate click produces no expected UI reaction (no popup, navigation, or change). It also tells the agent not to blindly repeat clicks and says re-screenshotting is unnecessary, which is direct, actionable usage guidance.

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

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

With no annotations, the description carries the full burden. It discloses the return format ('返回 JSON 文本') and the specific data fields, and '获取' implies a read-only operation. It doesn't explicitly state absence of side effects, but for a getter this is sufficient.

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

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

Two sentences with no redundancy. The first sentence lists what it returns, the second provides usage guidance. Information is front-loaded and every phrase adds value.

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

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

Output schema exists, so return structure is already documented. The description covers purpose, usage context, and return format. A minor gap is the lack of an explicit non-destructive statement, but given the tool's simplicity, it 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?

The tool has zero parameters, so baseline is 4. The description doesn't need to explain parameters and instead focuses on the output structure, which is acceptable.

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 ('显示器布局'), then enumerates the exact data fields: screen names, resolutions, offsets, primary flag, and virtual desktop size. This clearly differentiates it from sibling action tools like click or type_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 says '多屏/坐标问题排查时先调它理解几何环境', giving a concrete scenario and priority ('call it first'). It doesn't explicitly contrast with alternatives, but the guidance is clear and actionable.

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 and delivers richly: it discloses timing expectations (2-3s vs 8-10s), the snapshot semantics of coordinates with the warning not to reuse stale refs after UI changes, and a concrete known failure mode (text next to dark icons misrecognized) plus a mitigation (narrowing the region). This is exemplary disclosure for a sensing tool.

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

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

The description is long but front-loaded and tightly organized: function+format, when to use, how to chain with click, scope timing, region, then snapshot warning and known limitations. Each sentence earns its place given the tool's timing and failure-mode complexity, though the size is on the higher end and could tolerate minor trimming.

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 4 parameters, no annotations, and an output schema, the description covers nearly everything an agent needs: return format, scoping behavior with latencies, follow-up click usage, snapshot invalidation, and a failure-mode workaround. Small gaps remain — the semantics of min_conf/max_items, behavior when no text is found, and the coordinate reference frame (screen vs window-relative) are only 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?

Schema coverage is 0%, so the description must compensate. It adds deep semantics for scope ('window' default targeting the active window, 'screen' full-screen with heavy cost) and region (arbitrary [x,y,w,h] specification), which the bare schema cannot convey. However, min_conf and max_items receive no explanation at all, leaving two of the four parameters semantically 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+resource: '读取屏幕上的文字及其坐标' (read on-screen text and its coordinates), and specifies the exact return format `[ref] 文字 @ (x,y) 宽x高`. It differentiates from siblings by positioning itself as the preferred sensing method for gray-area apps with no element tree (SWT/Java, custom-drawn controls, games, remote desktop), which clearly separates it from get_ui_tree/find_element and screenshot.

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 use it (gray-area applications) and contrasts it against the alternative (screenshot): reading text avoids guessing pixel positions, which is 'the main cause of slow and offset clicks'. It also gives scope-specific guidance — window scope for the active window (2-3s) vs screen scope (8-10s) with an explicit '非必要别用' (don't use unless necessary) — and prescribes the follow-up action of click(x,y) or click(ref=N).

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 well: it explains the compact text-tree return, the [ref] mechanism for click/type_text, and the token-cost implications of scope and interactive_only. It does not disclose edge behaviors like failure modes or output size limits, but the core behavioral profile is 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 a single dense paragraph with no filler, front-loading the most important guidance (preferred over screenshot) before explaining return format and parameters. Every clause adds operational value.

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

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

Given an output schema exists, the description does not need to detail return structure, and it covers the main use cases, scope routing, and ref-based interactions. The only notable gap is the undocumented max_nodes parameter and a missing note about when screenshot might still be necessary, but overall the tool can be invoked correctly from this description.

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

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

Schema description coverage is 0%, so the description must compensate. It adds real meaning for scope values, the app keyword matching, and interactive_only, but never explains max_nodes or its default of 400, leaving one parameter semantically underspecified.

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 ('桌面无障碍元素树'), and immediately differentiates itself from screenshot by declaring itself the preferred screen-perception method. This makes it unambiguously distinct from siblings like screenshot, get_screen_text, and get_screen_layout.

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 ('这是感知屏幕的首选方式') and explicitly warns against defaulting to screenshot, while also giving concrete scope-selection guidance for active_window, app, and desktop. It does not state explicit exclusions or when screenshot would be preferable, so it stops short of a perfect 5.

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

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

With no annotations, the description carries the transparency burden and does well: it discloses sandboxing behavior, that commands are parsed with shlex, and that the result is a JSON object with pid, command, and display. Failure behavior and permissions are not covered, but key launch semantics are.

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

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

The description is compact and front-loaded: the core action comes first, followed by the key behavioral caveat, examples, return shape, and suggested workflow. It is dense but not wasteful.

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 provides useful workflow and return info, but it omits the meaning of settle and does not explain how the isolated/real mode is chosen given the schema only exposes command and settle. This leaves a meaningful gap for correct invocation.

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

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

Schema description coverage is 0%, so the description must compensate. It documents command with shlex parsing and examples, but it never explains the settle parameter, and it introduces isolated/real modes without saying how those modes are selected through the provided schema. An agent cannot fully determine argument 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 explicitly states it launches an application on the target display and distinguishes isolated vs real modes. This clearly separates launch_app from sibling tools, which are all interaction/inspection operations like click, type_text, and get_ui_tree.

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 explains when isolated mode is appropriate (the only way to put an app on the virtual screen without affecting the host) and gives a follow-up workflow: use wait_window, then get_ui_tree/click. It does not name alternative launch tools, but the context is clear 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?

With no annotations provided, the description carries the full burden. It discloses that the output is a JSON list sorted by area descending, filters out unmapped orphan windows and hidden helper windows, and returns JSON text. This is substantial behavioral context for a read-only listing tool, though it doesn't mention rate limits or authentication (likely irrelevant). Score 4 is appropriate.

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

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

The description is a single, dense sentence that packs purpose, output format, sorting, filtering, and use case without unnecessary fluff. It is front-loaded with the main action. It could be slightly more readable but is still efficient, so a 4 is justified.

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 presence of an output schema means the description need not explain return values in detail, and it does list the fields. However, the 'limit' parameter is completely undocumented, and there is no mention of error conditions or edge cases. For a tool with a single optional parameter, this is a notable omission, making the description incomplete.

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 one optional parameter 'limit' with a default of 100, and schema description coverage is 0%. The description never mentions 'limit' or explains its purpose or effect. Since the description does not compensate for the schema's lack of documentation, the parameter semantics are poorly conveyed. A score of 2 reflects this 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 clearly states the tool lists visible windows with a specific output structure (id, title, pid, x, y, w, h, area) and indicates sorting and filtering. It gives a concrete use case (distinguishing same-name windows, locating target window id). However, it does not explicitly differentiate itself from sibling tools like get_screen_layout or get_ui_tree, so it falls 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 provides clear context: it is meant for identifying windows by id and replacing multiple shell queries. It implies when to use it, but does not explicitly state when not to use it or name alternative tools. This meets 'clear context, no exclusions', which is a 4.

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 fully covers behavioral details: it explains the alias normalization to xdotool keysym, states that unrecognized key names cause explicit errors rather than silent failures, and notes that the returned active window title depends on focus. This is comprehensive for a single-purpose tool.

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

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

The description is information-dense but not bloated—each sentence adds value (purpose, format, modifiers, aliases, errors, return value). It is structured logically, though slightly long; a tighter phrasing could earn a 5.

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

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

Given the tool's simplicity (one parameter) and the presence of an output schema (which the description complements by mentioning the active window title), the description is complete. It covers invocation, input format, edge cases, and return behavior—nothing essential is missing.

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

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

Schema coverage is 0% (the combo parameter has no schema description), but the description provides exhaustive guidance: exact syntax examples, accepted modifier keys, alias behavior, and error handling. It fully compensates for the missing schema 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 opens with a specific verb and resource: '发送快捷键' (send hotkey) and '全局键盘注入' (global keyboard injection), which clearly distinguishes it from siblings like type_text (text input) and click (mouse action). The format examples further clarify the exact 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 purpose is immediately evident—sending key combinations—and the global scope is explicit. However, it does not explicitly state when NOT to use it (e.g., for typing text use type_text), though the distinction is strongly implied by the sibling names and the term 'keyboard injection'.

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 discloses behavior: token cost, region cropping, max_side downsampling, inline=false behavior (file path instead of image), non-overwrite error, and automatic path retention (only last 5 images). These are all behavioral traits an agent needs to know and are not derivable from 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?

The description is a single dense paragraph that front-loads the critical caution ('default not to use') before diving into parameters. Every sentence adds value, but the length is slightly high; still, given the complexity of 4 parameters and the need for behavioral context, it remains well-structured and efficient.

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

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

For a tool with 4 parameters, no annotations, and no output schema, the description covers usage context, parameter semantics, and behavioral constraints thoroughly. An agent has everything needed to decide when and how to call it correctly, including edge cases like file overwrite and auto-path cleanup.

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 each parameter. It does: inline (return image vs. file path), region (crop area), max_side (downsample long side, default 1280 to save tokens), save_path (specify location, with overwrite and retention warnings). This adds substantial meaning beyond the schema's type/default info.

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 function (take a screenshot) and explicitly positions it as a fallback tool for cases where element trees are unavailable. It distinguishes itself from siblings like get_ui_tree and find_element by naming them and specifying when they fail, making the purpose 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 gives explicit when-to-use (no element tree, self-drawn controls, games, video, remote desktop) and when-not-to-use (default, prefer get_ui_tree + click). It also mentions the alternative tool directly, leaving no ambiguity about the decision process.

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 the two execution modes (set_value vs keyboard injection), the effect of clear_first (select-all delete), and the behavior of reporting the active window title after keyboard injection, which aids verification. It doesn't mention potential failures or edge cases, but for a text-input tool this is reasonably 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?

The description is concise (about three sentences) and front-loaded with the core purpose. The fallback logic, suggestion, and reporting note are each purposeful, with no redundant information. It is well-structured and 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?

Given the tool's complexity (4 params, no annotations) and the presence of an output schema, the description covers the key operational details: method selection, clear behavior, focus suggestion, and verification hint. The undocumented 'app' parameter is a minor gap, but overall the description provides enough context for an agent to call the 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?

Schema description coverage is 0%, so the description must compensate. It explains ref (triggers set_value) and clear_first (clears existing content), and text is implied. However, the 'app' parameter is not explained, leaving a gap. Since it covers two of four parameters meaningfully but not all, a score of 3 reflects partial compensation.

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: '输入文本' (input text). It specifies the primary method (element-level set_value) and the fallback (keyboard injection), which distinguishes it from sibling tools like press_key (key presses) and click (clicking). The verb and resource are explicit, and the behavior 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 provides explicit usage guidance: it instructs to prefer set_value when a ref is given, otherwise fall back to keyboard injection, and it recommends clicking the target input first. It explains when to use clear_first. While it doesn't explicitly contrast with sibling tools, the internal decision logic and actionable suggestion give clear context for usage.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It explains internal polling, single-call completion, case-insensitive matching, window targeting behavior (specific window vs active window), and timeout behavior, all beyond what the schema conveys. This is strong 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 well-structured: core behavior first, then parameter semantics, then usage guidance. Every sentence adds value, with no filler or repetition 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?

The description covers purpose, behavior, parameters, and usage context well. However, it does not clarify what happens when title_contains is null despite being optional in the schema, nor the timeout unit. Since there is an output schema, return format is not a concern, but these two gaps slightly reduce completeness.

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 compensates for all three parameters: title_contains (case-insensitive matching), window_id (scoping to a specific window or active window), and timeout (timeout returns a timeout message). However, it does not specify the timeout unit (seconds vs milliseconds), which is a meaningful gap 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?

The description clearly states the tool's purpose: waiting for a window title to meet a condition, with server-side polling in a single call. This makes the tool's function obvious and distinguishes it from action-oriented siblings. However, it does not explicitly differentiate from any sibling tool by name, so it misses the top score.

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

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

The description explicitly states when to use it: 'for waiting for page load/app startup', and what it replaces: 'external repeated polling'. This gives an agent clear guidance on when to choose this tool over manual polling loops, satisfying the usage-guideline criterion.

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