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?

No annotations are provided, so the description carries the full disclosure burden — and it mostly delivers. It clearly states this is a batched export (multiple clips at once), that settings auto-load from session, that it produces a specific output spec, and that async_mode renders in background with polling. The only gap is side effects: it doesn't explicitly say whether it mutates state, overwrites existing outputs, or requires the Web UI (though async_mode mentions 'Requires Web UI running'). The precedence rule is a behavior, not just a parameter detail, and it is disclosed. Strong for a tool with zero annotation coverage.

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

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

A compact, front-loaded definition. The purpose and both usage paths appear in the first two lines; the precedence rule is a single tight sentence; the output spec is one line. No fluff, no repetition of what schema descriptions already state. Every sentence earns its place and is 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 batch tool with 8 parameters and zero annotations, the description explains the three selection modes, the precedence rule, session-state auto-loading, the output format, filtering behavior, and the async path (including that it requires the Web UI and that Claude should poll job_status for progress). The only residuals are the exact job_status polling mechanics and what happens in synchronous mode when no selection is given, but these are minor given the richness of the schema and the description. Strong coverage overall.

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% — every parameter (including nested ones) has a description in the JSON schema. Baseline is therefore 3 even with no extra detail, and the description adds meaningful value beyond that: it explains precedence among the three way parameters, notes that clips/clip_numbers/export_selected are alternatives, and clarifies the clean_fillers default comes from studio settings. The nested per-clip fields are fully described in the schema already. The description does add semantics beyond the schema, but the schema already carries high coverage, so a 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 opens with an explicit verb and resource ('Export multiple clips at once as finished vertical shorts') and establishes this as 'STEP 3' in a pipeline, which clearly distinguishes it from its siblings like create_clip (which likely handles single clips) and export_to_davinci_resolve (which targets a different output path). The mention of resolved output characteristics (9:16 vertical crop, captions, normalized audio, H.264 MP4) leaves no ambiguity about what the tool produces.

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 spelled out explicitly: pass export_selected=true for all, clip_numbers for specific ones, or clips for custom definitions. The precedence rule ('clips wins, then export_selected, then clip_numbers') and the auto-loading from session state remove guesswork. The 'EASIEST' callout gives a direct recommendation. This is one of the most actionable usage sections possible.

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?

With no annotations, the description carries the full behavioral burden. It discloses output format (H.264 MP4), audio normalization (-14 LUFS), burned-in captions, and session-state auto-loading. It also mentions the return of caption_overlay_path and cropped_source_path for the overlay option. It does not explicitly state non-destructiveness, but the export nature implies it; a small gap given no annotations.

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

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

The description is slightly long but tightly structured: step number, quick-start tip, output spec, alternative tool, then option summaries. Every sentence earns its place; no filler. The 'EASIEST' tip is front-loaded for actionable clarity.

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 14 optional parameters, the description is quite complete. It explains the majority workflow (auto-load via clip_number), key options (caption styles, crop modes, overlay), and points to related tools. Missing are error scenarios or prerequisites beyond session state, but schema descriptions fill in the rest, making it adequate.

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

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

Schema covers 100% of parameters, so baseline is 3. The description adds meaning by explaining caption styles (branded, hormozi, karaoke, subtle) and crop modes (speaker, face, center) with parenthetical characteristics, plus the quick-start tip about clip_number. This goes beyond the schema's terse enum 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 states a specific verb ('export'), a single resource ('clip'), and the outcome ('finished vertical short (1080x1920, 9:16)') with output format details. It explicitly contrasts with batch_create_clips, making sibling differentiation clear 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?

Provides explicit usage guidance: 'EASIEST: just pass clip_number' and clearly routes batch work to 'batch_create_clips instead.' It also references export_to_davinci_resolve for the overlay workflow, leaving no ambiguity about when to choose alternatives.

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

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

With no annotations, the description carries the full burden 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 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?

With no annotations, the description responsibly discloses the mutating effects of import and reset ('replaces', 'reverts') and what show returns ('effective config'). It hints at destructive behavior without promising reversibility or permissions, which is acceptable for a config utility.

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 compact sentence that leads with the four main verbs, immediately scopes the resource, and appends concise per-action semantics. Every phrase earns its place; there is no redundancy.

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

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

