podcli

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 describes the return value (manual paths and auto-discovered binaries) and hints at failure handling. It does not mention side effects or permissions, but for a read-only status tool this is sufficient.

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

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

The description is two sentences, front-loaded with purpose. Every sentence adds value: first states what it does, second explains return content and provides actionable guidance. No unnecessary 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?

Given there are no parameters and no output schema, the description covers the tool's behavior well. It explains what is returned and suggests a related tool for configuration. It could mention the exact format of the output, but overall it's complete enough.

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 tool has no parameters, so schema coverage is 100%. The description does not add parameter semantics since there are none. Baseline is 4.

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

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

The description clearly states the tool shows whether Claude Code/Codex CLIs are available, using a specific verb 'Show' and resource 'availability of CLIs'. It also mentions what it returns (paths and auto-discovered binaries), which differentiates it from siblings like manage_env.

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 says 'Show whether ... are available' and provides a fallback to manage_env for configuration. It implies when to use (checking CLI availability), but lacks explicit 'when not to use' or comparison to other tools. However, the guidance is clear for its purpose.

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 present, so the description must fully disclose behavior. It mentions defaulting to current UI video and suggestions, which is useful. However, it fails to describe return values, whether the operation is synchronous or asynchronous, any side effects, or whether it only reads data. These gaps are significant for an analysis tool with no 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?

The description is two concise sentences with no redundancy. The core purpose is stated first, followed by essential default behavior. Every word adds value, making it easy for an agent to parse quickly.

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

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

With only two optional parameters and no output schema, the description covers the core purpose and defaults. However, it omits any mention of the return format, whether the operation could be long-running (relevant given job_status exists), or what the results look like. This leaves some ambiguity for an agent, but overall it is adequate for a basic analysis tool.

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

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

Schema coverage is 100%—both parameters have descriptions. The description adds some context by reiterating defaults and the purpose, but it does not enrich parameter semantics beyond what the schema already provides. Since the schema already documents each parameter thoroughly, a baseline of 3 is appropriate.

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

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

The description clearly states the tool's function: 'Analyze audio energy levels for a video or specific segments.' It uses a specific verb and resource, and the mention of finding high-energy moments clarifies its utility. No sibling tool performs the same function, so it stands alone without ambiguity.

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

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

The description provides clear usage context: 'Useful for finding high-energy moments' and explains default behavior ('Defaults to the current UI video and suggestions if not specified'). However, it does not explicitly advise when to avoid this tool or mention alternatives, though no direct alternative exists among the siblings. The implied use case is sufficient for most agents.

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

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

With no annotations, the description carries the full burden and does well: it discloses that inputs auto-load from session state and enumerates the concrete output pipeline (9:16 vertical crop, burned-in captions, normalized audio, H.264 MP4). It doesn't address blocking vs background behavior or failure handling, but the core behavioral profile is present.

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

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

Front-loads the core action, then uses labeled EASIEST/Alternative blocks and a single precedence sentence. Every sentence contributes to correct invocation and nothing is padded.

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

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

For a 9-parameter tool with no annotations and no output schema, the description covers input selection, auto-loading, and output characteristics adequately. Minor gaps remain around async/blocking behavior and error cases, but an agent has enough 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 already 100%, so the baseline is 3; the description exceeds it by explaining how clips, clip_numbers and export_selected interact and which wins, which the schema alone does not convey.

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

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

States a specific verb (export/create) and resource (multiple clips at once) with scope (finished vertical shorts), and the workflow marker 'STEP 3' locates it in the pipeline. It is distinguishable from the sibling create_clip by the explicit 'multiple clips at once' framing.

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

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

Gives concrete selection strategies ('EASIEST: export_selected=true', 'Alternative: clip_numbers=[1,3,5]') plus a precise mutual-exclusivity and precedence rule for clips/clip_numbers/export_selected. It stops short of explicitly stating when to prefer this batch tool over the singular create_clip sibling.

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

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

With no annotations, the description carries the full burden of behavioral disclosure. It presents the tool as a read-oriented 'View'/'Check' action, but the schema reveals a destructive 'delete' mode; the description does not warn about this side effect or disclose any other behavioral traits such as output or filtering behavior.

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

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

Two short sentences, no filler, and the key purpose and usage guidance are front-loaded. Every word 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?

This is a multi-mode tool with 9 parameters, no output schema, and no annotations, yet the description only covers the duplicate-checking use case. It fails to mention the list/check/delete action modes or the destructive delete capability, so an agent is not fully equipped to use it safely and completely.

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

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

Schema description coverage is 100%, with each parameter already annotated for its applicable action (e.g., 'for delete', 'for check'), so the baseline is 3. The description itself adds no parameter-level meaning beyond that, but it does not need to because the schema is complete.

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

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

The description names a specific resource ('previously created clips') and a clear purpose ('avoid duplicates'), which distinguishes it from creation-focused siblings like create_clip and suggest_clips. However, it omits that the tool also supports deletion via the action enum, so the full scope is not stated.

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

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

