Save instant-replay clip

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

Beyond the annotations (readOnlyHint=false, destructiveHint=false), the description discloses important behavioral details: it saves two native files (horizontal+vertical), the duration_sec default behavior, and the retryable error scenario with waiting for user approval. This adds significant value beyond what annotations provide.

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 three sentences, each earning its place: the first states the core action, the second explains the optional parameter, and the third covers error handling. It is front-loaded with the verb and resource, and there is no wasteful repetition or filler.

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?

Given the tool's simplicity—one optional parameter, no output schema—the description is complete. It explains what the tool does, parameter behavior, and error handling. The agent has all necessary information to invoke it correctly, including the retry condition.

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 input schema already describes duration_sec as 'Clip length in seconds; omit for the configured default' with 100% coverage. The description merely restates this same information ('duration_sec is optional; omitted uses the user's configured default'), adding no new meaning. Thus the baseline of 3 is appropriate.

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 uses a specific verb 'Save' and identifies the resource as 'the stream' with output as 'a clip pair (horizontal + vertical files)'. This clearly distinguishes it from all sibling tools, which are about scenes, automations, widgets, etc., so there is no ambiguity about what it does.

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?

The description gives clear context: it is used to save a replay clip, with the optional duration_sec behavior explained. It also provides guidance on retryable errors ('If the replay buffer is warming up... wait for the user's go-ahead and try again'). However, it does not explicitly mention alternative tools or when not to use it, though no sibling tool overlaps in function.

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