get_screen_text

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.