'Check before creating new clips' is an explicit, actionable directive telling the agent when to invoke this tool relative to clip creation. It does not mention alternative tools or when not to use it, but the core usage context is clear.

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

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

No annotations are provided, so the description carries the full burden: it discloses the side effects (writes comparison.json and comparison.html to output_dir, self-contained HTML with audio player and seek buttons) and the default windowing behavior. It does not mention cost/API implications of engines like assemblyai or runtime expectations for two passes over the sample.

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

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

Three sentences, front-loaded with purpose, then interpretation caveat, then outputs. Every sentence earns its place; the 'neither engine is assumed correct' clause is short and materially changes how results should be read.

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

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

With no output schema, the description does the necessary work of naming the two artifacts produced and their nature. It could go further by describing what comparison.json contains (per-window disagreement records), but nothing required to invoke the tool correctly is missing.

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

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

Schema description coverage is 100%, so the schema already documents all nine parameters including enums and defaults. The description only reinforces the 20-second window default, adding no new parameter meaning beyond the schema — the baseline of 3 is appropriate.

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

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

States a specific verb and resource (transcribe a file with two engines and report disagreement), plus the scope constraint that it compares engines rather than measuring accuracy. An agent can immediately distinguish it from transcribe_podcast, which produces a single transcript.

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 frames when this tool is appropriate by negating the wrong use case ('not accuracy against a ground-truth transcript', 'neither engine is assumed correct'), which prevents misuse of the output. It stops short of naming the alternative (e.g. transcribe_podcast / parse_transcript) for when a single transcript is wanted.

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

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

No annotations are provided, so the description carries the full burden, and it does disclose meaningful behavior: the produced artifact type (H.264 MP4 with burned-in captions, normalized to -14 LUFS), and the side effects of keep_caption_overlay and write_clean_variant producing extra files. It stops short of stating where renders are written, overwrite behavior, or expected runtime, which for a 16-parameter writer is still a 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?

Front-loads the step number, the easy-path invocation, and the output artifact before the option catalogs, and every sentence carries information. It is slightly list-heavy in the style/crop enumerations, but nothing is padding.

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

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

For a 16-parameter, zero-required, no-output-schema render tool, the description covers the invocation shortcut, the artifact, the batch alternative, and the two flags that emit extra return paths. Missing pieces are output location, failure/fallback behavior beyond allow_ass_fallback, and expected duration.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real semantics the schema lacks: it explains each caption style (branded=professional, hormozi=bold/yellow, karaoke=progressive highlight, subtle=minimal) and each crop mode (speaker=speaker-aware, face=face tracking, center=fixed center), and clarifies the clip_number auto-load shortcut. It does not elaborate on hook, transcript_words, or the ffmpeg-ish fallback flag.

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

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

The first line states a specific verb (export/render), a specific resource (a single clip) and a precise output spec (1080x1920, 9:16 vertical short). It also names the sibling it is not (batch_create_clips), so an agent can disambiguate without opening either schema.

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

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

Gives an explicit recommended invocation path ('EASIEST: just pass clip_number — everything else auto-loads from session state') and an explicit exclusion rule ('For batch export, use batch_create_clips instead'). It also names export_to_davinci_resolve as the consumer of the keep_caption_overlay output, which routes the agent correctly.

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

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

With no annotations, the description carries the full burden of behavioral disclosure. It explains the output structure (compound clips with V1 and V2 tracks), compatibility (Resolve 20.x), and the integration requirement, which is substantial. However, it does not mention potential side effects like overwriting existing files at the output path, which is a minor 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?

The description is three sentences with no filler, front-loading the core purpose and then providing structural and prerequisite details. Every sentence contributes actionable information, making it highly 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 description covers the essential aspects: purpose, output structure, compatibility, and integration requirement. It doesn't mention the logo_path parameter's role in the output (schema does), nor does it discuss error handling or file overwrite behavior. Given the complexity of the nested shorts array, the description is reasonably complete but could include a note on the resulting file 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?

The input schema already has 100% coverage, so the baseline is 3. The description adds value by mapping shorts fields to video tracks (V1 source, V2 captions) and explaining the compound clip concept, which goes beyond the schema's individual field descriptions.

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

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

The description states a specific verb (export) and resource (podcli shorts to DaVinci Resolve FCPXML project), distinguishing it from any sibling tool. It clearly communicates the output format and target application, leaving no ambiguity about what the tool accomplishes.

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

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

The description provides a clear prerequisite (integration must be enabled) and how to enable it, which is essential context for using the tool. While it doesn't explicitly name alternatives or exclusion conditions, no sibling tool performs a similar export, so the guidance is adequate for the context.

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. It does substantive work: describes the returned payload contents, reveals the compact phrase-grouped markdown view is ~10x smaller than raw segments, and discloses speaker attribution, silence gaps, and optional energy peaks. This gives the agent an accurate model of what the response contains without needing to inspect the data.

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

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

Purpose is front-loaded in the first sentence, followed by a high-value IMPORTANT call-order note, then parameter-specific detail. It runs a few lines longer than strictly needed ('the primary surface for reasoning about clip boundaries' is slightly ornamental), but every sentence adds real content and nothing is redundant.

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

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

