tool_element_action_at

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.