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

With no annotations, the description carries the behavioral burden. It usefully discloses that exports and push refuse to run on a cut without a rendered preview and explains the confirm_unreviewed=true escape hatch. However, it does not mention side effects, mutating behavior of reformat_timeline or relink_media, permissions, or output 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 short and front-loaded with the core purpose, followed by a critical behavioral warning. The action list overlaps with the enum but still usefully summarizes the tool's breadth without excessive detail.

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?

This is a multi-action dispatcher with a nested args object and no output schema. The description does not explain per-action required arguments, return values, or how args should be structured for each action. The confirm_unreviewed detail helps but is not enough to make the tool safely callable for all nine actions.

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%, so the baseline is 3. The description adds value beyond the schema by explaining the confirm_unreviewed=true flag and connecting action names to concrete output formats and workflows, which helps disambiguate the generic args object.

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 purpose with a specific verb phrase ('Get the edit out') and resource (a cut/edit), and clearly differentiates it from siblings like inspect, diagnose, preview, and watch by focusing on export, reformat, relink, and push operations. It also names concrete outputs and actions.

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 a clear context for when to use the tool—when you need to export or move an edit elsewhere. However, it does not explicitly state when not to use it or name alternatives for related tasks, instead leaving that mostly to sibling names and inference.

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 no annotations provided, the description carries the behavioral burden; it explicitly flags the tool as read-only and limits its behavior to the listed detection/validation actions. It does not disclose output format or per-action side-effect nuances, but for a no-annotation tool the core non-mutating behavior is clearly stated.

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 purpose, then usage, then a compact action list, with no filler. The action list is long but all entries are load-bearing for action selection, and the whole text remains scannable.

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 definition is adequate for a read-only diagnostic tool: purpose, read-only behavior, and action vocabulary are present. However, the 10 actions are heterogeneous and have no per-action argument breakdown or output description, so an agent may need supplemental information to invoke some actions with confidence.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema already covers both parameters fully, and the description's action list mirrors the enum. It adds no per-action argument semantics beyond the schema's example, so the description earns the baseline score of 3 rather than extra credit.

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 ('Find problems in a timeline') and enumerates concrete problem types and actions, so the tool's diagnostic role is clear. It does not explicitly differentiate itself from sibling tools like inspect or find, but the action vocabulary makes the intended scope fairly 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?

'Read-only. Run before editing.' gives a clear temporal usage rule and implies it is a pre-edit analysis step rather than a mutation. It does not name alternatives or state when not to use it, 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?

With no annotations, the description carries the behavioral burden. It does disclose a key trait: 'Writes a new file', which suggests a non-destructive output model. However, it does not describe failure behavior, prerequisites, permissions, or whether the original file is left untouched, so the disclosure is only partial.

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 purpose, immediately states the key side effect, and then lists all supported actions. The action list is long but useful; no sentences are wasted, though the list partially duplicates the enum in the schema.

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?

This is a complex tool with 15 actions, a generic nested args object, no output schema, and no annotations. The description covers the operation set and the new-file side effect, but it leaves per-action argument requirements, output location, and return behavior unexplained, which is a significant gap 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?

Schema description coverage is 100%, so a baseline of 3 applies. The description adds an example of args ('filepath') and names the action enum, but it does not explain what arguments each specific action needs beyond the generic 'args' object.

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 and resource ('Change clips on the timeline') and enumerates concrete operations, so an agent understands exactly what this tool does. The action list also separates it from read-only or output-oriented siblings like inspect, preview, and deliver.

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 it: whenever timeline clip edits are needed. It does not explicitly contrast it with sibling tools or state when not to use it, leaving the routing decision mostly to the action names and general intent.

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 no annotations provided, the description carries the behavioral disclosure burden. It reveals ranking criteria, the optional local vision model dependency, the constraint that find_index never transcribes or goes online, and what result elements are reported. It falls short of clarifying side effects for find_to_timeline, which appears to create a reel, and does not mention auth or failure 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 information-dense and front-loaded with the core purpose, then systematically covers each action. The final 'Actions:' enumeration is slightly redundant after the prose has already introduced all three actions, but it is harmless and aids quick parsing.

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 all three actions, their parameters, key constraints, and output hints, which is especially important given there is no output schema. Some details remain implicit, such as exact query syntax, clip_name format, and valid backend values, but the agent has enough context 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?

