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 the pipeline stages (validate, voiceover, record, compose), parallel execution, output path (`data/videos/`), and side effects of file creation. It also explains theme behavior and base_url auto-detection. However, it does not mention potential runtime, network dependencies, or destructiveness, which would improve transparency.

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

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

The description is well-structured with headings, bullet points for return format, and code examples. It is succinct (about 10 lines) with no redundant words. Every sentence contributes to understanding the tool.

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

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

Given the tool's complexity (multi-stage pipeline with external calls), the description covers the purpose, parameters, behavior, output structure, and examples. An output schema exists (not shown but referenced), so the return format description suffices. The description feels complete for an AI agent to use this 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 coverage is 100%, so the baseline is 3. The description adds meaningful context beyond the schema: it explains the theme values in terms of behavior (light mode toggle), clarifies auto-detection for `base_url`, and shows usage via examples. This adds significant 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 clearly states the verb 'Generate' and the resource 'demo video for a fleet repo'. It distinguishes itself from sibling tools (help, list, refine, script_draft, script_validate) by describing the full pipeline and final output, making it unambiguous that this is the main generation 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?

The description implies usage through the pipeline breakdown and examples, but it does not explicitly state when to use this tool versus the siblings (e.g., 'Use demo_vid_script_draft first to draft a script'). While the context is clear, there is no explicit 'when to use' or 'when not to use' 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 transparency burden. It explicitly states the action ('List') and provides the exact return format, clearly indicating a read-only operation. While it doesn't mention side effects, the nature of a help tool makes this self-evident.

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

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

The description is a single, front-loaded sentence followed by a compact return format block. Every element earns its place, and there is no wasted text.

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

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

For a zero-parameter tool with a simple output schema, the description is complete. It states the purpose and the exact return structure, and sibling context helps differentiate it from other tools. No critical information 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?

The tool has zero parameters, and the input schema is empty. Per the baseline for no parameters, a score of 4 is appropriate. The description adds no parameter details because none exist.

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 ('List') and identifies the exact resource ('all available demo-vid-mcp tools'), clearly distinguishing it from sibling tools like demo_vid_list (which likely lists videos) and demo_vid_generate. The purpose is 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?

The tool's purpose implies usage when an agent needs to discover available tools, but the description does not explicitly state when to use it versus alternatives like demo_vid_list or provide exclusions. Usage context is implied rather than stated.

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

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

With no annotations provided, the description carries the full burden for transparency. It discloses that the tool scans a local directory for .mp4 files, implying file-system access and a non-destructive read operation. However, it does not mention edge cases like empty directories, missing directory, or performance implications of scanning (e.g., large directories).

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 concise and well-structured, with 4 sentences plus a code block for the return format and examples. The key action ('List produced demo videos') is front-loaded, and every sentence adds value—detailing the scanning source, metadata, return format, and usage examples. No 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 the tool's simplicity (one optional parameter, output schema provided), the description covers the core functionality well. The return format and example usage are included, which compensates for the lack of annotations. However, it could briefly mention that the tool only lists already-existing videos (distinguishing from demo_vid_generate) and note potential issues like large directories.

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 has 100% coverage with a single parameter (repo) described as 'Filter by repo name (optional).' The description's examples show usage with and without repo, adding implicit meaning that filtering is optional. Since schema coverage is high, a baseline of 3 is appropriate; the description does not add significant semantic value beyond what the schema provides.

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

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

The description clearly states that the tool lists produced demo videos with metadata, specifying the source as the local data/videos/ directory for .mp4 files. It distinguishes itself from siblings like demo_vid_generate (which likely creates) and demo_vid_help (which likely provides assistance), though not explicitly naming alternatives.

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?

While the description explains what the tool does and provides an example for optional filtering by repo, it does not guide when to use this tool over siblings (e.g., when to call demo_vid_list vs demo_vid_script_draft or demo_vid_generate). There is no mention of prerequisites, context, or exclusions.

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

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

The description honestly discloses that the tool is a stub and returns a helpful message, with a stated return format. Annotations are absent, but the description provides clear behavioral context, including the 'success': False indication and suggestions list.

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 clear sections (rationale, return format, examples) and is appropriately sized for a stub tool. No wasted sentences, though the rationale could be more concise.

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

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

Given the tool is a stub, the description adequately covers its limited functionality and return format. The presence of an output schema and example adds completeness. No significant gaps for this 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 input schema has 100% description coverage, providing clear meanings for 'feedback' and 'video_name'. The description adds little extra beyond the schema, but an example use case is provided, which aids understanding. 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?

The description clearly states that the tool re-generates a video with timing or narration adjustments, distinguishing it from sibling tools like demo_vid_generate. However, it mentions it is a stub, which may slightly reduce clarity for agents expecting full functionality.

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 points to the working alternative (demo_vid_generate with updated script), offering good when-to-use guidance. However, it doesn't elaborate on when to use this tool vs other siblings, leaving some context implicit.

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

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

No annotations are provided, so the description carries the full burden. It discloses that the tool generates a 'placeholder' script, which is editable, and provides the return format. However, it does not discuss side effects, idempotency, rate limits, or authentication requirements. The description adds some behavioral context but is not comprehensive.

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 concise: three sentences plus a structured return format and an example. The first sentence clearly states the purpose, followed by the output format and a usage example. Every sentence serves a purpose, and there is no extraneous 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?

Given the tool's simplicity (one parameter, no annotations), the description is fairly complete. It includes the return format, links to the sibling tool demo_vid_generate for the workflow, and provides an example. However, it does not mention error conditions or prerequisites (e.g., repo existence). The output schema is not provided, but the description compensates with a return format.

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 has 100% description coverage for the single parameter 'repo' (description: 'Repository name to draft a script for.'). The tool description does not add additional meaning beyond the schema; it only uses the parameter in the example. With high coverage, baseline is 3, and no extra value 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: 'Draft a default narration script for a repo.' It specifies that it generates a placeholder YAML script for editing and passing to demo_vid_generate, distinguishing it from sibling tools like demo_vid_script_validate (validation) and demo_vid_generate (final generation).

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 a workflow: draft, edit, then pass to demo_vid_generate. However, it does not explicitly state when to use this tool versus alternatives (e.g., when to use demo_vid_refine instead), nor does it provide exclusion criteria or prerequisites. The guidance is implied but not explicit.

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 mentions checks for required fields and reasonable timing but does not disclose if the tool is read-only, whether it has side effects, or its behavior on validation failure (e.g., does it raise errors?). The description adds some behavioral context but lacks depth for a validation tool.

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

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

The description is concise with about 5 lines of prose plus a return format specification and example. It front-loads the core purpose and uses markdown headers for structure. No superfluous content.

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 tool has only one parameter (with 100% schema coverage), an output schema, and a clear validation purpose, the description covers the essentials. It provides return format and an example, but could add more context about error types or edge cases. General advice is addressed, but still complete enough for typical use.

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 baseline is 3. The description adds minimal value by stating the script must be YAML and listing expected fields like 'steps' and 'action', but does not elaborate on the parameter format or constraints beyond what the schema provides.

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

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

The description clearly states the tool validates a narration script for structure and timing, specifying the required fields and checks. It distinguishes itself from siblings like demo_vid_script_draft (which drafts scripts) and demo_vid_generate (which generates videos) but does not explicitly differentiate from all siblings.

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

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

The description implies use when you need to validate a script before generating a video, but it does not explicitly state when to use this tool versus alternatives like demo_vid_help for general help or demo_vid_refine for refinement. No when-not-to-use or alternative guidance is provided.

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