For a simple read-state tool with one optional parameter and no output schema, the description is well-rounded: it covers the return contents, the transcript mode's behavior, call timing, and how results connect to sibling tools. The only minor gap is that it doesn't disclose error conditions or when the state might be uninitialized, which is low-risk for a read operation.

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

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

Schema coverage is 100% and the schema already describes include_transcript ('Include full transcript segments... Set true when analyzing content for clip suggestions'). The description layers genuine extra meaning on top: setting it true 'analyzes transcript content' and returns a compact phrase-grouped markdown view with speaker attribution and silence gaps — explaining why the flag matters for clip-boundary reasoning beyond the schema's one-liner.

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

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

States a specific action ('Read the current podcli session state') on a specific resource, and adds what the agent gets from it: video path, transcript status, clip suggestions, settings, and workflow next steps. This clearly separates it from siblings like job_status and ai_cli_status, which monitor jobs/CLI health rather than session state plus guidance.

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

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

Gives explicit timing guidance ('Call this FIRST when starting a new conversation to understand the current state') and explains the clip-numbering convention that feeds into create_clip, batch_create_clips, modify_clip, and toggle_clip. It doesn't explicitly name alternatives to avoid, but the first-call guidance plus the workflow-routing note is strong and actionable.

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 burden. It discloses that it skips Whisper and requires word-level timestamps, but does not state side effects like overwriting existing transcript data or whether the import is append/merge. The 'into the UI' is vague — it doesn't say whether it replaces the current transcript or affects other assets.

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?

Extremely concise: two sentences that pack critical information — the use case (external transcript), the bypass of Whisper, and a hard requirement (word-level timestamps). All essential info is front-loaded.

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

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

For a tool with nested objects and no output schema, it would benefit from describing what happens on success/failure or whether it's idempotent. It also doesn't specify format expectations for the 'transcript' object beyond timestamps. It's adequate but not fully complete given the complexity of the transcript 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 coverage is high (100%), and the description adds context that the transcript must include word-level timestamps, which is critical. The schema already documents the file_path and the transcript structure, so the description adds the requirement for word-level timestamps beyond just the schema.

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

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

The description clearly states the tool imports external transcripts into the UI and explicitly notes it skips Whisper. It differentiates from sibling transcribe_* tools by indicating it's for external transcripts, though it doesn't name a specific alternative 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 description provides a clear context (use for external transcripts, skips Whisper) but does not explicitly state when to use alternatives or when not to use this tool. It implies usage via 'instead of Whisper transcription' but lacks explicit exclusions.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It explains long-polling semantics, the wait_seconds timeout behavior, and the return payload. It does not mention invalid job_id behavior or side effects, but 'poll status' is inherently read-only and the core behavior is 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?

The description is compact and front-loaded with purpose and behavior. The long-polling explanation and usage context each earn their place, and there is no redundant restating of the tool name or schema fields.

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

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

The description covers purpose, usage context, return shape, and long-polling behavior, which is sufficient for a simple two-parameter tool. It does not describe error handling for invalid job IDs, but the provided information is enough for an agent to call it correctly in the intended flow.

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 wait_seconds semantics and range, and the return shape gives meaning to job_id by tying it to background jobs from transcribe_start or batch_create_clips. Minor issue: description says wait_seconds is 1–60 while the schema allows 0, a small inconsistency.

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: 'Poll the status of any background job,' and enumerates the job types (transcription, clip render, batch export). It also includes the return shape, making the tool's purpose unmistakable. It distinguishes itself from siblings by being the only polling tool in the list.

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

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

The description explicitly says 'Use after transcribe_start or batch_create_clips(async_mode: true),' giving clear invocation context. It also explains when to use long-polling via wait_seconds, which is actionable guidance for an agent deciding how to call 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 burden for behavioral disclosure. It says 'manage' but does not explain that write/delete will modify or remove files, whether overwrites occur, or whether there are auth/destructive implications. The only added context is the .md file description and a workflow rule, neither of which is a tool behavior.

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

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

Two sentences with the core resource and purpose front-loaded before the workflow directive. No wasted words, and the example-free style keeps it scannable. Slightly more detail on write/delete behavior would be useful but not at the cost of brevity.

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

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

The description covers the central use case—reading KB context before clip work—and the schema fully documents parameters. However, with no output schema and no annotations, the agent is left to infer the return value of read_all/list/read and the effects of write/delete. This is a moderate completeness gap for a tool with five actions.

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

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

Schema description coverage is 100%, so the parameter meanings are already well-defined: 'action' enum, 'content' for write, and 'filename' with an example. The description adds only the context that files are markdown and the workflow reminder. Baseline 3 is appropriate because the schema carries the load.

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?