Although the schema only defines a generic args object, the description names the action-specific arguments and their meanings, such as filepath, query, limit, visual, clip_name, captions, backend, min_source_separation, and output_path. This goes well beyond the schema's bare example and effectively compensates for the lack of per-action schema detail.

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 clear purpose, 'Natural-language shot search,' then enumerates three concrete actions with distinct resources and behaviors. Each action is described with a specific verb and expected outcome, making the tool's scope immediately understandable.

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 strong routing guidance by explaining what each of the three actions does and when it applies, including boundaries like 'it never transcribes or goes online.' It does not explicitly compare against sibling tools such as index or transcript, but the action-level guidance is sufficient for most invocation decisions.

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 no annotations, the description carries the full burden of behavioral disclosure, but it only lists action names like flatten_compound_clip and import_edl_json. It does not explain side effects, whether operations mutate existing projects, required project state, or return behavior, leaving the tool mostly a black box.

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 and front-loaded: one clear purpose sentence followed by a compact action list. There is no filler, and the structure makes the tool's scope immediately scannable.

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 exposes seven distinct operations with a nested args object, yet the description provides no per-action argument guidance, output expectations, or usage caveats. No annotations or output schema compensate, so the description is not complete enough for reliable 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?

Schema description coverage is 100%, so the action enum and args object are already documented. The description repeats the action list but adds no additional meaning about what arguments each action needs or how args should be structured beyond the schema's single example.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific action and resource: 'Build new timeline structure from source clips', and enumerates seven concrete operations. It is clear what the tool does, though it does not explicitly differentiate itself from sibling tools like edit or organize.

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 purpose statement and action list imply when to use the tool—when constructing new timeline structures—but no explicit conditions, exclusions, or alternatives are mentioned. The agent must infer the boundary against sibling tools rather than being told.

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 no annotations, the description carries the full burden, and it discloses the key behaviors: status reads cache metadata, build warms the cache, and clear is destructive ('drops it'). It also signals low risk by stating every other tool works with the index off. Return values and build-overwrite behavior are left implicit, but the core operation semantics are honestly described.

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 dense and front-loaded with the resource and optionality, then lists the three actions. The final action list is slightly redundant with the earlier sentence, but overall every sentence contributes useful 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 all three actions and the cache's optional nature, but there is no output schema and it does not explain what each action returns. It also leaves 'the second question' vague and only states args for index_build, so an agent must infer the arg behavior for status and 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 both parameters with 100% description coverage, so the baseline is 3. The description adds that index_build takes filepath and with_transcript, which helps because the schema's args object is generic, but it does not explain what with_transcript means or whether status/clear accept args. This is only a modest improvement over 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 identifies the resource (~/.fcp-mcp/index.db) and enumerates three concrete operations (index_status, index_build, index_clear), so an agent can tell this is the index-management tool. It is specific and not a tautology, though it does not explicitly contrast itself with a sibling alternative.

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 sentence 'Every other tool works with the index off... this only makes the second question fast' gives an explicit selection signal: the index is optional and purely for performance. It does not spell out when to prefer one sub-action over another in detailed scenarios, but the contextual guidance is 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?

With no annotations provided, the description carries the full burden of behavioral disclosure; the phrase 'without changing it' adequately communicates that this is a non-mutating, read-only operation. However, it does not describe return shapes, failure modes, or differences between the 13 actions, which leaves meaningful gaps for a dispatcher-style 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 front-loaded with purpose and usage guidance, then compactly lists the supported actions. The action list repeats the enum but is useful for quick comprehension in a dispatcher tool, and there is no wasteful prose.

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?

As a 13-action multiplexer with no annotations and no output schema, the description gives a solid high-level orientation but lacks per-action argument requirements and expected results. An agent would likely call obvious actions like list_projects correctly, but less obvious actions like filter_by_role are under-specified.

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 'action' and 'args' have descriptions, and 'args' includes an example. The description itself adds no per-action parameter detail, so it remains at the baseline 3 without compensating for the generic args object.

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 begins with a clear read-only verb and resource ('Read a timeline or project without changing it'), which immediately distinguishes it from mutating sibling tools like edit, mark, and generate. It further lists all 13 concrete actions it supports, leaving no confusion about what the tool is for.

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 explicitly says 'Use this first to understand what you are working with,' giving a strong contextual trigger for selecting this tool. It does not explicitly name excluded situations or direct the agent to alternative siblings for modifications, but the read-only phrasing vs. mutation-oriented siblings makes the boundary 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?

