find_element

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.