FableCut

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

With no annotations, the description carries full behavioral disclosure burden. It explains that the path is copied into media automatically, threshold has adaptive defaults, and registerMusic extracts and registers the music track on A1. No contradictions or hidden side effects are apparent.

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 moderately long but well-structured: purpose first, then outputs, then recipe, then cross-reference. Each sentence adds value, but minor redundancy (e.g., 'Remake recipe' repeats some info). Still efficient for the amount of 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?

Despite no output schema, the description thoroughly explains the return values (shot boundaries, per-shot audio energy, beats, BPM, loudness curve, drop, extracted music) and provides a complete recipe for using the blueprint. It also references documentation for further details. No gaps identified.

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 description adds value: for 'path' it clarifies absolute vs. media/ src; for 'threshold' it explains adaptive default values (0.30→0.20→0.12) and tuning guidance; for 'registerMusic' it describes extraction and registration. This enhances understanding 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 clearly states the tool analyzes a reference video into an EDIT BLUEPRINT for rebuilding with different footage over same music. It lists specific outputs (shot boundaries, per-shot audio energy, beats, BPM, loudness curve, drop, extracted music) and distinguishes from siblings via cross-reference to documentation.

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 says when to use (analyze reference for remake) and provides a step-by-step remake recipe. It does not explicitly state when not to use, but the context and sibling tool names imply its specific role. Cross-reference to docs enhances 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?