Clear verb+resource pair: 'read or manage the podcli knowledge base.' The description adds a concrete characterization ('.md files that provide context about the podcast') and connects to clips, making the resource's role understandable. It doesn't explicitly contrast with siblings, but the KB is distinct enough from clip-oriented tools.

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 an explicit trigger: 'Always read the knowledge base before suggesting or creating clips.' This tells an agent when the tool is a required preliminary step. It doesn't discuss alternatives or when to avoid the tool, but the directive is actionable.

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 bears full responsibility. It only states what the tool lists but does not disclose behavioral traits like read-only nature, authentication needs, or error conditions.

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

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

The description is a single sentence of 12 words, front-loaded with the action and resource. No wasted words.

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

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

For a simple list operation with no parameters and no output schema, the description is minimally adequate. However, it does not mention any environmental constraints or behavior if the directory is empty.

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 are no parameters, so the schema coverage is automatically 100%. The description adds no parameter info, but baseline for 0 parameters is 4.

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

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

The description clearly states the action (List), the resource (rendered clip files in the output directory), and the included details (file sizes and dates). It distinguishes from siblings like clip_history or manage_assets.

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

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

The description provides no guidance on when to use this tool versus alternatives, missing an opportunity to differentiate from similar tools like clip_history or manage_assets.

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 convey behavior. It discloses the default-asset behavior, which is valuable, but does not mention more complex behaviors like destructive actions (unregister) or details of import vs. local file registration. The schema lists actions but not their implications, leaving a partial 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?

The description is compact and well-organized. It front-loads the purpose in the first sentence, then provides practical usage context in the second. Every sentence adds meaningful information without waste.

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

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

The description explains the core concept of reusable assets and their referencing, but does not elaborate on the actions such as 'resolve', 'import_url' vs 'import', or the response/return values. Given the schema lists nine actions with no per-action descriptions, the description only partially prepares an agent to invoke arbitrary actions correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds context about the 'name' parameter's role in referencing assets, but does not further elaborate on parameter specifics beyond what the schema already provides. It slightly reinforces the purpose of parameters like 'type' and '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?

The description clearly identifies the tool's purpose: registering and managing reusable assets like logos, outros, intros, music, and images. It differentiates from sibling tools by specifying the resource type and how the assets are used (referenced by name in create_clip/manage_reel).

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 states when to use this tool: to register assets so they can be referenced by name instead of full paths. It provides clear context on the usage pattern, but does not explicitly mention exclusions or alternatives, though the context implies using this over direct paths.

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 must convey side effects. It does mention that migrate moves files, export zips, import restores (with backup), and use writes a .podcli-marker. This covers key mutations. It does not mention permissions, return values, or error handling, but the core behavioral effects are 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 description is well-structured with a brief lead-in and a bulleted list of actions. Each action has a short, informative description. There is no redundant or extraneous content; it is efficient and focused.

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

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

The description covers the main behaviors and effects of each action, making it fairly complete for a configuration management tool. However, it does not describe expected return values or output formats (since there is no output schema), nor does it mention potential error states or edge cases. These omissions are not critical but keep it from being fully complete.

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

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

Schema coverage is 80% with each parameter having a description (home, action, dry_run, activate, bundle_path). The tool description adds little beyond these schema descriptions—it restates action names but does not elaborate on parameter nuances or relationships. Since coverage is high, the baseline is 3, and no additional semantic depth is provided.

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

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

The description clearly states the tool's purpose: managing portable config profiles and legacy path migration. It lists five specific actions (status, migrate, export, import, use) with brief explanations, distinguishing it from the sibling tools which handle transcription, clips, assets, and other unrelated concerns.

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 implicitly indicates when to use the tool (for config management, migration, export/import, activation) but does not explicitly contrast with alternatives or provide 'when-not-to-use' guidance. The actions are self-explanatory enough for an agent to infer appropriate usage, but explicit conditions are absent.

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

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

No annotations exist, so the description carries the full burden. It does disclose the mutation semantics (set modifies .env, unset removes a key) and the side-effect nuance that unset falls back to auto-discovery. A note that writes persist to disk and affect future CLI runs would have pushed this to 5, but the disclosure is clear.

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

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

Front-loaded with the core purpose in the first sentence ./tight bullet structure groups keys (with their semantic role) and actions (with default and side-effects) separately. Every bullet earns its place; no filler.

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

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

For a 3-parameter tool with no annotations and no output schema, the description covers the action enum semantics, the meaning of each key, the default action, the value requirement, and the side-effect of unset. The list action's output is addressed ('show all settings, configured values'). It is adequate, and the only real gap is not explicitly detailing the set action's confirmation behavior on success.

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 high (>80%: action enum, key enum, value), so the baseline is 3. The description adds real value by explaining what each key is for (speaker detection, auto-discovery fallbacks for the two CLI paths) and the constraint that the path must exist for PODCLI_*_PATH keys. This meaning goes beyond the raw schema, so a 4 is earned.

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

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

Opens with a precise statement of scope — 'List, set, or unset global podcli settings stored in .env' — then enumerates exactly which keys the tool manages and what each key is for. An agent can disambiguate this tool and understand its purpose 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?

