ffmpeg-mcp-video-editor

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

The description discloses important behavior beyond annotations: the result is shorter by exactly the overlap duration, and the second clip is conformed to the first's resolution and frame rate because xfade requires matching formats. Annotations (readOnlyHint=false, destructiveHint=false) are not contradicted; the description adds context about the non-obvious overlap and conforming behavior.

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 short paragraphs, each earning its place: the first states the purpose, the second explains the critical overlap/conforming behavior, and the third lists transition options. It is front-loaded, free of fluff, and appropriately sized for the tool's complexity.

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 has 7 parameters, a nested EncodeOptions object, and an output schema, the description provides the essential operational semantics (overlap, conforming, transition choices). It does not cover crossfade_audio behavior or output_path defaults, but the schema and output schema fill most gaps. Overall, sufficiently complete for correct invocation.

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 already describes most parameters (71% coverage), including duration and transition options. The description adds conceptual meaning by explaining that clips overlap by 'duration' seconds and the result shortens accordingly, and it lists available transition families in plain language. This supplements the schema without repeating it verbatim, but it does not detail encode parameters or output_path behavior.

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 the exact action ('Join two clips with a cross-fade or wipe-style transition') with a specific verb and resource. It distinguishes the tool from sibling concat by focusing on transitions and overlap behavior, and enumerates the transition families (fade, wipe, slide, circleopen/circleclose).

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 clearly explains the core usage: join two clips with a transition, with overlap duration and resolution/frame-rate conforming. However, it does not explicitly compare to alternatives like concat or trim, nor state when not to use this tool. The context is clear but lacks explicit exclusions or alternative recommendations.

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

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

Annotations already establish readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable non-obvious behavior beyond that: analysis is performed on sampled frames, and 'each sample is a separate fast seek,' implying quick, non-contiguous seeks rather than full decode. It also says 'Answers immediately,' setting synchronous performance expectations.

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 core function and uses a short explanatory paragraph to convey use cases, followed by a concise behavioral note. It is slightly wordy ('This is how a grade gets checked rather than guessed at') but every sentence contributes purpose, usage, or behavior.

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 purpose, use cases, sampling limitation, and speed, and the output schema exists for return details. However, the ambiguous start/end parameters and lack of input_path/project context are significant gaps for correct invocation, making it adequate but not complete.

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 only 25%; only 'count' is described ('Frames to sample'). The tool description does not compensate for start/end/input_path semantics — it doesn't define units for start/end, how samples are distributed across the range, or the meaning of input_path in relation to existing projects. 'Across sampled frames' only weakly hints at count/range behavior.

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 first sentence uses a specific verb and resource: 'Measure brightness and colourfulness across sampled frames.' It clearly differentiates from sibling tools by framing itself as an analysis/measurement tool (not color_grade/apply_curves) and lists concrete diagnostic use cases like shadow crush, clipping, and greyscale detection.

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 for when to use it: checking a grade rather than guessing — evaluating crushed shadows, clipped highlights, greyness, and exposure consistency across shots. It does not explicitly name alternative tools or exclusions, so it stops short of a 5.

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

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

The description discloses critical behavioral details beyond the annotations: points are sorted and validated, and ffmpeg silently ignores malformed curves. It also hints at the job-based nature ('before the job runs'). Annotations are all false, so the description adds substantial safety-relevant context.

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 two sentences, front-loaded with the primary purpose, and every sentence earns its place. The second sentence is dense with useful details about coordinates and validation, with no 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 complexity (8 parameters, nested encode options, output schema present), the description covers the essential curve-specific behavior and the preset/points conflict. It doesn't explain that the tool re-encodes, but the EncodeOptions schema makes that implicit. It is complete enough for an agent to use correctly.

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 50%, but the description adds meaning by explaining the coordinate system for control points (0..1 input/output) and the preset/points exclusivity. This helps understand red/green/blue/master parameters. Encode options are described in the schema's nested object, reducing the need for repetition.

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 'Apply a tone curve, either a named preset or your own control points,' which provides a specific verb and resource (tone curve) and differentiates it from siblings like apply_lut or color_grade. The mention of presets and control points further clarifies the tool's scope.

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: 'Give a preset or points, not both' is an explicit exclusion. It also explains that points are sorted/validated, which implies expected usage. However, it does not explicitly mention alternatives like apply_lut or color_grade, so it lacks full when-not/alternatives guidance.

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

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

