browser_evaluate

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

No annotations are provided, so the description bears the full burden of behavioral disclosure. It states that code is executed and a result is returned, but it does not disclose that executing arbitrary JavaScript can have side effects (e.g., navigation, DOM mutations, network requests) or that it may be irreversible. It also does not clarify whether the execution is synchronous or how complex results (objects, promises) are serialized. This is a significant gap for a code-execution tool.

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, concise sentence that directly states the action and result. It is front-loaded with the primary purpose, and there is no unnecessary elaboration. While it is minimal, it is efficient for a tool with one parameter and no annotations.

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 that this is a high-complexity tool (arbitrary code execution) with no output schema, the description is insufficiently complete. It does not explain the return value's format, potential failure modes, or safety considerations. For example, an agent would benefit from knowing whether the result is a JSON-serialized value, whether promises are awaited, or whether the code runs in the page's context. The description only offers the basic action and result without the details needed for confident 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 100%, and the parameter 'code' is described as '要执行的 JS 代码' (JS code to execute). The tool description adds no further meaning beyond what the schema already provides, so the baseline of 3 applies. No compensation is needed, but no extra value is added either.

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's purpose: executing custom JavaScript code in the page and returning the result. This specific verb-resource combination (execute JS) distinguishes it from sibling browser tools like browser_extract or browser_click, which perform different actions. No ambiguity remains 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?

The description provides no guidance on when to use this tool versus alternatives. With over 30 sibling tools, there is no indication that this is the appropriate choice for running arbitrary code, nor any mention of when it should be avoided (e.g., if a more specific browser action would suffice). The agent must infer usage entirely from the tool's purpose.

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