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

With no annotations, the description carries the full burden and does well: it states the file format (ASS v4.00+), the failure condition when the file exists (unless overwrite=true), and the output directory fallback chain. It omits return value specifics but covers the main side effects and preconditions.

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

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

The description is front-loaded with the primary action and then uses a structured @remarks/@param format. Every sentence adds value—no filler—and the organization makes it easy to scan.

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 has 7 parameters, no output schema, and no annotations, yet the description explains defaults, style details, overwrite logic, and environment variable fallbacks. It does not describe the return value or error cases beyond the overwrite condition, but for a file creation tool this is fairly 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 descriptions are absent (0% coverage), but the description provides @param lines for all 7 parameters, explaining meaning, optionality, defaults, and fallback behavior. This is a clear addition beyond the raw 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 opens with a specific verb and resource: 'Create a new ASS subtitle template file' and names the three included styles (Default, Title, Note). This is clear and distinct from sibling tools like ass__lint or ass__get_spec.

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 establishes clear context for when the tool is used (to generate an ASS template with pre-configured styles) and notes the overwrite behavior. It does not explicitly name alternatives or exclusions, but the purpose is apparent enough for an agent to choose it over siblings.

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 explicitly discloses the read-only nature, embedded content, and structured return format, providing adequate behavioral 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 concise and structured with @remarks and @param, front-loading the core purpose in the first sentence and keeping all content relevant 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?

For a simple reference tool with two fully described parameters, the description covers purpose, safety, and parameter semantics. It omits a detailed return schema, which is acceptable given the low complexity, but a bit more detail on the response structure would improve completeness.

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

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

Schema description coverage is 0%, but the description fully compensates by documenting both parameters: 'section' with allowed values/default and '__mcp_response_mode' with options, adding significant semantic meaning beyond the raw 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 'Returns the ASS (Advanced SubStation Alpha) subtitle format specification' with a specific verb and resource. The name ass__get_spec further distinguishes it from sibling tools like ass__create_template and ass__lint.

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 labels it as a 'Read-only reference tool' and notes that no external files or network access are required, establishing clear context for when to use it for spec lookups. However, it doesn't explicitly exclude alternative tools.

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 disclosure. It reveals that the tool validates ffmpeg presence and returns a small JSON health report, which gives a good sense of behavior. It does not discuss errors or side effects, but for a health check this is acceptable.

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 the core purpose, and the @remarks/@param annotations are compact. Every word adds value, with no fluff or repetition.

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

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

Given the simple schema (one optional param) and no output schema, the description adequately explains the tool's purpose and return type (JSON health report). It could specify the exact fields of the report, but for a health check the level of detail is sufficient.

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 includes a @param line that explains the __mcp_response_mode parameter as optional, with default 'content' and alternative 'structuredContent'. This adds human-readable meaning beyond the raw schema, which has no property descriptions. The meaning fully covers the single parameter.

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

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

The description uses a specific verb ('Check') and resource ('ASS tool bundle runtime dependencies'), clearly stating the tool's purpose. It distinguishes itself from sibling healthz tools by explicitly scoping to the ASS bundle and mentioning ffmpeg presence validation.

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 clearly states that this tool checks ASS runtime dependencies, providing context for when it applies. However, it does not explicitly mention alternatives or exclusions (e.g., use ffmpeg__healthz for ffmpeg-specific checks), so it lacks full cross-tool 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 full responsibility. It discloses that it runs 16 checks, returns a JSON report per check, and that strict mode adds field-count validations. It doesn't mention side effects, but a linter is inherently read-only and that is implied. The level of detail exceeds minimal expectations.

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 structured with @remarks and @param blocks, front-loading the primary purpose. It is somewhat detailed but not wasteful; each sentence contributes information about checks or parameters. Slightly verbose but acceptable.

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

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

With no output schema, the description mentions 'Returns a JSON report with per-check results', which gives a general sense. It doesn't detail the report structure or error handling, but the enumerated checks and strict-mode addition provide reasonable completeness for a validation 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 0%, but the description includes @param documentation for each parameter: ass_file_path (path), strict (enables additional checks), and __mcp_response_mode (response mode with defaults). This fully compensates for the schema's lack of description and adds meaning to each parameter.

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

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

The description starts with 'Lint and validate an ASS (Advanced SubStation Alpha) subtitle file', using a specific verb and resource. It clearly distinguishes itself from sibling tools like ass__create_template and ass__get_spec by focusing on validation/linting.

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 explains what the tool checks (16 structural rules, strict mode) and when strict mode is relevant. It doesn't explicitly state alternatives or exclusions, but the context is clear enough that no alternative lint tool exists among siblings.

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

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

No annotations are provided, so the description carries the full behavioral disclosure burden. It does disclose the ffmpeg lavfi virtual color source, the subtitles filter with libass dependency, and the output as a JSON summary or error payload. However, it omits important behavioral details such as whether the output file is overwritten, any permission requirements, or other side effects of writing files.

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

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

The description is front-loaded with the core purpose and then adds necessary mechanism and parameter details in a compact, organized structure. Each sentence contributes useful content with no filler, though the parameter list makes it slightly lengthy. Overall it earns its length.

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

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

For a tool with 7 parameters and no output schema, the description covers the operation, dependencies, output success/failure format, and parameter semantics with defaults and ranges. It does not detail the JSON summary structure or overwrite policy, but it provides enough for an agent to invoke the tool correctly and understand what will happen.

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 provides no descriptions (0% coverage), but the description's @param lines thoroughly document all seven parameters, including types, defaults, allowed ranges, and fallback behavior. For example, duration_sec is defined with a range of 1-300 and default 10, and output_dir's fallback chain is clearly described. This fully compensates for the schema gap.

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

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

The description opens with 'Render a short test video from an ASS subtitle file to verify renderability,' which names a specific verb, resource, and intended purpose. This clearly distinguishes it from sibling tools like ffmpeg__burn_subtitles by framing it as a smoke test for renderability rather than a final rendering 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 clearly states the use case: verifying renderability of an ASS subtitle file, and explains the ffmpeg lavfi/libass mechanism behind it. It does not explicitly name alternative tools or when-not-to-use conditions, but the smoke-test framing and sibling tool names provide enough context for an agent to understand when it should be used.

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

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

With no annotations, the description carries the full burden. It discloses the SIGTERM followed by SIGKILL escalation, which is meaningful behavioral detail. However, it omits consequences such as task state changes, return values, or whether the operation blocks until termination.

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 crisp sentences: the first states the primary action, the second adds the key behavioral detail. No wasted words, perfectly 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?

The tool is simple (1 param, no output schema), and the description covers the core purpose and signal flow. Yet it lacks guidance on taskId sourcing and post-cancel behavior, so it is adequate but not 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?

The description does not explain the taskId parameter at all. Schema coverage is 0%, and the description offers no guidance on how to obtain or validate taskId, leaving the agent without necessary semantic context even though the parameter name is somewhat self-explanatory.

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?

Description explicitly states the action: 'Cancel a running background task' with a specific verb and resource. It clearly distinguishes from sibling bg_task_list, bg_task_get, and bg_task_cleanup 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?