The description discloses that the LUT is parsed and validated before the job is queued, and explains the reason (ffmpeg's unhelpful errors). It also explains the effect of 'strength' below 1.0. These details go beyond the schema and the annotations (which are all false and carry no safety meaning).

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 with no fluff. It front-loads the core purpose, then gives behavioral context about validation and a useful parameter tip. Every sentence earns its place.

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?

With a rich input schema and an output schema present, the description doesn't need to explain parameters or return values. It adds key context about validation and job queuing. The only gap is the lack of explicit distinction from sibling color-grading tools, but overall it is complete enough for a job-based processing tool.

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 83%, so most parameters are already well-documented in the schema. The description adds only a minor clarification on 'strength' which is essentially already captured in its schema description, so it provides no significant new parameter semantics.

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 'Apply a .cube colour lookup table', which is a specific verb+resource statement that clearly distinguishes it from siblings like apply_curves and color_grade. It immediately tells the agent the tool's exact function without ambiguity.

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?

There is no explicit guidance on when to use this tool versus alternatives such as color_grade or apply_curves. The only usage-related tip is about the 'strength' parameter, which is parameter guidance rather than tool selection guidance.

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

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

The description adds workflow detail beyond the annotations: it chains jobs, retains the SRT alongside the video, and allows correction and re-burning. It does not contradict annotations and provides useful context about the generated artifacts and the option to fix Whisper errors.

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 compact and front-loaded. It uses three short paragraphs to convey the core purpose, workflow, and a key parameter option. Every sentence earns its place without fluff.

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 complexity (nested option groups and many parameters), the description adequately explains the high-level workflow and the SRT correction cycle. It relies on the detailed schema for parameter specifics, which is reasonable, though it could briefly mention asynchronous/orchestration behavior.

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 already provides descriptions for many parameters, and the main description adds value for translate_to_english and the SRT path behavior. However, several parameters (style, encode, options, max_lines) are left to the schema or nested definitions, and the description does not fully compensate for the 56% coverage gap.

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 opening sentence 'Transcribe a video and burn the captions in, as one job' clearly states the specific action and resource. It distinguishes itself from siblings by explicitly mentioning the chaining of transcription, SRT generation, and caption burning, and it references burn_captions for a related but different use case.

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 explains when to use this tool: when you want to avoid orchestrating three separate jobs. It also provides an alternative path by mentioning burn_captions for re-burning after correcting the SRT, and calls out translate_to_english as a specific option. However, it does not explicitly state when not to use it (e.g., if you only need transcription).

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

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

The description goes beyond annotations by detailing behavioral traits: per-face tracked blur regions, expanded boxes to cover hair/chin, and a critical warning that a missed detection leaves a face unblurred, advising review of output. This adds meaningful context beyond the readOnlyHint=false (write operation) and destructiveHint=false annotations. It does not mention output path behavior or error handling, but those are partially covered in the parameter schema.

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 short paragraphs, front-loaded with the core action, followed by behavior details and a safety note. Every sentence earns its place: the tracking explanation, the box expansion, the exclude_primary use case, and the review warning. No filler or redundancy.

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 complexity (10 parameters, encode settings, output schema), the description covers the essential behavior and a critical risk (missed detections). It does not explicitly mention that encode settings apply or that output is a file, but these are implied by the schema and output_path parameter. The description is nearly complete for a privacy-blurring tool.

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 70%, so many parameters already have descriptions. The narrative adds extra context for exclude_primary (street interviews) and expand (hair/chin coverage), but does not explain max_frames or sample_fps, which lack schema descriptions. Overall, the description adds some value beyond the schema but does not fully compensate for the uncovered parameters.

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 specific verb and resource: 'Blur every face in a clip', and then explains the tracking behavior ('following each one as it moves'). This clearly distinguishes it from sibling tools like detect_faces (detection only) and track_and_crop (cropping). The purpose is unambiguous and specific.

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 implies usage (blurring faces in video) and gives a contextual example ('the usual requirement for street interviews' for exclude_primary). It also warns to review output before publishing. However, it does not explicitly state when to prefer this tool over alternatives (e.g., detect_faces) or what situations are unsuitable. This is adequate but lacks direct usage exclusions.

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

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

The description goes well beyond annotations by disclosing key behaviors: 'Pure text handling — no ffmpeg call', 'Segments are sorted, empty ones dropped, and overlapping cues truncated', and 'Long lines are word-wrapped.' This provides important behavioral context that annotations (only basic hints) do not cover.

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 yet highly informative. It starts with a clear purpose, then efficiently lists behavioral traits and a downstream usage hint. Every sentence adds value with no redundancy 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 presence of an output schema and parameter descriptions, the description covers the essential aspects: input handling (sorting, dropping empty, truncating overlap), text wrapping, and the tool's lightweight nature. It also provides workflow context by referencing burn_captions, making the tool's role in the ecosystem clear.

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 already covers most parameters (75% description coverage), and the description adds behavioral meaning to segments (sorting, truncation) and wrapping for max_chars_per_line. However, it does not explain max_lines beyond the schema's title/default, which is a minor gap given the description's focus on text formatting.

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 the action: 'Turn a list of timed text segments into a valid SRT subtitle file.' It uses a specific verb and resource, and distinguishes itself from siblings like burn_captions and auto_caption by emphasizing pure text handling and no ffmpeg call.

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 provides clear context for when to use this tool: when you have timed text segments and need an SRT file. It also suggests a downstream workflow with burn_captions ('Feed the result to burn_captions, or edit it first'). However, it does not explicitly name alternatives or state when not to use it.

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

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

The description adds valuable behavioral context beyond the weak annotations (all false). It explains that colors are converted internally from hex to ASS's inverted BGR, that the subtitle file is passed to ffmpeg by path to avoid filter graph corruption, and that style overrides replace embedded .ass styles. These are meaningful implementation details that affect usage and expectations.

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 about 100 words across four sentences, each carrying substantive information. It is front-loaded with the primary purpose and then adds relevant details about styling, colors, and path handling. No redundant or filler content. It could be slightly more compact, but every sentence earns its place.

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 complexity (nested style and encode options, output schema present), the description covers the main function, styling capabilities, the safety of passing by path, and the caveat about .ass embedded styles. It wisely leaves encode option details to the schema. It does not describe the output path behavior or re-encoding implications, but the output schema and shared EncodeOptions mitigate this. Overall, sufficiently complete for a capable agent.

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?

With 67% schema description coverage, the schema already covers many parameters. The description enhances understanding by explicitly listing controllable styling aspects (font, size, fill/outline colour, position, margins) and explaining the hex-to-BGR conversion. This complements the schema descriptions, especially for style-related fields.

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 specific verb and resource: 'Burn an SRT or ASS subtitle file permanently into the video.' This clearly distinguishes it from sibling tools like text_overlay (which adds text without burning a file) and auto_caption (which generates captions). It immediately conveys the tool's core function.

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 implies when to use this tool (when you need to permanently bake subtitles into the video) but does not explicitly state alternatives or when-not-to-use. The note about .ass embedded styles being overridden is a useful caveat, but there is no direct comparison with sibling tools. Usage context is mostly implied rather than stated.

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

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

The description adds rich behavioral details beyond the annotations: queued jobs are cancelled immediately, running jobs are gracefully requested to stop, the worker terminates the ffmpeg subprocess within about a second, it works even if the job was started by a different process like the local UI, and finished jobs are untouched. This provides a clear picture of side effects and operational behavior, which the annotations (readOnlyHint false, destructiveHint false) do not convey.

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, front-loaded with the core action. The second sentence provides necessary nuanced behavior for running jobs, and the third covers the edge case of finished jobs. Every sentence adds value and there is no waste or redundancy.

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 parameter) and the presence of an output schema, the description is complete. It covers all relevant job states (queued, running, finished) and even mentions cross-process behavior. There is no missing context that would confuse an agent about when or how to invoke this tool.

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 has full coverage (100%) for the single parameter job_id, with description 'Job id returned when the work was queued.' The tool description does not add any additional parameter semantics, but the schema already provides sufficient meaning. Thus the baseline of 3 applies without needing extra compensation.

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 the tool's function: 'Stop a queued or running job.' The verb 'stop' (or cancel) plus the resource 'job' is specific and unambiguous. It distinguishes itself from sibling tools like job_status or job_result, which are about querying rather than cancelling, and there is no other cancellation tool among the siblings.

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 provides clear context on when to use the tool (for queued or running jobs) and explicit when-not guidance ('Jobs that already finished are left alone'). It does not name alternative tools, but the distinction is clear enough given that no other sibling tool performs cancellation, so the exclusion of finished jobs effectively covers when not to use it.

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

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

