browser_record_start

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

With no annotations, the description carries the burden and does disclose real behavior: the cursor overlay is rendered red, idle pauses keep their real duration (so the clip is real-time, not compressed), and the codec falls back from MP4 to WebM when ffmpeg is absent. It omits side effects like where the file lands and what is returned on completion.

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?

Four short sentences, front-loaded with the core action and the start/stop pairing, then pacing and codec caveats. Nothing is repeated from the schema except the one format constraint that matters operationally.

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 5-optional-param capture tool with no annotations and no output schema, the description covers the workflow, cursor overlay, timing behavior and codec fallback adequately. The main omission is what the call returns (handle, path, confirmation), which the agent cannot learn from an output schema that does not exist.

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 schema already documents fps, demo, file, format and maxSeconds. The description only reinforces the ffmpeg dependency behind format, adding little meaning beyond the field descriptions; 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?

States a specific verb and resource ("Empieza a grabar en vídeo la pestaña activa") plus the distinctive scope (red cursor visible, demo clips). It also names the companion tool browser_record_stop, so an agent can tell exactly which of the record pair to call.

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?

Explicitly says to keep using the other tools while recording and to finish with browser_record_stop, which defines the workflow context and the terminating alternative. It does not state when not to use it (e.g., instead of browser_screenshot or browser_trace for capture), leaving one gap.

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