Hover

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

With no annotations, the description carries the full behavioral burden. It usefully discloses that this is a non-clicking move whose purpose is to open menus/tooltips and hints that hovering changes page state (hence read=changes), but it says nothing about timing, whether the hover must be followed before the menu closes, or any permission/slot prerequisites an agent needs.

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 short sentences, zero filler, front-loaded with the action and the click distinction, followed by purpose and the read tip. Everything earns its place.

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 7-param action tool with no output schema and no annotations, the description covers the core interaction (non-clicking hover) and the read follow-up. It leaves the multi-tab slot/tab routing caveats to the schema, which does document them, so the coverage is nearly complete but the description itself does not reinforce those requirements.

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%, so the baseline is 3. The description adds genuine value on top by recommending the specific enum value read=changes for this tool's purpose, and by naming 'ref element' to reinforce the target parameter. It does not add syntax beyond the schema for other params, keeping it just above baseline.

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 ('Moves the real mouse over a ref element') and immediately disambiguates from sibling browser_click with '(no click)', so an agent can route between hover and click without opening either schema. The use cases (hover menus and tooltips) further pin down the intent.

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?

'For hover menus and tooltips' gives clear context for when to reach for this tool, and 'Use read=changes to see the opened menu' guides the follow-up action. It stops short of 5 because no explicit exclusion or named alternative (e.g. 'if the menu requires a click, use browser_click') is offered.

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