With annotations already signaling readOnly=false, the description adds useful behavioral context: neutral-value stages are omitted entirely and temperature is a relative artistic control, not an absolute white balance. This goes beyond what the schema and annotations alone 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?

Three short sentences, each earning its place. Front-loads the action, then explains the filter chain efficiency and temperature semantics with zero fluff.

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 output schema and high parameter coverage, the description covers purpose and key behavioral traits adequately. Missing is any comparison to sibling color tools, but the core workflow is understandable.

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 high, but the description adds meaningful clarification for temperature (relative warm/cool, not Kelvin) and the neutral-value omission rule. These insights help the agent understand the effects of leaving parameters at defaults.

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?

Description opens with 'Adjust brightness, contrast, saturation, gamma and colour temperature,' specifying the exact verb and resource. It clearly conveys what the tool does but does not contrast itself with sibling color tools like apply_curves or apply_lut.

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 notes that all five adjustments are combined in one filter chain to require a single re-encode, implying it's efficient for multi-parameter grades. However, it doesn't explicitly state when to use this instead of apply_curves/apply_lut or when a grade is unnecessary.

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

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

With annotations being minimal (all false hints), the description carries the burden and does well by detailing normalization steps (scaling, padding, resampling, audio layout) and the re-encode requirement. This goes beyond what the structured annotations reveal.

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?

Two sentences with no filler. The core action is front-loaded, and the second sentence precisely explains the conditional behavior. Every phrase contributes value.

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 tool has a nested encode object plus an output schema, and the description covers the main workflow and edge cases (compatible vs incompatible clips). It does not specify input media types, but the schema and output schema mitigate that gap.

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 80%, so the burden on the description is low. The description adds context about normalization behavior that relates to target_resolution and target_fps, but most parameter meaning is already present in the 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 opens with 'Join two or more clips end to end into a single file,' which is a specific verb+resource statement that clearly distinguishes this tool from siblings like overlay_media or trim. It unambiguously communicates the core function.

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 explains when remuxing happens (compatible clips) and when re-encoding occurs (incompatible clips), giving the agent context for expected behavior. It does not explicitly name alternatives or exclusions, but the conditions are clear enough to guide usage.

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

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

Annotations indicate readOnlyHint=false and destructiveHint=false, meaning this is a mutating but not destructive operation. The description adds meaningful behavioral context: default codec selection per container and the audio_only extraction path. This goes beyond the annotations without contradicting them.

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 two sentences, front-loaded with the core purpose and followed by actionable default behavior. There is zero redundancy and every phrase earns its place, making it an efficient and well-structured explanation.

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 tool with numerous encode options and an output schema, the description covers the key decision of default codecs and the audio_only shortcut. The schema handles parameter-level details, and the output schema likely covers return values. Minor gaps like error behavior and output path handling are covered by structured data or are not essential.

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 100%, with all parameters documented in the input schema. The description adds a small amount of linkage by referencing how 'encode' overrides defaults and 'audio_only' extracts audio, but this largely paraphrases schema descriptions. Baseline 3 applies given the schema already carries the heavy lifting.

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 'Transcode a file to a different container or codec,' a specific verb and resource that clearly states the operation. The added details about per-container defaults and audio_only further clarify the tool's scope and distinguish it from siblings like trim or concat.

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 implies usage for format conversion and explains how to override defaults, but it never explicitly contrasts with sibling tools or states when not to use it. There is no 'use X instead' guidance, so the agent must rely on tool names for differentiation.

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

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

Discloses that the tool downloads and caches a model on first use and requires the 'vision' extra. It also describes the output format (pixel and normalized coordinates, tracks) which adds transparency beyond the annotations. No contradiction with 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 compact yet informative, front-loading the main purpose and then expanding on output and usage. Every sentence adds value without redundancy.

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 complexity (6 params, output schema), the description covers purpose, output, sampling behavior, and dependencies. It is complete enough for an agent to select and invoke correctly.

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 already documents all parameters clearly, and the description adds extra context—e.g., sample_fps tuning advice and the max_frames safety cap. This goes beyond the schema descriptions, enhancing understanding.

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 starts with 'Find faces in a video, sampled over time,' clearly stating the action and resource. It further distinguishes itself from siblings like blur_faces or detect_scenes by detailing the output (bounding boxes, tracks). This is a specific verb+resource combination with strong differentiation.

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?

Provides practical guidance on sample rates ('2 fps is usually enough to follow a talking head; raise sample_fps for fast movement') and prerequisites ('Needs the vision extra'). It does not explicitly name alternative tools, but the context is sufficient for most use cases.

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

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

All annotations are false, offering no positive safety hints, so the description carries the burden. It adds meaningful behavioral context: uses ffmpeg's scene-change score, no vision dependency, threshold effects on cut detection, and the nature of the output (shot start/end times). It does not explicitly state that no files are modified, but the analysis-oriented wording implies it; a clearer read-only statement would earn a 5.

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 concise sentences, front-loaded with the core purpose, then usage context, then parameter guidance. Every sentence earns its place; no fluff or repetition of schema data.

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 tool has an output schema (present by context), so return values are covered. Parameter schema is fully documented. The description adds dependency context, integration with sibling trim, and parameter tuning — complete for a detection tool of this complexity.

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 100% and schema descriptions already explain each parameter. The description adds value by giving real-world guidance on how to tune the threshold ('Lower the threshold to catch softer cuts, raise it if handheld camera motion is being reported as cuts') and by connecting the output to another tool, which enhances understanding beyond raw 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 verb and resource: 'Find hard cuts in a video and report the shots between them.' It distinguishes the tool from siblings by noting it needs no vision dependency unlike other phase 4 tools, and by connecting its output to the trim tool.

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?

