Frapea

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

Annotations already flag destructive=true and non-idempotent, and the description adds the crucial mechanism behind that: clips overwrite by default unless trackId targets another track, tracks auto-pair for video audio (V2 ⇒ A2), and the return value is the created clip ids in order. It also discloses the fps unit for frame values, which is real behavioral context an agent needs before committing a destructive edit.

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?

Information-dense but delivered as one long run-on sentence with deeply nested parentheses, so the mediaRef variants are hard to scan. It is front-loaded with the action and nearly every clause earns its place, but a bulleted enumeration of mediaRef kinds would make it far more usable.

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?

Covers the essentials for a destructive placement tool: source addressing, positioning, track targeting, default overwrite behavior, linked audio, and return format (no output schema needed). The remaining gap is relational — no guidance on insert_clips, move_clips, or trim_clips boundaries, and no mention of error conditions such as invalid mediaRef or missing track.

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

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

Although schema coverage is 100%, the schema barely documents the clips array elements; the description supplies the full mediaRef grammar (timeline:, solid:, motion:, adjustment:, text:), explains atFrame as a timeline position, sourceInSec/sourceOutSec as the source segment with alignment hints to transcript words/sceneSamples, and trackId's targeting behavior. That is substantial 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?

A specific verb and resource ("Places media segments on a timeline") immediately tells the agent what happens, and the mediaRef grammar makes the scope concrete. It never distinguishes itself from the close sibling insert_clips, so an agent cannot tell from this text alone which of the two placement tools to pick.

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?

Strong operational context: default V1/A1 placement with overwrite semantics, when to supply trackId to target a same-kind track, and the note that a spare empty track (V2/A2) exists above the highest used one. Missing the key exclusion — nothing says when to use insert_clips instead of this overwriting placement tool.

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

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

Annotations already declare readOnly=false, idempotent=true, destructive=false, but the description adds substantive behavior beyond them: the copy lands in the project's media pool at the Library root, no API key or external fetch is involved, and re-adding an existing sample returns its existing mediaRef rather than duplicating — which concretely explains the idempotentHint.

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?

One paragraph, front-loaded with what the samples are and immediately followed by the two call modes. The parenthetical listing the clip types earns its place by telling the agent which sample suits which downstream task (transcripts, captions, b-roll).

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 describing the return shape (a mediaRef per added item, existing ref on duplicates) and the destination of the copy. With four parameters, two required, and full schema coverage, nothing an agent needs in order to call 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 baseline is 3, but the description adds operative semantics the schema only hints at: the no-ids call is a list operation (not an error), all:true is an alternative to enumerating ids, and the per-result mediaRef is the handoff value for add_clips.

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 (add/copy sample media into the project's media pool) and enumerates the asset types (talk clip, b-roll, photo, music bed). It also distinguishes the two modes — listing versus copying — and points to the sibling add_clips as the consumer of the returned mediaRef, so an agent can separate this tool from download_stock_media or search_media 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?

It states the situation clearly ('for trying the editor without your own footage') and gives exact call conditions: omit ids to list, pass ids or all:true to copy. What's missing is an explicit when-not or a named alternative tool — 'no download from elsewhere' only implicitly contrasts with download_stock_media/download_sound.

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

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

The description adds substantial context beyond annotations: the pack is synthesized, licence-free, requires no API key, and has no download wait. It also discloses that copied files are named `sfx-<id>.wav` at the Library root, each result returns a `mediaRef`, and adding an existing sound is an idempotent no-op returning the existing reference, consistent with `idempotentHint: true`.

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, starting with the built-in pack and its differentiator before moving to catalogue and copy behavior. Every sentence contributes operational 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?

There is no output schema, but the description adequately explains both return modes: catalogue entries with sound descriptions and usage guidance, or copied media results with `mediaRef` values. Annotations cover safety and idempotency, and the description fills in the remaining behavioral details.

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 already documents all four parameters. The description still adds useful semantic context by explaining that omitting `ids` lists the catalogue while supplying `ids` copies sounds into the media pool and returns `mediaRef` values, though it does not separately elaborate on the `id`, `token`, or `projectId` parameters.

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

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

The description states a specific verb and resource: adding sounds from Frapea's built-in sound-effects pack into the project media pool. It explicitly distinguishes this from search_sounds, which is reserved for ambience, foley, and real-world object sounds not covered by the pack.

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 when-to-use guidance: call with no `ids` to retrieve the catalogue, and call with `ids` to copy sounds into the media pool. It also names the alternative tool (`search_sounds`) and the conditions that select it, plus the downstream workflow with `add_clips`.

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

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

The description adds substantial behavioral context beyond the annotations: it writes ordinary transform and crop values, replaces the clips' geometry animation, and arranges clips in cell order. It also warns that non-overlapping clips produce no visible layout, which is important for correct use.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with the core action, then efficiently covers layout choices, mode and bias semantics, replacement behavior, and the overlap prerequisite. The enumeration is long but necessary, and no sentence appears 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 destructive mutation tool with seven parameters, nested bias, and no output schema, the description provides enough context to invoke it correctly: what it writes, what it replaces, how layout and mode work, and when the operation is visible. Missing return-value details are minor here because there is no output schema and the schema documents the token and ids.

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

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

Although schema coverage is already 100%, the description adds meaning the schema does not carry directly: it enumerates all layout ids, explains that the first clipId maps to the first cell, and clarifies fit versus cover plus bias behavior. This is valuable parameter-level guidance beyond the schema text.

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: arranging clips into a screen layout by writing transform and crop values. It is clear what the tool does, but it does not explicitly distinguish itself from siblings such as set_clip_properties or manage_effects.

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 applicability condition: the clips should overlap in time on different tracks, otherwise the layout has no visible effect. It does not name alternative tools or state when not to use this one, so it falls short of full when/when-not/alternatives guidance.

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

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

Adds substantial context beyond the annotations: a per-call timeout (~45 s), polling/retry semantics for 'pending', the full return shape with the meaning of each status, and the fact that the blocking interaction happens in the Frapea tab rather than being performed by this tool. Consistent with readOnlyHint/idempotentHint since waiting itself mutates nothing.

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 timing constraint, then the mechanism, then the return contract in a single tight paragraph. Every clause carries information; nothing is redundant with the schema or annotations.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description takes on the return-value burden and does so fully: status union, meaning of 'pending' and 'denied', and the required follow-up action. For a two-parameter waiting tool with annotations covering safety, nothing an agent needs 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 actionId and token are already documented in the schema with the same provenance detail (token from connect, actionId from a previous tool). The description reinforces where actionId comes from via the dialog example but adds no new syntax, format, or constraint information. 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 (waits for the user to resolve a pending Frapea prompt) and scopes it to dialogs another tool opened, which no sibling in the list does. An agent can immediately distinguish this from polling tools like get_job_status or get_analysis_status.

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?

Clear trigger condition: call this after a tool returned an actionId for an opened dialog, and call again while status is 'pending'. It also implies the retry protocol (~45 s per call). No explicit 'do not call when…' exclusion or named alternative, which keeps it just below top marks.

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

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

Annotations already flag destructive=true and idempotent=true, so the safety profile is partly covered; the description adds genuinely new behavior — motion is inherited relative to first-seen position while existing framing is preserved — and explains the unbinding mode. It does not say what the binding overwrites on the clip or how it interacts with existing keyframes.

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 core action, then the mechanism, then the knobs, then the undo path — each sentence carries distinct 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 9-parameter mutation tool with a nested channels object, the description covers what the tool does, how motion is applied, and how to reverse it, while the fully populated schema handles parameter detail. The only real gap is not stating the dependency on a prior face-tracking run.

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 every parameter including gap, channels, smooth and maxGlideSeconds is already documented in the schema. The description reinforces channels/gap/trackId-null but adds no semantics beyond what those descriptions state. 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?

Specific verb and resource: "Makes a clip FOLLOW a tracked face", plus concrete use cases (mask, label, blur). It is clearly distinct from the face-related siblings (track_faces, merge_faces, list_face_tracks) by what it produces, though it never names track_faces as the source of trackId, so the sibling relationship is implied rather than stated.

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 real usage context (attaching masks/labels/blurs to a head) and explains the two key optional knobs, channels and gap, in terms of when you'd choose them. It also documents the unbind path via trackId: null. It stops short of stating prerequisites, e.g. that a face track must exist first via track_faces.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the description's value is the specifics: the tab reloads, the headless runtime for that session is freed, and any in-flight export or render is interrupted. That is exactly the kind of consequence an agent needs before calling a destructive tool; only failure behavior (e.g. what happens if the project is not open) is left out.

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 tight sentences: the primary action and scope first, then the side-effect caveat. No filler, no restatement of the title.

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 two-parameter, no-output-schema tool with annotations covering safety, the description supplies the missing piece — what the destructive side effect actually is. Everything an agent needs to invoke it correctly is present, short of error conditions.

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 both token and projectId are already documented in the schema. The description adds only an indirect hint about the token's session scoping ('this session's headless runtime'), which is baseline-level added value.

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 (close/release) and resource (the project session and its headless runtime), and names the concrete effect of returning the tab to the project manager. It is distinguishable from open_project/new_project by the release-of-runtime framing, though the description never names the sibling it complements.

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 'releases this session's runtime' phrasing implies an end-of-session action, and the warning that a running export or render stops is a useful caution. But it never explicitly says when to call it versus leaving a project open, nor does it point to open_project for the reverse action.

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

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

