Start, poll or cancel the DevTools colour picker (eyedropper)

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

With only readOnlyHint=false supplied, the description carries most of the burden and does it well: it discloses that the call returns immediately, that the colour arrives later as an event, that a human click on the page is required, and that the picker session is cached on the chrome window so 'result'/'cancel' reach the same instance. It does not say what 'result' returns before any click, or what happens if 'start' is called twice.

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 actionable content is buried under internal implementation trivia (CommandsFactory.forTab, targetCommand.startListening, getFront("inspector"), spec file paths, bug 1701004) that an agent can never act on. Roughly half the text is Firefox-internals archaeology rather than decision-relevant guidance, and the 'MEASURED, and this is the whole trick' framing is noise.

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?

There is no output schema, and the description does cover the return value indirectly ('reports the colour', carried as a string). For a two-parameter tool with one enum this is close to complete; the missing pieces are timeout/error behaviour rather than core capability.

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 100%, so both parameters are already documented and the enum description duplicates the schema. The description adds timing semantics to 'result' ('reports the colour once the user has clicked'), which is worth something, but adds nothing at all about the 'context' tab parameter. Baseline 3 applies.

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?

Opens with a specific verb+resource ('Drive the DevTools eyedropper / colour picker on a tab') and the three-action model is spelled out. It never differentiates itself from the obvious sibling browser_pick_color_at, so an agent cannot tell the two apart from the description alone.

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 start/result/cancel lifecycle is explained well, including why polling is required ('picking requires a real pointer press'). However, there is no statement of when to choose this interactive picker versus browser_pick_color_at or how to recover if the user never clicks (timeout/abandon), which is exactly the failure mode of a poll-based tool.

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