Explicitly says when to use it ('Useful for chopping raw footage into clips'), gives a direct integration path ('feed the returned scene start and end times straight into trim'), and provides practical tuning guidance for threshold and scene length. It also contrasts with other phase 4 tools on dependencies.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is known. The description goes beyond by disclosing a performance behavior: 'each frame is a separate fast seek, so the cost tracks the number of frames, not the length of the video.' This is useful behavioral context not present in structured fields, earning a 4.

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: purpose, use case, and cost behavior. It is front-loaded with the core action and avoids any fluff or repetition of schema details.

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 read-only, idempotent tool with an output schema, the description provides the key decision factors: what the tool does, when to use it, and how it behaves (cost model). It does not explain return format, but the output schema covers that. The only minor gap is not explicitly describing default behavior for output_path, but the schema default handles that. Overall complete enough.

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 71%, and most parameters (count, columns, tile_width, end, input_path) have individual descriptions with defaults and ranges. The tool description itself adds no parameter-level meaning beyond the schema, so it does not compensate for the few undocumented parameters (start, output_path). This aligns with the baseline 3 for high coverage.

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 specific verb-resource pairing: 'Tile several frames into one contact sheet' which exactly states the tool's function. It also explicitly differentiates from sibling tools like extract_frame by focusing on 'several frames' and 'survey footage at a glance', making the purpose unmistakable.

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 provides clear usage context: 'The fastest way to find out what is actually in a clip — where the good moments are, where the camera settles, which shots are worth cutting to.' This tells the agent when to use the tool, though it does not explicitly name alternatives or state when not to use it. The strong use-case framing earns a 4.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, but the description adds valuable behavioral context: 'Answers immediately. Seeking is done before decoding, so grabbing a frame from an hour-long file costs the same as from a short one.' This explains performance characteristics beyond the structured metadata.

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 compact and well-structured: one sentence for the core action, one for performance, and two for use cases. Every sentence adds value with no redundancy 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?

For a read-only extraction tool with full schema coverage, output schema present, and annotations, the description covers the essential aspects: what it does, when to use it, and performance expectations. It is fully sufficient for an agent to select and invoke the tool correctly.

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%, and every parameter has its own description in the schema. The tool description does not add any additional meaning about parameters, but since the schema already fully documents them, 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 opens with 'Save a single frame as an image so it can actually be looked at,' which precisely states the tool's action and purpose. It clearly distinguishes from siblings like extract_filmstrip by emphasizing 'single frame' and the goal of visual inspection.

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 provides explicit use cases: 'Use it to check what is in footage before cutting, and to confirm a render looks the way it was meant to.' These are concrete scenarios, though it does not mention any alternatives or exclusions, so it falls short of a full 5.

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

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

Beyond the annotations (readOnly=false, destructive=false, idempotent=false), the description adds valuable behavioral context: video is stream-copied so only audio is re-encoded, and the fade-out is positioned from the file's measured duration. These are non-obvious traits that materially affect how the agent invokes and evaluates the tool.

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 two short paragraphs, front-loaded with the core action. Every sentence earns its place: the first states the purpose, the second clarifies fade-out mechanics and the encoding strategy. There is no filler or redundancy.

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 moderate complexity (nested encode options, 5 top-level params) and the presence of an output schema, the description is mostly complete. It covers the core behavior, the fade-out quirk, and the encoding approach. It does not explicitly mention output path defaults or encode option interactions, but those are already documented in the schema and are standard for this tool family.

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 high (80%), so the baseline is 3. The description adds meaningful semantic context for fade_out: it explains that you provide the fade-out length rather than computing a start time, because the tool measures from the file duration. This is beyond what the schema's 'Fade-out length in seconds' conveys. Other parameters are already well-documented in the 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 opens with 'Fade a file's audio in at the start, out at the end, or both' – a specific verb and resource. It clearly distinguishes this from sibling tools like trim or normalize_audio by focusing solely on audio fades. The additional detail about fade-out positioning and video stream-copying further defines the tool's specific role.

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 intended use is clear: apply fades to audio. It implicitly tells you when to use it (whenever a fade-in/out is needed) but does not explicitly mention alternatives or exclusions. The tool's narrow name and description make the context obvious, though it lacks an explicit comparison to siblings.

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

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

Annotations already declare read-only, idempotent, non-destructive behavior. The description adds valuable context beyond annotations: error behavior for incomplete jobs, structured failure reason for failed jobs, and the result field carrying the output path and probe for successful ones. This fully discloses behavioral traits.

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?

Two sentences, front-loaded with the primary purpose, and each sentence adds essential information (purpose and error/result behavior). No filler or redundancy.

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 single parameter, existing output schema, and strong annotations, the description fully covers all necessary context: what to do first, what error paths exist, and what the successful result contains. It is complete for a tool of this complexity.

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 has 100% coverage with the parameter 'job_id' described as 'Job id returned when the work was queued'. The tool description does not add further parameter-specific detail, but since the schema already covers it, the baseline of 3 applies. No additional semantics are needed.

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 verb ('Fetch') and resource ('output paths of a completed job'), clearly distinguishing it from siblings like job_status (status) and cancel_job (cancellation). It leaves no ambiguity about the tool's core function.

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 warns that the tool errors if the job hasn't finished and instructs to 'poll job_status first', naming the alternative tool and providing clear sequencing. It also notes the different behavior for failed vs. successful jobs, giving actionable usage context.

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

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

Annotations already declare readOnly, idempotent, and non-destructive behavior. The description adds valuable context by specifying that it parses ffmpeg output and returns a progress percentage, giving insight into how the status is determined beyond the annotation basics.

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 concise sentences with no filler. The opening sentence states the purpose, the second explains the return behavior, and the third provides sequential usage guidance. Every sentence adds value.

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 simple parameter set, rich annotations, and presence of an output schema, the description fully covers what an agent needs: what statuses to expect, that progress is included, and how to proceed. No critical information is missing.

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 100% for the single job_id parameter, with a clear description. The tool description reinforces that the job_id comes from queueing work, adding workflow context that complements the schema without redundancy.

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 explicitly states the tool checks a queued job's progress and lists the possible statuses (queued, running, done, failed, cancelled). It clearly distinguishes from siblings like job_result (getting final result) and cancel_job.

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?

