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

With no annotations the description carries the burden and does well: it discloses the unreviewed-cut refusal, the confirm_unreviewed override, and that filepath actions refuse if the file no longer matches expected_sha256. It omits auth/permission needs and whether reformat/relink mutate or destroy source media.

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 scope and guardrails, each earning its place. The trailing action list partly repeats the enum, which is the only real 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 nine-action dispatcher with no annotations and no output schema, the description covers the key precondition and the sha256 safety net. It stops short of describing where exports land or what stems/reformat produce, which an agent would still have to discover.

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 the args object already documents filepath, expected_sha256, and sha256 reporting; the description's action enumeration duplicates the enum. Baseline 3 is correct since the schema does the heavy lifting, though the sha256 guard is echoed usefully.

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 concrete domain (getting an edit out: export, reformat, relink, push) and enumerates the nine actions it dispatches, so an agent can tell it apart from edit/preview siblings. It is clear but the umbrella verb 'deliver' only becomes precise via the action list.

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 real usage rule: exports and push_to_fcp refuse a cut with no rendered preview of its current state, with the confirm_unreviewed=true escape hatch. It does not contrast when to use export_* versus preview or edit, so routing among siblings is left partly implicit.

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 whole burden; it does disclose the important trait "Read-only", which prevents an agent from fearing mutation. However, it says nothing about cost/latency across the ten actions, whether results are exhaustive, or what a "problem" result looks like, and the expected_sha256 refusal semantics live only in the 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?

Front-loaded and tight: purpose, safety trait, and timing rule come first, and the action list is a useful index. The action list is partially redundant with the enum already present in the schema, which keeps it out of 5 territory.

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 ten-action, nested-args tool with no output schema, the description omits what a caller receives back (findings format, severity, counts), which is the main gap it should have closed. Purpose and safety are covered adequately, so it is minimally complete but not rich.

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 enum values and the args/expected_sha256 contract are already fully documented. The description's action list merely restates the enum rather than adding per-action argument meaning, so 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?

States a concrete verb+resource ("Find problems in a timeline") and enumerates the specific problem classes it looks for (gaps, flash frames, duplicates, dead air, beats), which is far more informative than the bare name. It stops short of the 5 because it never contrasts itself with plausible siblings like inspect or find, so an agent must infer the boundary.

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?

"Run before editing" gives a clear lifecycle position for the tool, which is genuine usage guidance. There are no exclusions or named alternatives (e.g., when to use diagnose vs inspect), so it lands at a solid 4 rather than 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 full burden. It usefully discloses that the tool 'Writes a new file', implying the source is not mutated in place, which is the single most important behavioral trait for a write tool. It says nothing about failure/refusal behavior, overwrite safety, ripple side effects, or that actions differ widely in destructiveness, so the disclosure is 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?

Purpose is front-loaded in the first clause and the write behavior is stated early, before the enumeration. The 21-item action list is long and duplicates the schema enum, but for a mega-tool that breadth is defensible for agent routing, so it stays tight overall.

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 21-action, deep-nested, no-output-schema tool where the description covers only the umbrella purpose and the action roster. The rich schema compensates for parameter detail, but cross-action context (which actions produce new files vs modify in place, typical sequencing, expected results) is left entirely unstated.

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 the schema is unusually rich, including per-action conditionals and detailed field docs, so the baseline is 3. The description's action enumeration merely restates the schema enum and adds no parameter meaning beyond what the schema already carries.

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?

States a specific verb and resource ('Change clips on the timeline') and enumerates the operation categories plus every action name, so an agent can tell this is the mutation umbrella tool. It does not explicitly contrast with siblings like organize or generate, which could plausibly also alter a project, so it stops short of 5.

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 when-to-use / when-not-to-use guidance, no prerequisite sequencing (e.g. that clip_path must come from a prior inspect.list_keyframes call, which only surfaces in the schema), and no routing between the 21 actions. 'Writes a new file' is a behavioral fact, not usage guidance, so an agent gets little help choosing this tool over its 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?

