Subtitle Toolkit

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

With no annotations, the description carries the full burden. It clearly indicates a non-destructive audit (no modification verbs), lists the types of cues that get flagged, and states that a formatted report is returned. It goes beyond the schema by describing the output format and the nature of the checks. It does not disclose edge cases or limitations, but for a read-only audit tool the disclosed behavior is sufficient.

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

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

The description is a single, tightly structured sentence that front-loads the purpose ('audit subtitle readability') and then lists the criteria and output. Every clause adds information without redundancy. It is both concise and information-dense.

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

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

Given no output schema, the description appropriately explains the return value ('formatted report listing every flagged cue'). It covers the tool's purpose, checks, and output. Minor gaps remain (e.g., input format expectations, error handling), but for an audit tool with fully documented parameters, the description is complete enough 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 100%, so the schema already documents all five parameters. The description adds little beyond connecting parameters like max_cps and max_line_length to the checks they influence, but this is supplemental rather than necessary. Baseline 3 is appropriate since the schema does the heavy lifting.

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 'audit' and the resource 'subtitle readability', immediately distinguishing this from sibling transformation tools. It enumerates the exact checks (CPS, durations, line width, line count, overlaps) and states the output is a formatted report. This makes the tool's purpose unambiguous and clearly differentiates it from tools like clean_subtitles or merge_subtitles.

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 this is the tool to use when you need to verify subtitle quality, but it does not explicitly state when to use it vs alternatives or when not to use it. While the audit nature makes it obvious it is not for editing, there is no explicit exclusion or mention of a fallback tool. Guidance is present implicitly 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 behavioral burden. It lists 'speaker labels' and 'duplicate lines' as stripped noise, but the schema shows remove_speaker_labels and drop_duplicates both default to false, so those behaviors are opt-in rather than default. This overstates what will happen on a default call and could mislead an agent. It does disclose the return format, but the mismatch is significant.

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 efficient sentences with the primary verb and scope front-loaded, followed by a scannable list of handled noise types and a statement about output. Every sentence earns its place, with no filler 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?

The description gives a solid high-level view and mentions output formats, and the schema handles parameter documentation. However, it omits the opt-in nature of speaker-label and duplicate-line removal and does not describe edge cases like fully empty output after cleaning. Adequate for a typical call, but incomplete for robust agent decision-making.

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

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

Schema description coverage is 100%, so the schema already documents every parameter. The description adds some high-level context by naming the output formats and listing the operations, but it does not clarify defaults or add parameter-level detail beyond what the schema provides. This is the appropriate 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 uses a specific verb ('strip') and a clear resource ('auto-generated subtitles'), then enumerates exactly what noise is removed: tags, ASS codes, sound cues, speaker labels, empty cues, and duplicate lines. It also states the output formats, making it unmistakably distinct from sibling tools like convert_subtitle, merge_subtitles, or retime_subtitles.

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 intended use case is clear: clean noisy auto-generated subtitle files. However, it never explicitly names alternatives or says when not to use this tool, such as using convert_subtitle for format-only conversion. The context is clear but exclusion conditions and sibling routing are absent.

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

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

With no annotations, the description carries the full burden of behavioral disclosure. It accurately describes the conversion action, lists the formats, and notes auto-detection behavior. It does not mention potential edge cases like unsupported features or error handling, but for a pure conversion tool the core behavior is transparent. The description adds value beyond the schema by summarizing the read/write capabilities.

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 zero filler. The purpose is front-loaded with a verb and resource, and the format list is compact yet complete. Every sentence earns its place, and the auto-detection note is a meaningful addition rather than 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?

The tool has 4 parameters, all documented in the schema, and 2 enums. There is no output schema, but the description implies the return is the converted subtitle text. For a conversion tool of this simplicity, the description plus schema covers all necessary information. The only minor gap is not explicitly stating the return format, but it is easily inferred.

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

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

Schema description coverage is 100%, so the baseline is 3. The description reinforces the `from` default ('Format is auto-detected unless `from` is given') and names the output formats, but it does not elaborate beyond what the schema already documents. Since the schema fully defines each parameter, the description adds only marginal 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 states a specific verb ('Convert'), the resource ('subtitle text between formats'), and enumerates both input and output formats, making the tool's scope unmistakable. It clearly distinguishes itself from siblings like retime_subtitles or clean_subtitles, which address different concerns, without ambiguity.

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

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

The description provides clear context that this tool is for format conversion, and the auto-detection note implicitly tells an agent when to use the `from` parameter. It does not explicitly name alternative tools for other operations, but the purpose is specific enough that an agent can infer the right selection. No exclusions are stated, but the context is sufficient for correct routing.

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

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

With no annotations provided, the description is the only source of behavioral detail. It discloses the return value (repaired text and pass count), which is important for callers. It does not mention edge cases or side effects, but the core behavior is 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 exceptionally concise—just two sentences—and front-loads the purpose with examples. It contains no filler, and every clause provides value, making it easily skimmable for an agent.

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 core operation, return value, and common symptoms, and relies on the fully documented schema for parameter details. It omits failure behavior or when to manually set 'twice' vs 'read_as', but given the schema completeness, it is sufficiently robust 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 100%, so each parameter (content, twice, read_as) is already fully documented with its meaning and default values. The tool description adds no extra parameter-level semantics, placing it at the baseline of 3.

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 with a specific verb ('Repair mojibake') and resource (text), supported by concrete symptom examples ('é', '’'). This distinguishes it from sibling tools like convert_subtitle or clean_subtitles without ambiguity.

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

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