Provides explicit workflow guidance: poll this after queueing work, then call job_result once status is 'done'. This clearly establishes when to use it and what to do next, differentiating it from the related result retrieval tool.

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

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

Annotations already declare readOnly, idempotent, and non-destructive. The description adds behavioral context about what it reports (resolved build, encoders, filters, optional extras) and states 'Answers immediately', which is useful beyond the annotations. No contradiction and adds value.

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?

Two sentences, front-loaded with the main function and immediately followed by usage guidance. Every word earns its place; no fluff or repetition.

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 simple read-only query tool with an output schema, the description fully covers purpose, scope, and usage timing. No need to explain return values since output schema exists. It is complete for its complexity.

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% – both 'check_filters' and 'check_encoders' are well documented. The description aligns with these parameters but does not add any additional meaning beyond the schema. 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 uses a specific verb ('Report') and clearly identifies the resource ('resolved ffmpeg build', 'encoders and filters'). It also mentions optional extras (Whisper, vision), which distinguishes it from all the media processing siblings. The purpose is unambiguous.

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 states when to use it ('Use this before assuming something is available') and provides concrete examples (hardware encoders, filters, extras). It does not mention exclusions or alternative tools because not needed – this is the go-to capability query. Clear context but lacks an explicit when-not clause.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. Description adds valuable behavioral context: default scoping rationale (shared server), 'all' special value, and pagination semantics (offset/limit, total/has_more). No contradictions.

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, front-loaded with the essential purpose, and every sentence adds practical value. No redundancy 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?

With full schema coverage, output schema present, and annotations, the description covers scoping, sorting, and pagination. It is a complete and self-contained specification for a read-only list operation.

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 provides 100% coverage of all four parameters. Description enriches understanding by explaining why defaults matter (active project) and how to use offset/limit for pagination, going beyond the schema's basic descriptions.

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?

Description clearly states 'List jobs newest first, scoped to a project and returned a page at a time.' This uses a specific verb ('List'), names the resource ('jobs'), and adds ordering and scoping details that distinguish it from siblings like job_status or job_result.

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?

Provides clear guidance: defaults to active project, suggests project='all' to see everything, and explains paging with offset/limit and total/has_more. However, it does not explicitly mention when to use alternative tools like job_status, so it stops short of full when/when-not guidance.

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

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

Annotations already mark this as read-only, idempotent, and non-destructive. The description adds value by revealing that it indicates the current session's active project and per-project job counts (queued/running/done/failed), which isn't 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?

Two compact sentences; the first states core purpose, the second adds useful output detail and use case. No filler or redundancy.

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-argument list operation, the description fully covers what the tool does, what it returns, and when it's useful. The output schema exists, so return-value details don't need to be in the description.

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?

Tool takes zero parameters; schema coverage is 100% and the description carries no parameter burden. The description's mention of output content effectively replaces any parameter semantics needed.

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?

Clearly states verb 'List' and resource 'projects in the job store', with additional detail on per-project workload. It distinguishes itself from siblings like list_jobs by focusing on the project-level view, including session context and job counts.

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?

Provides explicit use case: to find the name of work started earlier or in another session. It doesn't name alternative tools, but the context is clear enough for an agent to choose this over list_jobs or list_capabilities.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds value by mentioning 'Answers immediately' (latency trait) and specifying the content covered (presets, fit modes, focus points), which gives the agent expectations about response scope beyond 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 two sentences: the first states the tool's purpose, the second provides usage context and latency. Every sentence earns its place, and it is front-loaded with the key verb and resource. 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?

For a simple read-only listing tool with zero parameters and an output schema, the description is fully adequate. It tells what will be listed, when to use it, and what to expect (immediate answer). The output schema handles return value details, so nothing is missing.

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?

With zero parameters, the schema description already states 'No arguments; lists the built-in presets.' The description does not need to add parameter details. The baseline for zero parameters is 4, and this description appropriately leaves parameter semantics to the 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 clearly states the tool lists 'named resolution presets, fit modes and focus points' that resize_video accepts, which is specific and distinguishes it from sibling tools like resize_video itself. The verb 'List' combined with the resource makes the purpose unambiguous.

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 provides clear usage context: 'Use it when you want to name a target platform rather than work out its pixel dimensions.' This implies when to use it, but it does not explicitly name alternative tools or methods, and the 'Answers immediately' note is more of a behavioral trait than a usage guideline. Still, the guidance is strong enough for an agent to decide appropriately.

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

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

With all annotations false, the description carries the burden. It discloses that the operation is a 'job rather than an instant answer' and explains why (integrated loudness cannot be sampled), which is valuable behavioral context. It doesn't mention side effects or permissions, but the async nature is the most important trait here.

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, front-loaded with purpose, then usage, then behavioral caveat. No filler, every sentence contributes.

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?

Combined with the existence of an output schema and sibling job tools, the description covers purpose, usage, and async behavior. It doesn't spell out how to retrieve results, but the job hint and sibling names (job_status, job_result) provide enough context for an agent to proceed.

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% and the description adds no meaning for input_path beyond 'file.' The tool name and description imply an audio file path, but there is no detail about path types, supported formats, or required conditions. This is a gap for a single-parameter tool.

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 specific verb+resource: 'Measure a file's loudness' and enumerates concrete metrics (mean, peak, EBU R128 LUFS). This clearly distinguishes it from siblings like normalize_audio or probe_media, which have different purposes.

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 gives concrete usage scenarios: 'decide whether audio is worth keeping' and 'check what a mix or a normalisation actually did.' It doesn't name an alternative tool explicitly, but the examples imply contrast with normalization and other processing tools, so it provides clear context without formal exclusions.

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

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

The description goes beyond the basic annotations by explaining ducking behavior, the order of operations ('Per-track gain and start offsets are applied before the mix'), and that video from the primary input is passed through untouched. No contradiction with readOnly/destructive 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 brief paragraphs, front-loaded with a clear purpose sentence. Every sentence contributes meaningful information with no 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?

