Act on observed elements

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

The description goes well beyond the annotations: failed postconditions keep effects and set replan_required, the batch stops on first failure, popup redirects skip post_checks, cancellation closes the session but retains effects, and click_xy coordinates lack DOM identity guards. This is exactly the behavioral context an agent needs beyond readOnlyHint/destructiveHint/openWorldHint.

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 and information-rich with no filler, and it fronts the core action-execution purpose. However, it reads as one long run-on paragraph rather than structured guidance, which slightly reduces scannability for an agent needing to quickly extract key constraints.

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—14 action variants, post_checks, snapshot refs, timeouts, popups, and cancellation—the description covers nearly all behavior an agent needs to call it correctly. It even explains effect persistence, failure semantics, and coordinate caveats. The only minor omission is a detail about include_snapshot, but that is not essential 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 very low at 14%, but the description compensates with meaningful semantics: post_checks reference the same snapshot's refs and poll for async outcomes, click_xy is in main-viewport CSS pixels, fill_secret uses an alias from snapshot.available_secrets, and action budgets/timeouts are specified. It does not explain every parameter (e.g., include_snapshot) or every action type, but the schema covers the structural constraints and the description adds the critical runtime 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 uses a specific verb ('Execute') and clear resource ('ordered actions against a current snapshot'), and immediately distinguishes tab_act from tab_verify by routing navigation-dependent checks elsewhere. It leaves no doubt about what the tool does.

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 'use separate tab_verify after navigation' and instructs using fill_secret with an observed ref and a snapshot secret alias, giving concrete when-to-use guidance. It also clarifies that post_checks are the in-call verification mechanism, with separate timeout semantics, which helps the agent choose between this and sibling verification tools.

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