页面元素基础交互

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

Adds substantial context beyond the destructiveHint=true annotation: failed operations return structured errors with a page screenshot to enable retry, clicks degrade to force-click when obstructed (and mark it in the return), fill degrades to simulated typing, and the tab auto-selection order is disclosed along with a delay floor of 20ms for web terminals to avoid dropped characters. The mutation actions align with destructiveHint=true, so there is no contradiction with the annotations.

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

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

A single dense paragraph that front-loads the core purpose, then flows coherently through action semantics, selector syntax, and error behavior. Given the tool's complexity (12 parameters, 9 action enums), the length is proportional — every sentence carries operational content and nothing is redundant. It could marginally benefit from bulleted structure, but the density 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?

For a 12-parameter tool with no output schema, the description achieves strong coverage: per-action semantics, selector grammar, degradation paths, tab disambiguation (pageUrlContains), iframe targeting (frameUrlContains), and error-return format. Two minor gaps remain — the undocumented 'reload' action and the unsaid success return payload (e.g., what get_text returns) — but neither blocks a competent agent from calling 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 coverage is 100%, so the baseline is 3; the description earns a point above baseline by giving operational meaning the schema lacks. The schema's action field only says '要执行的动作', while the description explains what each action does and how text/delay/submit apply per action, plus the full selector grammar (CSS, text=, xpath=, :has-text()). The only gap is that 'reload' appears in the enum but is absent from the description's action enumeration, leaving the agent to infer its meaning from the English name alone.

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 — '在当前页面上执行基础 DOM 操作' (execute basic DOM operations on the current page) — and then enumerates nearly all actions (click, fill, wait_for, hover, select, press, type, get_text) with one-line semantics each. This sharply separates it from functionally distinct siblings like connect_edge, take_screenshot, and add_dns_record, so an agent knows at a glance this is the page-interaction tool.

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 strong action-selection guidance: type is explicitly scoped to xterm/Canvas web terminals (Tencent Cloud OrcaTerm), fill is described as auto-compatible with controlled components with a degradation fallback, and pageUrlContains is flagged as strongly recommended in multi-tab scenarios with the auto-selection order spelled out and an honest '可能会选错' warning. It does not explicitly name sibling tools as when-not-to-use alternatives, but the siblings are functionally distinct enough that little exclusion guidance is needed.

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