Core mixing behavior and important edge cases are covered. Remaining details like duration, encode options, and output path are documented in the schema, and an output schema exists, so the description is sufficient for selecting and invoking the tool.

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 description adds practical meaning to central parameters: explains 'duck', clarifies gain/start application order, and maps video passthrough to keep_video_from_voice. Schema covers many other fields well, so the description augments rather than repeats.

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 specific verb and resource: 'Mix background music or effects under a primary voice track.' It clearly distinguishes this from sibling tools like concat or overlay by detailing ducking and video passthrough.

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 conveys a clear use case—mixing music or effects under narration—and explains when ducking is useful. However, it does not explicitly mention alternative tools or state when not to use this tool.

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

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

The description discloses the two-pass processing behavior and its accuracy tradeoff compared to a single streaming pass, which adds context beyond the annotations (which are all false). It does not mention side effects like file overwriting or permissions, but the output_path schema covers output behavior. Given the sparse annotations, this moderate disclosure is acceptable.

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 compact and well-structured: an opening purpose statement, a brief note on the two-pass behavior, and a final line with target-level recommendations. Every sentence adds value, and the most important information is front-loaded. No redundant or verbose content.

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 complexity (7 top-level parameters plus an encoder object) and that an output schema exists, the description covers the core function and key behavioral nuance but omits any guidance on advanced parameters (true_peak, loudness_range, encode) or how they interact. It is sufficient for basic use but not fully complete for an AI agent needing to make informed parameter choices.

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 57%, leaving parameters like true_peak and loudness_range undocumented. The description does not help clarify these, and it only repeats the target_lufs guidance already present in the schema (e.g., -16 vs -23 LUFS). For parameters lacking schema descriptions, the description provides no additional meaning, so it fails to fill the gaps.

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 the tool's function: 'Normalise a file's loudness to a target level (EBU R128).' It uses a specific verb and resource, and the reference to EBU R128 distinguishes it from generic audio tools. This unambiguously differentiates it from siblings like measure_audio or mix_audio.

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 provides useful context for parameter selection ('-16 LUFS suits online video, -23 LUFS is the broadcast standard') and implies the tool is used when loudness normalization is required. However, it does not explicitly mention when to use this tool over alternatives (e.g., measure_audio) or state any exclusions, so guidance is mostly implied rather than explicit.

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

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

Annotations are minimal (readOnlyHint=false, destructiveHint=false), so the description carries behavioral burden. It explains fade timing and chroma keying, but does not disclose output overwrite behavior or side effects on source files. No contradiction found.

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 two sentences, front-loaded with the primary purpose, and the second sentence efficiently summarizes key parameter behaviors. Every clause earns its place with no fluff.

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?

With 15 parameters, rich schema, and an output schema present, the description provides enough context for selection and invocation. It covers the core compositing behaviors but leaves some subtleties (opacity, margin, blend) to the schema, which is reasonable.

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 description adds significant meaning beyond the schema: 'x/y override position', 'width scales the overlay', 'start/end fade it in and out', and 'chroma_key hex colour'. This compensates for the 60% schema coverage by clarifying relationships between parameters.

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 the tool's function with a specific verb ('composite') and resource ('an image or video on top of another'), and lists concrete use cases (picture-in-picture, watermark, chroma-keyed). This differentiates it from siblings like text_overlay or transform.

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 contexts for use (picture-in-picture, watermark, chroma-key composite), but does not explicitly mention alternative tools or when not to use it. The intended usage is evident, though not exhaustive.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false. The description adds behavioral value by disclosing synchronous behavior ('answers immediately rather than returning a job id') and enumerating return fields. No contradictions with 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?

Three concise sentences: purpose, return data, and usage guidance. Information is front-loaded and every sentence adds value. No fluff or repetition.

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?