With no annotations provided, the description carries the behavioral disclosure burden. It does state that the tool adds/imports markers and chapters and lists the action names, which conveys basic mutating behavior. But it does not disclose side effects, whether existing markers are modified, prerequisites, or what happens after an import or snap operation.

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 short and front-loaded with the core purpose, followed by a compact action list. It is easy to skim, though the action list largely duplicates the schema's enum and adds little new 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?

This is a dispatch-style tool with six distinct actions and a nested args object, yet the description only names the actions and does not explain per-action arguments, expected inputs, or return behavior. An agent could not confidently call the correct action with correct arguments based solely on this definition.

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 high at 100%, so the baseline is 3 even without parameter explanations in the description. The description adds source-type context for actions like SRT/VTT and transcript imports, but it does not explain what arguments each action requires beyond the generic filepath example 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 uses a specific verb + resource ('Add or import markers and chapters') and enumerates the supported source types and action names. It is clearly a marker/chapter tool, so it is distinguishable from siblings like 'transcript' and 'edit', though it does not explicitly contrast itself with any sibling.

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 contexts via 'including from SRT/VTT subtitles, transcripts, and beat analysis', and the action list hints at the available operations. However, it gives no explicit guidance on when to choose this tool over an alternative, nor when one action should be used instead of another.

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 no annotations, the description carries the full behavioral burden and does so well. It discloses that apply=true writes keywords, that each operation writes a _organized copy, and that undo moves outputs to a journal folder, never deletes, and refuses when files changed since writing.

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 dense and information-rich, but the single block of text contains several run-on clauses and the final 'Actions:' list partially duplicates what was already described inline and in the schema enum. It is not poorly sized, but structure and conciseness could be improved with bullets or clearer separation.

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 multi-action tool with no output schema and no annotations, the description covers the main actions, selection criteria, side effects, and undo safety. Minor gaps remain, such as exact return values for history and precise required arguments per action, but the description gives enough context 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 only has action and args, but the description enriches both by explaining each action's relevant parameters such as clip_name, keyword, role, keywords, mode, rating, audio_role, video_role, and limit. It adds real meaning beyond the schema, though it does not provide a complete per-action argument spec.

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 identifies the tool as a bulk library logging and ledger utility, and enumerates specific operations like organize_auto, organize_keywords, organize_rate, organize_roles, history, and undo. This distinguishes it from the sibling tools by domain and action, though it does not name a sibling explicitly.

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 a concrete workflow: select clips, then apply keywords, ratings, or roles; it also explains when history and undo are relevant. However, it does not explicitly compare this tool to alternatives or state when not to use it, so the usage guidance is 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?

With no annotations, the description carries the burden of explaining behavior. It usefully reveals that previews read from SOURCE MEDIA rather than from the XML and that Final Cut Pro need not be opened. However, it does not disclose whether rendered proxies or check outputs persist as files, what side effects occur, or what output format the agent should expect.

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, front-loaded with the main value proposition, and every sentence adds information. It avoids restating the tool name or schema boilerplate and ends with a clean action list.

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 five distinct actions, no output schema, and no annotations, yet the description never explains what each action returns or what arguments each action needs apart from a generic filepath example. An agent selecting between preview_render and preview_timeline would still lack enough detail to invoke the right action 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 100%: both action and args have descriptions, and action is an enum. The description reinforces the action meanings by naming the five action values and clarifying that the check reads source media, but it does not add detailed semantics for the args object beyond the schema's single example.

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 clear, concrete purpose: 'See the edit without opening Final Cut Pro.' It then enumerates exactly what the tool produces (proxy video, contact sheet, single frame, filmstrip-plus-waveform check) and lists all five actions. This is a specific verb-plus-resource statement that distinguishes preview from sibling tools like inspect or diagnose.

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 a practical context for use: preview output can be generated from source media without launching Final Cut Pro, and preview_check should be run 'to confirm a fix actually landed.' It does not explicitly exclude cases or name alternative sibling tools, but it clearly indicates when preview 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?