Each action is defined, the default is stated ('list' is implied as default), and the two conditional behaviors are spelled out: 'set requires path to exist for PODCLI_*_PATH keys' and 'unset falls back to auto-discovery'. The guidance is concrete and actionable.

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 to rely on, the description carries the full behavioral disclosure burden and does it well. It explains side effects: enabling makes tools callable, disabling causes future calls to fail, and state persists through the active config home. This is transparent about mutating behavior and persistence.

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

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

The description is compact, scannable, and front-loaded with the core purpose. The bulleted actions are easy to parse, and the final state note is concise while still adding meaningful persistence context.

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

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

The tool is simple, with only two parameters and no output schema, and the description covers all operations, the default behavior, and the side effects. An agent has enough context to pick the correct action and understand what invoking the tool will change.

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

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

The schema already documents both parameters completely with 100% coverage, but the description enriches the enum values by explaining what each action actually does. The additional semantics around 'callable' and 'disabled error' go beyond the schema labels.

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

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

The description opens with a clear verb and resource: 'List, enable, or disable podcli integrations,' followed by distinct definitions for each action. This makes the tool identifiable and separates it from the other manage_* siblings in the same toolset.

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 concrete invocation guidance: list is the default action, and name is needed for enable/disable. It does not name alternatives or provide explicit when-not-to-use instructions, but the intended use is clear enough for an agent.

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

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

With no annotations, the description carries the full burden and discloses rich behavioral traits: background jobs return job_id and require polling job_status then 'show'; render skips unchanged work; every render runs validation checks with specific pass/fail criteria; cloud actions need podcli login and Pro; export review produces a marked review timeline. This goes well beyond what structured fields provide.

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

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

The description is long, but the complexity of a 17-action, 23-parameter tool justifies the length. It is front-loaded with purpose and workflow, and most sentences add actionable detail rather than filler, though the density could be slightly better organized.

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

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

Given no output schema and no annotations, the description is remarkably complete: it explains return shapes (session, job_id, validation), background job polling, workflow sequencing, export behaviors, cloud prerequisites, and special layouts for call recordings. An agent has enough context to select actions and invoke the tool correctly.

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

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

Schema description coverage is 96%, so the baseline is 3, but the description adds meaningful consolidated guidance: it groups mapping fields (people, sources, range_start, range_end, cut_settings, speaker_map, look, removals) as applying to 'map', 'sync', and 'plan', and clarifies that 'render' takes only look and stems. This helps an agent navigate 23 parameters even though the schema already documents them individually.

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: 'Edit a full multicam podcast episode', then enumerates the core operations (map, sync, auto-cut, render/export). It clearly distinguishes this tool from sibling tools like export_to_davinci_resolve or manage_assets by framing the entire multicam editing workflow.

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

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

It provides an explicit end-to-end flow ('new' → 'show' → 'map' → 'sync' → 'plan' → 'render' or 'export') and describes when to use each action, including alternatives and conditional branches. It also names prerequisites and consequences, such as re-running 'plan' after mapping changes.

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

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

With no annotations provided, the description carries the full burden. It discloses that the tool can mutate state (save/delete) and lists supported actions, but does not detail side effects, such as whether loading overwrites current settings or whether deletes are irreversible, or any permission requirements. It is adequate for a simple CRUD tool but lacks deeper behavioral context.

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

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

The description is two concise sentences with no filler. The action list is front-loaded, and the stored fields are stated clearly, ensuring an agent immediately understands the tool's scope.

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

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

The description is reasonably complete for a CRUD tool: it explains the config contents and actions. However, since there is no output schema, the description does not hint at return values (e.g., what list returns or what save/load/delete return). It also does not clarify that name is only required for specific actions, though the schema states that. This is a minor gap for a simple 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?

The schema covers all parameters with descriptions, so the baseline is 3. The description adds value by explaining that presets store these specific fields and that they enable quick reuse, which clarifies the purpose of the config object and reinforces the meaning of the action enum. It does not add syntax details beyond the schema but complements it effectively.

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

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

The description clearly states the tool manages rendering presets with four specific actions (save, load, list, delete) and enumerates the stored fields (caption_style, crop_strategy, logo_path, outro_path). This provides a distinct resource and verb, and no sibling tool addresses presets, so it is easily distinguishable.

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

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

The description implies usage for managing presets (e.g., 'for quick reuse') and no sibling tool overlaps this function, making the context clear. It does not explicitly state when not to use it or name alternatives, but given the unique purpose, the absence of explicit exclusions is acceptable.

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 convey side effects. It mentions detection runs once and that build avoids re-detecting, and lists mutating actions. However, it doesn't state whether delete is permanent, whether editing mutates the session in place, or whether an action requires a prior 'new' (except implied). Reversibility is not addressed.

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

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

A single dense paragraph that front-loads the main purpose and workflow, then enumerates actions and params. It's readable but long; could be split into steps. Every sentence carries information, though the param list at the end is a run-on list that might be better structured. Still, the key concept is up front.

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

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

The description explains the two-phase workflow (detect once, then edit/build) and the role of video_paths pooling. However, with no output schema, it omits what each action returns (e.g., list/show results, build output path). It also doesn't mention persistence or idempotency of 'new' (does it overwrite?). Given 16 params, it covers the main flow but not edge-case behaviors or return values.

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

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