With no annotations, the description carries the full burden and delivers: the ranking tiers used, the fact that the first result line explains which tiers answered and which could not, find_index's hard boundary (no transcription, no network), the diversity score returned by find_to_timeline, and the expected_sha256 refuse-on-mismatch guard on filepath actions. It stops short of naming permission or write side effects beyond the reel.

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 block is dense but every sentence carries information, and it is front-loaded with the core purpose. The trailing 'Actions: find_index, find_shots, find_to_timeline.' merely restates the schema enum, and the single-paragraph form makes three distinct operations harder to scan than bullets would.

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 high-complexity dispatcher with three sub-operations, nested args, and no output schema or annotations, the description covers each action's parameters and observable behavior well. Remaining gaps are minor: return shapes are not described (acceptable given no output schema) and find_shots' write side effects on filepath inputs are only implied.

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's args object is free-form, so the description is the only place that enumerates the real per-action parameters and defaults (limit=10, visual=false, clip_name?, captions=true, backend, min_source_separation=1, output_path?) and defines expected_sha256's semantics. This adds substantial meaning the schema cannot provide.

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?

Each action is given a concrete verb+resource: find_shots is 'natural-language shot search', find_index 'warms scenes and captions', find_to_timeline 'assembles the hits into a _found selects reel'. An agent can tell the three operations apart. It never contrasts itself with siblings like index, transcript, or scenes, so it falls short of a 5.

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 a workflow (index warms caches, shots searches, to_timeline builds a reel) and notes that find_index 'never transcribes or goes online', which constrains when it is useful. But there is no explicit 'use X when Y' or stated exclusion relative to the sibling tools; usage must be inferred.

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 does so richly: it names the required environment keys (FAL_KEY / GEMINI_API_KEY), the hard price ceiling FCP_MCP_GEN_MAX_USD (default 5), the exact refusal conditions, and post-execution side effects (ffprobe verification, output saved under generated/, clip attached with role `generated`, marker, DTD validation, journaling). This is far beyond what structured fields 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?

It is a dense single paragraph, but it is front-loaded (capability and quote-then-confirm model first, side effects after) and nearly every clause conveys actionable information. Slight deduction for run-on density that makes the per-action parameter lists harder 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 four-action tool with no output schema, the description covers the quote return (a quote id), the execution side effects, and the safety gates needed to invoke it correctly. It never states the shape of the fill-result response, but the described attach/journal behavior gives an agent enough 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 100% and the schema only defines a generic `args` object, so the description does real work by spelling out per-action arguments and signatures — provider, seconds, prompt, model?, filepath, clip_name, gap_index|at — plus defaults like seconds=5. The only gap is that it omits expected_sha256, which the schema documents instead.

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 concrete capability family (generative fill: quoting, gap fill, b-roll, clip extension) and enumerates the four actions, so an agent knows exactly what it does. It falls short of a 5 because the tool name 'gen' is opaque and the description never distinguishes it from the similarly named sibling 'generate', leaving a real risk of picking the wrong 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?

The quote-then-confirm workflow is spelled out as a precondition: gen_quote must run first to obtain a quote id, and the fill actions refuse without quote_id + confirm=true. What's missing is guidance on choosing among the fill actions themselves (gap_index vs clip_name vs at) and any explicit contrast with the 'generate' sibling.

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 are supplied, so the description carries the full burden. It says structures are 'built' from source clips, hinting at creation, but does not state that this writes/modifies project files, what happens to existing timeline content, whether flatten_compound_clip is destructive, or what permissions are required. The sha256 guard and filepath handling live in the schema, not 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?

Two sentences, front-loaded with the purpose before the action list; there is no filler. The action enumeration is slightly redundant with the enum but is useful for quick scanning.

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?

Seven distinct operations share a single free-form args object with no output schema, yet the description gives no per-action argument requirements — an agent must infer what auto_rough_cut versus import_edl_json needs. Naming the actions is a start, but for this complexity the definition is only minimally adequate.

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 the args object already documents the filepath/expected_sha256 pattern, so the baseline is 3. The description's action list merely restates the enum values already in the schema, adding no per-action argument meaning.

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 gives a specific verb and resource: 'Build new timeline structure from source clips,' then enumerates the capabilities (rough cuts, montages, A/B roll, templates, compound clips). This distinguishes it reasonably from siblings like edit or inspect, though it never names a sibling or explicitly draws the line between generating new structures and editing existing ones.

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?