No guidance on when to use this tool vs alternatives. It does not mention that taskId should come from bg_task_list, nor that only running tasks are valid, leaving the selection logic entirely to the agent's inference.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It clearly reveals the destructive nature ('Remove') and the specific task states affected, which is good. However, it does not mention potential irreversibility, whether the removal is permanent across sessions, or any return value. For a cleanup operation, these details are relevant and would improve the agent's understanding of consequences.

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, consisting of two sentences. The first sentence delivers the core purpose immediately, and the second explains the optional parameter. There is no redundant information, and every word contributes to understanding the tool's behavior. It is appropriately front-loaded with the primary verb and resource.

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 low complexity (one optional parameter, no output schema), the description provides enough information to use the tool correctly. It states what is removed and how to scope the removal by age. However, it does not mention the return value or behavior when no tasks match, but this is a minor gap for a simple cleanup operation. Overall, it is sufficiently complete for the tool's scope.

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 sole parameter maxAgeMs is explicitly explained: 'Optionally specify maxAgeMs to only remove tasks older than the given milliseconds.' This adds meaningful context beyond the schema (which only gives type and bounds). Since schema description coverage is 0%, the description effectively compensates by fully explaining the parameter's purpose. No further elaboration is needed for such a simple parameter.

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

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

The description clearly states the tool's function: 'Remove completed, failed, or cancelled tasks from memory.' It uses a specific verb ('Remove') with a clear resource ('tasks') and qualifies the scope (completed/failed/cancelled), which effectively distinguishes it from sibling tools like 'builtin__bg_task_cancel' that target running tasks. The optional maxAgeMs filter adds further clarity about the intended cleanup behavior.

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 indicates what the tool does and mentions the optional maxAgeMs parameter for filtering by age. However, it does not explicitly state when to use this tool versus alternatives such as 'builtin__bg_task_cancel' or 'builtin__bg_task_list'. The usage is implied (cleanup of already-finished tasks) but not directly contrasted with sibling tools, leaving some ambiguity for an agent selecting between cleanup and cancellation.

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 behavioral disclosure. It discloses a key behavior: the tool returns full details plus stdout/stderr output. However, it doesn't mention error handling, whether output could be partial for running tasks, or any access limitations, but the 'Get' verb safely implies a read-only operation.

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

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

The description is a single, front-loaded sentence that conveys the action, target, scope, and return content with no wasted words. Every element earns its place.

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

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

For a simple get-by-id tool with one parameter and no output schema, the description is adequately complete. It specifies what is returned (full details, stdout/stderr). It could mention behavior for missing/invalid taskIds, but given the tool's simplicity and lack of annotations, this is a minor gap.

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 mentions 'by taskId', which adds minimal context to the parameter's name in the schema. The parameter name is self-explanatory, but the description doesn't elaborate on the format or source of taskId, leaving meaning mostly derived from the parameter name itself.

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

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

The description uses a specific verb ('Get'), names the resource ('full details of a background task'), and scopes it by 'taskId' and output content ('stdout/stderr output'). It clearly distinguishes this from sibling tools (bg_task_list, bg_task_cancel, bg_task_cleanup) by focusing on retrieving details for a single task.

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 clear usage context: you use this tool when you have a taskId and need full details including output. It doesn't explicitly name alternatives or when-not-to-use, but 'by taskId' strongly signals this is for individual task lookup rather than listing or cancellation, providing clear context without 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, the description must carry the burden. The description states it lists tasks, implying a read-only operation, but does not disclose any further behavioral details such as pagination, ordering, permissions, or output structure. This is a minimal but non-contradictory statement.

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 compact two-sentence statement, front-loaded with the primary action. Every word serves a purpose, with no redundancy or unnecessary detail.

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 tool with one optional parameter, the description is sufficiently complete. It covers the action and the filter capability. However, it does not describe the returned data structure, which would be helpful given the absence of an output schema.

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

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

The single parameter 'status' is described as an optional filter in the description ('Optionally filter by status'), adding meaning beyond the raw schema. The enum values are self-explanatory, and the description clarifies the parameter's purpose.

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: 'List all background tasks.' The verb 'List' and resource 'background tasks' are specific, and the optional filter adds scope. This distinguishes it from siblings like bg_task_cancel and bg_task_cleanup.

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 when to use the tool (when you need a list of tasks) but does not explicitly name alternatives or exclusion criteria. Sibling names make the distinction obvious, but the description itself lacks explicit '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?

With no annotations, the description carries the full burden. It discloses the output format ('Returns JSON in stdout with output_path and applied parameters'), the audio fade behavior, and the requirement that at least one duration be positive. However, it does not cover error behavior or file overwrite semantics, leaving some gaps.

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: a one-sentence purpose, a brief remarks section, and a parameter list. It is front-loaded and avoids unnecessary prose.

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 all seven parameters and shares the output format, which is important given the lack of an output schema. It also includes a key constraint. Some edge-case behavior is absent, but for the tool's complexity, the description is largely 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?

The schema provides no descriptions (0% coverage), so the @param lines are the sole source. Each parameter is clearly explained with defaults and value domains (e.g., fade_color: black or white), fully compensating for the schema's lack of descriptions.

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

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

The description opens with a clear, specific statement: 'Add fade-in and/or fade-out transitions to a video clip.' This specifies the verb (add), the resource (video clip), and the scope (fade transitions), distinguishing it from sibling ffmpeg tools like concat or split.

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. The @remarks mention a precondition (at least one duration > 0) but do not clarify use cases or compare with other ffmpeg tools.

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

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

No annotations are provided, so the description carries the full burden. It discloses the return format ('Returns JSON in stdout with output_path and lut_path') and the underlying ffmpeg filter, which is useful. However, it does not mention potential side effects like file overwriting or dependency on ffmpeg, leaving some behavioral uncertainty.

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, leading with a clear one-sentence purpose followed by @remarks and @param entries. Every line adds necessary 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?

Given the tool's moderate complexity, the description covers the operation, filter, return format, and all parameters. There is no output schema, so the explicit mention of JSON output is helpful. Minor gaps like file overwrite behavior prevent a perfect score.

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

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

Schema coverage is 0%, so the description's @param lines fully compensate by explaining each parameter's purpose (e.g., 'input_path Source video path', 'lut_path Path to a .cube format LUT file'). It also clarifies the default for __mcp_response_mode, adding value beyond the schema's enum.

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

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

The description opens with a specific verb and resource: 'Apply a .cube format 3D color Look-Up Table (LUT) to a video for color grading.' This clearly identifies the tool's function and differentiates it from sibling ffmpeg tools like add_fade or mix_audio_tracks.

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 context by specifying the use case ('for color grading') and mentions the underlying filter ('uses the ffmpeg lut3d filter'). While it doesn't explicitly state when not to use the tool or list alternatives, the context is sufficient for an agent to select it appropriately among sibling tools.

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

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

No annotations are provided, so the description carries the full burden. It does disclose that the video track is re-encoded and that JSON is returned, which are important behavioral facts. Yet it omits details about file overwriting, codec implications, or failure modes, leaving notable gaps for a mutation-like 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 well structured with a concise summary followed by @remarks and @param details. It is not overly terse, but each sentence adds value. It could be tightened slightly without losing essential information, so it earns a 4 rather than a 5.

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 operation, parameter meanings, consumption of ass__create_template output, re-encoding behavior, and return format. There is no output schema, so mentioning the JSON stdout is helpful. However, it lacks examples of complete usage or edge-case behavior, leaving a small but acceptable gap.

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

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

Schema coverage is 0%, but the description compensates fully by documenting all five parameters in @param lines. It goes beyond the schema by clarifying formats, providing an example for force_style, and explaining the response mode options. This is exactly what the description should do.

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

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

The description opens with a specific verb and object: 'Hard-burn SRT or ASS subtitle file into a video using the ffmpeg subtitles filter.' This clearly distinguishes it from sibling tools like mixing audio or applying color LUTs. It states exactly what operation is performed and on which resource.

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

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

