qt_record_gif

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

There are no annotations, so the description carries the full burden, and it mostly does: the app keeps running while recording, you can interact concurrently, it works on Windows and Linux, and frames come from Qt's own rendering rather than screen capture. It does not say where the GIF is written or how large the output may be, but the output schema covers return values.

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 sentences that are front-loaded. The scoping sentence comes first and the alternative-tool pointer comes last. The widget identification listing is a dense parenthetical but earns its place because it points the agent to the sibling's semantics.

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 13-parameter recording tool with an output schema and no annotations, the description conveys the recording semantics, the platform support and the target-identification rules. The gaps (fps, expand, max_width, min_score) are tuning knobs whose defaults are probably acceptable, but an agent still has to guess what they do.

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 0% across 13 parameters, so the description must compensate. It names and explains duration and the identification parameters (ref, describe, window_title, class_name, object_name), but leaves fps, index, expand, max_width, min_score, search_fields and instance unexplained, so it compensates only partly.

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 opens with a concrete verb+resource: 'Record an animated GIF of a window or widget for `duration` seconds.' It also distinguishes itself from the siblings qt_record_start/qt_record_stop for longer or interleaved recordings.

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 states exactly how to identify the target ('identify the widget exactly like qt_screenshot', defaulting to the active window) and names the alternative tools plus the condition that selects them. An agent does not need to infer when to use this rather than qt_record_start.

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