Usage is only implied: the seven listed actions tell the agent what kinds of operations exist, but there is no statement of when to choose generate over edit, or when one action is preferable to another (e.g. auto_rough_cut vs generate_montage). No exclusions, prerequisites, or sequencing guidance are given.

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 does disclose persistence location, the environment flag that bypasses it, and that index_clear destroys cached data. It stops short of describing build cost, permissions, or concurrency behavior, but the safety-relevant traits (opt-in, destructive clear) are present.

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?

A single dense paragraph that front-loads the resource definition and then maps each action to its effect. Nearly every clause earns its place, though the trailing action list slightly duplicates the schema enum.

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 multiplexed cache tool with no output schema, the description covers what the cache is, where it lives, each action's effect, and its optionality. It does not sketch the shape of index_status output beyond 'what is cached and how old it is,' which is a minor 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 100%, so the schema baseline is 3, but the description adds meaning the schema lacks by naming the per-action args (filepath, with_transcript) and tying index_build to a timeline source. This goes beyond restating the generic action/args structure.

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 by naming the resource concretely (the analysis cache at ~/.fcp-mcp/index.db) and enumerates the three sub-actions the tool dispatches. It distinguishes itself from siblings by stating that every other tool works with the index off, though the top-level verb 'index' alone would not convey this.

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?

Each action is paired with its role: index_status reports cache contents/age, index_build warms it for every source in a timeline, index_clear drops it. It also gives an explicit when-not by noting the index is optional (FCP_MCP_INDEX=off) and that it only speeds up the second question, which tells the agent not to treat this as mandatory.

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 disclose the most important trait: this is a non-mutating read operation. It says nothing about permissions, supported input formats beyond the schema's own field notes, or failure modes for missing/corrupt files, so the reporting 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?

Two short sentences followed by a flat action list, with the read-only constraint and the 'use first' directive front-loaded before the enumeration. The list is long but functional; no sentence is filler, though the trailing list lacks any grouping or ordering rationale.

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 15-action dispatcher with no annotations and no output schema, the description covers the essentials (read-only, when to reach for it, available operations) but not the payoff: it never indicates what any action returns, nor references the expected_sha256 staleness check that guards against acting on an outdated file.

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 filepath, clip_path, args, and the expected_sha256 guard are already documented in the schema, including the versioning safeguard. The description adds nothing about parameter meaning beyond restating the action names, so the baseline 3 applies.

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?

States a specific verb and resource ('Read a timeline or project') and adds the key scoping constraint 'without changing it', which cleanly separates it from mutating siblings like edit, mark, generate, and deliver. It enumerates all 15 actions, though it does not explain what each action does, so an agent still has to infer what analyze_pacing vs. analyze_timeline return.

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 this first to understand what you are working with' gives a clear sequencing heuristic for entering an unfamiliar file. However, it names no alternative (find, view, scenes, transcript) and gives no guidance on when NOT to use it or how to choose among the 15 listed actions, leaving the hardest selection decision 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?

No annotations are provided, so the description carries the full burden. It implies mutation ('add', 'import') but says nothing about side effects, whether changes are reversible, what file is modified, or permission requirements. The only behavioral detail (sha256 refusal) lives in the schema's args description, not 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?

Two compact sentences with the capability front-loaded and the action list trailing as supporting detail. No filler, though the action enumeration duplicates the schema enum.

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 a nested free-form args object and no output schema, the description covers the broad purpose but leaves each action's required arguments to inference. It is minimally viable rather than 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 100% and both parameters (action enum, args object) are documented in the schema, so the baseline is 3. The description only restates the action values already enumerated in the schema and adds no per-action argument 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?

States a specific verb and resource ('Add or import markers and chapters') and enumerates the concrete actions the tool performs, so an agent knows exactly what domain it covers. It doesn't explicitly contrast with siblings like edit or organize, which are generic names, but the marker/chapter scope is distinctive enough.

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 action list implies when each operation applies (e.g., import_srt_markers for subtitle files, import_beat_markers for beat analysis), but there is no explicit statement of when to choose this tool over edit or organize, nor any prerequisites or 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?