It provides useful context: 'Consumes .ass files produced by the ass bundle (ass__create_template)' and mentions re-encoding and the output format. However, it does not explicitly contrast with alternative ffmpeg tooling or say when NOT to use it, so it stops short of a 5.

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

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

With no annotations, the description carries the full burden. It discloses that the tool uses the ffmpeg concat demuxer, returns JSON in stdout with output_path and clip_count, and provides defaults for reencode, video_codec, and audio_codec. However, it does not mention error behavior, file overwrite policies, or side effects on input files, which prevents a 5.

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

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

The description is compact and well-structured: a one-sentence purpose, a concise @remarks line with key guidance, and clear @param blocks. Every sentence adds value without excessive length 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?

Despite having 6 parameters and no output schema or annotations, the description manages to cover the main purpose, input format, output format, defaults, and a key usage caveat (re-encoding). Minor omissions like error handling and explicit overwrite behavior prevent a perfect score, but the overall completeness is strong.

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 0% description coverage, but the description's @param annotations thoroughly explain every parameter: input format and order for input_paths, destination for output_path, the condition for reencode, default codecs, and the response mode. This fully compensates for the schema's lack of 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 starts with 'Concatenate multiple video clips in sequence using the ffmpeg concat demuxer,' which states a specific verb, resource, and method. This clearly distinguishes it from sibling tools like ffmpeg__split_video or ffmpeg__add_fade, which have different operations.

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 usage condition: 'Use reencode=true when clips have different codecs or parameters.' It also explains the input path format and output behavior. While it does not explicitly name alternatives or exclusions, the context makes the tool's purpose and when to use it clear, warranting a 4.

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

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

With no annotations, the description takes on the full burden and discloses useful traits: input_paths accepts a comma/newline-separated list, output is JSON in stdout with output_path and clip_count, and all parameters have defaults. It does not mention overwrite behavior or resource implications, but it goes beyond the schema by returning format and input flexibility, which is stronger than the typical minimum.

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 tightly structured: a one-sentence purpose, then @remarks for input/output format, then @param lines for each parameter. It front-loads the key behavior and every line adds value without redundancy or 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?

