calibrate_sync

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

Annotations already provide mutating/idempotent/non-destructive flags, and the description adds genuinely useful behavioral context beyond them: the action records a persistent per-movie anchor, computes scale+offset, and warns about a subtle failure mode where passing screen-adjusted time silently shifts the anchor by the existing offset. No contradiction with annotations.

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?

Four sentences with no filler: the purpose is front-loaded, the recommended parameter is given immediately, and the warning is dense but essential. 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?

For a 4-parameter mutation tool with no output schema, the description covers the core workflow, the one serious time-source footgun, and the required-parameter recommendation. The only notable gap is store_id, which has a default and may be session-derived, so it is unlikely to block a basic invocation.

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

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

Schema description coverage is 0%, so the description carries full parameter-documentation burden. It explicitly explains spoken_text and subtitle_time, and 'pause position' maps to actual_time, but store_id is never mentioned, and actual_time is only implied rather than named. This is a meaningful partial compensation, not complete.

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 action and resource: it records a per-movie sync anchor from the current dialogue/pause position and calculates a two-point scale+offset. This clearly differentiates calibrate_sync from sibling tools such as start_overlay or translate_subtitle, so the purpose is unambiguous.

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

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

The description gives concrete guidance for the recommended input path ('권장 경로는 spoken_text') and a clear exclusion: subtitle_time must be the raw subtitle-file time, not the screen time after an offset is applied, otherwise the anchor drifts. It does not name a sibling alternative, but no sibling covers sync calibration, so this is sufficient context.

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