With no annotations, the description carries the full burden and largely succeeds: it discloses that apply=true actually writes, that each action produces a _organized copy rather than mutating in place, that undo moves outputs to a journal undone/ folder and never deletes, and that writes are refused when a file changed since it was written. These guard rails and side-effect semantics are exactly what an agent needs to call a write tool safely.

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?

Content is front-loaded and dense with no filler prose. The trailing 'Actions: ...' sentence merely restates the action enum already present in the schema, which is a small 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 six-action multiplexer with a nested args object and no output schema, the description covers the write/copy semantics, selection criteria, ledger behavior, and undo guard conditions well. It does not characterize the shape of returned data (e.g., what organize_auto proposes or what history emits), leaving a minor 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 100%, but the schema's args is an opaque nested object; the description compensates by naming the real inner arguments (clip_name glob, keyword, role, mode add|remove|replace, rating favorite|rejected|clear, audio_role, video_role, limit, n). This adds meaningful semantics beyond the structured 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 names a concrete function (bulk library logging/ledger) and enumerates the six operations the multiplexer exposes (organize_auto, organize_keywords, organize_rate, organize_roles, history, undo), so an agent can tell what each action does. It stops short of differentiating the tool from siblings like mark, edit, or inspect, which could plausibly overlap with rating/keyword work.

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 workflow: select clips with clip_name (glob), keyword and/or role, then dispatch to organize_keywords, organize_rate, or organize_roles, and it explains organize_auto's caption/transcript source. It never states when to prefer a sibling tool or when not to use this one, so context is clear but exclusions are absent.

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 does disclose one important trait: output is read from SOURCE MEDIA rather than the XML. However it says nothing about permissions, cost of rendering proxies, output formats, or how the read-only/mutating nature of the actions varies.

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?

Front-loads the value proposition ('See the edit without opening Final Cut Pro') and packs the action list into a single trailing sentence. Slightly dense given five actions are named, but no sentence is wasted.

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 five-way dispatcher with no output schema and no annotations, the description covers the broad purpose and one action's usage, but leaves the distinct inputs and outputs of preview_render, preview_sheet, preview_frame, and preview_timeline unspecified.

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 the schema itself documents 'action' and the 'args' object including the expected_sha256 guard, so the description does not need to explain parameters. It repeats the enum values already listed in the schema, adding no meaning beyond 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?

States a concrete verb and resource ('render a proxy video of the timeline, a contact sheet, a single frame...') and enumerates all five dispatched actions. It distinguishes itself from the editing siblings by being the no-FCP viewing path, though it never explicitly contrasts itself with 'view' or 'inspect'.

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 one concrete routing rule ('Run preview_check to confirm a fix actually landed'), which is genuinely useful, but gives no when-to-use guidance for the other four actions nor any guidance on when to prefer this over 'view', 'inspect', or 'scenes'.

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 does disclose real behavior: scenes_to_markers writes markers, scenes_split actually cuts clips (a mutation), and the runtime dependency determines whether PySceneDetect or ffmpeg answers, with the result naming the backend. It stops short of saying whether the split is destructive to source files, whether it is reversible, or what permissions/backups are needed.

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?

Front-loaded with the resource, then packed with action semantics and defaults in a couple of dense sentences; nothing is padding. The telegraphic fragments ('ffmpeg without it — the result names which one answered') are terse but still parseable, at a slight cost to 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?

There is no output schema, and the description compensates by stating that detect_scenes reports cuts in timeline time and that results name the answering backend. Combined with the three action descriptions and the arg defaults, an agent has enough to invoke it correctly; the main missing piece is the destructive/reversibility profile of scenes_split.

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 exposes a generic 'args' object plus a bare action enum, so the description is doing the real work: it enumerates filepath, optional clip_name, backend with its auto|content|adaptive|ffmpeg values, threshold, and the min_scene_len=0.5 default. That is genuine added meaning over the schema, though it does not explain how threshold interacts with the backend choice.

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?

Opens with a precise resource statement ('Shot boundaries') and then names all three sub-actions with a specific verb+object for each: detect_scenes reads sources and reports cuts, scenes_to_markers writes a marker per cut, scenes_split cuts the clips. The three internal operations are mutually distinguished, and no sibling tool (inspect, edit, mark, transcript, etc.) overlaps this 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 implies a workflow ordering — detect_scenes produces the cuts, the other two consume them — and notes which backend (PySceneDetect vs plain ffmpeg) will answer. However it never states when to prefer detect_scenes alone versus chaining to markers or split, nor any exclusion or prerequisite, so action selection is left 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, the description carries the full burden. It usefully discloses that transcription is 'local' and that filler words are removed, but says nothing about whether actions write files, what gets overwritten, or the sha256 refusal guard documented only in the 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?