The description provides strong contextual clues by listing specific symptoms of mojibake, helping an agent recognize when to apply it. However, it does not explicitly contrast with alternatives (e.g., clean_subtitles) or state when not to use it, which slightly limits 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, and it discloses the key behavioral trait that the second track is offset to start after the last cue of the first plus an optional gap. It doesn't discuss return format or edge cases, but the core transformation behavior is 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?

Two sentences that front-load purpose and behavior with concrete examples and no filler. Every phrase 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 description plus the fully described schema give an agent enough to select and call the tool: required inputs, optional gap, output format enum, and offset behavior are all covered. The return value is not explicitly described, but the tool's simplicity and lack of an output schema make this 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 100% (all 4 parameters have descriptions), so the baseline is 3. The description only adds a mention of 'optional gap', which maps to gap_seconds, but provides no additional semantic detail beyond the schema.

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

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

The description states a specific verb ('Append') and resource ('subtitle track'), and gives concrete use cases (CD1 + CD2, second language track). This clearly distinguishes it from siblings like split_subtitles, retime_subtitles, and convert_subtitle.

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 combining two sequential subtitle tracks into one, with examples. It doesn't explicitly name alternatives or exclusion conditions, but the sibling list and the offset behavior make the intended use clear.

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

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

With no annotations, the description carries the burden. It explains the three transformations clearly but does not disclose the return format (e.g., that it returns modified subtitle text) or any side effects. For a tool that likely modifies input content, this is a notable omission, but the core behavior is well-covered.

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

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

The description is a single, tightly packed sentence that front-loads the core purpose and then enumerates the three modes with examples. No wasted words, and the essential constraint is stated clearly.

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 5 parameters, full schema coverage, and no output schema, the description covers the main usage scenarios thoroughly. It does not address error handling when multiple modes are passed, but the explicit instruction to pass exactly one reduces ambiguity. Overall, a complete and useful definition for an agent to operate correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description adds significant value beyond the schema: the constraint to pass exactly one of the three, the example ratio value (1.0427 for 25→23.976), and the sign meaning for offset_seconds ('Negative = earlier'). This clarifies usage and relationships between parameters.

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

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

The description opens with a clear verb+resource ('Fix subtitle timing') and immediately distinguishes three specific adjustment modes (offset_seconds, ratio/fps). This clearly separates it from sibling tools like clean_subtitles or convert_subtitle, which handle different concerns.

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

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

Explicitly states when to use each method: offset_seconds for uniform shift, ratio/fps for progressive drift, and mandates 'Pass exactly one of the three.' This directly guides selection among the three approaches and implies the alternatives.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It does disclose a key behavior: 'keeping original timecodes' and that the tool returns one half via the 'part' parameter. However, it does not detail edge cases, error behavior, or potential side effects (e.g., whether the original track is preserved). This is adequate but not exhaustive.

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 only two sentences with no filler. The core purpose and behavioral note are front-loaded, followed by a direct usage hint. Every word contributes meaning.

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

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

Given the tool's complexity (split at timecode, return a part) and the absence of an output schema, the description sufficiently communicates how to call it correctly. It mentions the key output behavior (fetch either half) and relies on the schema for parameter details. Minor gaps like inclusivity of the split point or return format are not critical for invocation.

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

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

Schema coverage is 100% (all parameters have descriptions). The description adds semantic value above the schema by explaining the interplay between 'at' and 'part' ('Use the at argument plus part to fetch either half'), which is not explicitly stated in the parameter descriptions. This exceeds the baseline of 3 for high 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 clearly states the tool's function: 'Split one subtitle track into two parts at a given timecode, keeping original timecodes.' It specifies a verb (split), a resource (subtitle track), and a precise operation (split at a timecode). It also distinguishes itself from sibling tools like merge_subtitles or retime_subtitles without ambiguity.

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

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

The description provides clear context on how to use the tool ('Use the at argument plus part to fetch either half') which guides invocation. It does not explicitly mention when not to use it or name alternatives, but the purpose is self-evident given the siblings. This qualifies as 'clear context, no 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 carries the full burden. It discloses the key behavioral trait: timing is evenly spaced and not real transcription, and instructs the agent to communicate this to the user. It also mentions that blank lines are skipped and that long lines can be split, which are useful behavioral details. It doesn't mention output encoding or whether the SRT is returned as a string or file, but the core caveat is well covered.

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

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

Two sentences, front-loaded with the main action and the critical caveat. Every word earns its place; no fluff or repetition of schema 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 simple conversion tool with 100% schema coverage and no output schema, the description covers the essential behavior and the important caveat about timing. It could mention what the output looks like (e.g., SRT content returned as a string) but the absence of an output schema makes that less critical. The sibling list shows related tools, and the description's caveat helps distinguish it from retime_subtitles.

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

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

Schema description coverage is 100%, so the schema already documents all four parameters. The description adds context about the overall behavior (evenly spaced timecodes) but doesn't add per-parameter meaning beyond the schema. 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 ('Turn'), a clear resource ('plain transcript' → 'SRT file'), and the key behavior (evenly spaced timecodes). It also distinguishes itself from real transcription tools by explicitly saying timing is a starting point, which helps differentiate it from siblings like retime_subtitles or convert_subtitle.

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 you have a plain transcript and need an SRT with placeholder timing. It also tells the agent to disclose the synthetic timing when presenting results. However, it doesn't explicitly name alternatives or state when NOT to use it (e.g., when real timing is needed), so it falls just 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.