With a single parameter, rich annotations, and an output schema present, the description covers purpose, behavior, and usage context sufficiently. The guidance to probe before edits and verify renders completes the tool's role in a workflow.

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 100% coverage for the single parameter, which is described as 'Path to the media file to inspect.' The description does not add new semantic detail beyond the schema, aligning with the baseline 3 for high schema coverage.

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 ('Read') and resource ('media file's technical metadata'), listing exact output fields like container format, duration, codec, etc. It distinguishes from siblings by clarifying it returns immediate results rather than a job id, which separates it from async processing tools.

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?

Provides explicit when-to-use guidance: 'Call it before any edit that depends on the source dimensions or duration, and call it again on an output to verify a render.' It also states it answers immediately, implying use when sync results are needed. Lacks when-not-to-use or alternative tool names, so not a 5.

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

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

Annotations only provide uninformative false hints, so the description carries most of the burden. It does disclose processing behavior: every clip is scaled/padded, in/out points and speed are honored, transitions, overlays, captions, and audio tracks are layered. However, it omits operational details such as whether rendering is synchronous or asynchronous, whether the output file is overwritten, or whether there are any side effects on input files. This is a moderate level of transparency but not rich enough to fully anticipate the tool's runtime behavior.

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 a compact paragraph of about 100 words, front-loaded with the purpose, then explaining the use case and timeline semantics. Every sentence adds necessary context, and there is no repetition of the title or obvious filler. It could be tightened slightly, but it is well-structured and appropriately scoped for a complex tool.

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 complexity (large nested schema, 3 parameters) and the existence of a rich output schema, the description provides strong orientation: what the tool does, how it relates to the UI, and how the timeline is interpreted. It doesn't cover encode options or output_path, but those are self-explanatory given the schema and common sense. The main gap is the lack of mention of job/asynchronous behavior, but for a script-driven entry point this is a minor omission.

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 tool description does not mention any of the three top-level parameters (timeline, encode, output_path) by name, so schema coverage from the description is 0%. However, the description compensates by explaining the timeline structure in prose (clips, transitions, overlays, captions, audio tracks), which maps to timeline subfields. It does not address `encode` or `output_path` at all, leaving those to the schema's own descriptions. The schema itself is very detailed, so this is adequate but not exemplary.

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 is explicit: 'Render a complete edit — clips, transitions, overlays, captions, audio — in one pass.' It names the resource (a full timeline), specifies the action (render), and clearly distinguishes itself from the sibling tools that operate on individual aspects (e.g., add_transition, burn_captions, overlay_media). The opening sentence is unambiguous and specific.

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 states this is 'the entry point for driving the server from a script rather than calling tools one at a time.' This gives direct guidance on when to use it (fully composed timeline, scripted workflow) and contrasts it with the alternative of invoking individual tools. It also mentions it matches the local UI's timeline editor structure, providing additional context for when this tool is the right choice.

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

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

The description discloses the key behavioral implications of each fit mode (e.g., cover loses edges, contain pads with bars, blur overlays a blurred copy) and explains how focus affects cropping. With annotations only indicating non-read-only and non-destructive, the description carries significant burden and does so well. It could add more about encoding side effects, but the schema EncodeOptions covers those, and the core transformation behavior is transparent.

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 somewhat long but well-structured and front-loaded with a clear summary, then detailed sections for presets, fit modes, and alternatives. Every sentence adds value, though it could be tightened without losing critical information. The use of bullet-like formatting for fit modes enhances readability.

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 tool with 11 parameters and complex fit behavior, the description covers the essential decision points: presets, fit strategies, focus, and when to prefer an alternative. The output_path behavior is handled by the schema, and encode options are documented in the nested EncodeOptions, so the description is complete enough for an agent to invoke correctly. Minor gaps remain around default encoding behavior, but these are less critical.

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 73%, but the description greatly enriches parameter understanding: it enumerates specific preset names and their resolutions (e.g., reel, tiktok, story are 1080x1920), explains how aspect_ratio behaves when combined with width/height or used alone, and gives concrete examples of fit modes beyond the schema's brief descriptions. This adds substantial meaning beyond the structured 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 verb and resource: 'Convert a video to a different resolution or aspect ratio.' It clearly distinguishes itself from sibling tools by explicitly recommending track_and_crop for talking-head videos where the subject must stay in frame, making its scope and unique purpose 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?

The description provides explicit usage guidance, including when to use a named preset versus explicit width/height/aspect_ratio, and for each fit mode what trade-offs exist. It also names an alternative tool (track_and_crop) for a specific use case, giving clear when-to-use and when-not-to-use direction.

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

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

The description discloses behavioral side effects beyond annotations: subsequent jobs are filed under this name, outputs without explicit paths land in the project's directory, and list_jobs filters by default. Since annotations are minimal, this fully carries the transparency burden.

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, purpose first, then effects, then a concrete usage scenario. Every sentence adds value and there is no redundancy.

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 single-parameter state-setting tool with an output schema, the description covers purpose, usage, side effects, and setup requirements fully. It is complete for an agent to select and invoke the tool correctly.

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 fully describes the name parameter with allowed characters. The description adds that the name is created on first use, which is useful context over the schema. With 100% schema coverage, baseline is 3, and the added context raises it to 4.

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 'Work under a named project' with a specific verb and resource, and distinguishes from siblings like list_projects by explaining the effect on subsequent jobs and list_jobs filtering.

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?

Explicit guidance is provided: 'Two sessions editing different videos should each set their own project' and it notes the name is created on first use, so no setup is needed. This gives clear context for when to use the tool.

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

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

The description discloses rich behavioral details beyond annotations: default time-stretching with chained atempo stages, keep_pitch behavior for tape speed-up, drop_audio option, and independent audio_speed. Annotations are minimal (readOnlyHint: false, destructiveHint: false), so the description carries the burden and does so thoroughly, explaining how audio is processed and how options affect output.

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?

Two sentences total: the first states the core purpose, the second elaborates on key behavioral details. Every phrase earns its place, with no filler. The structure is front-loaded and efficient.

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 complexity of the tool (7 parameters, shared encode options, output schema), the description captures the essential behavior: speed adjustment, independent audio control, pitch handling, and audio discard. The output path behavior is covered in the schema. No critical behavioral context is missing.

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 already describes most parameters with 86% coverage, but the description adds interaction semantics: it explains that audio is time-stretched by default, what keep_pitch false does, and how audio_speed relates to speed. This adds contextual meaning beyond individual parameter descriptions, enhancing understanding of how they work together.

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 the tool's function: 'Speed a clip up or slow it down, video and audio independently.' It identifies the specific resource (a clip) and distinguishes it from sibling tools like trim or transform by emphasizing independent video/audio speed control. This is a specific verb+resource description with clear scope.

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 implies when to use the tool (speeding/slowing clips) and explains key behavior, but it does not explicitly mention when not to use it or compare to alternatives. There is no explicit 'instead of X' guidance, but the context of audio pitch handling gives some situational awareness. This is adequate but lacks direct exclusions.

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

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

The description goes beyond annotations by explaining the sidecar file mechanism, which guarantees character safety, and notes that everything renders in one pass. These are behavioral traits that the annotations (all false) do not convey. It does not fully describe output handling, but the schema covers output_path, so the description adds substantial context.

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 compact and front-loaded, with a clear first sentence stating purpose. The subsequent sentences efficiently add feature details and the sidecar safety note without fluff. Every sentence earns its place, making the description easy to scan.

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 tool with a complex schema, the description covers the essential behavior, item structure, and a notable edge case (special characters). An output schema exists, so not describing return values is acceptable. The only gap is explicit usage guidance, which is already partial, but overall the description is sufficient for an agent to invoke the tool correctly.

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 description adds meaning to the 'items' parameter by explaining each item's timing, position, font, and animation, which complements the schema's per-field descriptions. It also clarifies the safety of any text via the sidecar note. Given 50% schema coverage, the description compensates well by summarizing the core structure, though it does not detail encode options, which are already self-described in the 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 opens with a specific verb and resource: 'Draw titles and lower-thirds over the video, with timing and animation.' This clearly distinguishes it from siblings like burn_captions (caption burning) and overlay_media (media overlay), as it focuses on text overlays with timing and animation.

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 implies usage by describing the tool's purpose and features, but it does not explicitly state when to use this tool versus alternatives like burn_captions or overlay_media. There is no when-to-use or when-not-to-use guidance, leaving the agent to infer the appropriate context.

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

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

Annotations only state readOnly=false and destructive=false, so the description adds valuable behavioral context: crop paths are smoothed to avoid snapping, clamped to source edges, and fallback to center crop or fail. This goes beyond the sparse annotations without contradicting them.

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, well-structured, and front-loaded. The first sentence states the purpose, the second paragraph explains key behavior and rationale, and the third provides the workflow. Every sentence earns its place with no redundancy.

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 11 parameters and the existence of an output schema, the description covers the core workflow—reframing, face tracking, smoothing, clamping, fallback, and detect_faces integration—well enough for an agent to invoke it correctly. It omits details on some advanced parameters, but the schema partially covers those and the overall picture is clear.

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 64%, and the description adds useful meaning for track_id by explaining it comes from detect_faces. However, it does not compensate for undocumented parameters like sample_fps, max_frames, and min_confidence, which are left without explanation in both the schema and the description.

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 specific verb and resource: 'Reframe a clip to a new aspect ratio, following a face across the timeline.' This clearly distinguishes it from siblings like detect_faces, blur_faces, transform, and resize_video by combining reframing with face tracking.

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 for when to use the tool ('turning a horizontal interview into a vertical clip') and provides a concrete workflow: call detect_faces first if you want to choose a person, then pass its track_id. It does not explicitly name when-not-to-use alternatives, but the classic-use case and prerequisite are strong guidance.

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

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

Goes well beyond annotations by revealing that transcription can take roughly real-time on CPU, that the first run downloads model weights, that language auto-detection occurs unless specified, and that output includes timed segments with optional word timings. This is rich behavioral detail 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 tightly written across three short paragraphs, each sentence adding valuable information: purpose, output format, performance characteristics, and model weight download. No fluff or redundancy.

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 complex asynchronous transcription tool, the description covers return format, optional parameters, runtime expectations, polling behavior, and initial setup (model weights). It is sufficiently complete given the presence of an 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 coverage is high (67%), but the description adds meaningful semantics: it explains the effect of language auto-detection, mentions srt_path writing a subtitle file, and clarifies word_timestamps usage. This complements the schema rather than just repeating it.

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 specific verb+resource: 'Transcribe speech in an audio or video file using Whisper.' This clearly states what the tool does and distinguishes it from siblings like auto_caption or translate_transcript by naming the tool and the core function.

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?

Provides clear operational context: mentions polling job_status because transcription is slow, describes model choices, and explains when word_timestamps and srt_path are useful. However, it does not explicitly exclude alternatives or name sibling tools for comparison, so it falls just short of full guidance.

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

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

The description discloses operation ordering (crop, scale, pad, rotate, flip) and the cost implication of a single re-encode. This adds value beyond the sparse annotations, which only show readOnly/ destructive hints without explaining the transform behavior.

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 compact and well-structured, front-loading the main purpose and then providing the most critical usage nuances. Every sentence earns its place without unnecessary fluff.

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 complexity of 10 parameters and the presence of an output schema, the description sufficiently covers the key behavioral aspects: operation order, encoding cost, and aspect ratio handling. It could be more explicit about alternative tools, but it is adequate for correct invocation.

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 description adds essential interplay semantics: giving only one scale dimension preserves aspect ratio, while giving both with pad_to_fit letterboxes instead of stretching. This compensates for the moderate schema coverage (50%) by clarifying how the scaling and padding parameters relate.

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 the tool applies geometric transforms (crop, scale, rotate, flip) in a single pass. It differentiates from siblings by emphasizing the one-pass composable chain, which is distinct from simpler tools like resize_video or track_and_crop.

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 provides specific guidance on using scale_width/scale_height and pad_to_fit to control aspect ratio behavior, which helps agents use parameters correctly. However, it does not explicitly name alternative tools or state when to prefer this tool over sibling operations.

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

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

Annotations provide minimal behavioral hints (readOnlyHint false, destructiveHint false), so the description carries the burden. It discloses a key non-obvious trait: Whisper's translate mode always outputs English and cannot translate to other languages. This adds valuable context beyond the structured 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 concise, with a clear first sentence stating the purpose and a second sentence adding a crucial limitation. No redundant information or fluff; every sentence earns its place.

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 complexity (an options object with multiple fields) and the presence of an output schema, the description provides the essential context: it handles non-English speech, outputs English, and notes the limitation. This is sufficient for an agent to select and invoke the tool correctly, though it does not detail return structures, which is acceptable since an output schema exists.

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 already provides descriptions for most parameters, including input_path and srt_path, and the options object has detailed field descriptions. The description does not add per-parameter semantics beyond noting the general purpose, so it meets the baseline for schema-covered parameters.

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 the tool transcribes non-English speech and translates it into English, using a specific verb and resource. This distinguishes it from sibling tools like transcribe_audio or auto_caption by focusing on the translation-to-English aspect.

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 explains when to use this tool (for non-English speech) and provides an alternative for other target languages (a separate translation step). It lacks an explicit comparison to transcribe_audio or auto_caption but the context makes the intended use clear.

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

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

This text carries the full burden since annotations are minimal. It discloses critical behaviors: stream-copy snaps to keyframes, reencode is frame-accurate, and the job reports actual output duration. This goes beyond what annotations provide and helps set expectations for job results.

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 two short paragraphs: the first states the core purpose, the second explains the key behavioral nuances. Every sentence earns its place with no fluff, front-loading the most important 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 essential context for a trim operation: what it does, the key behavioral difference between copy and reencode, and how to verify results. Given the rich input schema and presence of an output schema, this is sufficient for correct use.

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 83%, so most parameters are already well documented. The description adds meaningful semantics beyond the schema, particularly for the 'mode' parameter (explaining keyframe snapping) and the 'output_path' behavior (job workspace path). This elevates it above the baseline.

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 'Cut a segment out of a video or audio file.' This is a specific verb ('cut') and resource ('video or audio file') that clearly distinguishes it from siblings like concat or convert_format. The additional detail about stream-copy versus reencode further clarifies its purpose.

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 provides clear guidance on when to use stream-copy vs mode='reencode', explaining the tradeoff between speed and frame accuracy. It does not explicitly name sibling tools or state when not to use this tool, but the context is clear enough for an agent to decide appropriately.

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