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

With no annotations, the description carries the full behavioral burden and says almost nothing: it does not state whether chapters must be added in order, what happens on duplicate timestamps, whether an existing chapter at that time is overwritten, or what permission/state the session must be in. It only confirms this is a mutation, which the name already implies.

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 no filler or redundancy. It earns its brevity, though it is under-specified rather than optimally concise.

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

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

An output schema exists, so return values need no explanation, but for a mutation tool with no annotations, three undocumented parameters, and unclear time units, the description leaves the agent guessing about prerequisites and side effects. It is not sufficient to call this tool confidently.

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 0%, so the description must compensate and largely does not. 'at a timeline time' gestures at at_time but gives no units (seconds, samples, timecode), and neither title nor the optional project_path is mentioned at all.

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 (Add) and resource (a chapter marker) plus the locating dimension (at a timeline time), which is clear enough to distinguish it from most siblings. It stops short of explicitly contrasting with remove_chapter_tool or list_chapters_tool, so differentiation relies on the tool name.

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 add a chapter versus editing an existing one, no mention that remove_chapter_tool/list_chapters_tool are the complementary operations, and no prerequisites (e.g. an open project or loaded timeline). Usage is only implied by the verb.

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

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

With no annotations, the description carries the full behavioral burden, and it discloses little. It is clearly a mutation ('Append') but does not say whether the TODO becomes part of the comment body or a separate structure, whether it is reversible, what permissions are needed, or what happens on repeated calls.

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 tight sentence with no filler and the key distinction ('existing comment') front-loaded. It is efficient, though brevity here borders on under-specification rather than true conciseness.

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

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

An output schema exists so return values need not be described, but for a 3-parameter mutation with zero annotation coverage and zero schema descriptions, the one-line description leaves an agent without enough to call it correctly in edge cases.

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 0%, so nothing is documented in the schema. The description only loosely implies comment_id ('existing comment') and text (the TODO content) and says nothing at all about project_path, leaving the optional scoping parameter entirely unexplained.

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 ('Append') and resource ('an action item TODO to an existing comment'), which is much clearer than the bare tool name. However, it does not differentiate itself from near-name siblings like add_comment_tool, add_comment_reply_tool, or set_comment_action_done_tool, so an agent must infer the boundary on its own.

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 statement of when to use this tool versus add_comment_tool (new comment), add_comment_reply_tool (reply), or set_comment_action_done_tool (closing an action item). The 'existing comment' phrasing implies a precondition but gives no explicit context or exclusions.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure for a write operation. It usefully notes the reply is 'flat' (no nested threading), but says nothing about notification side effects, editability, required permissions, or what happens if the parent comment is resolved or deleted.

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 that states the action and its placement without preamble. The parenthetical '(threaded discussion)' is mildly redundant with 'reply under an existing comment' but costs little.

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

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

An output schema exists so return values need not be explained, but for a mutation tool with zero annotations and 0% parameter coverage the description is too thin. Nothing tells the agent how the three required fields should be supplied or how the optional project_path affects behavior.

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

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

Schema description coverage is 0% across 4 parameters, so the description must compensate and largely does not. 'Existing timeline comment' hints that comment_id must reference a valid parent and 'reply' hints at body, but 'author' and the optional 'project_path' are entirely unaddressed in both the schema and the description.

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

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

Names a specific verb ('append') and resource ('reply') and constrains it to 'an existing timeline comment', which implicitly separates it from the sibling add_comment_tool that creates top-level comments. It never names that sibling or any other alternative, so the differentiation is inferential rather than explicit.

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 phrase 'under an existing timeline comment' implies the precondition that a parent comment must already exist, and 'threaded discussion' signals the conversational context. However, it gives no explicit when-to-use vs add_comment_tool/add_comment_action_tool, and no exclusions or prerequisites around visibility or permissions.

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

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

With no annotations, the description carries the behavioral load and does well: it discloses that the action is undoable via history (reversibility), that edit_decision_id creates a unique thread per decision, and how track_ids scoping behaves. It does not cover who may comment or permission requirements, and return behavior is left to the output schema, so it falls short of fully transparent.

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

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

Front-loads the core purpose, then layers the clock semantics, scoping, and thread rule without filler. The line-broken, markdown-tinged formatting makes it slightly fragmentary, but every sentence contributes meaning.

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 8-parameter, no-annotation mutation tool with an output schema, the description covers the ambiguous clock semantics, optional scoping lists, undoability, and reply-thread routing. Remaining gaps (project_path meaning, span vs instant rule for timeline_end, author/body expectations) are minor but real.

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

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

Schema coverage is 0% with 8 bare-titled parameters, so the description must compensate and it does for the hardest ones: timeline_start/timeline_end are defined as timeline (chapter) seconds rather than source-media time, track_ids/action_texts are optional string lists, and empty track_ids means session-wide. It leaves project_path and the exact instant-vs-span rule (timeline_end null) unexplained, so compensation is substantial but incomplete.

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

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

States a specific verb and resource ('Add a timeline review comment (instant or span)') and its scope is clear enough to separate it from list_comments_tool, get_comment_tool, and add_comment_reply_tool. The parenthetical immediately signals the two supported comment forms.

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 routing: use search_transcript_tool's timeline_start/end when anchoring to dialogue, empty track_ids means session-wide, and later notes on the same pending cut must use add_comment_reply_tool rather than this tool. It also warns that edit_decision_id opens a single unique Ask thread per decision, which is a concrete when/when-not rule.

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

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

With no annotations, the description carries the full behavioral burden, yet it discloses nothing beyond the one-line purpose: no permission/authorization requirements, no indication of whether the effect applies immediately or on render, and no explanation of how 'effect' and 'preset' interact (mutually exclusive? both allowed?). For a mutation tool with zero annotation coverage this is a real gap.

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 no filler and the target scope stated up front. It is efficient, though its brevity is partly the source of the specification gaps rather than a virtue.

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

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

An output schema exists so return values need not be described, but for a six-parameter mutation tool with no annotations the definition is far too thin: nothing on parameter relationships, defaults, required context (project_path), or side effects on the existing effect chain.

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?

Six parameters with 0% schema description coverage means the description must compensate, and it only partially does: 'effect (or preset)' maps to the effect/preset params and 'track or speaker' hints at track_id/speaker. The 'params' object and 'project_path' get no mention at all, and no format or exclusivity rules are given.

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

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