The description explains the workflow that ties params together, especially 'video_paths' pooling and the edit ops (longer/shorter/etc.). It clarifies the two-phase flow ('new' then 'edit'/'build') which the schema's per-param descriptions don't fully give. Since schema coverage is already high (100%), the description adds useful operational context beyond that baseline.

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 the tool's purpose clearly: create and iterate on a highlights reel. It distinguishes the two phases (detection with 'new' vs. editing) and lists the exact actions, making it unambiguous what the tool does and when each action 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?

Describes the workflow: detection runs once with 'new', then edit moments without re-detecting negative. It explicitly mentions pooling multiple videos with video_paths. Doesn't cover prerequisites like video format or whether files must be local, but the main usage pattern is clear.

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

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

No annotations are provided, so the description carries the full burden, and it does disclose key mutating behavior: 'import' replaces the config, 'reset' reverts to the generic default, and the layout falls back to one face when podcli cannot distinguish two people. It omits details like whether export overwrites an existing file or whether import validates the source, keeping it from a 5.

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

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

Actions are front-loaded and every clause carries information, but the body is one densely punctuated sentence and partially restates the layout enum already in the schema. It is efficient overall but slightly overloaded.

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

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

With no output schema and no annotations, the description covers the action semantics and layout behavior well enough to call the tool correctly. It leaves the concrete return shape of 'show' implicit, a minor gap for an otherwise complete definition.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description adds meaning beyond the schema by explaining the pair-layout fallback behavior and the interview-clip intent (guest left, host right) that the enum descriptions do not fully capture.

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 set and resource — the thumbnail template podcli uses to generate thumbnails — and enumerates all five actions, clearly distinguishing it from generic config siblings like manage_config and manage_env. An agent can identify the tool's domain 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?

Breaks down when to use each action ('show' returns effective config, 'export' writes to a path, 'import' replaces, 'reset' reverts, 'set_layout' picks layout), which is clear contextual guidance. It does not name sibling alternatives or state exclusions, so it stops short of a 5.

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

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

With no annotations, the description carries the full behavioral burden and does well: it repeatedly clarifies that no full video is ever downloaded, that 'mine' only fetches existing captions, prefers the original-language track over auto-translated, and converts to podcli's word-level format. It omits error/permission behavior beyond the schema's cookies hint, so not a full 5.

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

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

Well front-loaded, leading with the core purpose before detailing actions. The 'no download' point is restated three times ('without downloading any video', 'never the video itself', 'Never downloads a full video'), which is mild redundancy but the structure remains clear and scannable.

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

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

