adl_capture

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

Beyond readOnlyHint=true, it discloses that capture is gated by a trusted visual policy, returns PNG plus frame metadata, operates on retained frames (so results are stale-able), and that returned pixel content is untrusted. It doesn't say what happens when policy denies the request or how failures surface, but the added context clearly exceeds the single annotation.

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 purpose and return type, followed by the frame-retention usage pattern and the untrusted-content caveat. Nothing is padding, though the policy clause is suggestive rather than precise.

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?

It covers purpose, return type, and one usage pattern, but with no output schema, five parameters at 0% description coverage, and only readOnlyHint for annotations, gaps remain around size-limit semantics and policy-denial behavior for a tool whose output is pixels.

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 0%, so the description must carry the load. It usefully clarifies frame_id (must match a retained frame) and region (source coordinates), but leaves max_pixels and max_dimension — presumably downscale or cap limits — completely unexplained, so half the non-obvious parameters remain opaque.

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 (capture/observe) applied to a specific resource (actual rendered browser or exact-window pixels) and declares the return type (PNG plus frame metadata). It doesn't explicitly contrast with close siblings like adl_observe or adl_record, so an agent must infer which of the visual tools to pick.

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?

Gives one concrete usage pattern — combine frame_id with a source-coordinate region to inspect the SAME retained frame — and a precondition (trusted visual policy must permit). It never says when not to use it or names an alternative sibling, so selection guidance is only implied.

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