Annotations already cover safety (destructiveHint=false, idempotentHint=true), so the extra value here is the description's disclosure that the item persists in the media pool and remains editable/verifiable/nestable/exportable, plus the active-tab fallback. It omits what happens on an invalid or already-closed timelineId, but the idempotency hint partially covers that.

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 front-loaded sentence with the key distinction (tab vs. delete) placed first and the secondary behavior (next tab shown) last. Zero 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 simple 3-parameter mutation with no output schema, the description covers purpose, side effects, and persistence. Minor gaps: error behavior for unknown timelineId and whether the caller needs to re-set an active timeline afterward.

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 all three parameters are already documented in the schema. The description adds nothing parameter-specific, which matches the baseline 3 when the schema does the heavy lifting.

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

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

States a specific verb and resource (closes a timeline's tab) and immediately scopes it against the likely confusion with deletion and with close_project/open_timeline. The agent knows exactly what operation this is without inspecting 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?

The description makes the usage boundary clear against deletion ("does NOT delete it: it stays in the media pool") and describes the fallback when the closed tab was active. It does not explicitly route to a sibling such as open_timeline or close_project, but the intended context is unambiguous.

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?

Adds substantial context beyond the annotations: single-use codes, a ten-minute expiry, token lifetime until the user disconnects, and the fact that the user must accept in the browser before a token appears. The non-readonly, non-idempotent annotations are consistent with a session-establishing tool, so no contradiction. It stops short of saying what happens if a code is reused or expires mid-flow.

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 outcome and the two numbered branches, and the expiry/token-lifetime note is placed last where it belongs. It is slightly dense with nested parentheticals ('(the Connect MCP button)', '(they have to accept it in their browser first)') that could be flattened, 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?

No output schema exists, and the description compensates fully by describing both possible return values (a link on the first call, a token after acceptance). It also tells the agent how to sequence calls and what to send the user, which is everything needed to invoke it 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%, so the baseline is 3, but the description adds useful operational semantics: the code is 8 characters, can come from the user's screen or from the returned link, and omitting it produces a link. That connects the parameter to the two-step flow in a way the schema alone does not.

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 action and target: 'Pairs you with the user's Frapea browser tab', and names the concrete outcome ('a session token to pass on every later call'). This is clearly distinct from other connect-prefixed siblings like connect_media_folder, which deal with media rather than a browser 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?

Gives an explicit two-branch decision procedure: use case (1) when Frapea is already open, case (2) when it is not or 'you are not sure'. Names the alternative path, tells the agent to poll every few seconds, and states the exit condition (a token is returned).

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

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

Goes well beyond the annotations: it discloses that a browser security gesture requires a human, that a dialog opens with the 'reason' shown word for word, that the call returns an actionId which must be handed to await_user_action, and that 'granted' is what makes get_media list the files. That is the full interaction contract for a non-idempotent, non-destructive side-effecting tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the action and its human-only constraint, then the follow-up call, the trigger condition, the exclusion, and the no-dialog alternative — each sentence adds a distinct operational fact 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?

Even without an output schema, the description explains the return path (actionId → await_user_action → 'granted' → get_media) and the timing of the auto-scan fallback, so an agent knows exactly what to do after calling.

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

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

Schema coverage is 100%, so the baseline is 3; the description still adds real meaning by stressing that reason is displayed verbatim to the user and should name both the footage and the intended use, and by tying token to the browser-driving session. It stops short of explaining projectId beyond what the schema already says.

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 precise verb+resource ('Asks the user to attach a folder of THEIR OWN source footage') and immediately distinguishes it from siblings by scoping it to human-only, own-footage cases versus add_clips/download_stock_media/get_media. An agent can select it correctly 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 an explicit trigger ('Use when get_media comes back empty and the user has footage somewhere on their disk'), an explicit exclusion ('NEVER call it for files YOU made or fetched'), and names the alternative mechanism (drop files into the project's media/ folder and they join the pool automatically).

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?

Adds substantial behavior beyond annotations: the composition is compiled and test-rendered before saving, failures return the error verbatim, the call returns a mediaRef for use with add_clips, and preview mode does not load media (slots render empty and the count is reported). These are exactly the non-obvious traits an agent needs 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, starting with the core definition and then the authoring constraints. There is mild redundancy — the 'motion' skill is pointed to twice (once for API surface, once for creative guidance) — but nearly every sentence carries actionable information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 13-parameter tool with nested objects and no output schema, the description covers the return value (mediaRef), the compile/test-render lifecycle, preview semantics, and the partsBoard pattern. An agent has enough to call it correctly without further exploration.

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: files maps names to TSX source with working relative imports, entry must `export default`, and schema keys (type string|number|color|boolean|select|mediaRef + default) become tweakable Inspector controls. It pushes the agent toward parameterizing colors, copy and media slots rather than hardcoding.

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 (creates) and resource (motion composition), then defines it concretely as an animated graphic authored as a React TSX component with examples (infographic, title, end-card, chart). This clearly distinguishes it from get_motion_composition and update_motion_composition in the sibling 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?

Gives explicit workflow guidance: read the 'motion' skill before writing, use preview:true with previewProps:{partsBoard:true} when the composition has UI-like parts, and retry after fixing compile errors. It lacks an explicit statement on when to use update_motion_composition versus creating a new one, which is the main missing routing cue.

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

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

Beyond annotations (which only say non-readOnly, non-destructive, non-idempotent, closed-world), the description discloses the side effect of the initial track structure and the auto-expanding spare tracks, which an agent would otherwise not anticipate before adding clips.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three short sentences, front-loaded with the action and return value, then the format guidance, then the post-creation state. No filler and nothing repeated from structured fields.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a no-output-schema mutation tool, it covers the return value (id), the initial state, and the parameters. The one gap is whether the newly created timeline becomes the active/open one — relevant given the set_active_timeline and open_timeline siblings.

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

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

Schema description coverage is 100%, so the baseline applies; every parameter including token and projectId is already documented in the schema. The description's '1080×1920 @30' example adds a little intuition about how width/height/fps combine, but no constraints or defaults beyond what the schema already states.

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 ('Creates a new timeline in the project') plus the return value (its id), which is more than the title alone. It does not distinguish itself from sibling creation tools such as duplicate_timeline or create_motion_composition, 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?

The format hint ('Set fps, width and height for the target format... vertical short') implies the creation scenario, but there is no explicit when-to-use/when-not guidance and no named alternative such as duplicate_timeline for copying an existing timeline.

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

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

Beyond the annotations it discloses the key consequence: other angles' clips are DISABLED, not deleted, making every switch re-decidable — a non-obvious reversibility guarantee that a destructiveHint=false flag alone does not convey. It also states the refusal condition ('chosen track has no clip at the frame') and the linked-audio side effect, which annotations cannot express.

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 ('MULTICAM angle switch') and every sentence carries information. The heavy em-dash/parenthetical style makes it dense and slightly run-on, but nothing is 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 7-parameter mutation with no output schema, the definition covers preconditions, reversibility, audio coupling, defaults, and one failure mode — enough to call it correctly and anticipate effects. It stops short of describing what the call returns (e.g. new cut points) or other error conditions.

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 already 100%, yet the description still adds meaning: `angleTrackIds` defaults to every video track with a clip under the frame, and the cut extends 'to the next cut'. These defaults and scoping rules go beyond the terse schema strings, though `token`, `projectId`, and `timelineId` are left entirely 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?

States a specific verb and resource — 'razors the whole angle stack at `atFrame` and keeps only `chosenTrackId` live' — which is unmistakably distinct from generic siblings like split_clips or manage_tracks. The multicam framing in the opening sentence lets an agent route correctly 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 clear preconditions ('sync them beforehand — clips of the same take on V1..Vn') and a decision rule for `audioFollowsVideo: false` ('the usual choice when one good mic carries the sound'). It also explains the iterative workflow ('cut again with a different angle to change your mind'), though it never names an adjacent sibling such as split_clips or manage_tracks as an alternative.

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

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

Beyond annotations, the description discloses important runtime behavior: the tool is asynchronous, returns state values, produces a mediaRef when done, and uses a shared three-file download queue with stock video. It also clarifies that repeated polling is expected, consistent with the idempotent annotation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is dense but front-loaded: purpose, output location, async polling behavior, and queue semantics appear in that order. Every sentence earns its place by covering a distinct operational concern.

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 asynchronous download tool with no output schema, the description covers the full operational picture: what is downloaded, where it lands, how polling works, what the terminal state looks like, and why a 'queued' state is not an error.

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 already documents all three parameters. The description adds some context, such as the output filename using the sound id, but it does not add meaningful syntax or format guidance 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 states a specific verb and resource: downloads one Freesound sound into the project media pool. It adds concrete identity details (HQ MP3 preview, virtual file at Library root, `freesound-<id>.mp3`) that clearly distinguish it from search, import, and stock-media siblings.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives clear usage flow: first call accepts the download, subsequent calls with the same arguments poll until state becomes 'done'. It also names the natural next step (`add_clips`) and explains that 'queued' is normal, though it does not explicitly say when to prefer this over stock-media alternatives.

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

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

Annotations only declare the safety profile (idempotent, openWorld, non-destructive). The description adds critical context beyond that: the two-phase async state machine, that 'queued' is a normal state requiring no action, the concurrent-download limit, and how maxHeight selects a rendition.

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 and async semantics are front-loaded, and each sentence carries actionable content. The final paragraph on verifying scenes via get_media/inspect_media is useful but slightly tangential to downloading itself, adding mild 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?

With no output schema, the description must convey the return shape, and it does — state transitions culminating in 'done' with a mediaRef. Combined with the polling and queue semantics, an agent can invoke and poll this tool correctly without further information.

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

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

Schema coverage is 100%, so the baseline is 3. The description still earns a bump by documenting the maxHeight default behavior ('the best available rendition'), which the schema annotation ('cap the rendition height') does not specify.

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 (Downloads) and resource (one Pexels asset into the project's media pool), including the exact virtual file naming convention `pexels-<id>.jpg|.mp4` at the Library root. This is clearly distinct from the sibling search_stock_media.

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 explains the asynchronous workflow — first call accepts, subsequent calls poll with the same arguments — and names the downstream consumer (add_clips). It also prescribes batching behavior with a rationale (three files stream at a time) and tells the agent to verify content before cutting.

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?

Richly discloses behavior beyond the annotations: new ids for timeline/tracks/clips/transitions, clip links preserved inside the copy, nested timelines copied by default, motion compositions and media merely referenced, original untouched and still active, and one undo removes the copy. This is fully consistent with destructiveHint=false and readOnlyHint=false.

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 purpose, then layers the copy semantics economically. It is on the longer side with several clauses, but nearly every sentence carries information an agent needs to call it correctly.

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, but the description states the return shape ({timelineId, name, clips, nestedCopies?}) and covers the copy semantics, defaults, and undo behavior. Nothing an agent needs to invoke it safely 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 for includeNested — explaining that copying nests means editing a nest in the original does not alter the backup — which goes beyond the schema's terse phrasing.

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 ('Copy a timeline under a new name') and immediately clarifies it is a DEEP copy versus a plain new timeline, distinguishing it from create_timeline without the agent needing to open schemas.

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 scenarios — a backup before a review round, or a variant to experiment on — so the agent knows the intent. It does not explicitly name create_timeline or open_timeline as alternatives or state when NOT to use it, keeping it below a 5.

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

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

Annotations only cover the safety profile (not read-only, not destructive, not idempotent). The description goes well beyond: it discloses that one undo reverts the operation, that the created clips share a captionGroupId and can be restyled as a group, that the tool returns created clip ids, and — most valuably — the non-obvious track-placement behavior (joins existing caption tracks when they fit, opens a new one on overlap, joins the LOWEST caption track so later b-roll can occlude them). These are exactly the behavioral traits annotations cannot express.

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 purpose in the first sentence, then layered with placement and rendering details. Every sentence carries real information, but the paragraph is dense and long for a single tool, with track-placement lore that could be tighter. Efficiency is good, hygiene could be 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?

No output schema exists, and the description compensates by stating the return value ('Returns the created clip ids'). Preconditions, side effects, follow-up tooling, and the subtle rendering-behind-b-roll hazard are all covered, leaving nothing an agent needs to know before invoking it.

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 all nine parameters (preset, position, textCase, censorProfanity, maxWordsPerCaption, etc.) are already documented in the schema. The description adds no parameter-level meaning beyond what the schema provides — it never mentions the styling options or word-grouping controls. Baseline 3 is appropriate when the schema does all the parameter work.

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 ('Generates animated captions from a spoken clip's transcript') and immediately scopes the input ('a spoken clip'). It distinguishes itself from siblings by naming the preconditions (get_transcript) and the related follow-up tools (set_clip_properties, manage_tracks), so an agent knows exactly what this tool produces versus what neighboring tools do.

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 the prerequisite ('Needs a transcript (get_transcript tells you)'), names the alternatives for follow-up work (restyle via set_clip_properties with text.wholeCaptionGroup; tidy via manage_tracks {action:'tidy'}; merge via manage_tracks {action:'merge'}), and even explains when NOT to tidy up after captioning. This is a genuinely strong routing guide.

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?

Far exceeds what the annotations cover (annotations only say non-readonly, open-world, non-idempotent, non-destructive). The description discloses async job semantics with persisted-on-disk state that survives tab closes, the return shape {jobId, fileName} with format decided up front, that ElevenLabs SPENDS the user's credits, and the full structured-refusal catalogue (NO_API_KEY, INSUFFICIENT_CREDITS, CONSENT_REQUIRED with the await_user_action retry loop, PERMISSION_REQUIRED), plus the audio-tag stripping safety net.

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?

Well front-loaded: purpose and outputs first, then the workflow rationale, then the premium/error handling. It is long, and the audio-tag rule appears in both the body and the modelId schema text, which is mild redundancy — but for an 11-param tool with a consent flow, nearly every sentence carries operational weight.

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 11 parameters, a nested object, no output schema and a premium path, the description covers everything an agent needs: async return values, how to poll (get_job_status), the mediaRef on completion, the consent handshake, provider prerequisites, and the segmentation advice that prevents a bad edit. 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 description coverage is 100%, including the nested voiceSettings object, so the schema already carries the heavy lifting — baseline 3 applies. The description does reinforce a few behaviors (audio tags only valid when the model reports supportsAudioTags, consentActionId is good for one job, language ignored for ElevenLabs), but these are mostly repeated from the schema rather than adding new syntactic detail.

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

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

States a specific verb and resource ('Generates an AI voiceover from a script') and immediately distinguishes the two provider paths (on-device free models vs. cloud ElevenLabs). It also spells out the concrete side effects — WAV in the media library, script stored as metadata, word-level transcript written — so an agent knows exactly what this produces versus siblings like add_sfx or start_transcription.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly says when to do this (before picture is cut, because a script doesn't reveal its spoken duration) and names concrete downstream steps (get_transcript for word timings, read_skill {topic:'voiceover'}, list_voiceover_models for voices). It also gives exclusions and preconditions: check the elevenlabs status object first, a local model must be downloaded and at phase 'ready', and v2 only when the user asks.

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

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

Beyond the read-only/idempotent annotations it discloses non-obvious semantics that would otherwise mislead: percent 100 means 'nothing outstanding, not everything succeeded', etaSeconds is null until something finishes, and analysis runs automatically when media is connected. This is exactly the kind of surprise-prevention 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-loads the purpose in the first clause and each subsequent clause carries distinct information (percent caveat, failed list, field inventory, polling loop). Dense but somewhat cramped with parentheticals and capitalization emphasis; still no wasted sentences.

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 carries the return-value burden and does so thoroughly — percent semantics, failed items, done/total/pending counts, runningItem shape, etaSeconds, blockedOnModels, models. An agent has everything needed to poll and interpret results correctly.

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

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

Schema description coverage is 100% and both parameters (token, projectId) are documented in-schema, so the description adds nothing about parameters. 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 exactly what it reports: 'How far the project's media analysis has got', with the key clarification that analysis is automatic rather than triggered by this call. It does not explicitly distinguish itself from the sibling get_job_status, but the media-analysis framing is specific enough to identify the 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?

'Poll this while you wait' gives the usage pattern directly, and it routes to two alternatives by condition: request_ai_models when blockedOnModels > 0, retry_analysis for a failed item. Missing only a contrast with get_job_status, the other status-polling 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?

Goes well beyond the annotations (readOnlyHint=false, idempotentHint=true, destructiveHint=false) by disclosing the side effect that a UI panel opens, why the report is withheld from the agent, and what sanitization occurs (names and texts replaced, user files reduced to encoding fingerprints). It also enumerates exactly what summary the caller receives, which is the key behavior for planning.

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 key fact (report opens in the app, not returned), then the summary contents, then scoping. It is dense but each clause carries information; the long enumeration of report contents is the only mildly over-extended part.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description responsibly describes the returned summary and the privacy model. The one remaining gap is interaction flow: it does not say whether the call blocks while the user reads/saves, or whether a sibling like await_user_action is expected afterwards.

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 explains token, projectId, and timelineIds including the nesting behavior. The description's closing sentence on timelineIds largely restates the schema rather than adding new semantics, so 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 ('Prepare a BUG REPORT') and immediately clarifies the unusual mechanic that the report itself is opened in the Frapea UI rather than returned to the agent. This distinguishes it well from get_problems, which is never named, so sibling routing still requires inference.

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: an agent can infer to call it when a user wants to file a bug, and the note that output goes into the app hints at the user-facing context. There is no explicit when-to-use/when-not, no mention of get_problems as the alternative for inspecting problems, and no statement of prerequisites beyond the schema.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description adds substantive context beyond them: the state machine values, the progress field range, that result fields vary by job type, and that 'queued' reflects waiting on the analysis master tab which loads models once per browser. That is real operational insight an agent would not get from the annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the return shape, then usage, then the alternative. Dense but nearly every clause carries information; the brace-and-semicolon notation and the parenthetical on the analysis master tab are slightly compressed, but nothing is redundant.

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, yet the description covers the response shape, state values, progress, and job-type-specific result fields, plus polling guidance and the sibling routing rule. An agent has everything needed to call and interpret it 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 documents both jobId (returned by start_* tools) and token (from connect), so the baseline would be 3. The description adds routing value by clarifying which tools actually produce jobIds valid here and which route to get_analysis_status 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?

States a specific verb and resource ('Status of a background job') and immediately scopes it to jobs produced by named job-returning tools (generate_voiceover, verify_timeline, measure_loudness). An agent can distinguish it from get_analysis_status 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?

Gives explicit polling cadence ('poll every few seconds while state is queued or running'), explains what 'queued' means, and names the alternative tool (get_analysis_status) with the exact condition that selects it (analysis started by start_transcription or start_visual_indexing).

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

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

Goes well past the readOnly/idempotent annotations: analysis starts automatically and retries a failure a few times before sealing, onset data is truncated to the first 2000 entries with truncated + onsetCount signaling more, and the caller must map onsetsSec through clip trim/speed themselves. It also warns that bpm can be null and that speech has onsets but no bpm — non-obvious behaviors an agent would otherwise get wrong.

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 purpose then field-by-field meaning, and nearly every sentence carries information (phase enum semantics, onset-detector caveats, truncation). It is dense and long for a list tool, and the beats/onsets explanation could be tightened, but there is little outright 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?

With no output schema, the description fully carries the return-value burden: it documents every field, both index phase objects, the beats object and its enum values, and the truncation contract. Nothing material is missing for an agent to call it correctly and interpret the result.

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: mediaRef switches to single-asset mode and (only then) returns beats.onsetsSec in source seconds, truncated at 2000. That is a behavioral consequence the schema's one-line mediaRef 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?

Opens with a specific verb+resource ('Lists the project's media library') and enumerates the exact fields returned (mediaRef, name, kind, durationSeconds, resolution, sceneSamples). It also distinguishes its two modes (full list vs. single asset via mediaRef). It never names the adjacent siblings it competes with (inspect_media, search_media, get_analysis_status, get_transcript), 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?

Guidance is present but aimed at follow-up routing, not tool selection: it tells the agent to call retry_analysis on a 'failed' phase and request_ai_models on 'disabled', and to inspect/cut at sceneSamples first. There is no explicit statement of when to use get_media versus inspect_media, search_media, or get_transcript, so the choice is implied by 'lists' rather than stated.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds that both a manifest and full TSX sources are returned, which is useful beyond annotations, but it does not mention response size, pagination, or 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?

The description is a single, front-loaded sentence with no wasted words. It states the return payload directly and efficiently.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description carries some burden to explain return values; it says the result includes a manifest and full TSX sources but does not describe their structure or format. Given the fully documented parameters and rich annotations, this is adequate 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?

Schema description coverage is 100%, so all three parameters are already documented in the input schema. The description does not add any parameter-specific meaning beyond what the schema provides, which makes the baseline of 3 appropriate.

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

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

The description uses a specific verb and resource ("Returns a motion composition's manifest and full TSX sources"), making the operation clear. However, it does not explicitly distinguish this tool from sibling list_motion_compositions or explain that it retrieves a single composition rather than listing them.

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 guidance on when to use this tool versus alternatives such as list_motion_compositions or create_motion_composition. No prerequisites or exclusions are mentioned.

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

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

Annotations (readOnly, idempotent, non-destructive) are consistent and the description goes well beyond them: it discloses that problem lists are attached to every other tool result, defines the semantics of an open problem ('that timeline does NOT play or export correctly there, whatever inspect_timeline showed'), and unpacks all four `state` values including the non-obvious caveat that `superseded` is NOT proof of correctness.

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 purpose and failure taxonomy before the secondary behaviors; nearly every sentence carries distinct information. It is dense and slightly run-on (the parenthetical 'WHERE' clause is heavy), but there is no filler to cut.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description carries the burden and does: it specifies what each record contains (location in timeline/source/frames, the engine's reason in its own words, and `state`). The only omission is pagination/volume behavior, which is minor for a read-only diagnostic list.

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 token, detail, projectId, and includeResolved are already documented; that sets the baseline at 3. The description adds only an implicit mapping ('call this for the whole history' → includeResolved) and no guidance on when to turn on `detail` or how projectId scoping interacts with the free `problems` list.

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?

Starts with a specific framing ('What has gone WRONG in the user's editor') and enumerates the concrete failure classes it reports (failed renders, undecodable footage, unpreparable chunks, failed exports). It explicitly contrasts with inspect_timeline, so an agent can tell it apart from the diagnostic siblings (verify_timeline, get_bug_report) without opening schemas.

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 explicit triggers: call it 'for the whole history, or after a `moreProblems` count.' It also states the alternative channel — the `problems` list already piggybacked on every other tool result — so the agent knows when this call is redundant. It further routes remediation to the named sibling (update_motion_composition).

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

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

Annotations already establish read-only, idempotent, non-destructive, closed-world, but the description adds substantial behavioral context beyond them: the PERMISSION_REQUIRED failure mode and required relay-then-retry handling, and the fact that provider keys are the user's own and cannot be set from this tool. It also discloses conditional return shapes (providersAdvice present only when a provider is unusable).

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 routing sentence is front-loaded and the providers block is clearly delineated, but the PERMISSION_REQUIRED behavior is stated twice (once in the first paragraph, again in the closing line), which is mild redundancy in an otherwise dense description.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description carries the full burden of describing returns, and it does: project fields, the conditional `folder`, the `providers` map with its four status values, and the conditional `providersAdvice` note. An agent knows what it will get back and how to handle the error path.

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?

Only one parameter and the schema already documents `token` at 100% coverage, including that it selects which browser to drive. The description adds no format, lifetime, or reuse guidance for the token, so the schema is doing all the work — baseline 3.

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 plus the exact fields returned (id, name, lastOpenedAt, folder), and explains what `folder` implies for media pooling. It also positions itself against the sibling tools by declaring itself the entry point that yields the projectId every other tool needs.

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 explicit ordering guidance — 'Call first to find the projectId every other tool needs' — and prescribes the recovery flow for PERMISSION_REQUIRED (relay the instruction to the user, then retry). It does not name sibling alternatives such as open_project or new_project or state when not to use it, so it stops short of a 5.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the bar is lower, yet the description adds real behavioral detail: endFrame is exclusive, frames are expressed in that timeline's fps, linkGroupId indicates linked A/V pairs, and `look` only appears when non-default so an untouched clip has no look key. These are non-obvious contract details an agent would otherwise get wrong.

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 purpose, then the copy-paste UUID workflow, then the return-shape details. It is dense but every sentence carries contract information. The clip-field enumeration is long but earns its place given the absence of an output schema.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

No output schema exists, and the description compensates by describing the returned structure field by field, including the conditional `look` object and frame units. Combined with annotations covering safety, an agent has everything needed to call and interpret the result 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%, so baseline is 3, but the description adds meaning the schema lacks: omitting timelineId returns all timelines rather than erroring, and the no-timelineId path is the recommended route when the user supplies a clip UUID. The token and projectId semantics are left to the schema, which documents them well.

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 — reads a project's timeline structure — and immediately enumerates what is returned (timelines with tracks and clips). An agent can distinguish this from mutation siblings like set_clip_properties or move_clips 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?

Gives a concrete when-to-use scenario: the user pastes a bare UUID copied from the right-click menu, so call with no timelineId to match clip.id instead of guessing a name. It also states that omitting timelineId returns every timeline. It stops short of naming nearby alternatives (inspect_timeline, verify_timeline) or when not to use this tool.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the description focuses on value-add: the NOT_FOUND behavior and the fact that absence of a transcript is expected rather than an error. It doesn't cover token expiry/session failure modes, but the failure-path disclosure is the most useful thing it could add here.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three tight sentences: what it returns, when it's unavailable, and how to use the result. Return shape is front-loaded and nothing is redundant.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a read-only, 3-param tool with full schema coverage and no output schema, the description supplies exactly what's missing: the return structure, the precondition, and the failure semantics. Nothing an agent needs in order to call it correctly is absent.

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

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

Schema coverage is 100%, with token, mediaRef, and projectId each documented in the schema including provenance (from connect/get_media/get_projects). The description adds no parameter-level detail beyond what the schema already provides, 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 (Returns) and resource (word-level speech transcript of one media asset) and even sketches the return shape ({text, startSec, endSec}). This clearly distinguishes it from write-side siblings like start_transcription and generate_captions without the agent needing to open 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?

Explicitly states the precondition (only assets the user has transcribed have one), interprets the failure signal (NOT_FOUND means ask the user to run Transcribe on the clip in Frapea), and gives a downstream use case (use timestamps to align cuts). That covers when to use it and what to do when it isn't applicable.

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

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

With annotations already declaring non-read-only, non-idempotent, and non-destructive behavior, the description adds important mechanics: existing content at/after atFrame shifts right and clips under the cut split. It does not discuss return values or error/auth handling, though the schema's token description covers session requirements.

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 tight sentences, front-loaded with the operation and its key side effect. Every clause adds useful information without 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 five-required-parameter mutation tool with full schema coverage, annotations, and no output schema, the description covers the critical insertion mechanics and non-overwrite intent. It omits return and error details, which are not essential for invocation but would improve completeness.

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

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

Schema coverage is 100%, so the baseline is 3; the description adds semantics for atFrame by specifying the shift threshold and for clips by pointing to the add_clips clip shape. Other parameters remain schema-documented only.

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 ('Ripple-inserts media segments') and immediately explains the defining ripple behavior ('everything at/after atFrame shifts right'). It also distinguishes the operation from add_clips via 'Same clip shape as add_clips' and 'without overwriting'.

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 use case: splice a shot INTO an existing sequence without overwriting. It references add_clips only for clip shape, not as an explicit alternative or exclusion, so the when-not condition is implied rather than fully stated.

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

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

Annotations already establish read-only, idempotent, non-destructive behavior, so the burden is lighter; the description still adds real value by explaining that pixels:false costs no image and by defining the fingerprint metrics (nonBlankRatio near 0 = black/empty, colorRange near 0 = featureless). It does not discuss batching limits or failure modes beyond the 12-timestamp cap, which is 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 with purpose and output shape, then guidance, then interpretation hints. Every sentence carries actionable information; the only slight redundancy is restating the 12-timestamp cap already in the schema.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

There is no output schema, and the description fully compensates by describing the return value (single grid image with labelled cells plus per-cell fingerprint) and how to read it. For a read-only inspection tool with 100% schema coverage, nothing an agent needs to call 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 goes beyond the schema by explaining how to interpret the fingerprint values produced under pixels:false and by pairing atSec with get_media's sceneSamples. It makes the cost/benefit tradeoff of the pixels flag concrete rather than just restating its type.

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 (inspect frames inside a source asset) and precisely describes the output: one contact-sheet grid plus a per-cell fingerprint. It also explicitly distinguishes itself from the sibling inspect_timeline ('Shows the RAW source; use inspect_timeline for the composed cut'), so an agent can route correctly 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?

Gives explicit conditional guidance: start with pixels:false when only checking for emptiness, request pixels when judging subject/framing/legibility. It names the alternative (inspect_timeline) and a complementary tool (get_media sceneSamples for a storyboard), covering when-to-use, when-not-to-use, and what to combine with.

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

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

Annotations already cover the read-only/idempotent/non-destructive profile, and the description still adds real behavioral context: one grid image rather than N images, per-cell visibleClipIds plus nonBlankRatio and fingerprints, automatic cellHeight shrinking under a response budget with a note in the reply, and the cost tradeoff of enabling pixels. This is context an agent could not infer from annotations or 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 with the verb and output shape, then guidance, then the cheap-sweep tip — a logical progression with little waste. Some all-caps emphasis and the SAMPLE paragraph are slightly verbose for the amount of novel information, keeping it just under top marks.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description carries the return-value burden and does so fully: the contact-sheet grid, labelled cells, visibleClipIds, fingerprint, nonBlankRatio, and the budget-shrink notice. For a 7-parameter render tool it tells the agent everything needed to call it and interpret the result.

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 semantic guidance on two parameters: frames should be sampled at cut points and section middles (not just frame 0), and pixels:false trades image cost for structure plus fingerprints. It stops short of restating columns/cellHeight/format details, which the schema already handles.

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 — composites every video layer at requested frames and returns a single contact sheet with per-cell visibleClipIds and fingerprints. It explicitly distinguishes itself from get_timeline ('shows what actually PLAYS, as opposed to what get_timeline says is arranged'), so an agent can route 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?

Gives concrete when-to-use ('Use it to check an edit'), a concrete sampling strategy ('sample the cut points and the middle of each section, not only frame 0'), and a cost-based alternative mode ('use pixels:false for a cheap sweep'). It also names the sibling it is not, closing the loop on the decision.

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

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

Annotations already declare readOnly, idempotent and non-destructive, so the safety profile is covered. The description adds one genuinely useful disclosure — 'Sample data is deliberately not returned' — which prevents an agent from concluding data is missing, but it says nothing about ordering, pagination, or what an empty result means during polling.

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 tightly packed sentences: what it returns first, the notable exclusion second, the usage routing last. No filler and the most decision-relevant content is front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description carries the burden of describing the return shape and does so field-by-field, including the non-obvious visibility/gap metrics. Combined with the polling guidance, an agent has enough to call it and interpret the result without further tools.

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 token, projectId and clipId are already fully documented in the schema itself. The description adds no extra parameter meaning — no default behavior for omitting clipId, no notes on what the token scopes — so the baseline of 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 ('Lists face-tracking runs') and enumerates exactly what comes back per face: faceId, name, frame range, visible-frame count, gap count. That field list plus the explicit 'pick a faceId for bind_face' framing separates it cleanly from track_faces (which starts runs) and bind_face (which consumes ids).

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 to poll a queued run and to pick a faceId for bind_face' gives two concrete contexts and names the downstream tool that consumes the result. It stops short of naming the initiating tool (track_faces) or stating when not to use it, so it is clear context rather than 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?

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is fully covered. The description adds one piece of real behavioral context — that the returned props schema is editable — but says nothing about ordering, empty-project behavior, or how large the props payload is. With annotations doing the heavy lifting a 3 is right.

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 sentence with zero filler, front-loading the verb and resource and then packing the return fields inline. Nothing could be removed without losing 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?

With no output schema, the field enumeration does the job an output schema would, and the annotations cover safety. Slightly short of 5 because it does not describe the shape of the props schema or note that the list may be empty for a project with no compositions.

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%: token (the session token from connect) and projectId (from get_projects) are both documented in the schema. The description adds no parameter guidance of its own, 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 (Lists) and resource (the project's motion compositions), then enumerates exactly what comes back: id, mediaRef, name, size, fps, duration, editable props schema. That field list also implicitly separates it from get_motion_composition, which returns a single composition.

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 routes downstream usage by tagging mediaRef as "(for add_clips)", which tells the agent why it would call this before adding clips. It stops short of naming alternatives such as get_motion_composition for a single item or update_motion_composition for edits, 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?

Goes well beyond the readOnly/idempotent/openWorld annotations: voices/models stay empty until a key is stored, credits/consent/hasApiKey gate premium use, download phases cannot be forced, and audio tags are spoken aloud on non-v3 models. These are exactly the behavioral traps an agent would otherwise hit.

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 statement, but the body becomes a dense inline dump of nested return shapes with partial redundancy (the audio-tag rule restated by each model's `note`). Much of it earns its place as output-shape documentation, yet it could be tightened into a short list.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description carries the entire burden of describing the return payload, and it does so comprehensively: provider arrays, voice fields, model capability flags, status object with credits and consent, plus per-state consequences. An agent can call this and interpret the result without further input.

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?

Only one parameter (token) at 100% schema coverage, and the schema already explains it is the session token from connect. Nothing further is needed, so the baseline 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?

The description states the resource precisely: the text-to-speech providers the app can generate voiceovers with, and enumerates the returned provider shapes (free in-browser vs premium cloud). It clearly reads as a discovery/list tool, though it never names generate_voiceover directly, so the pairing must be inferred.

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 usage conditions: read the top-level `elevenlabs` status before choosing the premium provider, and note that a provider in 'needs-download' cannot generate until enabled in the Generators panel. It also rules out an alternative ('there is no tool to force the download; ask the user'), which is strong guidance, but it stops short of explicitly directing the agent to call this before generate_voiceover.

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

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

Annotations already declare destructiveHint=true, idempotentHint=false, readOnlyHint=false, so the safety profile is covered. The description adds real behavioral context beyond that: 'move' changes render order ("the order IS the render order"), 'set' values are clamped to each effect's ranges, 'add' returns the new effect's id, and an empty `resource` clears a LUT. It stops short of saying whether removals are undoable or what happens to indices after a remove.

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 purpose and no filler sentences — every clause carries a spec detail. However, it is a single dense run-on paragraph of semicolon-chained clauses, which makes the per-action contracts harder to scan than a short list 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 13-parameter, non-idempotent mutation tool with no output schema, the description covers action semantics, effect-type specs, and even the one return value ('add' returns the new effect's id). Remaining gaps are failure behavior (invalid effectId, out-of-range clamping outcome) and undo/irreversibility, which the destructiveHint alone does not fully convey.

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

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

With 100% schema coverage the baseline is 3, but this description goes well past the schema by giving value ranges (temperature/tint −100..100, exposure −5..5 stops, saturation 0..300) and neutral values (lift/gamma 0, gain 1, offset 25 printer points; curve identity [0,0,1,1]). It also maps parameters to actions and explains that points are flat control points in the unit square, which the schema only hints at.

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 ("Edits a clip's effect stack") and immediately enumerates the six supported actions and the effect types they operate on. It also explicitly names the sibling it is not — set_clip_properties motionBlur — so an agent can distinguish the two 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?

Each action is paired with the parameters it requires (add → type; remove → effectId; move → effectId + toIndex; toggle → effectId + enabled; set → params patch; curve → curve + points), which is actionable routing guidance. The one genuinely confusable case is called out explicitly with a when-to-use-this-instead rule: "For blur that follows the clip's own keyframed movement, use set_clip_properties motionBlur instead."

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

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

Annotations already flag destructiveHint=true and non-idempotent, but the description goes well beyond them: it says a running visual index stops at the next sample and keeps its checkpoint, that the asset then shows an incomplete-analysis badge, and that retry_analysis restores it. That is exactly the kind of blast-radius and recoverability context an agent needs before destroying work.

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 action semantics are front-loaded and every later sentence adds operational detail (checkpoint preservation, badge, retry path) rather than restating the schema. Only the opening 'Full control of the background work queue' is filler that duplicates the title.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description carries the return-value burden and largely discharges it by describing what 'list' returns (queued/running items across projects plus visible task rows with a cancellable flag). It does not say what a 'cancel' call returns, so an agent cannot predict the confirmation payload.

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: 'ONE kind of work for ONE asset' constrains cardinality so an agent knows multiple cancels require multiple calls, and the kind enumeration is repeated inline with cancel-only scoping. It omits any explanation of projectId's role, which is why it is not 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?

Names the resource (background work queue) and both actions precisely: 'list' enumerates queued/running work items plus visible task rows, 'cancel' stops one kind of work for one asset. The verb-and-resource pairing is specific enough to act on. It falls short of a 5 because it never distinguishes itself from plausible siblings like get_job_status, get_analysis_status, or get_problems, which an agent could easily confuse with queue listing.

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 context is clear: use 'list' to inspect queue state, use 'cancel' to stop work, and use retry_analysis or a tile retry button to re-run something afterwards — an explicit alternative for the follow-up case. It lacks explicit exclusions, i.e. no statement of when to prefer get_job_status or get_problems over list.

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

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

Annotations declare destructiveHint=true and idempotentHint=false, and the description goes well beyond them: solo silences non-solo tracks, merge aborts the WHOLE move on any overlap or source transitions, delete refuses a track holding clips, and delete on an empty track usually reports removedTracks: 0 without being a failure. It also documents the invariant that video and audio counts are forced equal — the key non-obvious side effect.

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 action list, then a numbered, well-structured section on ordering. Dense and mostly earning its space, though the 'removedTracks: 0 is not a failure' point is stated twice (in the delete bullet and again below), costing some 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?

No output schema exists, yet the description still discloses the key return signal (removedTracks) and the refusal behaviors. For a 12-action, 7-parameter mutation tool with destructive semantics, nothing an agent needs in order to call 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 baseline is 3, but the description ties parameters to actions: 'rename' needs name, 'merge' needs intoTrackId of the same kind, 'tidy' takes NO trackId. It also gives each action value behavioral meaning (duck uses transcript timings or energy VAD) that the bare enum list in the schema does not.

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 title-line 'Track operations on a timeline' is generic on its own, but the immediately following enumeration of the twelve actions (mute/rename/duck/merge/delete/tidy) makes the resource and scope unambiguous. An agent can distinguish this from remove_clips, manage_effects, or manage_transitions 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?

Explicit routing: deleting a non-empty track is 'remove_clips, by name', track ids come from get_timeline, projectId from get_projects. It also gives an ordered procedure (merge first, then tidy once at the end) and states which action to prefer and why.

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

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

Annotations already flag destructiveHint=true and non-idempotent, but the description adds substantial context beyond them: default durationFrames of 30 clamped to source handles, forced alignment for single-sided fades, refusal when a transition cannot fit, and automatic removal when an edit breaks the cut. It also discloses the return shape ({ok, transitionId?}). This is exactly the kind of mutation-behavior detail annotations cannot convey.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with the resource scope before breaking into the action list, and every clause carries information (defaults, constraints, enum values). It is dense and pipe-delimited, which makes it efficient but slightly harder to scan than a structured list would be; still, 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 an 11-parameter mutation tool with a nested params object and no output schema, the description covers all three actions, the type catalog with per-type parameters, defaults, failure/refusal semantics, and the return shape. An agent has everything needed to select and invoke it correctly without guessing.

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 already 91%, so the baseline would be 3, but the description meaningfully extends it: it defines atFrame as 'the cut where one clip ends and the next starts,' gives defaults and clamping rules for durationFrames, and documents the type-specific params (angle in degrees, softness 0-100) for wipe/slide/push. That is real semantic value beyond the schema's terse field descriptions.

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

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

The description opens with a precise verb-plus-resource statement — transitions on a track's cuts or lone clip edges — and then enumerates the three sub-actions ('add', 'remove', 'update') with their required identifiers. It clearly separates this tool from siblings like manage_effects or manage_tracks by scoping it to cut-level transitions and even explains the single-sided fade case for free head/tail clips.

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?

Useful operational context is given per action: 'add' needs trackId plus atFrame pointing at the cut, 'remove' needs transitionId, 'update' takes transitionId plus optional fields. It also states the preconditions (both clips need source material past the cut, unfittable transitions are refused, broken cuts remove the transition) which tells the agent when a call will fail. It stops short of naming sibling tools or explicit 'when not to use this' guidance, so a 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?

Annotations already declare read-only/idempotent/non-destructive, and the description adds rich behavior beyond them: asynchronous job returning jobId with polling, the full result shape, gating rules (−70 absolute, −10 relative) and what null means (under 0.4s or silent). It also discloses the prerequisite and error state an agent must anticipate.

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 core purpose and the async/polling contract before the dense return-shape breakdown; every clause carries information. It is long and somewhat dense, but the length is justified by the returned data structure it documents.

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 carries the full return contract and does so comprehensively—duration, integrated LUFS, true peak oversampling, LRA, windows, sections, speech/gap analysis, per-track breakdown, plus null handling and error conditions. An agent has everything needed 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 coverage is 100%, so the baseline is 3; the description adds meaning by tying `windows` cardinality to windowSec and explaining sections as named per-span reports (intro, interview answers). The remaining required params (projectId, timelineId) are already well described in the schema.

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

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

Opens with a specific imperative ('MEASURE THE MIX') and immediately explains the mechanism: offline mix of the timeline's audio measured with EBU R128/BS.1770. It clearly delineates what is included (tracks, nests, fades, keyframes, ducking) and distinguishes this measurement from export normalization, so an agent can tell it apart from siblings like get_analysis_status or inspect_timeline.

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?

Establishes the use case ('you cannot hear it; this is how you check it') and gives a concrete prerequisite: run start_transcription first if there's no transcript, plus the PROJECT_NOT_OPEN failure condition and the poll-get_job_status loop. It doesn't enumerate explicit when-not-to-use or a named alternative for pre-export verification, so not quite 5.

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

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

Annotations already flag destructiveHint=true and idempotentHint=true, and the description earns credit by explaining exactly what survives — the earliest face's id and name, so existing bindings keep working — and what happens to the intervening time (left as a gap for the clip's gap policy). That is substantive consequence-level detail an agent cannot get from the annotations or 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?

Four short sentences, front-loaded with the action and scenario, then the refusal rule, then the survival/idempotency consequence. No filler and no repetition of schema text.

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 destructive 4-parameter mutation with full schema coverage and no output schema, the description covers usage, the hard refusal condition, identity survival, and downstream gap behavior. Nothing an agent needs to invoke it safely and 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; the description adds a real constraint on faceIds beyond the schema's 'two or more within that run' — that no two may share a frame — which changes how an agent should build the call. It adds little about projectId/trackId/token, which the schema already documents.

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 — joins two or more faces from one run into a single person — and immediately grounds it in the real scenario (subject leaves frame and returns). That scenario framing distinguishes it from bind_face and track_faces without needing to name them.

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 an explicit when ('somebody who walked out of the shot and came back') and an explicit when-not/refusal condition ('REFUSED when any two of them appear on the same frame, since they cannot then be one person'). It stops short of naming the sibling (bind_face) an agent should use for the different-person case, so routing is inferred rather than stated.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true, and readOnlyHint=false. The description adds concrete behavioral detail beyond those annotations: linked partners follow automatically, and landing on another clip overwrites/trims it like drag-drop. That explains exactly what destructive effect to expect.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three tight sentences with no filler, front-loading the core action and then adding the key operational constraints. Every sentence contributes materially to correct invocation.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description is strong for a destructive batch-move tool with no output schema and full schema coverage. It could be slightly more complete by addressing failure behavior or atomicity for the moves array, but the essential operational semantics are present.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds useful meaning beyond the schema by clarifying that toTrackId is optional and must target a same-kind track, and by framing toStartFrame as the landing position under overwrite 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: 'Moves clips to new positions', with additional scope about linked partners and track targeting. It is clear what the tool does, though it does not explicitly contrast itself with nearby siblings such as trim_clips, insert_clips, or split_clips.

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 the tool is used for repositioning existing clips and notes that toTrackId must be a same-kind track. However, it gives no explicit when-to-use guidance, no exclusions, and no named alternative for operations like trimming or inserting clips.

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

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

Annotations only say readOnly=false, destructive=false, idempotent=false. The description adds real behavioral context beyond that: browser storage requires no permission or gesture and returns the id synchronously; folder storage triggers a browser security gesture, opens a dialog with a 'Choose folder' button, returns an actionId, and requires the agent to instruct the user in its reply before calling await_user_action. It also discloses that converting to a disk folder later loses nothing.

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?

Default-behavior and rationale are front-loaded, then the exceptional 'folder' path with its full follow-up sequence, with the critical instruction emphasized in caps. It is dense and runs as one block, but essentially every sentence carries a distinct operational fact; a slight reorganization into default-vs-exception beats would improve scanability.

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 async-capable creation tool with no output schema, it explains both return shapes (immediate project id, or an actionId awaiting a grant) and the post-grant verification step via get_projects. Nothing an agent needs to invoke it correctly or recover from the folder branch 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 meaning the schema does not: the default value of storage, why 'folder' is the exceptional case, and what the agent must do after passing it (actionId + await_user_action). The token and name parameters get no extra explanation, keeping it just short of full marks.

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?

A specific verb+resource ('Creates a project') followed immediately by the two storage modes and their consequences. It is clearly distinguishable from siblings such as get_projects (which it names as the place the project appears) and open_project/close_project. An agent knows exactly what is being created and where it lands.

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 an explicit default path (browser storage, no click needed) and an explicit exclusion: 'Pass storage:'folder' only when the user asked for a folder up front.' It also names the required follow-up sibling (await_user_action) and the condition for calling it, so the when/when-not decision is fully specified.

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

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

Annotations flag destructiveHint=true and idempotentHint=true, but the description is what explains why: reloading the tab kills any export or render in progress. That is exactly the kind of consequence an agent cannot get from the annotation flags alone, and it justifies the destructive hint rather than contradicting 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 short sentences, front-loaded with what the tool does, then the 'not required' caveat, then the one harmful side effect. No filler and the risk is stated last for emphasis.

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 two-parameter tool with annotations and no output schema, the description covers purpose, necessity, and the destructive side effect. It omits edge behavior such as whether a tab is created if none is open, or what the caller sees on success — minor gaps only.

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 both parameters are self-documenting (token identifies the browser session, projectId comes from get_projects). The description adds no parameter-level detail beyond the schema, so 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 — navigating the user's Frapea tab to a project — and clarifies the intent is passive viewing ("WATCH the edit live"). It doesn't explicitly contrast with close_project/open_timeline/set_active_timeline, so an agent must infer the boundary from the "headless editing" framing.

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 an explicit when-not ("Not required for editing — every tool works headlessly") and an explicit when ("use this for show-your-work moments"). The agent knows both that skipping this tool is safe and the condition that makes calling it worthwhile.

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

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

Annotations declare non-destructive and idempotent, and the description adds genuine context beyond that: a closed timeline is not deleted, all tools work on it as before, and get_timeline reflects the `open` state as last saved. This resolves the main behavioral ambiguities for a UI-state mutation.

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 in the first clause, the parenthetical clarifies tab semantics without waste, and the comparison to set_active_timeline follows immediately. 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 four-parameter UI-state tool with full schema coverage and annotations, the description covers the remaining gaps: what opening a tab means, what closing means, how activate changes behavior, and how the state is reported. Nothing an agent needs 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 for `activate` ('By default it does not change what the user is looking at; activate:true also shows it') beyond the schema's terse 'Also show it (default false).' The other parameters are already fully documented in the schema.

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

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

States a specific verb and resource ('Opens a timeline's TAB in the editor') and immediately distinguishes the action from set_active_timeline by noting the default does not change what the user is looking at. An agent can tell this apart from siblings like set_active_timeline and close_timeline 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?

Explicitly describes the default behavior and the condition that selects the alternative: 'activate:true also shows it, like set_active_timeline.' It also clarifies that closing tabs is cosmetic and every tool still works, which is exactly the context needed to decide whether to call this tool at all.

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

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

Annotations already flag destructiveHint=true, but the description adds the crucial nuance that 'delete' does NOT touch the file on disk while 'rename' does and takes referencing clips offline. That is exactly the kind of consequence detail annotations cannot express, and it prevents an agent from assuming a destructive unlink is a hard delete.

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 tool's two behaviors are front-loaded in a single dense sentence, and every clause about disk state and offline clips carries real decision value. The quote-per-action formatting is slightly dense but readable; nothing is redundant.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema and a destructive, non-read-only tool, the description carries the burden well by covering both actions, required arguments, and side effects. It stops short of saying what is returned or how failures (e.g., a name collision on rename) are reported, and says nothing about undoing an accidental unlink.

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

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

Schema coverage is 100%, so the baseline is 3; the description goes beyond it by explaining what each action value means for the file system and for existing clips, and by stating that newName is required only for rename. It does not clarify mediaRef/projectId beyond the schema, which already points to get_media and get_projects.

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 two concrete operations (rename a pool file on disk, unlink a file from the media pool) and precisely distinguishes what each does to disk versus pool. It is much clearer than the vague name 'organize_media' implies. It does not, however, distinguish itself from the near-identically named sibling organize_pool, which an agent could easily confuse it with.

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 semantics implicitly tell the agent which mode to pick: 'rename' when the real file should be renamed, 'delete' when only the pool reference should be dropped. But there is no explicit when-to-use/when-not guidance against siblings like organize_pool, remove_clips, or add_sample_media, so the agent must infer routing from the tool name.

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?

Adds substantial context beyond the annotations: bins are virtual, moves never touch the file or its mediaRef, and delete_bin reparents children without losing anything. That reconciles the destructiveHint=true annotation with actual semantics, telling the agent a delete is structurally harmless. Mirror-bin rename/move/delete restrictions are a behavioral rule found nowhere in structured data.

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 conceptual model (what a bin is) before the action list, which is the right order. Dense but mostly earning its space; the 'VIRTUAL ... cannot break a clip's link' sentence is emphasized at length relative to its weight, but it addresses the agent's main fear with this 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?

Eight parameters routed through a single action switch with no output schema, and the description compensates by documenting every action's payload, the item key grammar, the root-bin convention, and the mirror-bin exception. Nothing an agent needs to invoke any of the six actions 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 description coverage is 100%, so the per-parameter docs already carry the mapping. The description does add real value beyond them — item key formats ('timeline:<id>', 'motion:<id>'), the empty-string Library root, and which params pair with which action — but it largely restates the schema's action-to-param assignments. Slightly above the baseline, not decisively.

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 resource and verb set: the media pool's bin tree, with all six actions enumerated and what each does. An agent knows exactly this is bin/folder management. It stops short of 5 because it never contrasts itself with the sibling organize_media, so the agent must infer which 'organize' tool to reach for.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives clear operational sequencing — "call it first — you need the ids" — plus the use case (tidying a project instead of leaving eighty files at the root). It also states important when-not conditions (mirror bins cannot be moved or deleted). No explicit pointer to alternatives, hence 4.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds real value by characterizing what each topic actually returns (API surface, finished examples, craft rules, review loop) — effectively standing in for the absent output schema. It stops short of saying what happens with an unrecognized topic or how large the returned docs are.

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 purpose and the no-topic default, and every clause names a distinct topic with its payload, so there is little padding. The downside is structure: the whole thing is one run-on paragraph whose topic lists would read far better as bullets, and the topic names duplicate 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 two-parameter documentation lookup with no output schema, the description supplies exactly what an agent needs: the topic vocabulary, the meaning of each value, and the ordering rules between them. Nothing required to call 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% and the topic values are already enumerated there, so the baseline would be 3. The description earns above baseline by explaining what each enumerated value contains and how the values relate ('motion-craft ... a companion to motion'), which the bare enum cannot convey. The token parameter is left entirely to the schema, which documents it adequately.

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 ('Returns Frapea's editing documentation for a topic') and immediately scopes what the no-topic default yields. No sibling tool offers documentation lookup, so there is no ambiguity about which tool to call for guidance.

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?

Goes well beyond 'use this for docs': it names explicit ordering constraints ('read before create_motion_composition', 'core ... read first') and sequencing ('then the format you are making'), and it routes between the motion and craft families. An agent can pick a topic and a reading order without opening anything else.

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

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

Annotations already flag destructiveHint=true and idempotentHint=true, so the safety profile is covered; the description adds real value by disclosing that a lift leaves a gap and that linked partners are NOT removed automatically, which is non-obvious side-effect behavior. It stops short of mentioning reversibility/undo or what happens to invalid ids, so it is strong but not 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?

Three short sentences with zero filler, and the most decision-relevant fact (lift leaves a gap) is front-loaded before the partner caveat and the sibling redirect.

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 full schema coverage, no output schema, and annotations covering safety, the description supplies the missing behavioral context: gap behavior, linked-pair handling, and the alternative for gap-closing. Only return/confirmation behavior and failure handling are unaddressed.

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 all four parameters are already documented, including the clipIds array. The description adds only one semantic detail beyond the schema — that the clipIds array must contain both ids of a linked pair — which is useful but marginal against a fully described 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?

States a specific verb and resource ('Deletes clips') and immediately pins down the edit semantic ('lift — leaves a gap'), which is the exact distinction an agent needs. It is clearly separable from sibling ripple_delete_ranges 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 names the alternative explicitly ('To close the gap too, use ripple_delete_ranges instead') and gives a concrete usage rule for linked pairs: pass both ids to delete a pair whole. Both the when and the when-not are present.

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

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

Annotations already flag destructive=true and idempotent=false, so the safety profile is covered. The description still adds real behavioral content: it discloses that edits ripple (shifting downstream clip timing) and that a small margin is preserved so speech never clips, which explains why output differs from a naive cut. It does not mention undo or transcript dependency, 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?

Two compact sentences: the core mechanic and effect first, then the tuning presets. Every clause carries information; nothing repeats the schema or annotations.

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?

Five required params are all documented in-schema, annotations cover the destructive/non-idempotent profile, and no output schema exists. The description supplies the operational semantics needed to call it correctly; only the implicit transcript prerequisite and the fact that timing shifts downstream are left partly 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%, so the baseline is 3. The description earns above baseline by giving minGapSec concrete operating points (0.6 tight, 1.0 balanced, 1.5 loose), turning a bare number into an actionable tuning scale that the schema does not 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?

The description gives a specific verb and resource (cuts silent gaps inside a clip) and explains the mechanism precisely: pauses longer than minGapSec become a ripple delete. That mechanism implicitly separates it from remove_words and ripple_delete_ranges, but neither sibling is named, 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?

Usage is implied by 'between transcribed words' and the recommended minGapSec presets (0.6 tight / 1.0 balanced / 1.5 loose), which is genuinely helpful tuning guidance. However there is no explicit statement of when to pick this over remove_words or ripple_delete_ranges, and no prerequisite such as run start_transcription first.

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

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

Annotations already declare destructiveHint=true and idempotentHint=false, but the description adds the crucial consequence beyond them: each cut is a ripple delete where 'everything after each cut shifts left,' so downstream timing changes. It also notes contiguous indices merge into single cuts, which explains the resulting cut structure. Missing only reversibility/undo guidance for a destructive mutation.

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?

Four tight sentences, front-loaded with the operation and its effect, then the index semantics, then the use case. No filler or restatement of the name.

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 destructive, non-idempotent mutation with no output schema, the description covers what changes and how subsequent content reflows. It stops short of stating what is returned or how to recover from a bad edit, which would matter for a destructive tool.

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

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

Schema coverage is 100%, so baseline is 3; the description earns above that by tying wordIndices to a specific source ('positions in get_transcript's words array for the clip's media') and documenting merge behavior for contiguous values, which the schema does not say.

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 ('cuts the given transcript words OUT of a clip') plus the mechanism (ripple deletes). This clearly separates it from remove_clips, remove_silence, and ripple_delete_ranges, which operate on different inputs (whole clips, audio silence, time ranges).

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 go-to tool for removing filler words or tightening an interview' gives a concrete use case, and the reference to get_transcript establishes the required prior step for obtaining wordIndices. It implies but never explicitly states when to prefer remove_silence or ripple_delete_ranges instead.

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

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

Annotations only declare it is a non-read-only, open-world, non-idempotent call; the description adds real substance by disclosing that it opens a dialog in every Frapea tab, returns an actionId, and that the user must be told to confirm in the assistant reply. It stops short of warning about calling it repeatedly (which the non-idempotent hint implies) or what happens if the user declines, so not a 5.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three tight sentences: what it does, the side effect plus required return handling, then the trigger condition. Front-loaded and every clause carries operational 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?

No output schema exists, yet the description still names the return value (actionId) and describes the multi-step confirmation loop that follows, plus the entry condition. For a dialog-triggering tool this is complete enough to call correctly on the first attempt.

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 both parameters (token, projectId) are fully described in the schema, so the description adds no parameter-level meaning beyond what is already structured. 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 (asks the user to enable on-device AI analyzers) and names the concrete features affected (picture search, speech). It also situates itself in the flow relative to get_media, await_user_action, and get_analysis_status, so an agent can distinguish it from those siblings without opening schemas.

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 an explicit trigger condition ('Call this when get_media reports needs-models') and an explicit downstream procedure: tell the user in the reply, then call await_user_action and poll get_analysis_status. Nothing about when to invoke it 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?

Annotations already declare destructiveHint=true and idempotentHint=true; the description goes beyond them by specifying exactly what is destroyed — a finished transcript or index is deleted and rebuilt, and the recorded failure is cleared. It also discloses the return value ('the project's analysis status'), which matters since no output schema exists.

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?

Leads with the action and its scope, then the destructive consequence, then the trigger conditions, then the return value — a logical escalation with no filler sentences. Every clause carries information an agent needs.

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 destructive, four-parameter mutation with no output schema, the description covers what it does, what it overwrites, when to reach for it, and what it returns. Prerequisite parameters (token, projectId, mediaRef) are documented in the schema, so nothing essential 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% and each of the four parameters is self-documenting, so the schema already does the heavy lifting. The description only adds the mapping of the two kind values to human terms ('picture indexing or speech transcription'); it says nothing extra about mediaRef, projectId, or token handling beyond what the schema states.

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 ('Runs ONE analysis of ONE asset again'), names the two analysis kinds, and scopes the unit of work explicitly ('ONE analysis of ONE asset'). That scoping distinguishes it cleanly from start_transcription and start_visual_indexing, which presumably operate at a broader level.

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 two concrete trigger conditions: get_media reporting phase 'failed' with a worth-retrying error, or a file whose meaning changed. The word 'again' implies it is not the first-run path, but the sibling tools used for initial analysis (start_transcription, start_visual_indexing) are never named as the alternative, so the routing is inferred rather than stated.

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

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

Beyond the destructiveHint annotation, the description discloses important behavior: content after the extracted range is shifted left and sync-locked tracks follow. It does not mention reversibility or undo, but the core ripple effect is made explicit.

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 concise sentences with the operational behavior front-loaded and a short use-case sentence afterward. There is no redundant or wasted text.

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 destructive editing operation with annotations and a fully documented schema, the description provides enough behavioral context about the ripple effect. It does not cover return values, but there is no output schema and that is not required here.

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 parameters are already well documented. The description reinforces the half-open range semantics and track scoping, but adds limited parameter-specific detail 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 states a specific operation: extracting a half-open frame range on one track and shifting later content left to close the gap. It clearly describes ripple-delete behavior, though it does not explicitly name or contrast sibling tools such as remove_clips or trim_clips.

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 usage context: 'tightening a cut or removing a bad take.' This helps an agent understand the intended scenario, but it does not state when not to use it or name specific alternatives for non-ripple deletion.

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

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

Annotations already cover read-only/idempotent/non-destructive, so the description correctly spends its words elsewhere: the hit shape, that spoken matches are ranked first with a snippet, that timeSec is the best moment within a fromSec–toSec window, and the PERMISSION_REQUIRED failure mode with instructions to relay it. Missing only result-count/limit or empty-result 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?

Three dense sentences, front-loaded with the core purpose and the two-mode split before the return shape and the permission caveat. Every clause carries information, though the parenthetical example and the hits list make it slightly cramped for a single paragraph.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description helpfully enumerates the hit fields, and it flags the permission prerequisite. It is nearly complete for a 3-param read tool; the remaining gap is what happens when nothing matches or whether an index/transcription must exist first.

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 genuinely adds query semantics the schema's 'What to look for — plain language' does not: visual queries should describe imagery while spoken queries should use exact transcribed words. That materially changes how an agent fills the `query` parameter.

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 ('Semantic search over the project's media') and immediately splits the capability into two well-defined modes: visual scope (what is IN the picture) and spoken scope (transcribed speech). This is far more than a restatement of the name and lets an agent distinguish it from retrieval siblings like get_media or inspect_media.

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 guidance on how to phrase each query type ('describe a shot: aerial city at night' vs 'exact words'), which is effectively when-to-use-which-mode guidance. It also states the download prerequisite and the PERMISSION_REQUIRED relay path. It does not explicitly name alternative tools (search_stock_media, get_transcript, inspect_media), 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?

Beyond the readOnly/idempotent annotations, the description discloses the API-key dependency, the exact error code and where the user reconnects, the full return payload (description, tags, rating, download count, format, AudioCommons descriptors), the downloaded flag, and license implications. For an open-world tool with no output schema, this is substantive behavioral disclosure.

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 each subsequent sentence adds distinct value (return fields, license rules, error behavior). It is dense and the enumerated ac_ descriptor list is long, edging toward wall-of-text, but nothing is clearly redundant.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description carries the burden of describing return contents and does so thoroughly (ratings, duration, descriptors, downloaded flag). Combined with the auth error path and license guidance, an agent has everything needed to call and interpret results 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%, so the baseline is 3, but the description goes further by explaining what the license values mean (CC0 needs nothing, BY needs attribution, BY-NC excludes commercial) and steering toward cc0/by for commercial projects. It adds real semantic weight beyond 'cc0 | by | by-nc'.