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

Annotations already indicate readOnlyHint=true, but the description adds valuable behavioral details beyond that: it is free to use ('never charges'), it does not consume credits beyond the original analysis, and it converts an existing analysis rather than creating a new one. This financial and operational context is not present in the annotations.

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 front-loaded with the main purpose and then efficiently covers inputs, cost, prerequisites, and optional parameters. However, it is slightly verbose, repeating the 'free' aspect twice and including extra explanatory phrases like 'reusable generation prompt' that are already implied. Still, every sentence contributes meaningful information.

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 tool's purpose, input sources, prerequisite, cost, and optional parameters. It does not specify what happens if both report_id and video_url are provided or if neither is passed, but the schema's lack of required parameters could create ambiguity for an agent. Otherwise, it is complete for a conversion tool with no output schema.

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 description coverage is 100%, so the schema already thoroughly documents all four parameters. The description adds a high-level summary of mode and engine ('pass mode to control what the prompt describes, and engine to pick the model format'), but no additional syntax or usage detail beyond what the schema provides. Baseline 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 clearly states a specific action ('Turn one of your finished Video Analysis reports into ONE reusable generation prompt') and identifies the resource (analysis reports) and output (generation prompt). It distinguishes itself from siblings like analyze_video_report and generate_video. The mention of a {your photo} placeholder adds specificity about what the prompt contains.

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 explicitly tells when to use this tool: after a video has been analyzed. It instructs to pass report_id (from analyze_video_report or list_vision_reports) or video_url, and if the video hasn't been analyzed, to run analyze_video_report first. This clear guidance, including prerequisite steps, is exactly what an agent needs to decide when to invoke it.

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