Three tight sentences, with the core purpose front-loaded before the action enumeration. No filler, though the action list partially duplicates the enum rather than adding 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?

A four-action tool with a nested, generic args object and no output schema needs per-action intent, sequencing, and write-behavior notes; the description provides none of these. An agent cannot tell what each action consumes or returns from the description alone.

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 the args object is self-documented, so the baseline is 3. The description's action list merely mirrors the enum and adds no per-action argument meaning beyond what the schema already provides.

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?

States a concrete verb+resource ('Transcribe source media locally and edit the timeline') and contrasts the editing paradigm against the sibling 'edit' tool by timecode. The four action names are enumerated, but the overall umbrella purpose of a multi-action tool is only loosely bounded.

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 action list implies usage but never states when to pick transcribe_media vs edit_by_transcript vs transcript_pack, nor the ordering between them. No exclusions or alternative tools are named, so the agent must infer the workflow.

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 does well: it explicitly declares read-only semantics, describes the interactive MCP Apps rendering and the buttons that call other tools, and names the sha256 refusal behavior (via the schema). It omits any auth/permission or rate-limit notes, so it falls short of exhaustive.

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 dense sentences, no filler — the return payload is front-loaded and the routing note trails. The opening 'See the cut inline' is idiomatic and slightly opaque, but the specifics immediately follow and every clause 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?

No output schema exists, so the description must explain returns, and it describes view_timeline's payload thoroughly plus the UI affordances. It does not describe what view_clip returns and says nothing about pagination or size limits, leaving a small gap for a two-action tool with nested args.

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 is a generic {action, args} envelope with only 100% coverage of placeholder text, so the description is what actually documents the per-action parameters and defaults: view_timeline(filepath, thumbnails=true, words=true) and view_clip(filepath, clip_name). This adds real meaning the structured fields do not convey.

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 the two concrete operations (view_timeline, view_clip) with their signatures and states exactly what view_timeline returns — lanes, clips, markers, gaps, transcript words, filmstrip thumbnails as rational-time JSON. It also distinguishes the tool from siblings by declaring 'Read-only; edits go through edit and mark.' An agent can tell this apart from edit/mark/inspect without opening any schema.

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 supplies clear routing context: read-only viewing here, mutations via edit and mark, and 'view_clip is the inspect button' ties it to the inspect sibling. However it never states the selection rule between view_timeline and view_clip beyond naming them, so the when-to-use distinction is left partly implicit.

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. It does disclose meaningful traits: event-driven detection ('the moment it lands') and statefulness ('diff it against the last one seen'), implying a stored baseline. But it omits whether watch_start blocks, where watch state persists, what happens if started twice, and what each action 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 core purpose is front-loaded and the workflow/action list follows in a single compact paragraph. The opening fragment 'Close the round-trip' is slightly promotional, but overall there is little waste.

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 four-action dispatcher with a nested args object and no output schema, the description covers the overall purpose but leaves the individual action semantics and returns unexplained. An agent still lacks enough to invoke watch_status or watch_pull confidently, though the high schema coverage partly compensates.

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 enum action values and the nested args object are already documented, giving a baseline of 3. The description repeats the action names without explaining each action's arguments or behavior, so it adds no meaning beyond 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 names specific verbs and a resource: watch the Final Cut Pro export folder, detect XML on landing, and diff it against the previous version. It also enumerates the four actions (watch_start, watch_status, watch_stop, watch_pull), so an agent can tell what capabilities it exposes. It references the sibling workflow (deliver.push_to_fcp) but does not fully differentiate itself from the other siblings like preview or inspect.

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 clear context for use: 'Pair with deliver.push_to_fcp for a full loop: push in, edit, Cmd-E, watch_pull', which tells the agent when this tool belongs in a workflow. However, it offers no explicit when-not-to-use guidance and no exclusions relative to alternatives.

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