Set video settings

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

With no annotations, the description must disclose behavioral traits. It only says 'Medium risk,' which is vague, and doesn't explain the confirm parameter, whether changes are destructive, or if they require an idle state. It doesn't mention that changes may interrupt output or require confirmation, which are key behavioral aspects.

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 concise, with three short sentences that front-load the purpose and provide necessary details about parameter subsets and risk. No wasted words.

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?

The description covers the core purpose and lists key parameters, but it omits the confirm parameter's role, the nature of 'Medium risk' (e.g., interruption to output), and any usage constraints. For a tool with nested objects and a confirmation flag, this leaves gaps that the output schema may not cover.

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?

The schema has 0% description coverage, so the description must compensate. It lists the relevant keys (base_width/base_height, output_width/output_height, fps_numerator/fps_denominator), which is useful, but it doesn't specify types, units, or valid ranges, nor does it explain the 'confirm' parameter. It adds some meaning but not enough to fully compensate for the sparse 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?

The description states a specific action ('Change canvas/output resolution or FPS') with a clear resource, and the verb 'change' differentiates it from the sibling 'get_video_settings.' It also lists the specific settings involved, making the tool's scope clear.

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?

No guidance on when to use this tool vs alternatives like get_video_settings or set_output_settings. It doesn't mention prerequisites, whether changes take effect immediately, or exclusions. The 'Medium risk' is a warning, not usage guidance.

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