For two parameters and no output schema, the description covers the essential behavior for each action. It does not elaborate on edge cases like error handling or whether import/reset require confirmation, but the core information an agent needs to call it correctly 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?

Although the schema already describes 'path' as a file path, the description adds directional context ('destination' for export, 'source' for import) and clarifies the role of each action. This goes beyond the raw schema, adding practical value.

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

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

The description names a specific resource (thumbnail template config) and lists four precise verbs (show, export, import, reset), each with a one-line behavior. It clearly distinguishes itself from sibling tools like manage_config by scoping to thumbnail generation configuration.

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

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

It explains the purpose of each action and when each is appropriate (e.g., 'export writes to a file path', 'import replaces from a file path'). It does not explicitly mention when to avoid this tool or name alternatives, but the action-driven guidance makes the usage context 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 and no description; behavioral transparency absent.

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?

No description to evaluate for conciseness or structure.

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?

Tool context is incomplete; essential elements are 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 parameters exist but no description to enrich their meaning beyond 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?

No description provided; cannot determine purpose.

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 description provided; no usage 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 of behavioral disclosure. It mentions that it uses a Python backend and generates accurate word timings, but it does not disclose whether this operation is read-only or mutating (does it write anything? does it modify the video file?), whether it is idempotent, or what happens if the input format is invalid. It also doesn't state any side effects like caching or file writes. Given no annotations, this is a significant gap for a tool that processes and likely produces output.

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: the first states the core function and input format, the second adds a credibility note about the backend. Every sentence earns its place; the input format is front-loaded, which is practical. No redundant fluff.

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 4 parameters, 2 required, and no output schema, the description covers the input format and mentions the file path indirectly. It does not explain what the tool returns (presumably timestamps, but no output schema to clarify), nor does it address edge cases like malformed input or the relationship between file_path and the transcript. It is adequate for a straightforward parsing tool but leaves the agent to infer return structure and error 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 description coverage is 100%, meaning every parameter has a description in the schema. The tool description adds value by specifying the exact input format for raw_text ('Speaker (MM:SS)\ntext...'), which is not fully captured in the schema's generic 'Raw speaker-labeled transcript text'. It also implies that time_adjust and total_duration are optional enhancements. This goes beyond the schema 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?

The description states a specific verb ('Parse'), a clear resource ('raw speaker-labeled plain text transcript'), and the key output ('word-level timestamps'). It also includes the input format, which adds specificity. However, it does not distinguish itself from the sibling 'import_transcript', which likely overlaps in function, and the phrase 'Parse a raw speaker-labeled plain text transcript' could be more explicit about the scope (e.g., that it processes text, not audio files).

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 when you have a speaker-labeled plain text transcript and want word-level timestamps, and it references the Python backend for accuracy. However, it provides no explicit when-to-use vs. alternatives, no mention of prerequisites (e.g., that the video file path is required for context), and no guidance on when NOT to use this tool in favor of import_transcript or transcribe_start. The context is clear but lacks exclusions or alternatives.

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

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

With no annotations 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?

Despite no annotations, the description discloses behavioral rules and side effects. It states that suggestions must carry context and that clips opening on an answer without its question are rejected, with a concrete remedy ('widen start_second'). It also explains that the tool stores suggestions and pushes them to the UI, making the write operation explicit and transparent.

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

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

The description is well-structured and front-loaded, starting with 'STEP 2 — Submit your clip suggestions' and then logically organizing prerequisites, rules, action, and follow-up. It is detailed but not redundant, with each section serving a purpose. The use of headings and imperative phrasing makes it easy to parse and contains no wasted sentences.

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

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

Given the lack of annotations and output schema, the description is remarkably complete. It covers the workflow (before, during, after), validation rules, and the eventual outcome (UI review). It provides enough context for an agent to know exactly how to use the tool and what constraints apply, leaving no critical information 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?