For a dual-action tool with no output schema, the description covers mode semantics, side-effect avoidance, format conversion, and workflow integration. It leaves return-value shape and failure modes unspecified, but the essential call-time information is present.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaning on top by elaborating what each action value does (listing uploads with title/duration/date and mined flags; fetching one video's captions) and how the output is consumed downstream, exceeding the schema's terse enum descriptions.

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

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

The description names a specific verb+resource (mine a YouTube channel's back catalog for clip-worthy moments) and clearly delineates the two action modes. It references siblings (clip_history, suggest_clips, import_transcript) so an agent can place it in the workflow 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?

It explains when to use each action: 'list' to survey a channel's uploads and avoid re-suggesting already-mined videos, 'mine' to convert one video's captions into a transcript. It also routes the output into the suggest_clips flow. It stops short of explicit when-not-to-use conditions, keeping it at a strong 4.

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

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

With no annotations, the description carries the full behavioral burden. It usefully discloses that action='delete' removes a clip entirely and that adjustments happen before exporting, but it omits permissions, reversibility, whether updates are partial, and what happens to unspecified fields.

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

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

Four short sentences, front-loaded with the purpose and key actions. Every sentence contributes useful information about scope, editable fields, deletion, and clip reference without padding.

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

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

Given the rich nested schema and no output schema, the description supplies enough to select and invoke the tool: it names the resource, editable aspects, delete action, and clip reference. It leaves some behavioral context unstated, but the schema covers parameter details well.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds minor value by mentioning clip_number and action='delete', but largely repeats what the schema already documents in detail, including the nested updates fields.

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

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

The description uses a specific verb ('Adjust') and resource ('a suggested clip'), and scopes it to 'before exporting'. It clearly distinguishes adjustment from creation or suggestion, but does not explicitly name or contrast sibling tools such as toggle_clip or create_clip.

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 provides implied context ('before exporting') and a specific use for action='delete', but gives no explicit guidance on when to choose this tool over alternatives like toggle_clip, create_clip, or suggest_clips. The when-to-use is inferable but not 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 burden. It usefully discloses that processing happens via the Python backend and that output is word-level timings, but says nothing about permissions, cost/latency, whether results are persisted, or how the required file_path must relate to the text.

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

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

Three short sentences, front-loaded with the purpose and immediately followed by the format contract. The embedded format example is slightly verbose but earns its place by disambiguating input.

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 transformation tool with no annotations and no output schema, the description defines the input contract but omits what the caller gets back (timestamp structure) and any execution constraints. 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 coverage is already 100%, so the 3 baseline applies, but the description adds genuine value by spelling out the expected raw_text layout ('Speaker (MM:SS)\ntext...'), which the schema only calls 'Raw speaker-labeled transcript text'. The remaining params are covered by the schema itself.

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 (parse) and resource (raw speaker-labeled plain text transcript) plus the output (word-level timestamps), which is more than a tautology. It does not explicitly distinguish itself from siblings such as import_transcript or transcribe_start, so an agent must infer the boundary from the input format.

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

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

Usage is implied by the required 'raw speaker-labeled' input and the sibling set, but the description never says when to use this over import_transcript or the transcribe_* tools. There are no exclusion or prerequisite statements.

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 must carry behavior and it mostly does: it discloses the keying strategy (video path + file size, not session), the persistence behavior across ui-state.json overwrites, and the partial-update merge semantics. It doesn't cover permissions or failure modes, but the core behavioral traits are 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?

Three dense but purposeful sentences, front-loaded with the purpose before the keying and partial-update mechanics. No obvious filler, though the parenthetical field list is long.

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 10-param mutation tool with no annotations and no output schema, the description covers purpose, persistence model, update semantics, and a sibling pointer. The main omission is what the call returns and any permission requirements.

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 80%, so most parameters are already documented. The description lists the categories of decisions but adds little per-parameter meaning beyond the schema, which already describes fields like video_path, clip_count, and notes. Baseline 3 is appropriate.

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

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

States a specific verb (record) and resource (per-episode workflow decisions), then enumerates exactly which decision fields are covered. It distinguishes itself from siblings like get_ui_state by naming it as the read counterpart.

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

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

Explains the why (so later runs never re-ask) and the interaction model (pass only fields you have; existing answers preserved). It routes to get_ui_state for unanswered fields. It does not explicitly say when not to use it, but the context is clear.

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

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

With no annotations provided, the description carries the burden of behavioral disclosure. It clearly distinguishes the tool from transcribing operations ('without transcribing') and relates it to a broader workflow. However, it does not disclose what 'set' means in terms of side effects or persistence, nor does it mention permissions or whether any existing working state is replaced.

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

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

The description is compact at two sentences, with no filler. The core action is front-loaded, followed by relevant workflow guidance and next steps. Every sentence adds useful information.

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

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

For a single-parameter tool without an output schema and no annotations, the description adequately covers the action and the surrounding workflow. The mention of subsequent steps (transcribe or import) gives the context needed for an agent to plan. It stops short of a fully complete specification of state implications, but that gap is minor for a tool of this simplicity.

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

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

The schema fully describes the only parameter 'file_path' as an 'Absolute path to the video file', so the description doesn't need to repeat this. The description adds some context about the purpose (setting a working video) but does not add any new detail about the parameter's format or constraints.

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

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

The description clearly identifies the action as 'Set the working video file' and immediately clarifies it does not transcribe, distinguishing it from transcription tools like transcribe_podcast. The specific resource (video file) and the differentiation from siblings are established directly.

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

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

The description provides explicit context: 'Use this when you'll import a transcript separately' and outlines the subsequent workflow ('After this, either transcribe_podcast or import a transcript via import_transcript / parse_transcript'). However, it does not explicitly state a contrasting 'when not to use' case beyond implying a direct transcription alternative.

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

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

No annotations are provided, so the description carries the full burden. It does disclose real behavior: suggestions are stored, numbered, and pushed to the Web UI for human review, and the flow is gated by prior transcript analysis. It does not state whether repeat calls overwrite prior suggestions, whether a transcript must already exist, or what happens on rejection, which keeps it short of a 5.

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

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

Front-loaded with the workflow stage, then cleanly segmented into 'Before calling this', 'What it does', and 'After this'. Every sentence is functional, though the opening line and the 'What it does' line partially restate each other, so it is tight rather than maximally economical.

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 tool whose single parameter is a deeply nested object with many required fields, the description supplies the pipeline position, the content-quality constraint, and the export handoff, which is the information an agent cannot derive from the schema. Return values are not explained (no output schema), but the assigned clip numbering is covered, leaving only overwrite/idempotency behavior 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 100%, so the baseline is 3 and the schema already documents fields like payoff, standalone, preview_text, and hook. The description still adds validation semantics the schema does not enforce: every suggestion must carry its own context, and a clip opening on an answer whose question was cut is rejected. That rule-level guidance lifts it above baseline.

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 — submit/store clip suggestions — and elaborates with concrete effects: assigns clip numbers (#1, #2), pushes them to the Web UI. It is clearly distinguishable from siblings like create_clip and batch_create_clips, which it names as the downstream export step.

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

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

Explicitly states the prerequisite (read the transcript via get_ui_state(include_transcript: true) and identify viral moments), the ordering (STEP 2, after analysis), and the follow-up path (batch_create_clips(export_selected: true) or create_clip(clip_number: N)). It even encodes a rejection rule with the corrective action (widen start_second so the question is inside the clip).

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?

It discloses the core state change (select or deselect) and a downstream relationship (selected clips feed an export). However, with no annotations, the description carries the full burden and does not explain edge-case behavior, such as what happens if no clip identifier is provided or whether state is persisted across 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?

Two short sentences, front-loaded with the core purpose and no redundant wording. Every sentence earns its place.

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

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

The tool sits in a workflow between suggestions and export, and the schema's required field is only 'selected', so the description should clarify which identifier must be passed. It does not state what happens when no clip_number/clip_id/index is provided, and there is no return or side-effect detail, leaving meaningful ambiguity.

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

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

The schema already documents all parameters with 100% coverage, so the baseline is 3. The description reinforces clip_number but adds no information about precedence between clip_number, clip_id, and deprecated index, nor about the fact that only selected is required while an identifier appears to be semantically necessary.

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 ('Select or deselect') on a specific resource ('suggested clip by clip_number') and states the workflow context ('Selected clips are exported with export_selected'). This makes it clearly distinguishable from sibling tools like modify_clip by focusing on selection rather than editing.

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

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

It gives clear context: use this to mark suggested clips before exporting, reinforced by the reference to export_selected. It does not explicitly name exclusions or alternative tools, so it falls just short of full 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 and does so well: it discloses the returns are metadata-only, that transcript body is NOT returned, caching by file hash, format support, and a torch-unavailable fallback. This is exactly the behavioral context an agent needs to avoid a wrong post-call inference.

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

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

Well-structured with labeled sections (What it does / Returns / Caching / Supported formats / After transcription) and front-loaded purpose. Slightly long and repeats the diarization rationale, but every block is useful and skimmable.

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-param, no-output-schema, no-annotation transcription tool, the description covers the missing return-value contract, the follow-up read path, caching semantics, and format support. An agent could call this and its follow-ups correctly without inspecting anything else.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds real meaning: it explains the diarization default and why it matters (question vs answer), and explains sample mode via start_seconds/duration_seconds including the cache caveat. It does not cover engine, language, or model_size tradeoffs, leaving some value on the table.

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 ('Transcribe a podcast video/audio file') and frames itself as the entry point ('typically the first tool you call'), which distinguishes it from siblings like transcribe_start and compare_transcription_engines.

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

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

Explicit sequencing: 'After transcription: call get_ui_state(include_transcript: true) ... then ... call suggest_clips.' It also gives a when-to-disable condition for diarization ('Set false only for a single-speaker recording') and names the read step needed to access content.

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

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

No annotations are provided, so the description carries the full burden and it does: it discloses the async/background nature, the required runtime dependency ('Requires the Web UI to be running (npm run ui)'), long-running timing, and even the return shape { job_id, cached, status, estimate_minutes }. That is unusually complete behavioral disclosure.

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

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

Front-loaded with the core action, then a clearly labeled 'Flow:' sequence and a prerequisites/returns trailer. It is longer than most descriptions but nearly every sentence carries actionable information; only mild density could be trimmed.

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

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

For an async orchestration tool with no output schema and no annotations, the description supplies the missing pieces: return fields, runtime prerequisite, timing expectation, and the follow-up loop. Only the non-file_path parameters are uncovered, which is scored separately.

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, and the description only demonstrates file_path usage. Engine, language, model_size, num_speakers, and enable_diarization (two with enums, one with a default) are left with no semantic guidance anywhere, so the description fails to compensate for the schema 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 and resource ('Start transcription as a background job') and immediately distinguishes itself from the sibling transcribe_podcast. An agent can tell apart the async variant from the sync one without opening either schema.

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

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

Explicitly names the alternative and the condition that selects it ('use this instead of transcribe_podcast for long files'), plus a concrete duration heuristic (60-min episode = 15-25 min). It goes further and gives an end-to-end call flow naming job_status and get_ui_state.

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?

There are no annotations, and the description only states the action 'update' without detailing side effects, reversibility, or what happens to existing settings. It is unclear whether this is a partial or full update, and there is no mention of the response or any error conditions.

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

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

The description is a single, well-structured sentence that directly states the verb and object with a list of attributes. It is concise, with no unnecessary words 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?

Given the lack of annotations, the description is insufficient. It does not specify update semantics (partial vs. full replacement), prerequisites, or the expected response. It also omits the intro parameter. The agent would need to infer or inspect the schema to fully understand the tool's 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?

The schema provides brief descriptions for each parameter (e.g., 'Path or registered asset name for PNG logo' and 'Caption style'), covering all parameters. However, the description does not add extra context, and some parameters like intro_path are not mentioned. The schema descriptions are minimal and could be more informative.

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

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

The description clearly identifies the action (update) and the resource (rending settings) and names several attributes (caption style, crop strategy, logo, outro). However, it omits intro_path, and the resource is not fully enumerated. The tool is still distinguishable from its siblings based on the listed attributes.

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 explicit conditions for when to use this tool are given. The description does not mention alternative tools or scenarios where this should be preferred over others like get_ui_state or manage_config. This leaves the agent without clear guidance on selection.

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