With no annotations provided, the description carries the full burden and does a good job: it discloses that detect_scenes reads every source, reports cuts in timeline time, writes markers, and performs splits. It also reveals the backend dependency on PySceneDetect vs ffmpeg and that the result names which backend answered, though it does not describe the exact return shape or whether splitting is destructive/reversible.

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 dense and front-loads 'Shot boundaries,' then packs the three actions plus backend behavior into a compact format. The inline argument list inside the first sentence makes parsing slightly harder, but every clause contributes useful 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?

For a multi-action tool with no output schema and no annotations, the description leaves gaps: it does not describe the return value structure for detect_scenes, and it does not spell out the arguments required for scenes_to_markers and scenes_split. The action enum and filepath are covered, but an agent could still be unsure how to invoke two of the three actions 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 only describes args as a generic object, so the description adds substantial meaning by enumerating filepath, clip_name, backend, threshold, and min_scene_len with optionality and a default. However, it does not specify which arguments apply to scenes_to_markers and scenes_split, so it is not fully complete.

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 identifies the tool's domain with 'Shot boundaries' and names three distinct actions with specific outcomes: detect_scenes reports cuts, scenes_to_markers writes markers, and scenes_split cuts clips. This differentiates it from sibling tools like 'mark' and 'edit' by giving each action a specific verb and resource.

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 by laying out the three operations and their sequential relationship: first detect, then optionally write markers or split. It does not explicitly name sibling alternatives or state when not to use this tool, so it falls just short of giving full exclusion 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?

No annotations exist, so the description carries the full burden; it does reveal local processing and the 'by what was SAID' approach. But it never states whether edit_by_transcript or remove_filler_words mutates the timeline/project, whether changes are reversible, or what transcript_pack returns. Important behavioral gaps remain for a tool that implies editing side effects.

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 short sentences plus an action list; the description front-loads the core value proposition and is easy to scan. The filler-word sentence slightly duplicates the remove_filler_words action name but still provides immediate comprehension.

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?

This is a multi-action tool with no annotations and no output schema, and the description defines each action only by name, not by input/output or side-effect behavior. An agent would struggle to know which action to select in a given situation or what result to expect.

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 covers both parameters fully, including enum values and an args example, so the baseline is 3. The description repeats the action names but adds little meaning about expected args, return effects, or how each action customizes the args object.

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 names a concrete capability—transcribe media locally and edit the timeline by spoken content rather than timecode—and lists the accepted actions, making the tool's purpose and scope clear. It distances itself from generic edit and generate siblings by emphasizing transcript-based editing and filler-word removal. However, it doesn't explicitly contrast itself with the sibling 'edit' 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?

Use cases are implied: editing by transcript or removing filler words. But there is no explicit when-to-use/when-not-to-use guidance, no named alternatives, and no exclusions. This is minimum viable but leaves routing to inference.

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 no annotations provided, the description must carry the behavioral burden. It does disclose stateful behavior: watching the folder, detecting the XML, and diffing against the last seen one. However, it does not explain the side effects or lifecycle semantics of the four actions, such as what watch_start begins, what watch_status reports, or what watch_pull returns.

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 opens with the workflow value, then states the mechanism, then the companion tool, then the action list. The phrase 'Close the round-trip' is slightly jargon-heavy, but each sentence earns its place and there is no redundant 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?

This is a multi-action dispatcher with no output schema and no annotations, so the description needs to explain each action's individual contract. It does not: watch_start, watch_status, and watch_stop are only named, not described, and there is no indication of return values, state persistence, or prerequisites beyond the general workflow pairing with deliver.push_to_fcp.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the baseline is 3. The description lists the action enum values but adds no semantic detail beyond the schema's own 'Which operation to run' and the args example. It does not clarify which arguments each action requires.

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: 'Watch the Final Cut Pro export folder, detect the XML the moment it lands, and diff it against the last one seen.' This makes the tool's core function unmistakable and distinguishes it from siblings like deliver.push_to_fcp by framing it as the feedback step in a round-trip workflow.

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 explicit workflow guidance: 'Pair with deliver.push_to_fcp for a full loop: push in, edit, Cmd-E, watch_pull.' This tells the agent when in the process the tool belongs. It does not explicitly state when not to use it or name alternatives, 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.