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

Annotations confirm non-destructive and idempotent behavior, but the description adds critical context beyond them: the split is approximate, proportional to character count, does not change words, and produces estimated timings. These limitations directly affect how an agent should interpret and use the result.

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 definition is front-loaded with the key caveat, 'Approximate split, not audio-grounded segmentation,' then explains the algorithm and alternative in a compact paragraph. Every sentence contributes useful information, including the limitation and routing guidance.

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 non-destructive, idempotent cue-splitting tool without an output schema, the description provides the behavioral details an agent needs: approximation method, word preservation, and estimated timings. It also routes agents to the correct alternative when accurate timing is required.

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

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

Schema coverage is 100%, so jobId, track, and maxCueMs are already fully documented in the schema. The description explains the splitting algorithm conceptually but does not add syntax, constraints, or defaults beyond what the schema provides. A baseline 3 is appropriate when the schema does the parameter-level work.

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 operation: cue text is divided at clause punctuation and each piece receives a proportional share of the original span. It explicitly distinguishes this approximate split from audio-grounded segmentation and names the sibling tool for audio-derived timing. An agent can tell exactly what this tool does and does not do.

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 usage guidance: treat timings as a reading aid rather than a re-alignment, and use lunara_start_subtitle_job if timing must be derived from audio. This names both the condition and the alternative, leaving no ambiguity about when to select this tool.

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