With no annotations, the description carries the full burden and does so richly: it is a mutation (writes keyframes), it multiplies clip volume so level/keyframes/fades are untouched, re-running replaces previous dips, linked stems get the same keys, requires ffmpeg+ffprobe on PATH, and refuses locked clips unless force. These are exactly the side-effect and prerequisite facts an agent needs.

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 core action and free of filler, but very dense with long multi-clause sentences (em dashes, parentheticals) that pack several behaviors into each line. Efficient rather than wasteful, though slightly heavy to parse.

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 7-parameter mutation with no output schema, it covers what the agent needs: side effects, idempotency, dependency requirements, lock/force behavior, stem propagation, and what it writes. Nothing essential for correct invocation 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%, so baseline is 3, but the description adds real meaning beyond the schema — the interpolation/ramp semantics of attack and release, the gap-bridging rationale behind threshold, the defaulting logic of `under` ('every audio track the music isn't on'), and that amount 0 removes ducking.

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 ('Duck music under dialogue') plus the exact mechanism (finds voice via RMS threshold, writes duck keyframes in dB on the music clips). It clearly separates this from sibling audio tools like normalize_audio or denoise by naming the ducking/auto-duck pipeline 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?

Explains when this applies (ducking music under voice) and gives operational triggers: raise threshold if room noise triggers ducks, amount 0 clears, force to touch locked clips. It does not explicitly name sibling alternatives to prefer in other situations, so it stops short of full when/when-not routing.

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 and does so well: discloses that it renders a new FLAC into media/, that linked stems switch while the picture file stays (preserving links/timing), that re-runs are idempotent (reuses rendered file), the ffmpeg+ffprobe PATH prerequisite, and locked-clip refusal behavior. These are exactly the side effects an agent must know before invoking.

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?

Dense but front-loaded: purpose first, then mechanism, revert, idempotency, prerequisites, and force. Every sentence earns its place, though the parenthetical about picture files is slightly nested.

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 mutation tool with no annotations and no output schema, the description covers purpose, side effects, file layout, idempotency, prerequisites, and refusal semantics – more than enough 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 coverage is 100% – all three params are documented including the enum, defaults, and semantics of 'off'. The description adds the 'off restores original' behavior and force rationale, but the schema already carries most of this, 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 specific verb and resource ('Reduce background noise... on audio clips') and names concrete noise types (hiss, hum, room tone). Distinguishes itself from siblings like fablecut_normalize_audio and fablecut_auto_duck by identifying the exact mechanism (FFT denoiser / Noise control), so an agent can route correctly without opening a 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?

Explains when to use and what state changes occur, and covers the 'off' revert and force/locked-clip condition. Lacks explicit contrast with sibling audio tools (normalize_audio, auto_duck), which is the only gap.

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 indicates a read-only retrieval operation ('Return the documentation'), but does not explicitly state it has no side effects. Since no annotations are provided, the description carries the full burden; it successfully conveys the non-destructive nature through 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?

Two clear sentences plus a token tip. Front-loaded with purpose, no superfluous words. 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?

For a simple documentation retrieval tool with one optional parameter, the description covers purpose, usage, and filtering. It could mention what happens if a section is not found, but given the lack of output schema and low complexity, it is adequately 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?

The description adds significant value beyond the schema: explains the substring match behavior, provides concrete examples (props, Recipes, Remake), and offers a token-saving tip. This fully compensates for the schema's brief parameter 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 clearly states the tool's purpose: 'Return the FableCut project schema documentation'. It lists specific content areas (clips, tracks, props, etc.) and distinguishes itself from sibling tools which handle project data manipulation or analysis.

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 advises 'Read this before editing', indicating when to use this tool (before making edits). The token tip provides optimization guidance. While alternatives are not named, the context signals show siblings operate on projects, not documentation.

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 thoroughly: it names the config file (encoding-profiles.json), states it is edited on disk and hot-reloaded, discloses that settings are dry-run against ffmpeg at export start so bad config is refused before rendering, and warns that hardware encoders appear only when functional locally. These are exactly the operational traits an agent cannot infer from 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?

The purpose is front-loaded and the two-mode structure is easy to scan. However, the long parenthetical enumerations of preset ids, codecs, rate-control modes, and container details are largely re-derivable from the tool's own output, making the middle section denser than it needs to be.

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 zero-required-parameter, no-output-schema discovery tool, the description supplies return shape (per-preset spec fields, truncated vs. full args arrays), the backing file, and the validation model. What the no-argument default call returns as a whole is only implied, which is the one 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 3 is the floor, and the description earns extra by giving concrete usage forms ('{preset:"youtube"}' returns one full spec; '{profile:"hq"}' with detail:true includes every args array) and by clarifying that the default is a truncated summary. It largely echoes the schema's own wording, which keeps it from a 5.

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 concrete verb and resource: 'List what fablecut_export can make,' then splits the answer into two named categories (DELIVERY PRESETS and ENCODING PROFILES) with their backing artifacts. This distinguishes it cleanly from the sibling fablecut_export, which performs the render rather than the discovery.

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 division of labor is implied well: presets cover standard destinations, and encoding profiles exist 'for anything the presets do not cover,' giving the agent a selection rule between the two branches. It also tells the agent that encoders are listed only when they actually work on this machine. There is no explicit 'use this before calling fablecut_export' statement or named exclusion, so it falls 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 full burden and does it well: browser-tab vs headless Chrome/Edge, FABLECUT_CHROME env var, ffmpeg on PATH, one-export-at-a-time concurrency, timeout keeps export running, impossible combinations corrected. It does not state file-overwrite/collision behavior or permission requirements, which keeps it short of 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?

Front-loaded with the core action in the first clause, then operational detail; every sentence carries distinct information for a genuinely complex tool. It is dense, but not padded.

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, and the description compensates: it states it returns the file path by default, that the reply lists every file for multi-output renders, and that each finished file is validated with checks listed in the reply. Complete for an agent to call this 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% and already details every param, so baseline is 3, but the description adds operational meaning not obvious from per-field schema docs—linking wait:false → {job} → {cancel:job} into a polling workflow and stating the default inPoint→outPoint 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?

Specific verb+resource ('Render the timeline to a video file in exports/') with a precise mechanism (editor's Fast export: same compositor, audio mix, encoding profile) so it is unmistakable what this does. Clearly distinct from sibling tools like fablecut_import_media or fablecut_encode_profiles.

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 routing: use wait:false for long edits then poll with {job}, {cancel:job} to stop, where:auto/tab/headless semantics, and the preset-vs-profile fallback chain. Tells the agent exactly when and how to pick each mode.

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 entire burden and does so: it discloses the vision-capability requirement, that `path` is read in place and never copied, that ffmpeg must be on PATH, and that timeline mode runs in the open editor tab or falls back to a headless browser. These are non-obvious operational constraints an agent would otherwise discover only by failure.

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 critical fact (image output, vision requirement) is front-loaded before the modal breakdown, and the three modes are cleanly numbered. It is long for a single paragraph and the trailing ffmpeg/browser note is slightly buried, but nearly every clause carries distinct 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?

An 11-parameter tool with no output schema and no annotations is covered well: mode disambiguation, defaults, ranges, dependencies on a vision model and ffmpeg, and the fallback sibling are all addressed. Since the tool returns an image rather than structured data, no output-schema explanation is needed.

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, but the description adds genuine meaning beyond the schema by explaining the mode-selection logic: `path` present means source frame, `frames` present means contact sheet, neither means timeline via `time`. It also clarifies the default image widths and the 2–60 frame range, though per-parameter detail largely duplicates 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?

"LOOK at the footage — returns an actual image, not just numbers" names a specific verb and output, and the three modes are enumerated explicitly (single frame, contact sheet, composed timeline). It differentiates itself from fablecut_analyze_reference by calling out that sibling as the non-vision fallback, so an agent can choose between them without opening either 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 states exactly when to use it ("before choosing a clip's `in` point, or to pick footage matching a blueprint's shots[] energy") and gives explicit alternatives and exclusions: pass `text:true` if not vision-capable, or skip this tool and use fablecut_analyze_reference. That is when/when-not/alternative coverage in full.

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 must cover behavioral aspects. It describes the output format options but does not mention error conditions, permissions, side effects, or whether the operation is idempotent (implied read-only). The description is adequate but not thorough.

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 long, front-loaded with the purpose, and the second sentence efficiently delivers a valuable tip. Every sentence serves a purpose 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 only one optional parameter and no output schema or annotations, the description covers the main scenario (obtaining the project with optional compact format). However, it omits details like error handling, what the full JSON looks like, or behavior when the project is missing. It is minimally viable but not comprehensive.

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 covers the parameter compact with a basic description. The description adds meaningful context: 'one-line-per-clip summary (ids, tracks, timings, non-default props)' and advises when to use each mode, going beyond what the schema 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?

The description clearly states the verb 'Get' and resource 'FableCut project (the timeline document)', distinguishing it from sibling tools that patch or set projects. The compact option is also mentioned, adding specificity.

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 token tip provides explicit guidance on when to use compact:true versus full JSON, which helps the agent decide the parameter value. However, it does not compare against sibling tools like fablecut_status or fablecut_analyze_reference, so usage boundaries are not fully delineated.

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: it discloses side effects (local files are copied, remote files downloaded into ./media/), a refused input class (remote SVG/CORS-breaking URLs), and the deliberate decision not to retain the URL as the playback src. It also states the return value and how to use it.

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, front-loaded with what the tool does and then the input rules and return value. Every clause adds actionable 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?

For a single-parameter import tool with no output schema, the description covers the operation, input forms, failure modes, side effects (copy/download location), and the shape of the result plus how to use the returned id. Nothing material 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% so the baseline is 3, but the description adds real semantics beyond the schema: accepted source forms, format restrictions, and the .svg local-vs-remote distinction that the schema's one-line description does 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?

States a specific verb (import) and resource (a media file into FableCut's media library and the project), and the scope is narrow enough to distinguish it from siblings like fablecut_patch_project or fablecut_analyze_reference. An agent can identify the operation without opening the 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?

Gives concrete selection rules for the single input: a local absolute path (copied, .svg allowed) vs. an https:// URL (downloaded, video/audio/image only, remote SVG refused). It does not mention any alternative tool or when this is the wrong choice relative to siblings, 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 full burden and does so richly: the measurement standard (ITU-R BS.1770 integrated LUFS / sample peak), that it writes props.gain in dB, that linked stems share one gain so a stereo pair stays balanced, that it refuses locked clips unless force:true, and that volume keyframes/fades are left untouched.

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 is front-loaded with the core action and wastes little, though the run-on style packs many clauses (stems, keyframes, prerequisites, locking) together. Every clause is informative, so it stays efficient despite its length.

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 4-param mutation tool with no annotations or output schema, the description is nearly complete on behavior and prerequisites. The one gap is that it never states what the call returns (e.g., measured values), which the missing output schema would otherwise need it to cover.

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, but the description adds real meaning: target units depend on mode (LUFS vs dBFS), the force flag's intent ('only when they asked'), and concrete target values. It clarifies the mode/target interplay better than the schema alone.

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 ('Loudness-normalize clips') plus the exact mechanism (measures source audio, sets props.gain). An agent can instantly differentiate this from siblings like fablecut_denoise or fablecut_auto_duck, which perform unrelated audio operations.

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 concrete usage context via typical targets (-14 LUFS streaming, -16 podcast, -23 broadcast, peak at -1 dBFS) and states a prerequisite (ffmpeg + ffprobe on PATH). It does not explicitly name a sibling alternative or state when not to use it, so it falls 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 full burden and does so well: it discloses that the document is re-read from disk, ops applied in order, revision bumped once, save is atomic, the patch is all-or-nothing, and baseRevision produces a CONFLICT with nothing saved. What holds it below 5 is that the safety profile is buried inside an extremely long block rather than stated as a short, scannable set of guarantees.

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 routing guidance is correctly front-loaded, and the op catalog is separated by category headers, but the whole thing runs to well over a thousand words for a two-parameter tool — effectively an inlined manual that duplicates material a fablecut_docs sibling likely owns. Length of this magnitude raises selection cost and dilutes the one sentence an agent actually needs to choose the 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?

For a merge-patch tool with no output schema, the definition covers everything an agent needs: op grammar, merge/replace rules, lock refusal and override, conflict detection and retry protocol, and where the revision comes from. Nothing important about calling it correctly is left 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 coverage is 100% for only two top-level params, but the schema's 'ops' item is an untyped object that defers entirely to the description. The description compensates fully by enumerating op shapes, merge semantics (top-level replaced, props key-by-key, null deletes), and per-op optional fields like force and ids.

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 states a specific verb and resource ('Apply targeted edits to the FableCut project') plus the key differentiator: no full-document round-trip. It explicitly names the pattern it replaces ('get+set') and is therefore distinguishable from fablecut_get_project / fablecut_set_project 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 gives an explicit routing rule ('PREFER THIS over get+set for every edit') with a quantified rationale (~10-100x cheaper, merge-safe). It also scopes dangerous sub-operations ('openSequence … only when asked', 'removeSequence … only when the user asked') and tells the agent when to pass force:true versus leaving locked material alone.

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 and does well: open saves the current project first and reloads editor tabs, delete is restricted to archived projects, and duplicates/templates copy no footage because media/ is shared. Gaps remain on whether delete is permanent, what archive means to the user, and error 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?

Concept and the ./project.json relationship are front-loaded, then actions are enumerated in a compact ·-separated list, with the safety caveat last. It is dense and run-on in places, but the tightness is justified by 11 actions and nothing is padding.

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 an 11-param, 11-action mutation tool with no annotations and no output schema, the description covers the critical semantics: defaults, shared-media behavior, side effects of open, and delete safety. It omits return-value detail and error conditions, which would matter given the absence 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 100%, so baseline is 3, but the description adds cross-parameter meaning the schema can't: which params apply to which action, that archived:'only'|'all' exposes archived projects, that template accepts built-in canvas names or a saved template id, and that open defaults differ for new (true) vs duplicate (false).

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 names the resource (the projects dashboard) and the multi-action scope, and the follow-up sentence positions ./project.json as the OPEN project every other tool reads and edits. An agent can tell immediately this is the project-management hub rather than an editor-content tool like fablecut_get_project or fablecut_patch_project.

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 states the default action (list) and gives an explicit exclusion: 'only open, archive or delete when the user asked for it.' It also routes forward by noting the next fablecut_get_project call reads the newly opened project. What's missing is explicit guidance on when to prefer this tool over fablecut_set_project/fablecut_get_project for project-level vs. content-level work.

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 behavioral burden and does so well: it discloses background server-side creation, one-at-a-time processing, wait behavior, status reporting including progress and failure, deletion behavior, and the ffmpeg dependency. It also clearly states the critical invariant that proxies never affect export or measurement 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 front-loaded with what a proxy is and why it matters, then moves through reporting, creation, deletion, defaults, and prerequisites. Despite being dense, every sentence contributes operational context and there is no wasteful 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 six-parameter tool with no output schema and no annotations, the description is complete enough to call correctly: it covers the default report mode, create/delete behavior, wait semantics, default media scope, playback implications, status values, and the ffmpeg requirement. No major agent decision is left without guidance.

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, but the description adds meaningful semantics beyond the schema for create, delete, wait, height, and mediaIds. It explains defaults such as mediaIds covering every video in the project and height never exceeding the source, though timeout is left primarily 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 states a specific verb and resource: it proxies heavy video footage with light H.264 copies for smooth editing playback, while also reporting, creating, or deleting proxies. It clearly distinguishes proxy behavior from export, frame extraction, and scopes by explaining that those always read the original.

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 identifies the use case: heavy footage such as 4K, HEVC, ProRes, and long phone clips that need smooth playback and scrubbing. It also clarifies when create/delete are omitted versus set, and warns that export, fablecut_frame, fablecut_scopes, and every measurement read the original, which effectively routes the agent away from using proxies for final results.

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 discloses the rendering path (same compositor as export; open editor tab else headless Chrome/Edge), that measurement is over the export frame when set, the non-mutating nature (playhead does not move), and a sensible default timeout. It omits failure modes and any statement of required permissions, keeping it short of 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?

Purpose is front-loaded, but the middle sentence is a dense enumeration of every returned metric, and the numeric examples with tilde thresholds add length. Because there is no output schema, spelling out the returns earns its place, so the density is justified rather than wasteful.

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?

Complex, nested-object tool with no output schema, yet the description fully enumerates the return values and semantics (levels, clipped/crushed percentages, cast hue/strength with a neutral cutoff), the rendering fallback, and the default frame/time behavior. An agent has everything it needs to call it and interpret results.

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

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

Schema description coverage is 100%, so the schema already documents all five parameters including the nested mask/matte objects and the where enum. The description adds only indirect semantics ('over the export frame when one is set', playhead default for time), so the 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 specific verb and resource ('Measure the graded picture at one moment') plus exactly what the tool returns (numeric luma levels, clip/clip percentages, RGB means, saturation, colour cast, on-screen clips with grades/mattes/blends). Calling out that it returns numbers and is rendered by the same compositor as export implicitly separates it from image-producing siblings like fablecut_frame and fablecut_export.

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?

Gives concrete when-to-use guidance with actionable thresholds ('cast strength above ~0.03 on footage that should be neutral', 'whitePct above ~1', 'median far from ~0.4'). It clarifies that the playhead is not moved, but never names an alternative sibling or states when not to use it, so the guidance is strong but not fully routing.

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 auto-bumped revision, instant hot-reload, conflict error and retry pattern, and force overwrite behavior. No annotations to contradict.

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, front-loaded sentences covering all crucial aspects without 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?

Explains behavior well but lacks description of return value. Given set operation, 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%, description adds value by clarifying the 'project' must be complete and the read-modify-write cycle, and explains 'force' usage.

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 it replaces the project JSON with the complete document, distinguishing from patch tools. Verb 'replace' with resource 'project' is 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?

Explicitly instructs to read, modify, send whole. Provides conflict-safety retry guidance. Could mention that partial updates should use fablecut_patch_project.

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 discloses key behavior: auto-starting the web server. Does not detail error handling or idempotency, but for a status tool, this is adequate transparency.

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 sentence that concisely conveys purpose, behavior, and usage recommendation. 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 zero-parameter tool with no output schema, the description covers core functionality and usage. Could mention response details more explicitly, but overall 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?

No parameters in schema, so baseline 4 applies. Description adds no parameter info, but none is 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 clearly identifies the tool as ensuring the editor web server is running (auto-start) and retrieving the editor URL, project summary, and media library. It distinguishes from siblings by stating 'Call this first in a session.'

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 states 'Call this first in a session,' providing clear usage guidance as a prerequisite. Lacks details on when not to use or alternatives, but the instruction is sufficient for an agent.

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 discloses the execution environment (open tab vs headless Chrome/Edge), that results are persisted to props.tracks, that an existing name is extended/replaced over the tracked range, and that match quality (>=0.8) and lost-region locations are reported. It stops short of stating permission or locked-clip semantics beyond the force flag.

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 front-loaded with the core action and the optional apply step, and given a 14-parameter tool most clauses earn their place. The prose is a dense single paragraph with stacked parentheticals, which makes it heavier to parse than ideal, but there is little outright padding.

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, no-output-schema tool the description covers the essentials an agent needs: what is produced (a named track), the two application modes in the same call, target-selection heuristics, execution venue, and how to verify the result. Nothing required to invoke it correctly 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%, so the baseline is 3, but the description adds real meaning beyond the schema by explaining the interplay between region, point (+size), and apply (region-less implies following the mask) and by describing how the name default is derived. That relational context is not recoverable from the field descriptions alone.

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 states a specific verb (follow/motion track) and resource (something in a video clip, frame by frame), and it names its own output artifact (a named track stored on the clip). It also routes the agent to fablecut_scopes for verification, so it is distinguishable from siblings despite there being no direct tracker 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?

It states when and how to use it: pick a detailed target (corner, logo, text, eye) rather than a flat area, and use apply:{mask} with no region to inherit the mask's coverage. It does not name a competing tool to prefer or give explicit exclusions, but the practical selection 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, the description carries the full burden and does so: it declares the tool is never destructive, that restore first snapshots current state so it can be undone, and that versions are auto-created every 10 minutes plus before an agent's first edit or a set_project rewrite. These are non-obvious side effects an agent could not infer elsewhere.

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 and the safety claim, then structured as an action list with inline guidance. It is dense and long for one paragraph, but nearly every clause carries actionable information; a bulleted layout would scan better.

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 7-parameter, 6-action mutation tool with no annotations and no output schema — the description covers action semantics, side effects, defaults, consumers of version ids (fablecut_projects), and the human-visible consequence of restore. Nothing essential is missing 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 coverage is 100%, so the baseline is 3, but the description adds real meaning beyond it: which parameters belong to which action (save/diff/restore/update signatures), that project defaults to the open one, and that version accepts a number. The 'to' semantics for diff are useful too. It stops short of covering edge cases like 'final' uniqueness enforcement, which the schema mentions.

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 clause names the resource precisely (a project's version history, saved copies) and the description then enumerates all six actions with their payloads (list/save/diff/restore/update/delete). An agent can distinguish this from siblings like fablecut_projects or fablecut_set_project without opening a 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?

Explicit triggers are given per action: save 'before big or risky edits, and when the user is happy with a cut', restore 'only when they asked', diff to see what changed. It also states the default (list) and warns that restoring changes what the user sees, which functions as a when-not rule.

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