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

With no annotations provided, the description carries the full behavioral burden and does so thoroughly: it discloses base64 encoding, filesystem reads from path, defaulting rules for doc_id and name, kind inference via magic bytes with extension fallback, and replacement semantics when an attachment with the same name exists in the same section. It also lists the return fields, including the replaced flag.

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 action, then organized into Args and Returns sections. Every sentence adds useful information, and there is 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?

Given the absence of annotations, four parameters with 0% schema description coverage, and an output schema, the description is complete enough to invoke the tool correctly. It documents parameter defaults, file handling, inference behavior, return structure, and replacement behavior.

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

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

Schema description coverage is 0%, so the description must compensate, and it does: each of the four parameters is explained with meaning beyond the bare schema. It clarifies that path is read from disk, doc_id None selects the current document, name defaults to the file's basename, and kind accepts 'font' or 'image' with inference behavior when omitted.

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

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

The first sentence states a specific verb and resource: 'Attach a file to the document, base64-encoded.' This distinguishes the tool from sibling attachment operations like ass_remove_attachment, ass_list_attachments, and ass_extract_attachment 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 explains what the tool does but gives no explicit guidance on when to use it instead of alternatives such as ass_extract_attachment or ass_remove_attachment. The analogy to Aegisub's attach menu provides context but does not specify use conditions or exclusions.

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

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

With no annotations, the description carries the full behavioral burden and does so well: it discloses accepted time formats, clamping into the document timebase, the `end < start` error condition, that lines append at the end, that the index is 0-based, and that the operation is snapshot-backed and undoable.

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

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

Front-loads the core action, then layers time semantics, error conditions, undo behavior, and return shape in tight, non-redundant sentences. 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?

An output schema exists, so return values need not be re-explained, yet the description usefully summarizes the payload. Error and undo semantics are covered; the main gap is the undocumented non-timing parameters for what is a 12-param 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% across 12 parameters, so the description must compensate. It thoroughly explains the two timing params (accepted formats, clamping, ordering error) but leaves ten parameters (text, layer, style, effect, comment, margins, doc_id, actor) undefined in both schema and description.

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

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

States a specific verb+resource: 'Append a new line.' Clear and unambiguous. However, it does not differentiate from the sibling ass_add_lines (bulk add), leaving the agent to infer which to pick when adding one vs many.

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 when-to-use guidance, no prerequisites, and no routing to the closely-named sibling ass_add_lines for multi-line insertion. The only contextual hint is that ass_undo reverts the call.

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

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

With no annotations, the description carries the full burden and does well: it explains that insert positions are 0-based, that indices resolve against the in-progress list (earlier inserts of the same call already placed), that omitted indices append, and that times accept ms or time strings. It does not cover permissions or failure behavior, but the mutation semantics are unusually well disclosed.

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

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

Purpose is front-loaded in the first sentence, followed by necessary schema detail and the return shape. The key enumeration is long but each element adds meaning; no filler sentences.

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

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

An output schema exists, so the return description is a bonus rather than a necessity, and the insertion-ordering semantics are fully specified for a mutation tool. The only omission is any mention of doc_id or which document the operation targets.

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 compensate, and it comprehensively enumerates the accepted dict keys (start_ms/end_ms/text/style/actor/effect/layer/comment/margins) plus the optional index and time-format flexibility. The optional doc_id parameter is never mentioned, which is the only gap.

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

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

States a specific verb and resource ('Append several lines in one call') and implicitly distinguishes itself from the singular sibling ass_add_line by referencing its keys and the batch nature ('in one call'). An agent can identify this as the bulk-append variant without opening the schema.

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

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

The phrase 'in one call' hints that this is the efficient batch alternative to repeated ass_add_line invocations, but there is no explicit when-to-use/when-not guidance or named alternative. Usage is implied rather than stated.

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

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

With no annotations to lean on, the description carries the full burden and delivers: verbatim storage rules ('/48.0' becomes 48), colour normalization, pre-write validation constraints (font_size positive, alignment 1-9, border_style 1 or 3), the destructive semantics of overwrite=True (fields revert to defaults), and the relative_to/Format-line 'ignored_fields' edge case.

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

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

Front-loads the core create/replace action and the overwrite distinction before the detail paragraphs. Dense and largely waste-free, though the validation and returns blocks could be tightened.

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?

Covers the hard parts an agent needs: overwrite semantics, validation, the Format-line caveat, and the return shape. With a declared output schema, the explicit return documentation is a bonus rather than a necessity, and the partial parameter coverage is the only real 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% across 26 parameters, so the description must compensate. It adds real validation meaning for font_size, alignment, border_style, margins, colours, overwrite, and relative_to, but leaves the majority (bold, italic, outline, shadow, scale_x/y, spacing, encoding, angle, font, underline, strike_out) to inference from titles/defaults.

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

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

States a concrete verb+resource ('Create a style, or replace an existing one of the same name') and immediately distinguishes itself from the sibling ass_update_style. An agent knows exactly what this tool does versus its neighbors without opening any schema.

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

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

Explicitly names the alternative ('use ``ass_update_style`` to change a few fields and leave the rest alone') and gives the precise condition under which overwrite replaces versus preserves fields. This is the when/when-not/alternative pattern at its best.

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

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

