record_camera

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

Adds real context beyond the annotations: repeating the call creates a NEW clip (consistent with idempotentHint=false), there is no continuous background recording, output is an absolute local path, the clip is silent, and low_light means 10 fps with night exposure rather than software-controlled IR. Only the lack of failure/permission behavior keeps it below a 5.

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 format, then constraints, then mode semantics. Every sentence adds information; the line break placement is slightly awkward but nothing is wasted.

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 two-parameter, annotation-backed tool with no output schema, it covers duration limits, mode behavior, non-continuous behavior, and return value (absolute local path). Only inter-tool routing against capture_camera is missing.

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?

With 0% schema description coverage the description carries the load and does it well: it gives the 1–20 second duration bound the schema lacks and defines low_light as 10 fps plus night exposure with no IR illumination. Both parameters gain meaning not present in the schema.

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 plus format detail: 'Record a new silent 720p MP4 for 1–20 seconds and save it on the controller.' An agent can tell this is a video-recording action distinct from audio capture, though the sibling capture_camera is never named to make the boundary explicit.

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?

It explains mode choice (normal vs low_light) and excludes continuous background recording, which is useful guidance. But it never states when to use this tool versus capture_camera or record_audio, so selection between siblings is left to inference.

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