browser_evaluate

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

With no annotations, the description carries the full burden of behavioral disclosure. It only states that a function is evaluated and JSON is returned, but does not mention that the function can modify the page, require permissions, or have side effects. It also omits any note about the safety implications of running arbitrary code, which is critical for a tool that executes JavaScript.

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 a single, well-structured sentence that states the core action, the optional scope (page vs element), and the return format. No wasted words, and the key information 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 tool that executes arbitrary JavaScript, the description is incomplete. It lacks safety warnings, an explanation of what constitutes a valid function or how results are serialized, and any mention of when to use this instead of browser_run_code_unsafe. The absence of an output schema and annotations increases the need for more thorough documentation.

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?

The schema provides 100% coverage with descriptions for all three parameters, including examples for the function parameter. The description adds the context that the function runs against the page or a target element (ref or selector), which clarifies the 'target' parameter. This is helpful but not essential beyond what the schema already implies.

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 clearly states the tool evaluates a JavaScript function on the page or a specific element and returns a JSON result. It uses a specific verb ('evaluate') and resource ('page or element'), and the return type is clear. While it doesn't explicitly contrast with the sibling browser_run_code_unsafe, the name and description already differentiate it from click/type/hover tools.

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?

There is no guidance on when to use this tool versus alternatives, particularly browser_run_code_unsafe, which also executes JavaScript. The description does not mention when to prefer this over other browser tools, nor does it note any limitations or prerequisites (e.g., page load state).

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