The description names a specific verb ('Add') and resource ('effect (or preset)') and scopes it to a target ('a track or speaker's effect chain'). That is enough to distinguish it from remove_effect_tool and set_effect_bypass_tool by verb alone, though it never names those siblings explicitly.

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

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

There is no statement of when to use this versus remove_effect_tool, list_effects_tool, or set_effect_bypass_tool, and no preconditions (must the track exist, must the effect be installed?). Usage is only implied by the verb.

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

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

With no annotations, the description carries full burden, but 'Return' at least signals a read-style retrieval and the output schema covers the return shape. It does not state read-only status, whether the brief is cached/computed, or any permission requirements, so it is adequate but thin.

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 no wasted words, and the key content of the brief is stated up front. It borders on under-specification rather than wordiness, but structurally it is efficient.

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

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

The output schema exists, so return values need not be described. For a one-parameter tool this is nearly sufficient, but the omission of the optional project_path semantics and the lack of any safety/behavior note leave small but real gaps.

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

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

The single parameter project_path has 0% schema description coverage and the description never mentions it. It does not explain what the path resolves to or what happens when it is omitted (default null), leaving a real ambiguity unaddressed.

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 ('Return') plus a named resource ('the alignment acceptance brief') and clarifies the content as a checklist of what to verify before marking done. This implicitly distinguishes it from align_done_tool and align_status_tool, though it never names those 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?

'what the agent must check before marking done' implies the workflow position (read this before calling align_done_tool) but never says so explicitly or names alternatives. Usage is inferable 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?

No annotations, so the description carries full burden, and it discloses almost nothing beyond 'optional notes': no side effects, no idempotency, no prerequisites, no indication of what state the alignment gate transitions to or whether the action is reversible. For a state-mutating gate action this is a significant gap.

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 no wasted words. It is appropriately sized, though its brevity is partly under-specification rather than pure economy.

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

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

An output schema exists, so return values need not be explained, but for a mutation tool with zero annotations, undocumented project_path, and a crowded alignment-oriented sibling set, the description leaves too much unspecified for confident invocation.

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

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

Schema coverage is 0%, so the description must compensate. It only hints that notes is optional; it says nothing about what notes are used for or what project_path does, despite project_path being the parameter that likely determines which session/project the gate applies to.

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 ('Mark ... done') and a specific resource ('conversation-clock alignment acceptance gate'), which is more precise than the bare name. It implicitly distinguishes from align_waive_tool by framing this as acceptance rather than waiver, but never names or contrasts a sibling explicitly.

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

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

No when-to-use guidance. It is unclear whether this is called after align_brief_tool/align_status_tool report readiness, or whether it can be called at any time, and no mention of align_waive_tool as the alternative path. The workflow position must be inferred.

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

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

With no annotations, the description carries the full burden. It usefully discloses that apply=False is a preview path, that prior manual/declined decisions take precedence, and that placement overrides have a precondition. It does not say whether the change is reversible, what exactly gets modified, or what permissions/context are needed, leaving significant behavioral gaps for a mutation 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?

Three short lines, front-loaded with the core operation and then the preview/precedence/precondition notes. No filler, though the terse phrasing borders on cryptic rather than self-explanatory.

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

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

An output schema exists so return values need not be described, but with six undocumented parameters, no annotations, and a mutation in a dense editing domain, the description leaves too much unspecified about scope and side effects to be fully callable without trial and 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 0%, so the description must explain all six parameters, yet it only gestures at apply (preview via apply=False) and the timeline-window requirement tied to start_sec/end_sec/override_placement_lock. track_id and project_path are entirely unexplained in both the schema and the description.

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

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

The description names the operation domain ('align supported complete direct phrases locally while keeping uncertain audio intact'), which is more than a restatement of the name, but 'supported complete direct phrases' is opaque jargon and nothing distinguishes this from the nearby sibling set_retained_bleed_alignment_mode_tool or align_brief_tool. An agent would have to guess which alignment tool 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?

It gives real usage rules: use apply=False to preview, saved manual/declined decisions win, and legacy placement overrides need an explicit timeline window. However, it never says when to choose this tool over the sibling alignment/mode tools, so the alternative-selection guidance is only implied.

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

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

With no annotations, the description carries the full behavioral burden, but "Report" does imply a non-mutating read of gate state, and the three enumerated states tell the agent what values to expect. It does not disclose permissions, whether the report reflects unsaved session state, or any rate/scope constraints.

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 tight sentence with the verb and resource front-loaded and the state enumeration in parentheses. Nothing is wasted, though the brevity contributes to the missing guidance noted elsewhere.

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?

Because an output schema exists, the description need not explain return values, and it does name the possible gate states. However, for a tool sitting in a dense alignment/ingest sibling cluster with an undocumented parameter, it leaves the agent without routing or argument guidance.

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

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

The single parameter project_path has 0% schema description coverage and is not mentioned in the description at all, so the agent gets no meaning for it beyond its name. The description does not compensate for the coverage gap.

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

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

States a specific verb ("Report") and a specific resource ("conversation-clock alignment acceptance gate status") and enumerates the possible states (pending/done/waived). It is distinguishable from siblings such as align_done_tool and align_waive_tool, which mutate the gate rather than read it, though it never names them explicitly.

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

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

The description never says when to call this versus align_brief_tool, align_done_tool, align_waive_tool, or ingest_verify_alignment_tool. Usage is only implied by the word "Report" - no prerequisites, exclusions, or alternatives are given.

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

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

No annotations are supplied, so the description must carry the behavioral burden, yet it does not say whether waiving is irreversible, what downstream state it changes, or what preconditions/permissions apply. 'With a recorded reason' hints at audit logging but stops there.

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 efficient sentence with the action front-loaded and zero filler. It is well-sized for the amount of information it actually conveys.

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 gate-bypass operation with no annotations, undocumented parameters, and only a bare mention of an output schema, the description leaves the agent without enough context to invoke it safely or understand consequences.

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

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

Schema coverage is 0% and the optional project_path parameter is entirely undocumented. The phrase 'recorded reason' loosely signals the required reason field but adds no format, length, or validation guidance.

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 (waive) and resource (the alignment acceptance gate), which distinguishes it reasonably from siblings like align_done_tool and align_status_tool. It does not explicitly contrast itself against those siblings, so it falls short of a 5.

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

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

Implies a use case (bypassing the alignment gate when it cannot be satisfied) but gives no explicit when-to-use, when-not-to-use, or prerequisites such as checking align_status_tool first. The alternative of resolving alignment properly via align_done_tool is never named.

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

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

With no annotations, the description carries the full behavioral burden. "Analyze" implies a read-only inspection, but the description never confirms whether anything is modified, what permissions or session state are required, or how the tool relates to the downstream cleanup actions (strip_silence_tool, propose_range_mute_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?

A single well-formed sentence with no filler; the purpose leads. It is tersely efficient rather than padded, though the brevity is partly under-specification rather than discipline.

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

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

An output schema exists, so return values needn't be described, but the definition still leaves the targeting model (speaker vs track_id vs project_path), the read-only assumption, and the relationship to cleanup actions entirely unexplained for a 3-parameter tool with no annotations.

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?

Three optional parameters with 0% schema description coverage and no mention in the description. The schema exposes speaker, track_id, and project_path with null defaults, but nothing explains which one selects the target, what happens if all are null, or how speaker and track_id relate to each other.

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 ("Analyze") and resource ("a track") plus the signal classes it looks for (silence, clicks, hum). That is enough for an agent to know the operation, but it never distinguishes itself from the nearest sibling, audio_diagnostics_tool, which sounds like an overlapping analysis pass.

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?

No when-to-use guidance, no prerequisites, and no named alternative. The only hint is the implied workflow of "analyze then clean," which the agent must infer from the phrase "cleanup opportunities" rather than being told.

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

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

With no annotations, the description carries the full behavioral burden, and it only discloses the dry_run preview path. It says nothing about permissions, whether suppression is reversible, what happens to matched words, or how 'apply' and 'dry_run' interact - a substantial gap for a 9-parameter mutation 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?

A single front-loaded sentence with no filler, so there is no waste to trim. Its brevity is only a virtue relative to the space it uses; the tool clearly needs more content, but that is a completeness problem, not a conciseness one.

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 output schema exists so return values need not be described, but with 9 undocumented parameters, no annotations, and no usage routing, the definition is far too thin for a destructive-sounding suppression operation. An agent would have to guess at required inputs and the effect of the apply/dry_run flags.

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

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

Schema coverage is 0% across 9 parameters, so the description must compensate and does not. It never explains words, exclude_words, speaker, track_id, project_path, or start_sec/end_sec, nor clarifies the apparently overlapping 'apply' (default true) and 'dry_run' (default false) switches.

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+resource combination ('Suppress mic-bleed words') that identifies the operation clearly. However, it does not distinguish itself from close siblings such as bleed_words_tool (likely detection/listing) or apply_low_audibility_suppression_tool, so an agent cannot confidently route between them on this text alone.

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 only guidance is the parenthetical about dry_run previewing, which is really a parameter note. There is no statement of when to use this versus bleed_words_tool, apply_transcript_gate_tool, or mute_off_speaker_tool, and no prerequisites such as needing bleed words identified 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?

With no annotations, the description carries the full disclosure burden, and it does volunteer one real behavioral trait: applied entries 'undergo fresh cut assessment', implying the tool does not blindly apply the list. However it says nothing about whether this mutates the project destructively, whether it is reversible, or what permissions/state it requires, which is a significant gap for an apply-style mutation 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?

A single compact sentence with the primary action front-loaded and no filler. It is terse to the point of ambiguity, but it wastes no words.

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

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

An output schema exists so return values need not be explained, but the description leaves the core semantics underspecified: no usage routing among many sibling edit tools, no explanation of 3 of 4 parameters, and no mutation/reversibility context despite zero annotation coverage.

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 0% across 4 parameters, so the description must compensate and largely does not. 'edit-plan list' loosely maps to the edits array, and 'fresh cut assessment' loosely gestures at review_required, but project_path and use_inaudible_opt are entirely undocumented anywhere.

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 a verb ('Stage cuts') and a resource ('edit-plan list'), but the verb is ambiguous — 'stage' usually means to queue rather than to apply, which sits oddly with the name apply_edit_plan_tool. It does not distinguish itself from closely named siblings such as apply_edits or apply_suggested_actions_tool.

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

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

There is no statement of when to use this tool instead of apply_edits, approve_edits, apply_suggested_actions_tool, or reject_edits_tool, all of which operate on the same edit-approval pipeline. No prerequisites or ordering guidance is given.

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

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

With no annotations, the description carries the full behavioral burden. 'Auto-apply' implies a mutation but it does not disclose reversibility (a revert_applied_edit_tool sibling exists), what happens to decisions that are not auto-appliable, whether it is idempotent, or whether project scope defaults to the active project.

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 compact sentence with the filter condition front-loaded and no filler. It is terse to the point of being cryptic, but nothing 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?

An output schema exists, so return values need not be explained, but for a mutation tool with zero annotations, no parameter documentation, and no workflow context the description is too thin. The agent cannot determine scope, safety, or how this fits relative to approve/reject/apply-plan 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?

There is one parameter, project_path, with no schema description (0% coverage) and an unspecified default of null. The description says nothing about it, leaving the agent unable to tell whether omitting it targets the current project or is an error.

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

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

The description names a specific action (auto-apply) and a precise subset of targets (non-review REMOVE/MUTE decisions with reasons prefixed filler: or pause:), which is more specific than a bare 'apply edits'. However, the domain terms 'decision', 'review', and the REMOVE/MUTE taxonomy are undefined, and it does not distinguish itself from close siblings such as approve_edits_tool, apply_edit_plan_tool, or apply_suggested_actions_tool.

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

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

The reason-prefix filter is a selection criterion, not usage guidance; the description never says when to run this versus approve_edits_tool or apply_edit_plan_tool, nor what prerequisites (e.g., proposals existing) must hold. No exclusions or workflow position are 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?

No annotations are provided, so the description carries the full disclosure burden. "Apply ... to the project" signals a mutation but says nothing about what gets modified, whether existing fades are overwritten, whether the operation is undoable or previewable, or what permissions are required. For a write tool with zero annotation coverage this is a significant gap.

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 efficient sentence with the verb front-loaded and no filler. Its brevity is appropriate structurally, though it contributes to the under-specification penalized in other dimensions.

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

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

An output schema exists so return values need not be described, but for a mutation tool with no annotations and undocumented parameters the description is too thin. An agent cannot tell what the applied fades will do, whether prior fades are replaced, or what project_path should point to.

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 0% and neither property has a description. The description gestures at the recommendations list only by naming its producer; it never explains the expected item shape (the schema is a loose array of objects with additionalProperties), and project_path is entirely unaddressed.

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+resource ("Apply a list of fade recommendations") and names the producing tool, which distinguishes it from the analyzer sibling recommend_fades_tool. It stops short of stating the concrete effect (e.g. fades written onto clip edges vs. joins), so it is clear but not fully precise.

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 parenthetical "(from ``recommend_fades_tool``)" implies the intended workflow: call recommend_fades_tool first, then apply its output here. However, there is no explicit statement of when to use this versus manually placing fades via set_clip_fade_tool or fade_joins_tool, and no prerequisites or exclusions.

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

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

No annotations are provided, so the description carries the behavioral burden. It does disclose one genuinely useful, non-obvious trait — audio is left untouched, so the mutation is transcript-only — but it says nothing about reversibility, idempotency, permissions, or how the supplied ``words`` are matched.

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 no filler; the trailing 'leaves audio unchanged' clause earns its place. Minor deduction for terse phrasing that leaves the optional-words semantics slightly ambiguous.

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

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

An output schema exists, so return values need not be described. But for a four-parameter, zero-required, zero-annotation mutation tool, the description omits parameter meanings, prerequisites, and alternatives — substantially incomplete for its complexity.

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

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

Schema description coverage is 0% across four parameters, and the description only addresses ``words`` (optional narrowing of the target set). speaker, track_id, and project_path receive no meaning in either the schema or the description, leaving the agent to guess at scoping behavior.

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

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

States a specific verb and resource: suppressing low-audibility transcript words, with the 'leaves audio unchanged' qualifier clarifying scope. It does not, however, differentiate itself from close siblings like set_word_suppressed_tool, apply_bleed_suppression_tool, or low_audibility_words_tool (which presumably detects rather than applies).

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 only usage hint is that suppression can be limited to a ``words`` list. There is no statement of when to use this instead of low_audibility_words_tool, set_word_suppressed_tool, or apply_bleed_suppression_tool, and no prerequisite (e.g. must detection/analysis have run 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?

With no annotations, the description carries the full behavioral burden and does so thoroughly: it explains one-undo-step semantics, how cut/shorten/lower/leave are handled, held audio-check behavior, history/edit-log recording, and revise rollback behavior. It also names returned fields and a refusal case.

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 long but appropriately dense for a complex mutation tool. The key operation is front-loaded in the first sentence, and subsequent paragraphs are organized around batch behavior, override behavior, and revise behavior with no obvious 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 complex apply tool with five parameters and an output schema, the description is complete enough: it covers batch application, held items, overrides, revise semantics, refusal behavior, and the returned summary fields. The only minor omission is project_path, but the overall operational context is fully supplied.

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 0%, so the description must compensate. It explains ids, overrides, revise, and override_audio_checks well, including action and decision-id semantics, but project_path is never mentioned, leaving one parameter undocumented.

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

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

The description opens with a specific verb and resource: applying every pending sound's own suggested action in one undo step. It clearly distinguishes this from propose_edits by referencing where the suggestions come from and explains the batch-apply scope.

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

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

It gives explicit when-to-use guidance: apply all pending actions, apply only selected ids, handle held cuts with override_audio_checks, and revise a batch with revise=true and overrides. It also states the refusal condition no_suggested_batch_to_revise, leaving little ambiguity for an agent.

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

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

With no annotations, the description carries the full burden. It usefully discloses that the whole batch lands in one undoable history step, which is real behavioral context. However, it says nothing about permission requirements, whether indices must be valid/contiguous, error behavior on partial failure, or what the response contains.

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 blocks, zero filler, with the operation and its undo property front-loaded before the payload shape. Every element 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?

An output schema exists so return values need no explanation, and the corrections payload is documented. But for a mutation tool with no annotations and two undocumented parameters (track_id, project_path), the definition omits usage routing and failure/validation semantics that an agent would need to call 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 0% and 'corrections' is an open object with additionalProperties:true, so the description's inline shape for words ({word_index, text}) and phrases ({start_word_index, end_word_index, text}) is the only documentation of the hardest parameter. It does not explain track_id or project_path, but the critical nested structure is covered.

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 ('batch word + phrase fixes') and adds a distinguishing trait ('one undoable history step') that separates it from single-fix siblings like correct_transcript_tool. It stops short of naming those siblings explicitly, 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?

No when-to-use or when-not-to-use guidance. The word 'batch' implies this is for multiple corrections at once versus correct_transcript_phrase_tool or find_replace_transcript_tool, but the agent is left to infer that from the adjective alone, with no stated prerequisites or 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?

With no annotations, the description carries the full burden. It does disclose real behavior: retained speech and unresolved audio stay open, the plan's policy/scope is persisted for later renders, alignment respects saved timing, and alignment can trigger transcript reconciliation. That is genuine side-effect disclosure, but it omits what apply=false or override_placement_lock=true actually do, and whether the operation is destructive or reversible.

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

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

The main purpose is front-loaded, which is good, but the remaining four sentences are abstract and jargon-heavy ('policy and scope', 'saved timing choices') without adding concrete guidance. Roughly half the text is padding that does not earn 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?

An output schema exists, so return values need not be described. But given 9 undocumented parameters, no annotations, and a mutating 'apply' operation with a dry-run mode, the description leaves key invocation decisions (what dry_run returns, whether override_placement_lock is dangerous, what 'source scope' resolves to) 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 description coverage is 0% across 9 parameters, and the description names no parameter at all. The only faint signal is 'runs by default,' which loosely gestures at align_retained_bleed's default, but dry_run, apply, override_placement_lock, and the scope parameters (start_sec/end_sec/speaker/track_id/project_path) are left completely unexplained. It does not compensate for the coverage gap.

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

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

The description gives a specific verb and resource: 'Apply an acoustic bleed plan to fresh dialogue stems and persist its source scope.' An agent can grasp the operation. However, it does not differentiate itself from close siblings like apply_bleed_suppression_tool or align_retained_bleed_tool, and the name ('transcript_gate') diverges from the body ('acoustic bleed'), which muddies identification.

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 implied context ('Later renders reuse the plan's policy and scope') that hints at when the persisted plan matters, and it notes alignment runs by default. But it never states when to choose this tool over apply_bleed_suppression_tool, speaker_gate_track_tool, or the align_retained_bleed_* siblings, and gives no exclusions or prerequisites.

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

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

With no annotations, the description carries the burden and does well: it discloses that passing edits must clear automatic audio-quality and cut-position checks, that blocked edits are returned in 'held' with their finding and stay pending, and that override_audio_checks skips those checks for the call and records the override (actor and surface) in History and the edit log. It omits permission/auth requirements and reversibility, but the gating and audit behavior is unusually well disclosed.

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

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

The core action and its scope are front-loaded in the first sentence, followed by the sibling alternative and then the override/held behavior. Sentences are dense but each adds routing or behavioral information; only the double-back reference to the held/override flow feels slightly repetitive.

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-parameter mutation tool with no annotations and an output schema covering 'held', the description supplies the key semantics: batching, the quality-gate outcome, and the override/audit path. The unexplained project_path and absence of any reversibility note are the remaining gaps.

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

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

Schema coverage is 0%, so the description must compensate, and it explains three of four parameters with real semantics: ids (which proposals), all_pending (approve every pending proposal), and override_audio_checks (skip quality checks for this call and log the override). project_path is left unexplained, keeping this short of 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?

States a specific verb (approve), resource (pending edits), scope (by id or all pending), and the consequence (applied to the timeline). It also names the sibling it is not (apply_suggested_actions_tool), so an agent can route correctly 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 alternative for a related-but-different intent ('To give every pending sound its own suggested action at once, use apply_suggested_actions_tool') and clarifies the ids vs all_pending selection. It does not state when not to call it (e.g. versus reject_edits_tool or update_pending_edit_tool), so it falls short of full when/when-not coverage.

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

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

With no annotations provided, the description carries the full behavioral burden, yet it says nothing about what approval actually changes, whether it is reversible, whether it requires permissions, or what happens to clips not listed. For a state-mutating tool this is a substantial gap.

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 no filler, but the brevity comes at the cost of under-specification rather than efficiency — it is terse where it should be informative.

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

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

An output schema exists so return values need not be described, but the definition still leaves the mutation semantics, prerequisite workflow, and both parameters undocumented, which is not enough for an agent to invoke it confidently.

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 0% for two parameters. 'By id' only loosely points at the ids array and says nothing about whether it accepts multiple clips, what a clip id looks like, or what project_path is for.

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 ('approve') and resource ('social clips') plus the lookup key ('by id'), which is clear. However it makes no attempt to differentiate itself from the closely-named siblings reject_social_clips_tool, propose_social_clips_tool, or list_social_clips_tool.

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

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

There is no guidance on when to approve versus reject, whether a prior propose_social_clips_tool step is required, or what state the clips must be in. The agent must infer the workflow entirely from the sibling names.

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

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

No annotations are provided, so the description must carry the full behavioral burden. 'Return' implies a read operation, but the description does not state whether it is read-only, whether it requires a loaded session, how large the output may be, or any other operational constraints.

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 no filler. It states the resource and scope immediately and does not waste words.

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

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

Although an output schema exists and covers return values, the input side is severely under-specified: three optional parameters have zero schema descriptions and no annotation support, and there is no guidance on choosing between track_id, speaker, or project_path. The description is too thin for an agent to invoke this tool confidently.

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 0% for all three parameters. The description gestures at 'track or speaker' which maps to track_id and speaker, but gives no format, default behavior, or interaction between them, and completely omits project_path, leaving an agent unable to choose correctly.

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: 'Return per-word audibility scores' and scopes it to 'a track or speaker.' This clearly identifies the tool's function, though it does not explicitly differentiate from related siblings like low_audibility_words_tool, which may also surface audibility information.

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 about when to use this tool versus alternatives such as low_audibility_words_tool or audio_diagnostics_tool. The description only says what is returned, leaving the agent to infer context entirely.

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

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

No annotations are provided, so the description carries the full behavioral burden. It does not state whether this is a read-only analysis or a mutation, whether it requires an active session or project context, what permissions are needed, or how costly/long-running it is. The parenthetical check list is the only substantive behavioral detail.

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 no filler; the verb and scope lead, and the enumerated checks are packed in without waste. Nothing in it 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 5-parameter tool with no annotations and no schema descriptions, the description is far too thin. The presence of an output schema means return values need not be explained, but the description still fails to say how the input parameters scope the diagnostics or what context (session/project) is required.

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 0% across 5 parameters, so the description must compensate and largely does not. 'Time window' loosely maps to start_sec/end_sec, but speaker, track_id, and project_path are never addressed, leaving the agent to guess at scoping and target selection.

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 ('Run'), resource ('audio diagnostics'), and enumerates the checks performed (clipping, hum, level) over a 'time window' scope. It is clear on its own, but it does not distinguish itself from adjacent analysis siblings such as check_loudness_tool, audibility_map_tool, join_quality_tool, or analyze_cleanup_tool, which an agent could easily confuse with this one.

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 the many other diagnostic/QA tools in the sibling list. No prerequisites, no exclusions, no indication of whether it is a precursor to other tools or a standalone check.

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

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

No annotations exist, so the description carries the full burden and does so well: it discloses the three detail modes and their cost tradeoff, the prosody profile status values (missing/stale/unavailable with redacted error), time units, and explicitly that it does not play audio. It stops short of discussing permissions or latency beyond the 'visual' hint.

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 and organizes detail modes legibly, but the sentence 'Caption each dialogue track in a timeline window + clip-skew / render freshness' is compressed to the point of ambiguity and the overall block is dense with inline code spans.

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

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

For a complex tool with 5 params, no annotations, and an existing output schema, the description covers detail modes, prosody statuses, and clock semantics, so an agent can call it confidently. The main gap is the unexplained project_path/skew_warn_sec params.

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 0%, so the description must compensate. It thoroughly explains `detail` and the timeline semantics of start_sec/end_sec, and 'clip-skew' gestures at skew_warn_sec, but `project_path` and the numeric meaning of skew_warn_sec remain undocumented.

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: captioning each dialogue track over a timeline window, with clip-skew and render-freshness attributes. An agent can distinguish it from context siblings like build_edit_context, though the jargon ('caption', 'clip-skew') blurs it slightly.

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 useful mode-selection guidance for the `detail` parameter (summary/full/visual, with 'visual' noted as slower), which is a form of when-to-use. However it never routes the agent against alternatives such as build_edit_context or get_session_state_tool, and states no preconditions, so context is only implied.

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

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

No annotations are provided, so the description carries the full behavioral burden, and it delivers only a one-line statement. "List" weakly implies a read-only operation, but there is no disclosure of scope limits, permissions, whether results are filtered by project context, or what a caller should do with the output. This is a thin disclosure for a tool with zero annotation coverage.

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 no filler or redundancy. It is efficient, though its brevity borders on under-specification rather than deliberate conciseness.

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

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

An output schema exists, so return values need not be explained, but the definition is still incomplete for a 5-parameter, annotation-free tool. Nothing describes what the optional filters do or how results relate to the bleed-suppression and speaker-gate 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?

Five parameters (start_sec, end_sec, speaker, track_id, project_path) have 0% schema description coverage, and the description mentions none of them. The time-range, speaker, and track filters materially change what the tool returns, yet an agent gets no explanation of their meaning, units, or defaults.

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

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

States a specific verb ("List") and a specific resource ("words contaminated by another speaker's microphone bleed"), which separates it from generic word-list siblings like flagged_words_tool or low_audibility_words_tool. However, it never names those siblings or explains how bleed-contaminated words differ from flagged or low-audibility words, so the differentiation is left to 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?

No when-to-use guidance, no prerequisites, and no alternatives. An agent cannot tell whether this should be run before apply_bleed_suppression_tool, alongside align_retained_bleed_tool, or as a standalone diagnostic. Usage is only implied by the verb "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?

With no annotations the description carries the full burden. It discloses useful behavior: output goes to export/bounces/, no mastering is applied, and unset track_ids/formats default sensibly. It is silent on overwrite behavior, whether files are written or merely staged, permission requirements, and any side effects on the session.

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, front-loaded sentences with no filler; the core action and destination come first, then defaults. Slightly terse on the time parameters' purpose but nothing 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?

An output schema exists so return values need no explanation, and the description covers the action, destination, selection rules, and format defaults. For a 5-param export tool the remaining gaps (project_path, overwrite behavior) are minor.

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 0%, so the description must compensate. It clarifies track_ids (stem list, omission semantics) and formats (extension list, wav default) and gives units for the time bounds ('times are timeline seconds'). It says nothing at all about project_path, leaving one of five parameters fully undocumented.

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+resource ('Bounce ... stems') plus scope ('selected (or all)') and a distinguishing qualifier ('without mastering') and destination ('export/bounces/'). It implicitly separates itself from render_final/export_audio_tool via the no-mastering note, but doesn't name any sibling explicitly.

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

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

Gives one concrete selection rule ('omit for all non-muted mixable tracks') and a default for formats, which is real usage guidance. However it never says when to prefer this over export_audio_tool, render_final, or render_preview, so the routing decision is left to inference.

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

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

With no annotations, the description carries the full behavioral burden. It discloses the content it assembles but says nothing about whether this is a read-only/idempotent computation, whether it mutates session or project state, or whether it requires specific permissions – meaningful gaps for a 'build' verb that could imply a write.

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 that front-loads the action and immediately qualifies the output and its consumers. No filler or redundancy.

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

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

An output schema exists, so return values need not be explained, and the description correctly identifies purpose and downstream consumers. But with no annotations and 0% parameter coverage, an agent still lacks guidance on the two inputs and on the tool's side-effect profile.

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 0% and neither of the two parameters (project_path, max_utterances) is mentioned in the description. The passing reference to 'utterances' loosely relates to max_utterances but conveys no default or format, so the description does not compensate for the documentation gap.

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

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

The description gives a specific verb+resource ('Build the JSON edit-planning context') and even states the payload contents ('utterances with word indexes'), which distinguishes it from the many cut_*/apply_* siblings. It stops short of explicitly naming which sibling it feeds versus the other context-producing tools, so it is clear but not fully differentiated.

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?

By naming the 'cut_* tools' as consumers, it implies this is a prerequisite step to run before those tools. However, it never states when to call it versus alternatives (e.g., other propose_/preview_ tools) or any precondition/exclusion, leaving usage to inference.

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

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

No annotations are provided, so the description carries the full burden. 'Without refreshing' usefully signals a non-mutating read, and it names the output fields, but it omits permissions, side effects, and whether a refresh is ever triggered; with zero annotation coverage the behavioral picture is thin.

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 leading sentence is front-loaded and reasonably tight, but the backtick-formatted output-field sentences read as reference notes rather than actionable guidance and are partly redundant against the 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?

An output schema exists, so return values needn't be spelled out, but with no annotations and two undocumented optional params the definition leaves an agent unsure how to parameterize the call. Adequate but with clear gaps.

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 0% for two optional params (audio_path, project_path), and the description adds no meaning for either. The one hint ('an explicit unrelated file has stale=None') gestures at the audio_path case but never explains what each parameter selects or their relationship.

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

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

States a specific verb and resource: 'Measure LUFS' plus staleness reporting. It is clear what the tool does, though the jargon ('artifact staleness', 'dialogue-balance') is not anchored to sibling tool names, so differentiation is only implicit.

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

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

There is no explicit when-to-use or when-not-to-use guidance, nor any named alternative. At best the reader infers 'without refreshing' means this is a passive check, but the description never says in which situations an agent should pick this over a recompute/analysis 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?

With no annotations, the description carries the full burden and does disclose the key trait ("Read-only") plus the shape and conditional contents of the return ({duration, extracts}, all tracks vs only track_ids). It omits permission/auth or size-limit context, which are minor for a copy operation.

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

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

Front-loaded with the core action and range, and the reversal/workflow note is worth its space. Slightly dense with backtick-heavy cross-references and the "Studio Copy / Cut" comparison, but no sentence is wasted.

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

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

For a read-only copy tool with an output schema present, the definition supplies the workflow context and return shape an agent needs. The only real gap is the undocumented project_path parameter.

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 0%, so the description must compensate. It usefully clarifies the half-open [start, end) interval and hints that track_ids restricts the copy, but it never explains project_path, leaving one of four parameters undocumented anywhere.

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 (Copy) plus the exact resource and range semantics: "[start, end) timeline seconds." It distinguishes itself from cut/paste siblings by naming paste_segment_tool, propose_range_cut_tool, and delete_clips_tool, so an agent can place it in the edit workflow 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?

Explicitly routes the agent: pass the result to paste_segment_tool, and for cut-and-paste copy first then cut via propose_range_cut_tool or delete_clips_tool with its mode. It names alternatives and the ordering condition, leaving little to inference.

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

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

With no annotations the description carries the full burden, and it does disclose meaningful behavioral traits: optimistic-concurrency refusal when expected_text no longer matches, and the word_source_required refusal code when a multi-take track lacks source_id. It omits permissions, reversibility/undo, and rate context, but the concurrency and error semantics are unusually concrete.

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 one sentence, followed by targeted parameter guidance; little wasted text. The backtick-heavy phrasing is dense but each sentence carries information.

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

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

An output schema exists, so return values need not be described, and refusal behaviors are covered. But for a mutation tool with no annotations, 7 params, and 0% schema coverage, the description leaves key input semantics and safety/mutation context unexplained.

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 0% across 7 parameters, so the description must compensate and largely does not. It clarifies expected_text and source_id but omits track_id, new_text, project_path, and even the boundary params it references only obliquely as 'word_index' rather than start_word_index/end_word_index.

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 ('Replace a word range's text with corrected phrase text'), which is clear. However, it never distinguishes itself from the close sibling correct_transcript_tool, so an agent cannot tell from the text alone why it would pick this phrase-level tool over that one.

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 explains the conditional use of expected_text (refuse if words changed) and when source_id is required, which is useful. But it gives no guidance on when to choose this tool versus correct_transcript_tool, precorrect_transcript_tool, or find_replace_transcript_tool, leaving alternative selection implicit.

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

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

With no annotations, the description carries the burden well: it discloses the mutation is text-only (timing preserved), a stale-word refusal mechanism via expected_text, and a named failure mode (word_source_required). It omits permission/undo-history implications, but the core behavioral contract is clearly stated.

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

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

Front-loads the purpose in one sentence, then layers optional-parameter semantics compactly with no filler. The backtick-heavy conditional phrasing is dense but each clause carries distinct information.

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

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

An output schema exists, so return values needn't be described. The description covers the mutation scope, the concurrency guard, and the required-source error path. It is close to complete, lacking only how the fix interacts with adjacent word indices or project_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?

Schema description coverage is 0% across 6 parameters, so the description must compensate. It explains expected_text and source_id meaningfully, but leaves track_id, word_index, new_text, and project_path (index base, format, scope) entirely to guesswork from bare titles.

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+resource+scope ('Fix the text of one transcript word') and a distinguishing constraint ('without changing its timing'), which implicitly separates it from set_word_timing_tool and correct_transcript_phrase_tool. It stops short of naming those siblings explicitly, so the differentiation relies on 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?

Gives actionable conditional guidance: pass expected_text as a concurrency guard, omit it to skip; supply source_id on multi-take tracks or the call refuses with word_source_required. It never states when to prefer this over phrase-level or find/replace siblings, so exclusions are missing.

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

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

With no annotations, the description carries the full behavioral burden and delivers little. It implies creation and link generation, but says nothing about room lifetime, expiry behavior (despite an expires_at parameter), auth requirements, or what revoking/reuse looks like. The docs/recording-session.md pointer is a weak mitigation.

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 that leads with the verb and object, with no padded prose. The trailing documentation pointer is somewhat dangling but does not bloat the 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?

Although an output schema exists (so return values need not be described), a creation tool with zero annotations and zero parameter documentation should convey lifecycle, expiry, and auth context. Those gaps leave the definition inadequate for correct invocation.

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

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

Schema description coverage is 0%, so the description must compensate, but it fails to explain any of the three parameters (expires_at, project_path, public_base_url). The phrase "guest + producer /rec/ links" only vaguely gestures at the URL parameter and clarifies nothing about the others.

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 ("Mint") and resource ("recording room") and names the concrete output ("guest + producer /rec/ links"), which lets an agent distinguish it from the sibling revoke_record_room_tool. It stops short of explicitly contrasting itself with siblings, so it is clear but not maximally differentiated.

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 no when-to-use guidance, prerequisites, or named alternatives. An agent must infer that a room should be minted before recording, and it is not told how this relates to revoke_record_room_tool or record_start_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?

With no annotations, the description carries the full behavioral burden. It usefully discloses defaults ('Anyone with the link by default', general_access link vs restricted, require_sign_in forcing login) and the side effect of minting an MCP URL when with_mcp is set. It stays silent on required permissions, error/conflict behavior, and what happens when the version_id does not exist, so it is only partially transparent for a 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?

Front-loaded with the purpose, then a tight per-parameter list with no filler. Slightly terse and list-like rather than prose, but every line earns its place and nothing is repeated from 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?

An output schema exists, so return values need not be described. For an 8-parameter, no-annotation mutation tool, the description covers the access-control parameters well but leaves the required version_id unexplained and never states permission prerequisites or failure behavior, so it is adequate but incomplete.

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 0%, so the description must compensate, and it does explain the five semantics-heavy parameters (role, with_mcp, general_access, require_sign_in, invite_emails) with real meaning — notably a genuine role taxonomy. However, it omits the one required parameter (version_id) entirely, plus project_path and public_base_url (whose localhost default is surprising), leaving invocation-critical semantics undocumented.

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

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

The description opens with a specific verb+resource: 'Create a review share URL', which unambiguously identifies the operation. It does not, however, distinguish this tool from its close siblings (publish_review_version_tool, list_review_versions_tool, set_active_review_version_tool), so the agent must infer the relationship between sharing and publishing.

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

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

There is no explicit when-to-use or when-not-to-use guidance and no alternative named. Usage is only loosely implied by the notion that a review version must first exist before a share URL is created. The agent is left to infer that this is a post-publish step.

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

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

No annotations are provided, so the description carries the full behavioral burden. It does disclose the mutation plus a non-applying preview mode, which is genuine value. It omits what happens to existing crossfades, whether fade_ms must be supplied, scope when track_id is null, and whether changes are reversible.

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

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

A single tight sentence with the action front-loaded and the preview semantics appended. Nothing is wasted, though the brevity is part of why so much parameter and scoping context is missing.

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

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

An output schema exists so return values need not be explained, but for a 5-parameter mutation tool with zero schema descriptions and a confusable sibling, the definition does too little. Missing scope rules, fade_ms defaults, and sibling routing leave real gaps.

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 0% across 5 parameters, and the description only touches dry_run. It adds no meaning for fade_ms (units/default when null), speaker, track_id, or project_path, so four of five parameters are undocumented in both places.

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

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

States a specific verb and resource: 'Add crossfades at edit joins on a track.' Clear enough to know it is a fade-application operation. However, it does not distinguish itself from the near-identically named sibling fade_joins_tool or from set_clip_fade_tool, leaving the agent to guess which fade tool is the right one.

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?

'dry_run previews without applying' implies a safe preview path, which is useful implied usage. But there is no explicit statement of when to use this versus fade_joins_tool, set_clip_fade_tool, or recommend_fades_tool, and no prerequisites are given.

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

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

With no annotations, the description carries the full burden, and it does convey one important trait: the cut is 'pending' rather than applied, implying a staged/review workflow. It says nothing about permissions, reversibility, whether prior pending edits are affected, or the effect of review_required and use_inaudible_opt, so significant disclosure gaps remain.

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 no filler; the primary action comes first and the branching condition follows. It is efficient, though arguably under-sized for a 7-parameter mutation tool.

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

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

For a mutation tool with 7 parameters, zero schema coverage, and no annotations, the description is far too thin. An output schema exists so return values need not be explained, but the staging/review lifecycle and the role of most parameters are left 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 description coverage is 0% across 7 parameters, so the description must compensate and largely does not. It conveys meaning for query ('text match') and match_all, but speaker, track_id, project_path, review_required, and use_inaudible_opt carry no explanation anywhere.

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 a specific verb ('Stage a pending cut') and resource ('text match'), and clarifies the first-vs-all branching behaviour. It does not, however, differentiate itself from close siblings such as cut_utterance_tool, cut_words_tool, or cut_time_range_tool, leaving the agent to 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 only guidance is the inline condition 'or every match with match_all=True', which explains one parameter's effect rather than when to pick this tool over the other text-based cut tools. No exclusions, prerequisites, or alternatives are offered.

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

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

With no annotations, the description carries the full burden. It does disclose the key behavioral trait that this is a staged/pending mutation requiring approve_edits to take effect, which is genuinely valuable. But it says nothing about the review_required flag defaulting to true, reversibility, or what a 'staged' cut does to the timeline in the interim.

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 tight sentence with no filler, front-loading the action and the resource. It is arguably over-terse for a 7-parameter mutation tool, but nothing is wasted.

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

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

For a 7-parameter, annotation-free mutation tool with an output schema, the description leaves too much unspecified: the units/format of start and end, the effect of review_required, and whether the staged cut is reversible are all unaddressed. The approve_edits dependency is the only workflow context given.

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 0% across 7 parameters (track_id, start, end, reason, project_path, review_required, use_inaudible_opt), so the description must compensate and does not. It adds no meaning for units of start/end, the reason default, or the purpose of review_required and use_inaudible_opt.

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 (stage a pending cut) and resource (a time range on a track), and notes it applies after approve_edits. However, in a sibling set containing propose_range_cut_tool, cut_utterance_tool, cut_words_tool and cut_text_match_tool, it does not distinguish itself from the closest alternative, propose_range_cut_tool.

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

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

The clause 'applies after approve_edits' implies the pending-edit workflow and locates the tool in a sequence, which is useful. But it never says when to choose this over propose_range_cut_tool or preview_inaudible_cut_tool, nor any prerequisites for staging.

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

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

With no annotations, the description carries the full behavioral burden. 'Pending' usefully implies the cut is staged rather than applied, but nothing is said about what applies it, what review_required does, whether it is reversible, or what the inaudible option changes.

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 no filler. It is efficient, though for a four-parameter staging tool it may be terse to the point of under-specification rather than optimally sized.

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

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

An output schema exists so return values need no explanation, but the definition is still incomplete: no annotation coverage, no parameter semantics for three of four params, and no description of the staging/review workflow the tool participates in.

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 0% across four parameters, and the description only names utterance_index, which the schema already makes required. project_path, review_required, and use_inaudible_opt remain entirely unexplained, and the required param gains no meaning beyond its name.

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 ('stage a pending cut') and resource ('one utterance by its index'), which is enough to distinguish it from siblings like cut_time_range_tool or cut_words_tool. It does not, however, explicitly name which sibling to prefer in which situation.

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

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

There is no when-to-use guidance, no mention of the alternative cut tools (cut_words_tool, cut_time_range_tool, cut_text_match_tool), and no explanation of the workflow that turns a staged cut into an applied one (apply_edits). The agent must infer all routing.

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

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

No annotations are provided, so the description carries the full behavioral burden. 'Stage a pending cut' usefully signals the edit is not immediately applied, but it omits whether review_required gates application, what permissions are needed, and how the pending edit is later committed. For a mutation with zero annotation coverage this is a significant gap.

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 no filler. It is efficient, though arguably too terse for a 7-parameter mutation tool, leaving no room for the operational detail the reader 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?

An output schema exists so return values need no explanation, but with 7 parameters at 0% coverage, no annotations, and no workflow guidance, the description is not complete enough for an agent to invoke this mutation 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 0% across 7 parameters. The description only implies the meaning of track_id and the two word-index bounds, leaving source_id, project_path, review_required, and use_inaudible_opt completely undocumented in both schema and description.

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

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

States a specific verb+resource: staging a pending cut of a word-index range on a track. This implicitly distinguishes it from time-based siblings like cut_time_range_tool and cut_text_match_tool. However, it never names those siblings, so the differentiation is left to 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?

The word 'Stage' hints at a two-step stage-then-apply workflow, but there is no explicit guidance on when to use this versus the many cut/delete/propose siblings (propose_range_cut_tool, cut_time_range_tool, cut_utterance_tool, etc.). No prerequisites or preconditions are 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?

With no annotations, the description carries the full burden and does: it discloses reversibility ('undoable'), the safety guard that a ripple cutting outside speech 'changes nothing and returns needs_confirmation', the override flow being 'recorded', and the underlying mutation ('Submits DeleteClip on the document plane'). This is rich mutation-safety context beyond 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 the core verb+resource, then well-organized into mode semantics, confirmation flow, and sibling routing using inline code formatting. Information-dense and nearly waste-free, though it runs long enough that a trim would help.

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 mutating, confirmation-gated tool, it covers action, reversibility, guard behavior, override, and alternatives. An output schema exists so return values needn't be explained, and the only notable omission is the meaning of project_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?

Schema description coverage is 0%, so the description must compensate. It explains clip_ids (list of clips from list_clips_tool), mode semantics (gap vs ripple with exact track behavior), and override_audio_checks (applies a blocked ripple, recorded). Only project_path is left unexplained, so it is strong but not complete.

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

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

States a specific verb+resource ('Delete whole clips by id') and immediately distinguishes scope with the sibling ripple_delete_tool ('For a time range across tracks use ripple_delete_tool'). An agent can tell this apart from related clip/ripple tools 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 routes: clip_ids come from list_clips_tool, mode='gap' vs 'ripple' is defined with when to choose each, and time-range-across-tracks work is directed to ripple_delete_tool. The confirmation-path condition (needs_confirmation, then override_audio_checks=true) is spelled out.

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

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

With no annotations, the description carries the full behavioral burden. It does disclose one valuable trait — the deletion is 'undoable via history' — but says nothing about whether attached replies/actions are cascaded, required permissions, or whether project_path must resolve to the active review version.

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 zero filler; the core action comes first and the reversible-mutation note is a compact aside. It is efficient, though it leaves most of the definition's obligations unmet rather than being genuinely complete.

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

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

An output schema exists, so return values need not be explained, but for an annotation-free mutation tool with 0% parameter coverage the definition is thin. Missing are cascade behavior on replies/actions, permission requirements, and how project_path relates to the timeline review context.

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 0%, so the description must compensate for both parameters and does not. It never mentions comment_id (what form an ID takes, where to get it) or project_path (why it defaults to null, what scoping it applies); the parenthetical only adds behavioral, not parameter, meaning.

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

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

States a specific verb and resource ('Delete a timeline review comment'), so it is clearly distinct from additive siblings like add_comment_tool and add_comment_reply_tool. However, it does not distinguish itself from the nearest neighbor, resolve_comment_tool, which an agent must choose between without further help.

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 statement of when to use this tool versus resolve_comment_tool, update_comment_tool, or merely resolving a thread. No prerequisites or context (e.g., which review version the comment belongs to) are given.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It hints that the source is preserved and a copy lands elsewhere ('at a new time'), but says nothing about whether bounds are validated, whether the operation ripples/lengthens the timeline, whether it is undoable, or what permissions are needed.

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

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

A single front-loaded sentence with zero filler, which is structurally clean. But for a four-parameter mutation tool with no annotations, this brevity is under-specification rather than true conciseness.

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

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

An output schema exists, so return values need not be described. Still, with no annotations, 0% parameter coverage, and no usage context, the definition is too thin for a mutation tool that an agent must invoke with three required numeric coordinates.

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 0% for four parameters (source_start, source_end, insert_at, project_path), so the schema provides titles only. The phrase 'at a new time' loosely maps to insert_at and 'segment' implies a source range, but units, ordering constraints (insert_at vs source range), and project_path semantics remain entirely undocumented.

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 ('Duplicate') and resource ('timeline segment') with the effect ('at a new time'), so an agent knows what it does. However, it offers no differentiation from near-identical siblings like copy_segment_tool, paste_segment_tool, or move_segment_tool, leaving the agent to guess which one 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?

There is no when-to-use guidance at all: no prerequisites (e.g. does a segment need to be selected first?), no exclusions, and no pointer to the copy/paste alternatives. The agent must infer everything from the 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?

No annotations exist, so the description carries the full burden. It does disclose the report's content (pending vs applied edits, seconds cut in aggregate and per track), which is genuine behavioral value, but says nothing about whether this is a read-only operation, permission requirements, or cost/latency.

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 efficient sentence with the resource and the key metric front-loaded. Nothing is wasted, though it is arguably too terse to cover two undocumented parameters.

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

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

An output schema exists, so return values need not be explained. However, with no annotations and 0% parameter coverage, an agent still cannot tell whether 'markdown' changes the response format or what 'project_path' defaults to, leaving a real gap for a two-parameter tool.

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

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

Schema description coverage is 0% for both parameters. The description never mentions 'markdown' (which controls output format) or 'project_path' (which selects the project), so it fails to compensate for the undocumented schema. Only the phrase 'by track' hints at grouping, not at any 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: it reports both pending-review and applied edits, and quantifies the payload as 'seconds cut in total and by track'. This distinguishes it from list_applied_edits_tool (applied only) and list_edit_decisions_tool, though it does not name those siblings explicitly.

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

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

No when-to-use guidance is given. The description does not say when an agent should call this impact report rather than list_applied_edits_tool, list_edit_decisions_tool, or reconciliation_status_tool, and no prerequisites or exclusions are 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?

With no annotations, the description carries the full burden. It says the tool creates an episode and returns a path, but does not disclose side effects, failure conditions, overwrite/conflict behavior, or required permissions for a mutating operation.

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

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

A single front-loaded sentence with no filler; the action and the returned value are stated immediately. Efficient, though it is under-specified rather than deliberately compact.

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

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

An output schema exists so return values need not be explained, but for a creation tool with zero annotations, zero schema descriptions, and no stated preconditions or error behavior, the description leaves substantive gaps.

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

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

Schema coverage is 0% and the description only loosely gestures at 'workspace directory'. The 'name' parameter (default 'episode') is never mentioned, so an agent gets no meaning for half the inputs and no format hints for either.

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

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

States a concrete verb+resource ('Create a new episode project') and its scope ('in a workspace directory'), which is enough for an agent to distinguish it from the many session/track/transcript siblings. It stops short of naming any sibling or clarifying how it relates to 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?

No guidance on when this should be called versus other project/session setup tools, no prerequisites (does the workspace directory need to exist first?), and no mention of alternatives. The agent must infer the trigger condition entirely.

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

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

With no annotations, the description carries the full burden and does so well: it discloses all-or-nothing atomicity ('files replace export/ only after every one is written') and precise cancellation semantics (encode stops, CancelledProgress raised, prior export untouched, no JSON-RPC reply). It omits permission/auth requirements, but the key behavioral traits are unusually well covered.

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 sentence, and the second paragraph is dedicated to the non-obvious cancellation contract. The cancellation detail is somewhat dense but every clause earns its place by preventing a real misuse (waiting for a reply that never comes).

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

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

An output schema exists, so return values need not be explained, and cancellation behavior is thoroughly documented. The definition is still incomplete for invocation because one of two parameters is entirely undocumented and no format-object structure is provided.

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 0% and neither parameter is documented structurally. The description hints that 'formats' come from pipeline.yaml or formats objects, adding marginal meaning, but 'project_path' is never mentioned and no format object shape is given, leaving a significant gap.

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

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

The description gives a specific verb and resource ('Encode mastered audio to export/') plus the format source (pipeline.yaml or formats objects), which distinguishes it from export_transcript and export_social_clips_tool. However, it does not explicitly name or contrast those siblings, so differentiation is left to 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?

There is no when-to-use or when-not-to-use guidance and no mention of alternatives such as render_final, bounce_audio_tool, or render_preview. The only implied usage is that formats come from pipeline.yaml, which is a format detail rather than routing guidance.

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

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

No annotations are provided, so the description carries the full burden. It does disclose a valuable behavioral default: omitting IDs exports all approved, non-review-required drafts. But it says nothing about permissions, where the export lands, whether it overwrites anything, or what happens to clips still in review — significant gaps for an export/write 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?

One front-loaded sentence, no filler, and the default/fallback behavior is stated right after the primary action.

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

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

An output schema exists, so return values need not be described. Still, with zero annotations, zero schema coverage and an unaddressed project_path parameter, the definition is only minimally sufficient for an agent to call 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 description coverage is 0%, so the description must compensate. It explains the `ids` parameter's omit-behavior reasonably well, but `project_path` is never mentioned and no format or example for IDs is given.

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 (export) and resource (clips), plus the fallback scope when IDs are omitted. It is distinguishable from siblings like propose_social_clips_tool or approve_social_clips_tool, though it never names an alternative explicitly.

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

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

The clause 'when IDs are omitted' implies the two usage modes (selective export vs bulk export), which is genuine guidance. However there is no explicit when-to-use/when-not framing, no mention of prerequisites, and no pointer to a sibling for listing or approving clips 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?

With no annotations, the description carries the full behavioral burden. It does disclose the output format and that a file path is returned, but says nothing about where the file is written, whether it overwrites an existing export, or what permissions/scope the export uses.

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 tight sentence that front-loads the action, output format, and result. 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?

The output schema exists, so the return value needn't be restated, and this is a simple one-parameter tool. Still, the undocumented optional parameter and absent usage guidance leave gaps an agent would have to guess at.

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

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

The single parameter project_path has 0% schema description coverage and is not mentioned in the description at all; its meaning, default behavior, and what happens when it is null are left entirely unexplained.

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 ('Export') and resource ('the transcript') plus the output format (Markdown) and the return artifact (file path). It does not distinguish itself from neighbors like get_transcript or export_audio_tool, so an agent must infer which export route to take.

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

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

There is no when-to-use guidance, no alternatives named (e.g., get_transcript for reading versus export for producing a file), and no prerequisites stated. The agent gets a purpose but no routing logic.

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

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

With no annotations, the description carries the full behavioral burden. It discloses one useful trait (dry_run is a non-applying preview), but says nothing about permissions, whether the fade insertion is reversible, undo behavior, or side effects on surrounding clips for what is clearly a mutation 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?

A single tight sentence with the core action front-loaded and the dry_run caveat appended. Efficient, though its brevity contributes to the documentation gaps noted elsewhere rather than being purely a virtue.

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 5-parameter mutation tool with zero annotation coverage and zero schema descriptions, the description is far too thin. The existing output schema does relieve it of explaining return values, but an agent is left guessing how to target a track and size a fade.

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

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

Schema coverage is 0% and the description explains only dry_run, leaving fade_ms, speaker, track_id, and project_path completely undocumented. It adds meaning for one parameter but does not compensate for the four unexplained ones.

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 ('Add') and resource ('fades at edit joins on a track'), which is clear enough for an agent to know the operation. However, it never distinguishes itself from close siblings like crossfade_joins_tool, set_clip_fade_tool, or apply_fade_recommendations_tool, leaving the fade-vs-crossfade boundary ambiguous.

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 only usage guidance is that dry_run previews without applying. There is no indication of when to prefer this over crossfade_joins_tool, set_clip_fade_tool, or recommend_fades_tool, nor any stated prerequisites or when not to use it.

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

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

No annotations are provided, so the description carries the full behavioral burden, and it discloses nothing beyond the core action. It does not say whether the edit is destructive or reversible, whether it writes to the track in place, what happens if no room tone has been captured, or what permissions/state are required — all material for a mutation tool with zero annotation coverage.

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 well-formed sentence with zero filler, front-loading the action and the resource. It is terse but not padded; the only issue is that the brevity leaves substance unstated rather than that it wastes words.

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

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

An output schema exists, so return values need not be explained, but for a three-parameter mutation tool with no annotations and no schema descriptions the definition is far too thin. Nothing tells the agent how to select the target track or what state must be in place before the fill will succeed.

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 0% and all three parameters (speaker, track_id, project_path) are undocumented optional strings. The description alludes to 'a track' but never explains how track_id, speaker, or project_path identify the target or what happens when they are omitted, so it fails to compensate for the coverage gap.

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

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

The description names a specific verb ('fill'), a specific resource ('a track's silences'), and the fill material ('its own room tone'), so the operation is unambiguous. It does not, however, distinguish itself from close siblings such as strip_silence_tool, shorten_gaps_tool, or insert_gap_tool, which an agent would need to disambiguate among.

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

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

There is no when-to-use guidance, no preconditions (e.g., that room tone must already exist for the track, cf. create_record_room_tool), and no mention of alternatives. The agent is left to infer that this is the tool for silence-filling rather than one of the many other gap/clip-editing siblings.

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