subtitle_info

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

With no annotations supplied, the description carries the full burden and does well: it declares "Read-only," explains the detection method and that reason and confidence are reported, and gives a remediation path for misdetection. It does not state what happens on an unsupported or missing file, or whether it parses the whole file (cost on large inputs), which keeps it below 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 output inventory is front-loaded in the first sentence, followed by the encoding-detection paragraph and a compact Args block. The middle paragraph on detection heuristics is slightly longer than needed for an agent's decision-making, but every part is relevant and there is no filler.

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

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

An output schema exists, so the enumerated return fields are arguably redundant, but their presence confirms scope and the description also covers safety posture, parameter semantics, and a retry strategy for encoding failures. Only error/failure conditions and large-file cost are left implicit for a tool that is the mandated first step in the workflow.

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: `path` is constrained to .srt/.vtt/.ass/.ssa, and `encoding` is described as a Python codec name with a concrete example ('cp1254') and an explicit auto-detect default. It leaves path resolution (relative vs absolute) and error behavior for bad codecs unstated, so it is strong but not exhaustive.

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

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

The description opens with a specific verb and resource ("Inspect a subtitle file") and enumerates exactly what is reported: format, detected encoding, line endings, cue count, time span, overlaps, gaps, longest line, reading speed statistics, and a problem list with cue numbers. That level of specificity clearly separates it from siblings like read_cues (raw cue content) and fix_common_problems (mutation).

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 explicit sequencing guidance with "Run this first," which tells the agent where this sits in the workflow, plus a concrete conditional branch: if text looks garbled, force `encoding` and rerun. It stops short of naming specific alternative tools (e.g., read_cues for content inspection), so the when-not guidance is implied rather than spelled out.

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