Play media range

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

The description discloses key behavioral traits: it returns immediately while the server watches the OBS cursor, and at the end it pauses on the exact frame by default or stops. This goes beyond the annotations, which are all false and thus provide no behavioral hints. However, it doesn't mention how speedPercent or pollIntervalMs affect execution, nor does it clarify what happens if both mediaId and mediaName are omitted. Still, the core behavior is well explained.

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

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

The description is two sentences long, front-loads the primary purpose, and includes essential behavioral details without fluff. Every word earns its place, and the structure is efficient.

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 complexity (7 parameters, low schema coverage, output schema exists), the description is incomplete. It does not explain how to identify the media (mediaId vs mediaName, or that one is needed), nor does it clarify the role of speedPercent or pollIntervalMs. It also doesn't mention what the return value indicates, though the output schema covers that. For a tool with this many parameters, more context is needed 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 low (29%), so the description must compensate. It adds meaning to startMs/endMs (defines them as the range), endAction (pause/stop), and implicitly the default behavior. It does not explain speedPercent or pollIntervalMs, but those are somewhat self-explanatory and have constraints in the schema. Given the coverage gap, the description provides meaningful semantics for the most critical parameters.

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

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

The description clearly states the tool plays a specified time range ([startMs,endMs]) on a media source, using the verb 'play' with a specific resource. It also distinguishes this from general media_play (which plays the whole media) and media_seek (which jumps to a position) by focusing on range playback. The sibling tool names reinforce this 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?

The description implies usage for playing a segment, but it does not explicitly state when to use this over alternatives like media_play or media_seek. It also doesn't mention prerequisites (e.g., requiring a mediaId or mediaName to identify the source) or scenarios where this tool is inappropriate. The guidance is implied rather than explicit.

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