screencast_start

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

With only readOnlyHint:false in annotations, the description adds important behavioral context: output is saved to downloads directory, the tool returns an ID for later use, and recordings can run concurrently. It also implies side effects (file creation) beyond the annotation. It lacks details like audio capture or cleanup, but the core behavior is transparent.

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 three concise sentences, each adding valuable information: action and output, return value and usage, concurrency capability. It is front-loaded with the primary purpose and has no fluff or repetition.

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 with 5 optional parameters, no output schema, and minimal annotations, the description covers the essential workflow: start recording, save to downloads, get ID for stop. It doesn't explain return format or recording format, but those are implied by the schema and sibling stop tool. The description is complete enough for an agent to select and invoke the tool.

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 parameters already have descriptions. The tool description adds context like 'current page viewport' which aligns with width/height defaults, but doesn't elaborate on individual parameters. For high schema coverage, a baseline of 3 is appropriate.

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 action ('Start recording a screencast (video)') and the resource ('current page viewport'), with output details ('saving to a file in the downloads directory'). It distinguishes itself from sibling tools like screenshot_page (still image) and screencast_stop (stop action).

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 implies when to use this tool (when a video recording of the viewport is needed) and provides workflow guidance: 'Returns a screencast id to pass to screencast_stop' and 'Multiple recordings can run at once.' It doesn't explicitly mention alternatives, but the 'video' keyword differentiates from screenshot tools well enough.

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