With no annotations, the description carries the full behavioral burden and does so well: it states the default write behavior (snapshot-backed, in_place=True), the no-write alternative (in_place=False), and the merge semantics ('merged into the line's existing first block so duplicated tags are updated instead of stacking'). It also discloses validation behavior (booleans, floats and out-of-range values rejected for 'an'; drawing strings without a command rejected). It stops short of permissions/undo implications, hence not 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 opening sentence front-loads the purpose, and the verbosity is almost entirely load-bearing parameter documentation rather than padding. A few entries are dense, but each shape mapping earns its place and there is little that could be cut without losing 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?

For a complex 11-parameter mutation tool this covers purpose, per-parameter encodings, mutation semantics, and even the return shape (although an output schema already exists, so return values need not be explained). Nothing an agent needs to construct a correct override block correctly appears to be missing.

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

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

Schema description coverage is 0%, so the description must compensate entirely, and it does: each of the 11 parameters is documented with accepted input shapes and exact tag output (e.g. move as 6/4/2-tuple or dict with optional t1/t2 in milliseconds; fade 2-tuple vs 4-tuple vs 7-tuple; clip rectangle vs drawing path vs [scale, path] vs dict with inverse). This is far richer than anything the bare schema provides.

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

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

The description gives a specific verb and resource ('Build a leading override block out of named typesetting pieces') and enumerates exactly which ASS tags it can emit (\pos, \an, \move, \fad/\fade, \clip/\iclip, \org). It is clear on its own, but it never names or contrasts with closely related siblings such as ass_set_tag, ass_apply_tag_to_block, or ass_insert_tag_at, so an agent cannot disambiguate purely from the text.

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 explicit when-to-use, when-not-to-use, or alternative-tool guidance. The arg notes imply the block is applied to every selected line and that in_place=False returns a plan without writing, but the caller is left to infer when this helper is preferable to the many other tag-manipulation 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, the description carries the full burden and does so well: it discloses the default is dry_run=True so nothing is written, exactly how line ends change under shift_only='both' vs 'start', and that the result carries 'dry_run'/'applied' so the caller knows whether the document changed. Mutation scope is fully characterized.

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

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

Front-loaded with the core action and cleanly organized into Args/Returns. It is appropriately sized for eight parameters, though the Returns paragraph partially overlaps with the existing output schema.

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

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

For an eight-parameter, no-annotation mutation tool this is complete: every parameter is explained, the default dry-run behavior is stated, and the dry_run/applied return fields are surfaced even though an output schema exists.

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 compensate, and it documents all eight parameters (selection, video, noise_db, min_silence_s, doc_id, dry_run, shift_only, max_shift_ms) with meaning beyond the bare titles, including the enum-like values for shift_only.

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

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

States a specific verb+resource ('Move line starts out of audio silence') and the mechanism (ffmpeg silencedetect). It also implicitly distinguishes itself from the sibling ass_align_to_silence by referencing that function's plan as its return baseline.

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

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

Explains the operational context clearly ('Lines that start on audio are left alone and are not reported as suggestions'), so an agent knows which lines are affected. It does not, however, explicitly name when to prefer this over adjacent timing tools such as ass_fix_timing or ass_align_to_silence.

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

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

No annotations are provided, so the description carries the full burden, and it does the most important part: it loudly declares 'never modifies the document' and marks the return with applied:False plus a note. It also discloses that max_shift_ms filters suggestions and the shift_only semantics. It stops short of permissions/rate-limit context, so a 4 rather than a 5.

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

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

Front-loaded with purpose and cleanly sectioned into Args/Returns with no filler sentences. Slightly redundant in that an output schema already exists yet the full return shape is restated, which costs a bit of brevity.

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

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

For a 7-param, all-optional tool with no annotations, the description covers the read-only guarantee, every parameter's meaning, and the return contract. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 0% (no parameter descriptions), so the description must compensate, and it documents all 7 params. It adds real meaning beyond the schema: noise_db is passed to silencedetect, shift_only 'both'/'start' controls whether the end moves, and max_shift_ms filters out long suggestions.

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

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

States a specific verb and resource ('Report audio silence intervals and the per-line shifts they suggest') and explicitly distinguishes itself from its write counterpart, ass_align_lines_to_silence. An agent can tell exactly what this does and how it differs from the applying tool.

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

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

Names the alternative and the condition that selects it: this tool is the 'look before it leaps' preview, while ass_align_lines_to_silence applies the same plan when dry_run=False. Explicit when-to-use routing against a sibling.

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

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

With no annotations, the description carries the full behavioral burden and does so well: it explains block numbering (including comment blocks), creation when no block exists, payload rules (braces optional, inner braces rejected), text preservation, and the write-back behavior (snapshot-backed for in_place). It lacks edge-case or error-handling details, so it is not a full 5.

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

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

The description is structured into clear sections (purpose, Args, Returns) and front-loads the core action. It is detailed but every sentence contributes necessary information for a complex tool; it could be slightly tighter but is not wasteful.

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 6 parameters, no annotations, and an existing output schema, the description provides sufficient detail for correct invocation, including parameter semantics and behavioral notes. It does not cover when to prefer this tool over siblings, but otherwise it is complete enough for practical use.

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

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

Schema description coverage is 0%, so the description must compensate, and it does: every parameter (index, text, doc_id, block, override, in_place) is explained with semantics beyond the schema, including block numbering, creation behavior, payload format rules, and mode-specific write behavior. This adds substantial meaning over 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 states a specific verb ('Append tags') and resource ('one override block (or to every block) of a line'), making the purpose clear. It does not explicitly differentiate from close siblings like ass_set_tag or ass_insert_tag_at, 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?

The description implies usage by explaining the behavior in different modes ('raw-string mode never writes') and the effect of block selection, but it does not provide explicit when-to-use or when-not-to-use guidance relative to alternatives such as ass_set_tag.

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

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

With no annotations, the description carries the full burden and does reasonably well: it discloses the mechanism (fontconfig resolution), the comparison semantics, and crucially what 'substitutions' means ('exactly the set of styles that will not render in the font they ask for'). It omits anything about cost/latency of calling fontconfig or whether it mutates anything, but the read-only nature is evident from the verb '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 one-line summary is front-loaded and efficient, but the Args/Returns block duplicates the output schema field-by-field, which is redundant given has_output_schema=true. The verbose return enumeration crowds out guidance the tool actually lacks.

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

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

For a single-parameter, read-only diagnostic with an output schema available, the definition covers the mechanism, parameter meaning, and result semantics well enough to call correctly. The missing piece is cost/performance context for a tool that walks every style through fontconfig.

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% and the single parameter is undocumented in the schema, but the description fully compensates: 'doc_id: document id or None for the current document.' That resolves the anyOf string/null ambiguity and explains the None default's effect.

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

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

States a specific verb and resource: comparing each style's requested font against what fontconfig resolves. This is distinct from siblings like ass_match_font (resolve a font) and ass_fonts_used (inventory fonts), so an agent can pick it without opening any schema.

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

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

There is no when-to-use / when-not guidance and no named alternative, even though ass_match_font, ass_font_coverage, and ass_glyph_check sit in the same font-diagnostic space. The description implies a diagnostic purpose via the output explanation but never instructs the agent when to reach for this over those 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, the description carries the full behavioral burden and discloses important traits: default layer-strict comparison, treatment of comments, tolerate_ms threshold, and ordering by start time. It could be stronger by explicitly stating the operation is read-only and has no side effects.

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

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

Front-loaded with the core action, followed by compact notes and a structured Args/Returns section. Every sentence adds useful context without padding.

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

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

Given the lack of annotations and low schema coverage, the description supplies the needed behavioral and parameter context. It also redundantly documents the return shape, which is harmless because an output schema exists.

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 explain all four parameters. Its Args section defines selection, doc_id, layer_strict, and tolerate_ms meaningfully, though selection remains somewhat underspecified regarding expected format.

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

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

States a specific verb and resource: list overlapping pairs of lines, ordered by start time. The overlap focus clearly distinguishes it from general validation or QC 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?

Explains the key usage condition: layer_strict defaults to comparing only within the same layer because cross-layer coincidences are intentional, and comment lines are excluded. It does not explicitly compare against alternatives like ass_qc or ass_validate, but the context is clear.

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

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

No annotations exist, so the description carries the full behavioral burden. It discloses the return envelope and the 'known path' precondition for saving, but omits the single most important behavior for a close tool: what happens to unsaved changes when save=false. Listing return fields adds little here since an output schema already exists.

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

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

Front-loaded purpose sentence, then compact Args/Returns blocks. The trailing 'Line indices are 0-based' is copy-paste boilerplate irrelevant to a close operation, a small amount of dead weight.

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 two-parameter lifecycle tool with an output schema present, the description covers purpose, both parameters, and preconditions. The only real gap is the unsaved-changes/discard semantics, which an agent would want before closing a dirty document.

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, and it does: doc_id is defined as the target document defaulting to the current one, and save is defined with its precondition. Both parameters are covered clearly, though no mention of error behavior when the path is unknown.

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

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

The first sentence names a specific verb and resource (close a document) and adds the optional-save nuance, which is enough to distinguish it from ass_open, ass_save, and ass_save_all. It stops just short of 5 because it never names a sibling or the boundary with ass_save + ass_close done separately.

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 rather than stated: doc_id defaults to the current document and save 'requires a known path'. There is no explicit when-to-use versus alternatives guidance, e.g. whether to prefer ass_save followed by ass_close for untitled documents.

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

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

With no annotations, the description carries the full burden and does so exceptionally: it documents the rounding behavior, the explicit \clip(T,...) rewrite, the measurement-based proof via measure.measure_render, the failure mode (measurement.error instead of an exception when ffmpeg is missing), the empty-ink trivial-convergence caveat, and what dry_run actually touches. This is far beyond a bare mutation description.

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 core purpose is front-loaded in the first line, followed by rationale, then caveats, then the return shape – a sensible ordering. It is dense and somewhat long, but nearly every sentence adds real information (math, proof semantics, empty caveat, dry_run); only the formula derivation is arguably heavier than needed.

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?

Even though an output schema exists, the description anticipates the tricky parts: the empty-ink false-positive convergence and the explicit check ('not measurement["before"]["empty"]') a caller must perform for a real proof. Combined with the error-handling note and dry_run semantics, the definition is complete for a tool of this complexity.

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 compensate. It richly explains target_scale (the 2**(T-S) ratio, rounding) and dry_run ('computes everything ... without touching the document'), covering the two non-obvious params. doc_id and selection are left unqualified, but those are conventional in this tool family, so the gap is minor.

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

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

States a precise verb and resource ('Rewrite vector clip coordinates') plus the exact transformation (from current \p scale to target_scale). An agent can distinguish it from siblings like ass_set_clip or ass_remove_clip purely from this sentence, and the level math makes the operation 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?

Usage is implied by the mechanism (rescale an existing clip when the script resolution/level changes) and dry_run=True is explained as a non-mutating proof mode. However, it never states when to prefer this over siblings such as ass_set_clip/ass_scale_drawing, nor any preconditions or exclusions.

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

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

With no annotations, the description carries the full burden and meets it: it discloses that only tag names inside braces change, that visible text is never rewritten, that braces stay intact, that the operation is snapshot-backed unless dry_run is set, and that both character index maps are preserved exactly. These are exactly the mutation-safety and reversibility facts an agent needs.

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

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

Front-loaded with purpose and cleanly sectioned into behaviour, Args, Returns, and Indices. The multi-sentence Returns block is largely redundant since an output schema already exists, which is the main deduction; the rest of the prose 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 four-parameter, no-annotation tool with an output schema, the description covers everything an agent needs: mode selection, scope of edit, snapshot/dry-run behaviour, and index invariants. Nothing required to invoke it correctly is missing.

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

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

Schema description coverage is 0%, so the description must supply all parameter meaning, and it does: selection defaults to every line when None, doc_id falls back to the current document, mode enumerates 'to_ass'/'to_ssa' (values the schema does not enumerate), and dry_run's reporting-only semantics are spelled out. Every one of the four parameters is documented 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?

States a specific verb and resource ('Normalise legacy SSA override tags to their ASS spelling (or back)'), and scopes it precisely to the inside of override blocks. An agent can distinguish this from tag-manipulation siblings such as ass_set_tag, ass_swap_an_pos, and ass_find_replace from the opening sentence alone.

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

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

Gives clear conditions for each mode ('to_ass' default rewrites legacy spellings, 'to_ssa' does the opposite) and explains dry_run's no-write behaviour. It stops short of naming an alternative tool or an explicit when-not-to-use rule, so it is strong context without full routing 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 does disclose real behavior beyond the schema: overwrite replaces an existing style instead of failing, and the return payload exposes an "ignored_fields" key hinting that some source fields may not transfer. It says nothing about permissions, where the new style lands in the style order, or whether lines referencing the source are affected.

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

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

Front-loaded one-line statement of purpose followed by a tight Args block; each parameter gets a single clause. The Returns block is largely redundant given an output schema exists, but it is short enough not to bloat the definition.

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?

A mutation tool with no annotations, an output schema (so return values need not be spelled out), and undocumented parameters. The description covers the basics but omits how the copy interacts with the document (style ordering, whether lines are untouched) and any permission or conflict context beyond the overwrite flag.

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 documents all four parameters, but "source: style to copy" and "new_name: name for the copy" essentially restate the titles; only doc_id ("None for the current document") and overwrite ("replace an existing style of that name instead of failing") add genuine 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?

Specific verb+resource ("Copy a style ... under a new name") with the additional qualifier "field for field" that clarifies the copy semantics. It is distinguishable from siblings like ass_add_style, ass_rename_style, and ass_update_style, though it never names them explicitly. Clear but without sibling differentiation in the text.

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 only implied: the wording suggests duplicating an existing style, whereas ass_add_style would create one from scratch, and the overwrite flag hints at the failure mode being avoided. No explicit when-to-use, when-not-to-use, or named alternatives are given.

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 burden. It describes the computed output but does not state whether the tool is read-only, whether it modifies the document, what permissions are needed, or any side effects. This leaves the agent guessing about safety and side effects.

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 tool's purpose and then structured into Args and Returns sections. It is appropriately sized, but the Returns block duplicates information already available in the output schema, making it slightly redundant.

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

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

Given no annotations and 0% schema description coverage, the description adequately documents the parameters and notes the return shape. However, it omits when to use this tool versus similar siblings and provides no safety or side-effect context, leaving gaps for an agent deciding between related 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 coverage is 0%, so the description must compensate. It documents both parameters: selection is 'lines to measure' with None/[] meaning every line, and doc_id is the document id. This adds clear meaning beyond the bare schema, though selection's expected type (e.g., indices vs. line objects) remains slightly ambiguous.

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 metric and scope: characters per second for selected lines plus totals. It distinguishes the tool from a generic stats tool by naming the exact output metric, but it does not explicitly differentiate itself from the similar sibling ass_reading_speed.

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 the selection parameter's default behavior but gives no guidance on when to use this tool over alternatives such as ass_reading_speed or ass_stats. No exclusions, prerequisites, or usage context 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 burden and does reasonably well: it warns that None deletes every line ('use with care'), which is the key destructive-scope disclosure, and 'Snapshot-backed' signals the operation is undoable. It omits permission/auth requirements and what happens to the document state otherwise, keeping it out of the top tier.

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

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

Front-loaded with the action, then the critical selection caveat, then the return shape and snapshot note. No wasted sentences, though the inline backtick/JSON formatting is slightly heavy for the amount of 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?

An output schema exists, yet the description still restates the return shape, which is redundant but harmless. For a destructive tool with zero annotations and an undocumented doc_id parameter, it leaves gaps around which document is targeted and the exact undo semantics, so it is adequate rather than 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 description coverage is 0%, so the description must compensate. It clarifies that 'selection' accepts any selection spelling and that None means all lines, which is genuinely useful, but the second parameter 'doc_id' (defaulting to null) is never explained in either the schema or the description.

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

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

States a specific verb and resource ('Delete the selected lines'), which clearly separates it from siblings like ass_duplicate_lines, ass_merge_lines, or ass_move_lines. It does not explicitly name a sibling or contrast scope, so it stops short of full 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?

Usage is implied by the verb, and the description adds one important conditional ('None means every line (use with care)'). However, it gives no explicit when-to-use/when-not guidance and never points to alternatives for recovering or undoing deletions.

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 implicitly discloses a read/no-side-effect nature, states the current-document defaulting behavior, notes the 0-based index convention, and describes the entire return shape. It does not mention any permission requirements, but for a pure information-read tool that is a minor omission.

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 Args block is tight and front-loaded, but the description then lists a very long set of return fields. Since an output schema exists, much of this enumeration is redundant and inflates the description beyond what an agent needs to select and call the tool.

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

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

For a single-optional-parameter informational tool with an output schema, the definition covers the defaulting rule and index convention adequately, and return values are documented by the schema. The remaining gap is the lack of sibling differentiation against ass_stats.

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 for the single doc_id parameter. It does so by explaining that doc_id identifies the document to describe and that omitting it targets the current document, adding meaning the bare anyOf string/null schema does not convey.

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

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

States a specific verb+resource combination ('Detailed information about one document') and enumerates exactly what the returned summary contains, which makes the scope concrete. It distinguishes itself from ass_list_documents, but does not explicitly separate its role from ass_stats or ass_get_script_info.

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 only guidance is the argument default ('the current one when omitted'), which is useful context for calling it. There is no explicit when-to-use vs. when-not, and no routing to siblings like ass_stats for aggregate metrics or ass_get_line for line-level data.

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

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

With no annotations, the description carries the full burden and does reasonably well: it discloses the coordinate space (drawing's own scale space, \p level) and the non-obvious semantic that the box is the control polygon box including Bézier/B-spline handles, matching VSFilter/Aegisub. It does not cover error cases or how the drawing is resolved, so it falls short of full disclosure.

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

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

Front-loaded with the purpose, then relevant coordinate-space caveat, then return shape. Slightly redundant (the centre/center and size/bbox duplication), but every sentence is short and useful.

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?

An output schema exists, so listing return fields is optional reinforcement rather than required content. The real gap is that a 3-parameter tool with zero schema coverage and no annotations leaves the agent unable to know which selector to pass or how the drawing is located.

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 all three parameters (text, index, doc_id) are undocumented in both schema and description. The description never explains how these selectors interact or which one takes precedence, only mentioning doc_id/index incidentally as return fields.

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

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

The first line states a specific computed resource — 'Bounding box / size / centre of a drawing' — with a clear implicit verb (compute/return). This is easily distinguished from siblings like ass_drawing_info, ass_get_drawing, or ass_transform_drawing, which mutate or describe rather than measure.

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 statement of when to call this versus alternatives such as ass_drawing_info or ass_drawing_to_svg. The VSFilter/Aegisub note explains what the result means for positioning, but not the condition that selects this tool. No exclusions or prerequisites are given.

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. 'Parse' implies a read-only, non-mutating operation and the coordinate-scale note ('drawing's own scale space') is genuinely useful context, but the description never explicitly states read-only semantics, side effects, or permission needs, leaving notable 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 actionable sentence is front-loaded, but the description then enumerates the entire return dictionary field-by-field, which is largely redundant given that an output schema already exists. The structure is fine, but the return enumeration does not earn its space.

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 low-complexity parse tool with an output schema and no annotations, coverage is borderline adequate: the coordinate-scale caveat is useful, but three undocumented input parameters leave the agent guessing about how to actually invoke it. It is the minimum viable level.

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% and all three parameters (text, index, doc_id) are undocumented in both schema and description. The only faint signal is that doc_id and index reappear in the described return shape, but the description never explains what these inputs mean or how they combine, so it fails to compensate for the coverage 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 names a specific verb and resource ('Parse a drawing') and usefully scopes it by negation ('no measurement, no line needed'), which distinguishes it from the measurement-oriented siblings. It does not differentiate it from closer siblings like ass_get_drawing, ass_drawing_bbox, or ass_parse_text, so it stops 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?

The parenthetical 'no measurement, no line needed' hints at when this is the right call versus a measurement tool, but no alternative is named and no positive when-to-use condition is given. An agent must still infer the selection criteria from sibling names alone.

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 load, and it does disclose meaningful behavior: the target file 'is overwritten if it exists', path resolution rules ('resolved inside workspace.output_dir' or absolute), and the padding effect on the viewBox. It does not cover permissions or failure modes, but the destructive overwrite and path semantics are exactly the kind of trait an agent needs.

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

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

Front-loaded with the action and output location, then progressively details path data, padding, path semantics, and return shape. Every paragraph does work; the RST double-backtick noise is minor and nothing is redundant.

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

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

An output schema exists so return values need not be restated, and the description is complete on file/location behavior. But for a tool with five parameters at 0% schema coverage it omits any explanation of text, index, or doc_id, which is a real gap for a tool whose core job is selecting a drawing to export.

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% across 5 parameters, so the description must compensate and only partly does: path (resolution, defaults, overwrite) and padding (viewBox growth) are explained well. However text, index, and doc_id receive no explanation at all, leaving the crucial question of how the source drawing is selected undocumented.

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

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

States a specific verb and resource: 'Export a drawing as a standalone .svg file in workspace.output_dir.' The direction of the operation (drawing -> svg) is unambiguous. It does not name the inverse sibling ass_svg_to_drawing, so there is no explicit sibling differentiation, but the purpose itself is clear.

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 when-to-use guidance and no mention of alternatives such as ass_get_drawing or ass_drawing_info. It explains how the output path resolves, but never says in what workflow or context this export should be chosen over the other drawing 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, the description carries the full burden and does disclose meaningful behavior: copies preserve every source field (style, actor, effect, layer, margins, comment flag, tags), the operation is 'snapshot-backed' (implying undo support), and it returns a structured result. It still omits permission requirements, error conditions, and an explicit statement of reversibility, so it does not reach 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?

Purpose is front-loaded, followed by args and then behavioral guarantees, so the agent gets the essentials first. The Args formatting is efficient and each line adds value, though the return-shape sentence is somewhat redundant given an output schema exists.

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 4-parameter, 0%-schema-coverage, annotation-free mutation tool, the description covers params, field-preservation behavior, and snapshot backing, which is close to complete. The unexplained doc_id parameter is the main remaining 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 documents three of four parameters with real semantics (selection = None means all lines; offset_ms shifts copies in time; insert_after toggles placement), which is far beyond the bare schema. Only doc_id is left unexplained, keeping it short of a 5.

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

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

States a specific verb (duplicate) and resource (the selected lines), which cleanly separates it from creation-oriented siblings like ass_add_line/ass_add_lines and restructuring siblings like ass_split_line or ass_merge_lines. It does not explicitly name a sibling it differs from, 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?

The description explains parameter behavior but gives no when-to-use guidance, no exclusions, and no comparison to alternatives such as ass_add_lines or ass_copy_style. An agent can infer intent from the verb but is given no routing logic.

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

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

With no annotations, the description carries the full burden and does so well: it discloses that txt/srt skip comment lines while tsv/ass-fragment keep them, that the default separator preserves the ASS escape for lossless re-import, and that output_path defaults into workspace.output_dir which is created if needed. It omits file-overwrite behavior, permission/auth requirements, and failure modes, keeping it short of a 5.

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

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

Purpose is front-loaded in the first line, then parameters are laid out in a scannable Args block followed by the two format-dependent behaviors and the return shape. Slightly long, but each sentence adds distinct information and nothing is redundant.

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

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

For a five-parameter, zero-schema-description export tool, this is complete: every parameter is explained, format-specific comment-line handling is called out, and the return payload is enumerated. Nothing an agent needs in order to invoke it correctly is missing.

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

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

Schema description coverage is 0%, so the description must compensate, and it does: all five parameters are documented with meaning beyond the schema, including the four format values and their output shapes, the exact semantics of line_separator with worked examples ('\n', '|'), and the defaults for selection, doc_id and output_path.

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

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

States a specific verb (export) plus a precisely scoped resource (selected lines) and enumerates the four output formats, which implicitly separates it from siblings like ass_plain_text or ass_karaoke_export. An agent can tell what it produces without opening the schema.

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

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

The description gives useful in-parameter guidance (selection=None means every line, doc_id defaults to the current document, which line_separator value to pick for wrapping vs lossless re-import), but it never states when to choose this tool over alternatives such as ass_plain_text or ass_karaoke_export. Usage is implied through parameter semantics rather than stated.

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

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

With no annotations, the description carries the full burden. It usefully discloses that output is written into workspace.output_dir and how relative paths resolve, plus the return shape, but omits permission requirements, overwrite behavior, and error handling when the named attachment is absent.

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

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

Front-loaded purpose followed by clearly separated Args and Returns sections. Efficient and scannable, with only minor redundancy in restating the return keys that the output schema already covers.

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

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

For a 3-param tool with a full output schema, the definition covers purpose and all parameters adequately. The remaining gap is behavioral (no annotations, no error/overwrite disclosure), which would matter for a write-to-disk operation.

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

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

Schema description coverage is 0%, so the description must compensate, and it does: it documents all three params, adding non-obvious semantics like case-insensitive name matching, doc_id=None meaning the current document, and output_path resolving inside workspace.output_dir.

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

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

States a specific verb and resource: 'Decode an attachment and write it into the workspace output directory.' This clearly distinguishes it from siblings ass_list_attachments, ass_add_attachment, and ass_remove_attachment, which handle listing/adding/removing rather than decoding to disk.

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 purpose (extract an attachment's decoded bytes to a file), but there is no explicit when-to-use guidance, no exclusion conditions, and no routing to alternatives. The agent must infer that this differs from add/remove/list 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, the description carries the full behavioral burden. It usefully discloses that dry_run only counts changes, that edits are snapshot-backed unless dry_run, and that result indices are 0-based. It still does not cover failure modes, permission requirements, or all side effects of selecting fields like style/actor/effect.

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 organized into Args and Returns blocks, so it is easy to scan. It is somewhat long and includes return information that may partly duplicate the output schema, but most detail earns its place for a 9-parameter tool with no schema 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?

For a complex mutation tool with 9 parameters, no annotations, 0% schema coverage, and a large sibling set, the description supplies enough parameter and behavioral context to invoke it correctly. An output schema exists, so the return-value block is not strictly required, but the additional notes about snapshot backing and 0-based indices are useful.

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 document all parameters. It does so thoroughly: pattern semantics with regex and back-references, replacement behavior, selection spelling, doc_id default, case sensitivity, allowed fields, dry_run behavior, and limit 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 gives a precise verb+resource+scope: 'Find and replace text across the selected lines.' This distinguishes it from line-mutating siblings such as ass_update_line(s) and clearly indicates a search/replace operation over a selection or whole document.

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 parameter-level choices (regex vs literal, selection None means all lines, omitted doc_id means current document), which implies usage. However, it does not explicitly name alternative tools or say when to prefer this over ass_update_lines, ass_update_line, or other bulk edit 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, the description carries the full burden and does so well: it discloses that only end times move (scope of mutation), that dry_run=True writes nothing, and that avoid_overlap can cause a fix to be reported as blocked rather than applied. The blocked/no-room behavior is exactly the kind of non-obvious trait annotations would otherwise need to supply.

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

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

Front-loaded with the core behavior (compute + conditional apply), then the algorithm, then structured Args/Returns blocks. Efficient, though slightly long and the Returns block partly duplicates the output schema.

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?

An 8-param mutation tool with no annotations is fully covered: what changes, when it changes, what happens when it can't change, and the shape of the result. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema description coverage is 0% and 8 parameters are undocumented in the schema, so the description has to compensate — and every parameter is explained with real semantics (selection, doc_id, dry_run default, min_duration_ms, target_cps vs max_cps fallback, avoid_overlap, keep_gaps_ms). The target_cps/max_cps precedence rule is meaning the schema alone could never convey.

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

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

States a specific verb+resource ('Compute timing fixes and apply them'), and the body narrows it to a precise operation: extending end times so lines meet min_duration_ms and cps limits. An agent can tell what it does, but it never names the close siblings it could be confused with (ass_set_durations, ass_shift_times, ass_scale_times), which would have made the purpose discriminating rather than merely clear.

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 rather than stated: the tool is for fixing lines that are too short or read too fast, and the dry_run default advertises a plan-then-apply workflow. There is no explicit when-to-use vs when-to-use-something-else guidance, nor any mention of when this is preferable to set_durations/set_times.

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

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

With no annotations, the description carries the full burden and does well: it discloses fontconfig-based resolution, that a substituted request is reported honestly, and that missing characters return codepoints plus covering fallback families. It does not state permissions or that the operation is read-only, but the read-only nature is strongly implied by '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 operation is front-loaded in the first sentence, which is good. However, the long backtick-quoted enumeration of every return field is redundant given that an output schema already exists, making the passage longer than it needs to be.

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?

Return values are covered by the output schema, so that enumeration is surplus. Behavior and the family parameter are reasonably complete, but the missing bold/italic semantics and the absence of any sibling routing leave an agent guessing in a crowded font-related tool family.

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 compensate. It does explain family resolution and the default-sans behavior when omitted (default_used), but it never explains the bold or italic flags or the required text parameter, leaving half the parameters undocumented in both places.

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

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

The first sentence names a specific verb (checking coverage) and resource (characters of text against a font family), so an agent can grasp the operation immediately. It does not, however, differentiate itself from close siblings like ass_fonts_with_char, ass_glyph_check, or ass_match_font, so the boundary is left to inference.

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 when-to-use guidance, no mention of alternatives, and no task context (e.g. pre-flight check before rendering subtitles). The only usage hint is the default family behavior, which is parameter semantics rather than selection 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 does disclose meaningful behavior: names are resolved through fontconfig and both uninstalled families and substituted families are flagged explicitly. However it says nothing about error behavior, cost, or what doc_id=null means (presumably the active document), leaving the null-default contract unexplained.

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 text is front-loaded and information-dense: purpose first, then the resolution mechanics, then the return shape. The final sentence largely restates the output schema, which is a slight redundancy, but everything else 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?

Because an output schema exists, the description does not need to spell out return fields, and the explicit statement that uninstalled/substituted families are flagged covers the main interpretive risk. The only real gap is the un-documented default behavior of doc_id.

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 single doc_id parameter is nullable with default null. The description only mentions doc_id inside the return shape and never explains that omitting it falls back to the active/current document, which is the one semantic an agent most needs here.

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+resource: enumerate 'every font the script asks for, plus embedded font attachments', and explains the two contributing sources (style Fontname fields and the [Fonts] section). It is clear in isolation but never distinguishes itself from close siblings such as ass_check_font_substitution or ass_list_fonts, so an agent must guess which of the font-related tools to pick.

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 when-to-use guidance, no prerequisites, and no named alternative despite several overlapping siblings (ass_check_font_substitution, ass_list_fonts, ass_font_coverage, ass_match_font). The agent is left to infer selection criteria entirely.

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 required input constraint ('char must be exactly one character') and the exact return shape, and the phrasing implies a read-only scan of installed fonts. However, it says nothing about the scope/cost of scanning all installed fonts, permissions, or failure behavior for unmapped characters.

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 tight sentences: the query intent is front-loaded, followed by the input constraint and the return shape. No filler, no redundancy.

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

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

For a single-parameter query tool with an output schema present, the description covers the input constraint and the returned fields, so an agent has enough to call it. It stops short of explaining when this is preferable to sibling font/glyph tools, leaving a small completeness 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% – the schema gives only a bare 'string' type for 'char'. The description compensates by stating the semantic constraint that 'char' must be exactly one character, which is real meaning beyond the schema. It does not clarify surrogates, whitespace, or empty-string handling, so not a 5.

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 query intent: which installed font families contain a given glyph. That is a clear verb-plus-resource framing (query installed fonts by glyph presence). It does not explicitly distinguish itself from close siblings like ass_glyph_check or ass_font_coverage, so it lands at 4 rather than 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?

There is no guidance on when to reach for this tool versus ass_list_fonts, ass_font_coverage, ass_glyph_check, or ass_fonts_used. Usage is only implied by the purpose statement; no conditions or alternatives are named.

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

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

With no annotations, the description carries the full burden and does well: it lays out the complete fps resolution fallback chain (argument, workspace video dict/probed path, script config, [Script Info] FPS, then failure) and discloses error behavior (a ToolError explaining what is missing). It does not state whether the call is side-effect-free, but the read-only nature is strongly implied by a pure conversion.

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 Args/Returns structure is front-loaded and every sentence earns its place, though the Returns block enumerates keys already present in the output schema, which is mildly redundant. Otherwise efficient and well organized.

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

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

For a three-parameter conversion tool, the description covers parameter meanings, the fps resolution chain, failure behavior, and return keys. With an output schema present, there is nothing an agent needs for correct invocation that is missing.

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

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

Schema description coverage is 0%, so the description must compensate entirely, and it does: ms is typed as int/float or a time string, fps is documented along with its full resolution order, and doc_id is clarified as being used only as an fps source. This adds meaning the bare schema (defaults only) does not provide.

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

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

The description states a specific verb and resource ('Convert a time in milliseconds to a frame number'), and the directionality is explicit, which implicitly distinguishes it from the inverse sibling ass_ms_from_frame. It does not, however, name that sibling or any alternative, so it stops short of full 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?

Usage is only implied by the direction of the conversion; there is no statement of when to prefer this over ass_ms_from_frame, ass_frame_from_timecodes, or ass_snap_to_frames, and no prerequisites or exclusions. Adequate but leaves the routing decision to the agent.

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

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

With no annotations, the description carries the full burden and largely meets it: it discloses the dependency on workspace.timecodes, the fallback to frame rate, that the method field reports which path was taken, and that both coordinates are returned to keep the pair unambiguous. It does not state read-only/purity explicitly, but the behaviour described is clearly a deterministic lookup.

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

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

Front-loaded with the core purpose, then structured Args/Returns sections. The RST double-backtick markup and the explicit Returns line add some noise, but every sentence (fallback rule, method field, unambiguous pair) carries real information.

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

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

An output schema exists, so return values need not be spelled out, yet the docstring lists the returned keys anyway. Between the fallback rule, the method discriminator, and per-parameter notes, the agent has enough to invoke it correctly; only sibling differentiation against the other frame/ms/timecode converters is missing.

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

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

Schema description coverage is 0%, so the description must compensate, and it does: frame is defined as a frame number and doc_id is explained as the document id needed only for the fps fallback. That conditional caveat is the key semantic the schema lacks, though the frame parameter's accepted range/format is left implicit.

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

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

States a specific verb+resource: it returns the start time of a given frame, resolved through the loaded timecodes file with an fps fallback. This is more precise than a bare 'convert frame' but it never names its closest siblings (ass_ms_from_frame, ass_frame_from_ms, ass_ms_from_timecodes), so the agent must infer the split from context.

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

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

It explains the conditional path clearly: timecodes are honoured when a file is loaded, otherwise the document/workspace frame rate is used, and doc_id is only needed for that fps fallback. That tells the agent when each input matters, though it stops short of an explicit 'use this instead of X' routing statement against the other conversion 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 burden. It implies a read-only listing and gives the coordinate-conversion math (multiplied by 2 ** (1 - effective_scale)), which is genuinely useful, but says nothing about error cases, what happens when no clips exist, or the precedence rules for its three mutually optional inputs.

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

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

Front-loaded with the purpose, then a dense enumeration of returned fields. The field-by-field list largely restates what the existing output schema already conveys, so much of the length earns little, though the scale-space vs normalised explanation is valuable.

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?

An output schema exists, so the return-shape prose is largely redundant rather than necessary, and the real gap — how the three optional parameters interact — is left unexplained. For a read-only extraction tool this is workable but leaves invocation ambiguity unresolved.

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

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

Schema description coverage is 0% across three parameters (text, index, doc_id). The description only hints at the text-vs-line duality via the parenthetical and never explains what doc_id does, what 'index' indexes, or which parameter wins when several are supplied. It does not compensate for the coverage gap.

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

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

States a specific verb and resource ('List every \clip / \iclip tag') with the scope ('on a line (or in raw text)'). Clearly distinguishable from siblings like ass_parse_text or ass_tag_summary by its clip-specific focus, though it does not name any sibling to contrast against.

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 parenthetical '(on a line (or in raw text))' implies two invocation modes but never states when to use this versus ass_set_clip, ass_remove_clip, ass_convert_clip_scale, or ass_parse_text. No prerequisites or exclusions are given.

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 does disclose non-obvious behavior: the returned commands, bbox, size, centre and path length are all in scale space (units as written in the file), with the explicit conversion factor 2 ** (1 - scale). It stops short of stating read-only/side-effect status explicitly, relying on 'Inspect' to imply it.

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

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

Front-loaded with the two input modes, then the scale caveat, then the return shape; the bulleted structure is easy to scan. The enumeration of every return dict key is somewhat verbose given an output schema exists, which keeps it from 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?

For a read-only inspection tool with three optional params and an output schema present, the description covers everything an agent needs: modality selection, the scale-space semantics that would otherwise cause silent unit errors, and the aliasing of center/centre. Return values are additionally backed by the 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?

Schema description coverage is 0% and the schema only gives bare titles, so the description must compensate — and it does. It defines exactly what index + doc_id mean (line at that 0-based index in doc.events() order, split with tags.drawing_parts) and what text accepts (a full override line containing '{' or a \p tag, or bare drawing path data), plus the 'exactly one' constraint.

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?

Specific verb ('inspect') plus resource ('drawing part of a line, or a raw drawing string') that clearly identifies it as a read/extract operation on drawing data. It does not, however, name or differentiate itself from close siblings such as ass_drawing_info, ass_drawing_bbox or ass_drawing_to_svg, so an agent must still infer the boundary.

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 mutual-exclusion rule for the two input modes (index+doc_id vs text) is spelled out clearly, which is real usage guidance. But there is no when-to-use / when-not-to-use framing relative to alternatives (e.g. ass_get_line, ass_drawing_info), so selection among siblings is only implied.

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 genuine behavioral detail — that resolved_style is None when the style is absent from the document and that karaoke syllable times are resolved against line timing — but says nothing about error behavior for an out-of-range index or the doc_id fallback.

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 purpose is front-loaded and the bulleted structure is scannable, but the bulk of the text enumerates return keys that an output schema already describes, so several lines do not earn their place against the structured data.

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 an output schema present, the exhaustive return-value listing is largely redundant, while the genuinely missing pieces — doc_id meaning and out-of-range index behavior — go unexplained. It is adequate but leaves clear gaps for a 2-parameter 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 description coverage is 0%, so the description must compensate. It usefully clarifies that index is 0-based and refers to a line, but doc_id is never explained at all, leaving half the parameters undocumented in both schema and prose.

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 line names a specific verb and resource (full detail for a single line) and distinguishes it from the bulk sibling by framing the result as the ass_list_lines dict extended with extra keys. It does not explicitly route the agent between the two, but the 'extends ass_list_lines' framing makes the distinction inferable.

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

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

Usage is implied by 'Full detail' versus the list variant, but there is no explicit when-to-use/when-not statement and ass_list_lines is never named as the alternative for bulk reads. An agent must infer the routing from the phrasing alone.

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 correctly conveys a read operation and usefully discloses ordering fidelity and raw-line preservation, but says nothing about permissions, whether doc_id defaults to the active document, or any error/empty 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 purpose is correctly front-loaded in one short sentence, but the bulk of the text exhaustively documents return fields that the output schema already declares, so a large share of the description does not earn 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 single-parameter read tool with an output schema, the definition is adequate, but it omits the doc_id semantics and any usage context. The return documentation is redundant given the output schema, so the description is not adding value where it is actually needed.

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% and the single parameter doc_id (nullable, default null) is never mentioned in the description. The agent is left to guess whether null means the active document; the description does not compensate for the coverage gap it should have covered.

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 specific verb+resource ("Read `[Script Info]`") cleanly separates it from the mutation siblings ass_set_script_info and ass_remove_script_info. It does not, however, distinguish itself from the potentially confusable ass_document_info, leaving one ambiguity unresolved.

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 statement of when to use this tool, what precondition applies, or which sibling to prefer for related reads (e.g. ass_document_info, ass_list_styles). The description jumps straight into return-value semantics, so usage must be inferred from the name alone.

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

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

With no annotations, the description carries the full burden and does disclose real behavior: out-of-range indices are silently dropped and indices are 0-based. It does not state whether a document must already be open or what happens on an empty selection, but the pruning rule is genuinely useful context.

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

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

Front-loaded with the one-line purpose, then the return shape and the dropping rule. Tight and waste-free, though the embedded JSON-shaped return listing is slightly heavy 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?

An output schema exists, so return values need not be spelled out, yet the description adds useful semantics (0-based indexing, out-of-range pruning) that an agent needs. The only real gap is the missing call-context guidance against sibling selection 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?

The tool takes zero parameters, so the baseline is 4. The index-base note (0-based) is about returned values rather than inputs, but it is the only semantic the schema could not convey.

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

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

States a specific verb (read back) and resource (the session selection), immediately distinguishing it from write-side siblings like ass_select. The return payload is named concretely (doc_id, selection indices, count, lines), so an agent knows exactly what comes back.

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 explicit when-to-use guidance, no mention of the natural counterpart ass_select (which sets the selection being read), and no stated preconditions such as requiring an open/active document. Usage is only inferable 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?

With no annotations, the description carries the burden and does reasonably well: it discloses that include_glyphs runs an approximate fontconfig-based check, that sample_text defaults to the plain text of lines using the style capped at 2000 characters, and that font resolution exposes substitution state. It doesn't state read-only status or permission requirements explicitly, but the inspection nature is evident.

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

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

The purpose is front-loaded in one sentence, and the Args/Returns blocks are well organized. The detailed Returns enumeration is somewhat verbose given an output schema already exists, but it remains useful and non-repetitive.

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 moderately complex inspection tool, the definition covers parameters, defaults, side behaviors (glyph check), and return shape. An agent has everything needed to call it correctly, and the output schema covers the structured return.

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 fully compensates: it defines name (case-insensitive), doc_id (None = current document), include_glyphs (adds a glyphs report), and sample_text (default source and 2000-char cap). Every parameter is given 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 first sentence gives a specific verb (inspect) and resource (one style) plus the distinguishing feature (font resolution). It clearly separates from the plural sibling ass_list_styles and from ass_style_usage/ass_style_for_line, since it targets a single named style.

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

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

Usage is implied by the Args (name required, doc_id optional) but there is no explicit when-to-use guidance or routing against alternatives like ass_style_usage, ass_check_font_substitution, or ass_list_styles. The reader must infer the use case.

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 full burden and does a good job: it explains that override tags are removed, how the font is resolved through fallbacks, and what the output contains. It stops short of explicitly stating that the operation is read-only or has no side effects, which keeps it from a 5.

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

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

The description is front-loaded with a clear purpose sentence and well-structured input logic. However, it includes a long return-value specification even though an output schema exists, which makes it less concise than it could be.

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, zero annotation coverage, and an output schema, the description is mostly complete: it covers input resolution, fallback behavior, and output fields. It misses doc_id semantics and any explicit read-only assurance, which are minor gaps for a check 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%, so the description must compensate, and it does for four of five parameters: it defines when text vs. index is used, and when family vs. style is used, including fallback to line style then system default. The doc_id parameter is not explained at all, leaving one 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 states a specific check: 'Missing glyphs for a line's text or for a style's font.' It clearly identifies the resource (glyphs in text/font) and the action (checking for missing ones). It does not explicitly differentiate from siblings like ass_font_coverage or ass_check_font_substitution, 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?

The description explains the input resolution (text vs. index, family vs. style) but never states when to use this tool versus alternatives such as ass_font_coverage or ass_check_font_substitution. Usage is implied by the parameter logic rather than made explicit.

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

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

With no annotations, the description carries the burden and does fairly well: it discloses parsing edge cases (comma/dot decimal separators, multi-line blocks, CRLF, UTF-8 BOM), the conversion rule (multi-line bodies become \N hard breaks), and the snapshot-backed/undoable nature. It omits permission or open-document requirements, but the behavioral disclosure is meaningfully richer than a bare verb.

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

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

Purpose is front-loaded, then behavior, then args and returns in scannable sections. Every sentence earns its place, though the doubled backtick formatting adds minor visual noise.

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 moderately complex import tool, the description covers format handling, all params, and the return payload (even restating the output schema). The main residual gap is document-state prerequisites, but overall an agent has what it needs to call it correctly.

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

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

Schema description coverage is 0%, so the description must compensate, and it does: all four parameters are explained with real meaning (path = file to read, doc_id = document to append to with current-when-omitted fallback, style = ASS style for imported lines, offset_ms = time shift). This is exactly the compensation the low coverage requires.

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

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

The first sentence states a specific verb and resource: importing a SubRip (.srt) file as new ASS lines. It is unambiguous and distinguishable from siblings like ass_add_line/ass_add_lines, which create lines rather than import an external format.

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

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

Usage is implied by naming the .srt source format, but there is no explicit when-to-use vs alternatives, no statement of prerequisites (e.g. must a document be open / is ass_new_document required first), and no guidance on when importing is preferred over manual line creation.

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?

Annotations are absent, so the description must carry behavioral disclosure. It does well by stating that raw-string mode never writes, in_place writes back to the document, braces inside the payload are rejected, and override blocks do not count toward plain indices. It does not discuss permissions, reversibility, or undo behavior, but the core mutation semantics are disclosed.

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

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

The description is front-loaded with the tool purpose and then organized into Args and Returns sections. It is appropriately sized for a seven-parameter tool with nuanced index semantics, though the Returns section is somewhat redundant given the existing output schema.

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 high-complexity mutation tool with no annotations and no schema parameter descriptions, the description supplies enough parameter and behavioral context to invoke it correctly. It stops short of explaining when to use it versus sibling tools, but the core invocation requirements are covered.

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 explain all seven parameters, and it does. It defines index/text/doc_id, plain_index with concrete examples, override payload rules, after behavior including the plain_len edge case, and in_place write 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?

States a specific verb and resource: insert a bare override block at a plain character position. It is clear what the tool does, but it does not distinguish itself from sibling tag-insertion tools such as ass_set_tag or ass_apply_tag_to_block.

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 by explaining raw-string versus document mode and in_place writing, but it does not explicitly say when to choose this tool over alternatives like ass_set_tag or ass_apply_tag_to_block. No when-not 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 burden and does disclose real behavior: every part must parse, empty strings are rejected so no subpath is silently lost, and coordinates are serialised as integers. It also enumerates the return payload. It does not state side effects or whether the operation touches the document beyond returning doc_id, leaving a modest gap.

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

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

Front-loads the core action, then adds validation and return details in compact, well-organized sentences with no filler. 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?

An output schema exists, so return-value explanation is redundant but harmless. For a two-parameter transformation tool the description is nearly complete, with the only real omission being any explanation of the doc_id parameter.

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

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

Schema description coverage is 0%, so the description must compensate. It explains 'parts' well (list of drawing strings, single string coerced to a one-element list) but says nothing about 'doc_id', leaving one of the two parameters undocumented in both schema and description.

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

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

States a specific verb ('join') and resource ('drawing strings') and explicitly positions itself as the inverse of the sibling ass_split_drawing. An agent can distinguish it from ass_split_drawing, ass_transform_drawing, and ass_scale_drawing without opening a schema.

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

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

The inverse-of-ass_split_drawing framing gives clear context for when this tool applies, and the note that a single string is treated as a one-element list clarifies accepted input shapes. It stops short of naming exclusions or an alternative to pick when the parts don't parse, so it is clear but not exhaustive.

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

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

With no annotations, the description carries the full behavioral burden and does well: it discloses that apply=False is a pure read that only proposes text, that apply=True writes \k tags, and that the write happens after workspace.snapshot. This is meaningful side-effect disclosure beyond what any structured field provides; only auth/rate-limit style context is absent, which is reasonable for a local editor 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 purpose is front-loaded in the first sentence, and the Arguments/Returns headings make it scannable. The Returns block is lengthy, but since no output schema exists it is earning its place rather than padding; a minor trim of the field list would make it tighter.

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 tool with 0% schema coverage and no output schema, the description covers nearly all arguments and, helpfully, documents the return dict so an agent can interpret results like discrepancy_cs and matches_line_duration. It is nearly complete; the only gaps are doc_id semantics and deeper explanation of the non-syllable modes.

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, and it largely does: index, mode (with its four values and the marker dependency for 'syllable'), weights, start_ms/end_ms, apply, kind, and pattern are all given meaning and defaults. Only doc_id is left unexplained, and 'char'/'word'/'regex' modes get no elaboration on split behavior, but overall this is strong parameter documentation.

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

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

States a specific verb+resource ('Propose karaoke timings') with a clear scope constraint ('for one line from its duration') and notes the default read-only behavior. It is clear what the tool does, but it never names or contrasts with the nearest siblings (ass_karaoke_generate, ass_karaoke_retime), so sibling differentiation is left to inference.

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 through the argument explanations (e.g. mode selects the splitting strategy, apply toggles write), and the 'no write by default' framing hints at the propose-vs-commit use case. However, it never states when to prefer this over the many other karaoke tools (generate, retime, scale, set_timings), so no explicit when-to-use guidance is present.

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 largely does: it discloses the write side effect (writes into workspace.output_dir), the exact filename convention, and the return payload shape. It omits overwrite/clobber behavior and any permission requirements, which keeps it short of a 5.

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

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

Purpose is front-loaded in the first line, then arguments and returns are cleanly sectioned. The format listing is verbose but each format's output is materially different, so most sentences earn their 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?

No output schema exists, so the description correctly supplies the return key list and per-format output details. A 4 rather than 5 because doc_id's role and file-overwrite behavior are left unstated for a tool whose job is writing a file to disk.

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, and it documents three of four parameters in detail, including the exact column layout for each format value and the default behaviors. It does not document doc_id at all, which is the only gap.

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

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

States a specific verb and resource ('Export syllable timings') plus scope ('for other karaoke tools'), which distinguishes it from generic siblings like ass_export_text or ass_plain_text. An agent can tell what it produces without opening the schema.

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

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

Usage is implied by the purpose and by the stated default ('None exports every line that carries karaoke tags; pass a selection to override'), but no alternative tool is named and no when-not condition is given (e.g. vs ass_karaoke_get or ass_karaoke_tags_only). Adequate but leaves routing to 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 present, the description carries the full burden and does so thoroughly: it discloses that line times are never modified, that replace_existing=True rewrites existing tags while False reports lines in 'skipped', that min_cs violation raises ToolError rather than producing zeros, and that snap_to_line clamping is reported in 'snapped'. These are real behavioral traits an agent needs and none of them come from structured fields.

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

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

Front-loads the one-sentence purpose, then organizes the rest under clear Arguments/Returns headings with every parameter call-out earning its place. It is long, but the length is justified by 14 parameters and a missing output schema; density is appropriate rather than padded.

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

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

No output schema exists, and the description supplies an explicit Returns shape plus the exact-sum guarantee semantics. Combined with the parameter coverage and mutation rules, an agent has everything required to invoke this complex 14-parameter tool correctly.

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

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

Schema description coverage is 0% across 14 params, so the description must compensate, and it documents nearly all of them in prose (selection/index, start_ms/end_ms, mode, kind, link, weights, replace_existing, min_cs, snap_to_line) including allowed values for mode/kind/link/weights that the schema leaves un-enumerated. Only doc_id and marker are left undocumented, so it falls just short of fully covering the schema.

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

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

States a specific verb (Generate), a specific output artifact (\k tags), and a specific scope (a line's syllables). It also explicitly distinguishes itself from the sibling ass_karaoke_retime ('The line's own times are never modified by this tool'), so an agent can route correctly without opening another schema.

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

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

Explains the line-selection contract (index names one line, otherwise selection via base.resolve_indices, None uses the session selection, error when nothing is selected) and points to ass_karaoke_retime for retiming. It stops short of contrasting against other karaoke siblings (auto_timings, set_timings, set_kind), so a 4 rather than 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 and does well. It implies read-only behavior ('Read') and explicitly notes that discrepancy_cs is 'reported explicitly, never corrected here,' which is a useful behavioral trait. It also describes the return shape thoroughly. It does not mention error handling or required document state beyond 'open document,' keeping it from a 5.

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

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

The description is front-loaded with the purpose, followed by clearly labeled Arguments and Returns sections. It is somewhat long, but the detailed return documentation is justified because there is no output schema. Every section earns its place, though the return field list is 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 a moderately complex tool with no output schema and no annotations, the description provides complete parameter semantics and a full return structure. It could be more complete by stating error cases or that the document must be open, but it covers what an agent needs to call the tool correctly.

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

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

Schema coverage is 0%, so the description must compensate and it does fully. It explains 'index' as a 0-based line index in doc.events() order for an open document, and 'doc_id' as an open document id that defaults to the current one. Both parameters are completely documented in the description.

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+resource: 'Read the parsed karaoke of one line.' It is clear what it does. However, it does not explicitly distinguish itself from similar siblings like ass_karaoke_tags_only or ass_karaoke_export, 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?

There is no guidance on when to use this tool versus alternatives. It implies usage by saying it reads karaoke from an open document, but it does not state prerequisites, exclusions, or which sibling to use for other karaoke-related tasks.

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

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

With no annotations, the description carries the full burden and does well: it explains exactly what is destroyed (the karaoke tags, optionally the | markers), the default retention of markers and the reason, and the precise retightening/truncation side effect on the line's End when keep_times=False. It stops short of stating auth/permission needs or reversibility.

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

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

Front-loaded with the core purpose, then follows with the two behavioral flags and return shape. The prose is dense but each sentence carries information; only the return-shape dump is somewhat verbose.

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?

No output schema exists, yet the description supplies the full return structure, and with no annotations it fully documents the mutation's side effects. The only real gap is the unexplained required 'selection' parameter.

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

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

Schema description coverage is 0% across 4 params. The description compensates well for drop_markers and keep_times, including the default behavior of each, but leaves the required 'selection' parameter and 'doc_id' entirely unaddressed.

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

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

States a specific verb (remove) and a precisely scoped resource (\k/\kf/\ko/\kt karaoke tags), plus the underlying operation name. It is clearly distinguishable from generic siblings like ass_strip_tags and ass_remove_tag, which do not target karaoke timing tags specifically.

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

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

It gives implicit guidance: markers are kept by default because ass_karaoke_generate re-splits on them, which hints at the workflow. However it never states explicitly when to prefer this over ass_strip_tags/ass_remove_tag, nor any prerequisites about the selection or doc_id.

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