The description covers purpose, all parameters with defaults, input format, and return value format. It does not include error behavior or examples, but with no output schema and a moderate parameter count, this is largely sufficient. The only gap is a deeper explanation of how the montage is assembled, but the parameters imply the sampling logic.

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 fully compensate. It does so with @param lines for all six parameters, adding meaning (e.g., input_paths as a comma/newline-separated list, clip_duration_sec as each sampled clip's duration, and defaults for interval_sec, clip_duration_sec, and merge_audio). This exceeds the schema's raw type/constraint information.

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 'Create a montage-style summary clip from one or more videos,' which clearly identifies the action (create), the deliverable (montage-style summary clip), and the input (one or more videos). This distinguishes it from sibling tools like concat_clips or split_video by focusing on summarization rather than concatenation or splitting.

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 purpose statement makes the tool's primary use obvious, but it does not explicitly state when to prefer this over alternatives or mention exclusions. Since the description gives a clear role, an agent can infer usage, but no alternative or when-not-to-use guidance is provided.

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 supported codecs, the crf/bitrate interaction, and the JSON stdout return format with output_path and applied parameters. It does not mention overwrite behavior or failure modes, but the provided details go beyond the basic name/schema and give the agent actionable expectations.

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 due to param listings, but each line adds necessary information because the schema provides no descriptions. The opening sentence front-loads the core purpose, and the @param lines are structured and scannable. No unnecessary filler, though it could be slightly more compact.

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

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

For a 12-parameter tool with no output schema and no annotations, the description covers a lot: all parameter semantics, defaults, return format, and mode selection. Missing details like overwrite behavior and error reporting prevent a 5, but the description is sufficiently complete for an agent to invoke the tool correctly in most cases.

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

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

Schema description coverage is 0%, but the description includes a @param entry for every one of the 12 parameters, adding defaults, examples, and mutual exclusivity. For instance, crf defaults vary by codec, bitrate overrides crf, and resolution keeps original if omitted. This fully compensates for the empty schema and exceeds the 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 opens with a specific verb and resource: 'Transcode a video to a delivery-grade output with full codec and quality control.' This clearly differentiates it from ffmpeg siblings like generate_proxy or generate_thumbnail, which serve different purposes. The scope (codec, quality control, delivery) is explicit and 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 description clearly explains parameter usage: use crf for quality-based encoding or bitrate for target-bitrate mode, notes that bitrate takes precedence, and provides sensible defaults for codec, crf, preset, etc. However, it does not explicitly mention when to prefer this tool over alternatives like generate_proxy, so it lacks explicit exclusions but still gives clear 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?

With no annotations provided, the description carries the full behavioral burden. It discloses that output is JSON on stdout, includes frame_paths and frame_count, and explains the output directory fallback chain (FFMPEG_OUTPUT_DIR or SHELL_AS_MCP_OUTPUT_DIR). This provides useful behavioral context, though it doesn't mention side effects like writing files or potential resource usage.

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

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

The description is front-loaded with a clear one-sentence purpose, followed by a concise @remarks line and structured @param entries. Each line serves a purpose and the whole document is easy to scan, with 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 complexity (8 parameters, no output schema), the description does an excellent job of covering return format, parameter semantics, fallback directories, and the overall purpose. It is nearly complete, though it doesn't specify the output image format or discuss edge cases like empty frame extraction, keeping it slightly short of a perfect score.

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 no descriptions (0% coverage), but the description includes a @param line for every one of the 8 parameters, with meaningful details such as an example for fps and an explanation for keyframes_only. This fully compensates for the schema gap and adds significant semantic 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 starts with 'Extract image frames for multimodal vision prompts,' clearly stating the verb and resource. It mentions returning JSON with frame_paths and frame_count, but does not explicitly differentiate from sibling tools like generate_thumbnail or process_video_for_llm, so it is clear but lacks sibling differentiation.

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 multimodal vision prompts but provides no explicit guidance on when to choose this tool over alternatives, nor any exclusions or prerequisites. It does not mention when to use this instead of generate_thumbnail or process_video_for_llm.

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 present, the description carries the full burden of behavioral disclosure. It explicitly notes that the tool returns JSON in stdout with output_path and applied parameters, and it documents defaults and aspect-ratio auto-calculation. However, it does not mention file overwrite behavior, whether the source file is untouched, or potential error conditions, leaving some behavioral aspects undisclosed.

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 an initial purpose sentence followed by a @remarks and @param block. It is slightly redundant because the first sentence and @remarks both describe proxy generation, but each parameter entry is concise and adds necessary value. The length is appropriate given the seven parameters.

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

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

For a tool with seven parameters, no output schema, and no annotations, the description covers all parameter semantics, defaults, and the output format. It lacks details on error handling, prerequisites like ffmpeg installation, and edge cases, but overall it provides sufficient information for an agent to select and invoke the tool correctly.

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

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

The input schema has zero descriptions (0% coverage), so the description must compensate. It provides detailed @param documentation for all seven parameters, including defaults (width=1280, crf=28, pixel_format=yuv420p), meaning (CRF lower = better quality), and purpose (fps to unify mixed-fps footage). This fully compensates for the schema's lack of descriptions.

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

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

The description opens with a specific verb 'Transcode' and clearly identifies the resource: 'high-bitrate source footage to an edit-friendly H.264 proxy.' This clearly distinguishes the tool from sibling operations like generate_thumbnail or export_video. The @remarks reinforces the purpose by stating it generates a lower-bitrate proxy for 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?

The description implies the applicable use case: converting high-bitrate source footage into an edit-friendly proxy. It provides clear context for when to use the tool, though it does not explicitly mention alternatives or when not to use it. The mention of 'edit-friendly' and 'proxy' is enough for an agent to differentiate from final export or thumbnail generation.

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 output is JSON in stdout containing output_path and applied parameters, that output format depends on extension, and provides defaults and quality semantics. This offers meaningful behavioral context, though it omits potential edge-case behaviors like error handling or file overwriting.

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 clear purpose sentence followed by @remarks and @param entries. Every line adds value, and while longer than the ideal two-sentence format, it remains concise and free of fluff. The use of parameter annotations aids scanning.

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 has 6 parameters, no output schema, and no annotations. The description covers purpose, all parameters, defaults, output format, and response mode, which is quite complete. It lacks only a few optional details like accepted timestamp formats or explicit error behavior, but given the moderate complexity, it is well-rounded.

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

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

Schema description coverage is 0%, and the description fully compensates by documenting all six parameters with clear semantics (@param input_path, output_path, timestamp, width, quality, __mcp_response_mode), including defaults, value ranges, and format guidance. This adds substantial meaning beyond the bare 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 'Extract a single frame from a video at a specified timestamp to use as a thumbnail or poster image.' This uses a specific verb and resource, and explicitly mentions 'single frame' and 'thumbnail or poster', which distinguishes it from sibling tools like extract_frames_for_vision that extract multiple frames for other purposes.

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 by specifying the intended use case (thumbnail/poster). However, it does not explicitly mention alternative tools or when not to use this tool, so it lacks explicit exclusions but still gives enough context for selection.

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 burden. It discloses the output format (JSON with version and health status) and the check nature, implying a read-only, non-destructive operation. It does not explicitly state side effects, but none are expected for a health check.

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 short, well-structured sentences. It front-loads the core purpose, then adds remarks and parameter details without redundant text or filler.

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

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

For a simple health check with no output schema, the description adequately summarizes the return content. It could be more complete by specifying exact health status values or behavior when ffmpeg is unavailable, but the low complexity keeps this from being a major gap.

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 only parameter is fully described by the schema via enum and default. The @param line merely restates this information without adding meaning, such as when to use structuredContent versus content or how the response differs. Schema description coverage is 0%, but the description fails to compensate with deeper semantics.

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

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

The description clearly states the tool's purpose with a specific verb ('Check') and resource ('ffmpeg runtime dependency availability'). It also mentions it returns version and health status, which distinguishes it from sibling healthz tools like shell__healthz and ass__healthz via the ffmpeg prefix.

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

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

Usage is implied: the tool is for verifying ffmpeg availability, presumably before ffmpeg operations. However, the description gives no explicit when-to-use or when-not-to-use guidance, nor does it name alternative healthz tools for other runtimes.

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

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

With no annotations, the description carries the full burden. It discloses the output format ('Returns JSON in stdout with output_path and applied volume parameters') and default volume values, which is valuable. It does not mention potential failure modes or file overwrite behavior, but overall it provides meaningful behavioral insight.

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

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

The description is front-loaded with the primary action, followed by a useful 'remarks' note and then a structured parameter list. Each sentence adds value, though the @param list is lengthy; however, this is justified given the schema has no descriptions.

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?

Despite having no output schema or annotations, the description covers core behavior, parameter semantics, and return format. It lacks details on edge cases (e.g., file overwrite, invalid paths) but is sufficiently complete for an agent to use the tool correctly in typical scenarios.

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%, but the description compensates fully with @param annotations for all 7 parameters, including defaults and allowed values (e.g., duration strategy and __mcp_response_mode). This goes well beyond the schema and directly supports correct invocation.

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 a specific verb ('Mix'), the resource ('two audio tracks'), and mechanism ('amix filter'), distinguishing it from sibling tools like ffmpeg__normalize_audio and ffmpeg__concat_clips. It leaves no ambiguity about the tool's function.

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 'Typical use' workflow ('normalize voice first, then mix with BGM using a low bgm_volume'), which gives clear context for when to apply this tool. It does not explicitly name alternatives or state when not to use it, but the context is enough to guide an agent.

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

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

With no annotations, the description carries the full burden. It discloses that the original audio track is discarded, states that output is JSON in stdout, and notes default behaviors for audio_delay_ms and reencode_audio. This adds significant behavioral context beyond the schema.

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

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

The description is well-structured with a clear opening sentence, @remarks, and @param lines. It is longer than minimal, but the length is justified by the complete parameter documentation needed due to zero schema coverage. Every sentence contributes value.

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?

Despite having no output schema, the description explicitly states the return format (JSON with output_path and applied parameters) and key side effects (original audio discarded, stream copy default). It also covers all six parameters with defaults and behavior, making the tool fully understandable for an agent.

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's @param annotations are essential and fully compensate. Each parameter gets meaningful explanation: video_path discards original audio, audio_delay_ms positive means delay, reencode_audio default false means stream copy, and __mcp_response_mode has an enum. This is comprehensive parameter semantics.

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

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

The opening sentence clearly states the tool's function: 'Replace or attach an audio track to a video by muxing a separate audio file.' This is specific and distinguishes it from sibling tools like mix_audio_tracks by explicitly noting that the original video audio is discarded.

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 with 'Typical use: attach a mixed or dubbed audio track to a graded video.' However, it does not explicitly mention alternatives or when not to use this tool, so it stops short of a full 5.

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

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

There are no annotations, so the description carries the full burden. It discloses the output behavior ('Returns JSON in stdout with output_path and applied normalization parameters') and gives defaults, which is useful. However, it does not mention whether the output file is overwritten, what happens if the input is a video vs audio, or error handling, leaving some ambiguity.

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: a single purpose sentence, a remark about output/defaults, and parameter list. Every sentence carries necessary information without 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 a 6-parameter tool with no annotations or output schema, the description covers purpose, all parameters with defaults, return format, and input types (audio or video path). It does not cover edge cases like overwrite behavior or error handling, but overall it is reasonably complete for an ffmpeg audio 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 has 0% description coverage, but the tool description compensates with a @param line for each of the 6 parameters, including clear explanations and defaults. This fully adds meaning beyond the bare schema types.

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: 'Normalize audio loudness to a target EBU R128 LUFS using the ffmpeg loudnorm filter.' This is a specific verb and resource (loudness normalization) and distinguishes it from sibling ffmpeg tools like mix_audio_tracks or mux_audio.

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 context by noting the default target of -14 LUFS is 'suitable for most streaming platforms (YouTube, Spotify),' implying when to use the default. However, it does not explicitly state when not to use this tool or mention alternatives, so it falls short of a 5.

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

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

With no annotations provided, the description carries the behavioral disclosure burden. It reveals the tool returns ffprobe JSON output to stdout containing streams and format information, which is a key behavioral trait. It does not mention failure conditions or side effects, but for a read-only probe operation this is adequate.

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 uses a structured @remarks/@param format that is easy to parse. There is slight redundancy between the opening sentence ('return full metadata as JSON') and the @remarks line ('Returns ffprobe JSON output in stdout'), but it is not verbose and every line earns its place.

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

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

For a simple probe tool with no output schema, the description covers the essential aspects: what it does, the parameters, and the return format. It omits details like error handling or file accessibility, but these are not critical for such a straightforward operation. The absence of annotations is offset by the parameter and output disclosures.

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 zero description coverage, but the description fully compensates with explicit @param lines: input_path is defined as the source media file path, stream_type explains filtering with default 'all' and valid values 'video' or 'audio', and __mcp_response_mode clarifies the 'content' default and 'structuredContent' option. This adds significant meaning beyond the bare schema types.

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

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

The description opens with a specific verb and resource: 'Probe a media file and return full metadata as JSON using ffprobe.' This clearly states what the tool does and its output format. The use of 'probe' and 'metadata' distinguishes it from sibling ffmpeg tools that process or transform media rather than inspect it.

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

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

Usage is implied: use this tool when you need to inspect a media file's metadata. There is no explicit 'when to use vs alternatives' or exclusionary guidance, but the purpose is clear enough that an agent would naturally select it for probing. No sibling tool performs the same role, so explicit alternatives are not necessary.

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 returns a JSON summary in stdout with output_path and normalization parameters, and it mentions defaults and the compact audio output. This goes beyond the schema and gives the agent a clear picture of behavior, though it does not cover every possible side effect like overwrite policies.

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: a one-sentence summary, followed by @remarks and @param lines. Every line adds value, and the most important information is front-loaded. Despite the length, it is concise because no words are wasted.

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

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

The description is complete for a complex tool with 9 parameters and no output schema or annotations. It covers the purpose, return format, parameter defaults, and input/output paths. It even explains the optional response mode, leaving little ambiguity for an agent.

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 fully compensates. It provides @param lines for every parameter with examples (e.g., '00:04:30'), defaults, and value meanings (e.g., sample_rate default 16000, remove_silence default true). This adds substantial meaning that the schema lacks.

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

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

The description opens with a specific verb phrase: 'Build a Whisper/STT-ready compact audio output from either audio or video input.' This clearly states what the tool does and its scope, distinguishing it from sibling tools like ffmpeg__normalize_audio or ffmpeg__mix_audio_tracks.

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 its use case via 'Whisper/STT-ready', which is clear guidance for when to select this tool over generic audio processing. However, it does not explicitly mention when not to use it or name alternatives, so it stops short of full exclusion criteria.

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 disclosure. It does reveal that the tool returns a compact JSON summary in stdout, which is useful contextual information. However, it does not mention whether the output file will be overwritten, permission requirements, or failure modes, leaving some behavioral gaps for a write operation.

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

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

The description is well-structured with a concise opening summary followed by a systematic @param list. While it is somewhat long due to the number of parameters, each line serves a purpose and the front-loaded purpose statement is effective.

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

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

For a 10-parameter video processing tool with no output schema, the description provides a clear output contract (JSON summary), documents all parameters with examples, and explains the combined operation. It lacks detail on error handling or edge cases, but overall it is sufficiently complete for an agent to invoke correctly.

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

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

Schema description coverage is 0%, but the description includes @param lines for all 10 parameters with clear explanations and examples (e.g., 'max_resolution Optional longest-edge cap (for example 720)'). This fully compensates for the schema's lack of descriptions and adds significant meaning beyond raw types.

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: 'Build an LLM-ready video in one ffmpeg run' and enumerates specific operations (trim, scale, fps, speed, optional audio strip, watermark). This distinguishes it from sibling tools like add_fade or extract_frames, which have narrower scopes.

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 preparing videos for LLM consumption and mentions optional operations, but does not explicitly state when to prefer this over using separate ffmpeg tools or alternatives. No exclusions or alternative tool references are provided.

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 fully discloses behaviors: it states the JSON stdout output structure, fallback to FFMPEG_OUTPUT_DIR or SHELL_AS_MCP_OUTPUT_DIR, and the re-encoding default with its keyframe misalignment consequence. This is 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 well-structured: a one-sentence purpose, a remarks block for shared behavior, then per-parameter docs. Every line adds value with no wasted words or repetition.

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

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

Given six parameters and no output schema, the description covers all inputs, the output JSON shape, environment fallbacks, and behavioral nuances. An agent would have everything needed to invoke and understand the result.

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

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

The schema has 0% description coverage, but the @param lines explain every parameter, including examples (split_points), defaults (output_prefix, reencode), and fallback logic (output_dir). This fully compensates for the schema's silence.

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 'Split a single video into multiple segments at specified timestamps,' using a specific verb and resource while scoping the operation. This clearly distinguishes it from sibling tools like concat_clips or extract_frames.

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 context on how to use the tool, including the required parameters and flexible timestamp formats. It explains the reencode default and its trade-off, but does not explicitly name alternatives or when-not-to-use conditions.

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 explaining behavior. It discloses the return structure (system and dev_environments sections), contents of each, and tool count (~35). It also explains parameter defaults and semantics. It does not mention potential side effects (likely none) or error behavior, but otherwise provides substantial 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 a purpose statement, @remarks, and @param sections. Every sentence adds value, with no fluff. It front-loads the key purpose and uses a consistent JSDoc style that makes scanning easy. Despite length, it remains concise 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 tool's purpose, return sections, parameter behaviors, and ideal invocation context. Since there is no output schema or annotations, it adequately substitutes for them. It does not provide a sample output or exhaustive list of the ~35 tools, but for a retrieval/inspection tool, the level of detail is sufficient. Minor room for improvement in describing return types or edge cases.

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

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

Schema parameters have no descriptions (0% coverage), but the description fully compensates with @param documentation for all four parameters. It explains meanings, defaults, format examples ('python3,node,rustc'), and the effect of empty filter_tools. This exceeds baseline by making every parameter self-explanatory.

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 'Collect host system context for code development tasks in a single call,' which clearly states the action, resource, and purpose. It distinguishes itself from sibling tools like host_info__healthz by focusing on system context rather than health checks. The 'Ideal as a first call' note further articulates its role.

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 guidance on when to use it ('before writing or running code on the host'), but does not mention when not to use it or name alternative tools. Since sibling tools are mostly unrelated, this is not a major gap, but it falls short of the 'explicit when-not/alternatives' level.

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 carries the burden. It discloses the main behavior (checking uname availability) and the output (compact JSON report). It does not explicitly mention side effects, but as a healthz tool, read-only behavior is implied. It adds useful context beyond just the name.

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 well-structured sentences: the first states the primary purpose, the second adds a remark about the verification and output, and the @param annotation is concise. Every sentence earns its place with 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?

The description tells the user the tool emits a 'compact JSON report', but does not specify the report's structure or fields. Since there is no output schema, this is a gap. It is adequate for a simple health check, but not fully complete for an agent that needs to interpret the result.

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

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

The @param line describes the only parameter, but it largely mirrors the schema's enum and default values. It clarifies 'content' vs 'structuredContent' as response modes, but does not explain what each mode returns. Since the schema already provides the options, the description adds minimal extra meaning.

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

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

The description states a specific verb ('Check') and a clear resource ('whether host_info bundle can access basic host context commands'), and further clarifies with 'Verifies uname availability'. This distinguishes it from sibling healthz tools by focusing on the host_info bundle and uname.

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 when to use the tool (to verify host_info bundle's access to basic host context commands), providing clear context. However, it does not explicitly exclude alternatives or state when not to use it, so it lacks full exclusions.

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

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

No annotations exist, so the description carries the burden. It discloses behavioral traits such as the use of quality gates and iterative repair rounds (max_repair_rounds), but it does not describe the return format, side effects, or failure behavior, leaving some transparency gaps.

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 opens with a concise, front-loaded purpose statement and then uses a structured @param list. Every line is informative and scannable, with no redundant or filler 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?

The description thoroughly documents parameters but omits the return value or output structure, which is important given there is no output schema. It also lacks explicit usage prerequisites or when-to-use guidance, making it incomplete in context but adequate for basic invocation.

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

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

The @param lines add meaningful human-readable definitions for all 9 parameters, compensating for the 0% schema description coverage. It explains each parameter's role, optionality, defaults, and mode-specific behavior, providing value beyond the bare type declarations.

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 action ('generate a shell-as-mcp bundle') and a target location (SHELL_AS_MCP_SPEC_DIR). This clearly distinguishes the tool from all siblings, which are in unrelated domains like ffmpeg or ytdlp.

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 a shell-as-mcp bundle is required, but it does not explicitly state when to use this tool versus alternatives or provide any exclusions. There are no direct runprompt siblings besides healthz, so the usage context is mostly self-evident but not spelled out.

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

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

With no annotations provided, the description carries the full disclosure burden. It discloses that the tool checks python3 availability and returns a JSON version, which gives useful insight into behavior. However, it does not explicitly state whether the operation is read-only or whether there are side effects, though 'Check whether' suggests non-destructive. It also does not mention error handling or exit behavior.

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

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

The description is concise and well-structured, with the primary purpose stated in the first sentence, followed by a @remarks line with key behavioral details and a @param line for the parameter. Every sentence provides value with no redundancy or 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?

For a simple healthz tool with one optional parameter and no output schema, the description is quite complete. It states what is checked, what is returned, and the parameter semantics. It does not describe failure modes or exit codes, but for a health check this may be acceptable. The sibling healthz tools are distinguished by the 'runprompt' bundle reference.

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 a single parameter with an enum but no description, and schema description coverage is 0%. The description compensates by explicitly explaining the `__mcp_response_mode` parameter, its allowed values, and its default, which aligns with the schema but adds clarity for an agent.

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 'Check' and identifies the resource as 'runprompt bundle runtime prerequisites', which clearly distinguishes it from other tools. It further specifies that it verifies python3 availability and returns the version in JSON, leaving no ambiguity about the tool's function.

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 context by stating that this tool checks runtime prerequisites, implying when it should be used. However, it does not explicitly mention alternatives or exclusion criteria, though the bundle name 'runprompt' differentiates it from sibling healthz tools.

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 discloses read-only behavior via 'read' and describes parameter behavior (include_rotated, rotated_file_limit). However, with no annotations, it lacks details on side effects, permission requirements, or what happens when audit files are missing or unreadable.

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: one opening sentence plus compact parameter docs. No redundant text, and the structure is easy to parse. Every word adds value.

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?

All parameters are well-documented, making the tool usable, but the response format is not described. Since there is no output schema, the agent is left guessing what the audit records look like (fields, ordering, etc.). Missing this context reduces completeness.

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

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

Schema coverage is 0%, but the description provides explicit @param documentation for all four parameters, including defaults (20, true, 10) and range (1-50). This fully compensates for the schema's lack of descriptions and adds semantic meaning.

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

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

The description clearly states the tool reads recent run_safe_command execution audit records, using a specific verb ('read') and resource ('audit records'). This distinguishes it from sibling tools like run_safe_command__audit_rotate, which implies a different (write/management) function.

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

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

Usage context is implied by the tool name and description: if you need to view audit logs, this is the tool. However, it does not explicitly mention when to use this versus alternatives, nor does it reference the related audit_rotate tool or any 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 to rely on, the description carries the full burden of behavioral disclosure. It mentions 'immediately' and 'enforce retention' but does not explain what happens to the existing audit file, whether old files are deleted, if the operation is reversible, or any side effects. The lack of context leaves the agent unsure of the tool's safety profile and consequences.

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. The main action is front-loaded in a single sentence, and parameter docs are appended in a clear @param format. Every sentence earns its place without unnecessary 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 relative simplicity (two optional parameters, no output schema), the description covers the core purpose and parameters. However, it lacks information about return values, error conditions, and the exact retention behavior (e.g., whether max_files deletes oldest files). A bit more context on outcomes would make it 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?

The description compensates for the 0% schema description coverage by explaining both parameters: max_files is the optional retention count with a range of 1-100, and __mcp_response_mode is an optional response mode with a default of 'content'. This provides meaning and constraints beyond the raw schema types.

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 (rotate), the resource (run_safe_command audit file), and the effect (enforce retention) in a specific verb+resource form. It distinguishes from sibling tools like run_safe_command__audit_get and run_safe_command__execute by focusing on rotation, a distinct maintenance operation.

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 guidance is provided on when to use this tool versus alternatives. The description implies a specific operational task but does not state prerequisites, situations where it should be preferred, or exclusions. It would benefit from a note like 'Use when you need to immediately archive and limit audit logs' or a comparison to audit_get.

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 does disclose useful behavioral traits: commands are executed without shell eval, in a validated working directory, runtime control behaviors are internal-only, and darwin/arm64 uses a specific auth fallback. However, it does not describe the return format, side effects, or error behavior, which would make it more complete.

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 front-loaded, with a clear opening sentence followed by focused @remarks and well-structured @param explanations. Each sentence provides meaningful information without fluff, and the overall length is appropriate for the tool's four parameters.

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

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

Given the absence of an output schema and annotations, the description does not explain return values, exit codes, or potential side effects, leaving a notable gap for a command execution tool. It covers usage and safety constraints well, but the lack of output structure means an agent may not know what to expect beyond the vague 'structured security and audit metadata.'

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%, but every parameter is documented in the description with practical examples: 'command' is described as an executable name with examples, 'args_json' includes an example JSON array string, 'working_dir' is defined as an absolute path, and '__mcp_response_mode' is explained with its default. This fully compensates for the lack of schema descriptions.

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

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

The description opens with 'Execute a command safely with structured security and audit metadata,' a specific verb and resource that clearly states the tool's function. It also distinguishes itself from sibling tools by emphasizing safe execution without shell eval and structured audit metadata, setting it apart from simpler shell execution 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 implies usage for safe command execution ('Execute a command safely') and highlights key constraints like no shell eval and validated working directory, but it does not explicitly state when to use this tool versus alternatives such as shell__run_script_echo or run_safe_command__pipeline. No exclusions or alternative recommendations are provided.

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

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

With no annotations, the description carries the behavioral disclosure burden. It adds a meaningful behavior: missing optional trace tools are reported as warnings, not hard failures. This gives insight into how the tool handles partial environments. It does not mention side effects, but the verb 'Check' implies a non-destructive read-only operation. The description adds useful context beyond the bare minimum.

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 no fluff, using clear tags (@remarks, @param). It front-loads the core purpose in one sentence. The @param line is arguably redundant with the schema but still compact. Overall, well-structured and 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?

For a simple healthz tool with one optional parameter and no output schema, the description covers the main purpose and a key behavioral trait (warnings for missing optional tools). It does not describe the return format, but given the tool's simplicity and the presence of sibling healthz tools, the description is reasonably complete. A more detailed return contract would be helpful but is not essential.

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 fully describes the sole parameter with enum values and a default. The description's @param line simply restates the schema information ('content (default) or structuredContent') without adding new meaning. Since schema coverage is effectively complete for this parameter, 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 states a specific verb ('Check') and a specific resource ('run_safe_command runtime dependencies and platform capabilities'). It clearly differentiates this healthz tool from the various sibling healthz tools by scoping it to run_safe_command. This is a precise, non-tautological statement of 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?

The description implies usage as a health check for run_safe_command, but it does not explicitly state when to use it versus alternatives (e.g., other healthz tools) or provide any exclusions. The context is understood but not articulated, so it falls in the 'implied usage' category.

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 transparency. The verb 'Show' implies a non-mutating, informational tool, but it does not explicitly state that it has no side effects or that it is read-only. It also does not mention any permissions or rate limits, which is a gap for a help 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 extremely concise: one clear declarative sentence followed by two compact parameter lines. Every word earns its place, and the structure is front-loaded with the primary purpose before parameter details.

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 help tool with two optional parameters, the description covers its purpose and parameter semantics sufficiently. However, it does not describe the output format or what happens when no topic is provided, which would be useful for an agent to 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?

The @param annotations in the description provide meaningful guidance for both parameters: topic is explained as optional and lists valid filter values (execute, audit, healthz, security), and __mcp_response_mode is described with its options and default. This adds substantial value since the input schema has no property descriptions (0% schema description coverage).

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

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

The description opens with a specific verb ('Show') and names the resource ('usage and safety model for run_safe_command tools'), making the tool's purpose immediately clear. This clearly distinguishes it from all sibling tools, which perform actual commands like execution, auditing, or health checks.

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 establishes that this tool provides help specifically for run_safe_command tools, which implies when to use it. However, it does not explicitly compare it to alternatives or state when not to use it. The context is clear enough for an agent to infer usage.

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 the safety model: validation against an allowlist, subprocess chaining via Popen (not shell eval), explicit command allowlist, and prohibition of destructive/network commands. It also notes platform-specific auth behavior (native Swift+WKWebView fallback to OSA on darwin/arm64). These are significant behavioral traits not visible elsewhere.

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

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

The description is front-loaded with a one-sentence purpose, followed by structured @remarks and @param blocks. Every sentence adds value: safety implementation, allowlist details, sibling differentiation, and parameter semantics. No filler or repetition; the length is justified by the tool's complexity.

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 rich in purpose, parameters, and safety behavior, covering most context needed. However, it lacks any statement about return values or output format (e.g., stdout/stderr). Since there is no output schema, this information would complete the picture. Minor gap, but the rest is comprehensive.

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

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

Schema description coverage is 0%, so the description must compensate. It does so thoroughly: @param stages_json explains the JSON array structure, required keys, lists valid commands, and gives a concrete example. @param working_dir specifies 'absolute working directory shared by all pipeline stages.' @param __mcp_response_mode explains the enum options. This adds substantial meaning beyond the raw 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 opens with a specific verb and resource: 'Execute a safe shell pipeline from structured stage definitions.' It clearly distinguishes itself from the sibling tool by stating 'Unlike run_safe_command__execute, this tool accepts pipe-connected stage sequences but applies stricter per-stage command validation to compensate.' This is a clear, specific purpose that differentiates from 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?

The description explicitly names the alternative run_safe_command__execute and notes the key difference (pipe-connected stages vs. presumably single command). It also gives context on when this tool is appropriate (when you need a pipeline of allowlisted commands) and mentions validation and auth behavior. However, it does not explicitly state the inverse condition (e.g., 'use execute for single commands'), so it stops short of a full when/when-not prescription.

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 burden. It states that the tool verifies bash presence and returns JSON status, which implies a read-only operation. However, it does not explicitly confirm no side effects or disclose any potential edge cases (e.g., timeout, exit codes), leaving some ambiguity.

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 a clear structure: a one-line summary followed by a @remarks and @param. No filler; every sentence adds value.

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 health-check tool with no output schema, the description adequately states what it checks and the return type ('JSON status'). However, it does not detail the structure of the JSON or the exact meaning of 'basic runtime' beyond bash presence, leaving a small gap in completeness.

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

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

Schema description coverage is 0%, but the description fully compensates with the @param line: 'Optional response mode: content (default) or structuredContent.' This explains the parameter's meaning and default, which the schema lacks entirely.

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?

Description clearly states the tool's purpose: 'Check whether shell bundle basic runtime is available' and further specifies it verifies 'bash command presence'. This distinguishes it from sibling healthz tools (ffmpeg, ytdlp, etc.) by scoping to the shell bundle.

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 does not explicitly state when to use this tool versus alternatives, but the name and purpose imply it is the health check for the shell bundle. Usage context is implied but not elaborated, such as when you need to verify shell capabilities before running scripts.

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 only says 'run a script and echo,' but does not mention side effects, return format, potential for shell injection, error behavior, or whether it executes arbitrary code. This is a significant transparency 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 front-loaded: a single sentence followed by param annotations. It wastes no words, though the phrase 'with prefix' is vague and could have been clarified. Overall, it is appropriately concise for a simple 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?

The description omits critical context: what script is executed, what 'prefix' means, and the expected output/response shape. Since there is no output schema, the description should at least mention return behavior, but it does not. This leaves the agent underinformed.

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 includes @param annotations explaining both parameters: 'value' is described as the input value passed to the script, and '__mcp_response_mode' is clarified as optional with a default. This adds meaning beyond the bare schema, which only shows types and enums. Schema coverage is 0%, but the description compensates adequately.

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

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

The description clearly states the action: 'Run a local script and echo the input value with prefix.' This names a specific verb and resource, distinguishing it as an echo/script-running tool. However, it lacks detail about what 'prefix' refers to or which script runs, so it falls short of a 5.

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

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

No usage guidance is provided. The description does not indicate when to use this tool over siblings like run_safe_command__execute or shell__healthz. There are no exclusions, alternatives, or context hints, so it provides no 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. It discloses output format (m4a), quality selection (best-quality audio track), fallback directory order, support for cookies/proxy, and retry cap. It omits response/return value details, but given the tool's nature (audio download) and the amount of behavioral context provided, it is sufficiently 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 with a front-loaded summary followed by @remarks and @param annotations. Each line adds unique value—no fluff. The @param block is necessary given the 0% schema coverage, and 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 has moderate complexity (network access, optional authentication, fallback directories, retries). The description covers all parameters, output format, quality, and default behavior. However, it does not describe what the tool returns (no output schema), which would be useful for the agent to know. This minor gap prevents a perfect score.

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%, but the description uses @param tags to explain all six parameters with constraints (URL must start with http/https), examples (proxy), fallback logic (output_dir), defaults (maxRetries capped at 2), and formats (cookies Netscape). This fully compensates for the missing schema 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 clearly states the verb 'Download', the target resource 'audio from a video URL', and the output format 'm4a'. It distinguishes itself from sibling tools like ytdlp__download_video by focusing on audio extraction and mentioning 'Extracts best-quality audio track'.

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 clearly implies when to use this tool (when audio is needed) but does not explicitly name alternatives or exclusion cases. Sibling tool names are visible, but the description itself does not compare with download_video or download_transcript. Still, the context 'Download audio' is clear enough for an agent to infer appropriate 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 the full burden and discloses key behaviors: downloads to a temp dir, converts/strips timestamps and duplicates, then cleans up. It also notes maxRetries cap at 2. It omits potential failure modes but provides substantial internal process detail.

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

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

The description is front-loaded with a one-sentence summary, followed by a structured @remarks block and param annotations. Every sentence adds value, and the format makes it easy to parse both behavior and parameter semantics without 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 7 parameters, no output schema, and no annotations, the description is quite complete: it explains the internal pipeline, temp file handling, cleanup, and all parameter semantics. It stops short of describing return values or error scenarios (e.g., missing subtitles), but it covers the essential context for safe usage.

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

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

Schema coverage is 0%, so the description must fully explain parameters. Each @param adds meaning beyond the schema: url protocol requirement, language default, output_dir conditional side-effect, cookies format, proxy, maxRetries cap, and response mode enum. This completely compensates for the schema's lack of 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 action ('Download and extract plain-text transcript') and resource ('from a video URL using yt-dlp'), clearly distinguishing it from siblings that download raw subtitles or other media by emphasizing the plain-text transcription output.

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 when to use it (when you need a plain-text transcript) by explaining the VTT-to-text conversion and cleanup, but it does not explicitly name alternatives or state when not to use it, such as when raw subtitle files are needed instead.

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

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

With no annotations, the description carries the full burden of behavioral disclosure. It adds meaningful details: the fallback to environment variables and ~/Downloads, the constraint that trimming requires both times, the default resolution, and the maxRetries cap. It does not mention failure handling or whether files are overwritten, but for a download tool, the provided behavioral context is quite useful.

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 concise opening sentence, a @remarks section for special behavior, and @param entries for each parameter. Every line adds value and is not redundant. The structure improves scannability and helps an agent quickly extract parameter semantics.

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 parameters and key behaviors, but it does not describe the return value or what the output looks like (e.g., file path, status message). Since there is no output schema, the description should clarify the result format. Also, error scenarios and edge cases (e.g., invalid URL, network failures) are not addressed, leaving an incomplete picture for the agent.

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 fully compensates by documenting every parameter with @param lines. It adds format constraints (URL must start with http/https), resolution choices with a default, examples for time strings, the fallback order for output_dir, and the cap on maxRetries. This goes well beyond the bare 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 opens with a clear, specific verb+resource statement: 'Download a video from a URL using yt-dlp, saving to output_dir or a configured default directory.' This clearly distinguishes the tool from siblings like ytdlp__download_audio and ytdlp__download_video_subtitles by focusing on video download and output behavior.

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 usage context such as resolution selection, optional time-range trimming, and the requirement that both startTime and endTime be provided together. It also explains fallback directories and the maxRetries cap. However, it does not explicitly state when to prefer this tool over alternatives (e.g., ytdlp__download_audio), so it falls short of full 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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It discloses some important behaviors: downloads both manual and auto-generated subtitles without the video, saves to output_dir with a fallback chain (YTDLP_OUTPUT_DIR, SHELL_AS_MCP_OUTPUT_DIR, ~/Downloads), and caps maxRetries at 2. However, it does not state whether existing files are overwritten, what happens when subtitles are unavailable, or what the return value looks like. This is a moderate level of 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 efficiently structured: a first sentence stating the purpose, a @remarks line with a key behavior, then a clean @param list. There is no filler or redundant content. Every sentence and parameter line adds useful information, and the format is 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?

The tool has 7 parameters, no output schema, and no annotations, so the description must cover essentials. It does cover the operation, output location fallback, and parameter semantics. However, it lacks a description of the return value (e.g., saved file paths) and does not mention failure modes or prerequisites like yt-dlp availability. These gaps prevent it from being fully complete, though it covers the core functionality.

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 0% description coverage, but the description compensates with detailed @param annotations for all seven parameters. For example, it specifies URL must start with http:// or https://, language defaults to 'en', output_dir has a specific fallback order, cookies must be Netscape-format, and maxRetries is capped at 2. This adds meaning beyond the raw schema. Some params like 'proxy' are terse, but overall all params are explained.

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

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

The description opens with a specific verb and resource: 'Download subtitle files (VTT) for a video URL using yt-dlp, saving to output_dir or a configured default directory.' It clearly distinguishes itself from sibling tools like download_audio, download_video, and download_transcript by explicitly stating it downloads only subtitle files, not the video, and that both manual and auto-generated subtitles are included.

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 context for use: it downloads subtitles without the video, which is a key differentiator. However, it does not explicitly mention alternatives or exclusions, such as 'use download_transcript for text transcription' or 'do not use if you need the video file itself.' The @remarks statement gives implied usage context but stops short of explicit when-to-use vs. 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?

There are no annotations, so the description carries the transparency burden. It usefully discloses the yt-dlp --write-comments -j command, Python filtering/sorting, maxComments cap, retry cap, and response mode. However, it does not address failure behavior, authentication prerequisites (besides cookies), or potential side effects, leaving gaps.

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

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

The description is front-loaded with purpose and implementation, followed by a structured @param list. Every line adds useful information, with no filler or unnecessary repetition.

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

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

Given 7 parameters and no output schema, the description covers all parameters and states the output is structured JSON with at most maxComments entries. It lacks explicit return-field details and caveats about when comments may be unavailable, but overall it provides enough context for correct invocation.

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

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

Schema description coverage is 0%, but the description provides @param entries for all 7 parameters, including URL format, maxComments range and default, sortOrder enum, cookies, proxy, retry cap, and response mode. This fully compensates for the sparse schema and adds significant meaning beyond the bare property names.

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 'Fetch video comments from a URL using yt-dlp and return structured JSON,' which identifies the specific operation and resource. It does not explicitly differentiate from the sibling tool ytdlp__get_video_comments_summary, so it loses a point for not distinguishing among 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?

No when-to-use or alternative tool guidance is provided. The description does not mention when to prefer this over ytdlp__get_video_comments_summary or other ytdlp tools, leaving the selection entirely to inference from the tool name.

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

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

No annotations are provided, so the description carries the full transparency burden. It discloses the return format and optional cookie/proxy/retry settings, but does not mention network dependency, potential failures, or the fact that 'summarize' appears to mean 'return a formatted list of top comments' rather than an AI-generated summary. This ambiguity is a significant gap.

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

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

The description is compact and front-loaded with a clear purpose sentence, followed by a return-format remark and @param entries. The @param lines are necessary given the schema's lack of descriptions, but the wording could be tighter and the 'summarize' term is imprecise.

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, return format, and all parameters, which is helpful for a 6-parameter tool with no output schema. However, it omits usage context, error/network behavior, and any distinction from sibling comment tools, leaving gaps that could confuse an agent deciding between tools.

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

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

Schema description coverage is 0%, but every parameter is documented in the description with concrete constraints and defaults: URL scheme requirement, maxComments range, cookies file format, proxy example, maxRetries cap, and response mode default. This fully compensates for the bare schema and adds real meaning beyond parameter names.

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 action and resource: 'Fetch and summarize top comments from a video URL using yt-dlp.' It conveys the tool's main function and return type. However, it does not explicitly differentiate itself from the sibling tool ytdlp__get_video_comments, relying on the name 'summary' to imply the distinction.

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

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

There is no guidance on when to use this tool versus alternatives such as ytdlp__get_video_comments. The description only explains what the tool does and its parameters, without any 'use this when' or 'instead of' 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 provided, so the description carries the burden. It discloses the URL scheme requirement, retry cap (2), response mode options, and cookie/proxy usage, giving useful operational context. It does not mention potential side effects (none expected) or API rate limits, but the provided details go beyond the schema.

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

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

Starts with a clear one-sentence purpose, then uses @remarks and @param annotations to organize details. Each parameter line is necessary and accounts for all 6 params, with no fluff. The structure is front-loaded and scales well to the tool's complexity.

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

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

With no output schema, the description mentions the return format ('full or filtered metadata fields as JSON') but does not give an example or deeper structure. All parameters are covered, and the tool's role among video-processing siblings is clear. Slight vagueness in output shape prevents a 5.

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%, but the description's @param lines fully compensate, providing examples, constraints, and defaults for every parameter. For instance, 'must start with http:// or https://', 'Comma-separated field names... empty returns all', and 'capped at 2 (default: 2)' add substantial meaning.

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

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

The description uses a specific verb ('Fetch') and resource ('raw metadata JSON for a video URL'), which clearly distinguishes it from sibling tools like ytdlp__get_video_metadata_summary. The phrase 'raw metadata JSON' and 'using yt-dlp' add specificity.

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 clear context for use: fetching raw metadata from a video URL with optional filtering. However, it does not explicitly name alternative tools (like the summary sibling) or state when not to use it, so it falls short of a 5.

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