setCameraFullscreen

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

Annotations declare a non-read, non-destructive, closed-world mutation, so safety is partly covered. The description adds genuinely new behavior beyond them: merge semantics for omitted fields and a documented refusal condition, which the agent could not infer from the schema or hints.

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?

Three short sentences, each front-loaded with a distinct fact (action, merge semantics, refusal condition). No filler and no repetition of the schema.

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 no-output-schema mutation tool this covers the essentials: what it edits, how omitted fields behave, and when it fails. It stops short of return value or permission requirements, which is acceptable given the schema and annotations carry the rest.

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 only 25% (just projectId), so the description must carry the load. It usefully supplies the unit for startSec/endSec ('virtual-timeline seconds') and the meaning of cameraFullscreenId ('by id'), but adds nothing about valid ranges or the relationship between startSec and endSec.

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 pair ('move or resize'), the resource ('existing camera-fullscreen region'), and the lookup key ('by id'), which cleanly separates it from the sibling addCameraFullscreen. An agent can pick it without opening the schema.

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 the partial-update contract ('Only the fields you pass are changed') and a hard precondition ('Refused if the new span lands on footage with no linked webcam'). It does not explicitly name addCameraFullscreen as the creation alternative, but the 'existing ... by id' framing makes the edit-vs-create split clear.

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