The schema already covers all parameter descriptions (100% coverage), but the tool description adds meaningful semantic context beyond that. For instance, it explains that 'context_line' does not satisfy the standalone check and that 'preview_text' must be the actual opening line. This enriches understanding of parameters like start_second and preview_text, elevating the baseline score from 3 to 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's purpose: 'Submit your clip suggestions after analyzing the transcript.' It specifies the verb (submit) and resource (clip suggestions), and distinguishes it from siblings like 'create_clip' by framing it as a suggestion step that stores and pushes to UI for review. The 'What it does' section reinforces the unique action of storing suggestions and assigning clip numbers.

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 explicit usage context: 'Before calling this: read the transcript via get_ui_state(include_transcript: true) and identify the best viral moments.' It also explains the follow-up steps with 'After this: the user reviews in the UI. Then with batch_create_clips(export_selected: true) or create_clip(clip_number: N).' This clearly indicates when to use this tool relative to alternatives, providing a workflow and prerequisites.

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

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

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?

With no annotations provided, the description carries the full burden — and it delivers. It explicitly discloses that only lightweight metadata is returned and the transcript body (500KB+) is NOT here, that results are cached by file hash so the same file won't be re-transcribed, supported formats, and the packed_ready flag's purpose. This prevents an agent from wrongly expecting the transcript content in the response.

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 tightly structured with labeled sections (STEP 1, What it does, Returns, Caching, Supported formats, After transcription) and is front-loaded with the purpose. Every section earns its place — the Returns disclosure is critical behavioral info, not filler. Slightly verbose, but nothing is redundant.

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

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

For a complex tool with 6 parameters, no output schema, and no annotations, this is impressively complete. It explains the return shape (metadata fields including packed_ready), the redirect to get_ui_state for the actual transcript, caching semantics, format constraints, and the end-to-end workflow. An agent has everything needed to call it correctly and know what to expect.

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 real value beyond the schema: it explains why enable_diarization matters ('without them a clip cannot tell a question from an answer') and when to disable it, and it ties the file_path parameter to the file-hash caching behavior. Remaining params (language, num_speakers, model_size) are adequately covered by the schema.

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

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

States a specific verb+resource: 'Transcribe a podcast video/audio file.' It clearly differentiates from siblings by declaring it's 'typically the first tool you call' and by explicitly noting the actual transcript body is NOT returned, which distinguishes it from get_ui_state and import_transcript. The Whisper AI + speaker-detection detail makes its function unmistakable.

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

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

Provides strong workflow context: explicitly labeled 'STEP 1', states when to call it versus later steps, and repeatedly routes to get_ui_state(include_transcript: true) and suggest_clips afterwards. It also gives a parameter condition (enable_diarization=false for single-speaker). However, it never names explicit alternatives for the 'already have a transcript' case (import_transcript/parse_transcript siblings), so there's no explicit when-not-to-use.

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

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

With no annotations, the description carries full responsibility. It discloses background execution, immediate return of job_id, and a required prerequisite (npm run ui). While it omits error scenarios or cancellation, it covers core behavioral aspects well.

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 focused and not overly verbose. The inclusion of a three-step flow adds operational clarity, though it slightly extends length. Overall structure is logical and easy to parse.

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

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

Given the absence of an output schema, the description does specify the return object { job_id, cached, status, estimate_minutes }, which is helpful. However, it does not detail parameter meanings or handle edge cases, leaving gaps for an agent needing full context.

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

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

The schema has zero description coverage, and the description does not explain any parameter individually (e.g., 'file_path', 'engine', 'language', 'model_size', 'num_speakers', 'enable_diarization'). Only 'file_path' is mentioned in passing within the flow, without elaboration.

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

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

Clearly states the action (start transcription), the resource (transcription), and the return (job_id). Explicitly contrasts with sibling 'transcribe_podcast' for long files, making the tool's distinct purpose unambiguous.

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

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

Provides explicit guidance: 'Use this instead of transcribe_podcast for long files' and describes a detailed flow (call, emit status, poll job_status, read transcript via get_ui_state). Also gives performance expectations (60-min episode → 15–25 min) and a prerequisite (Web UI running).

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.