get_clip_properties

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

With no annotations, the description carries the behavioral burden. It discloses return details beyond the schema: positions are returned both normalized and in pixels using sequence frame size, and motion values include opacity/scale/rotation/position. 'Gets' signals a read-only operation, which is appropriate, though error cases and the full scope of 'detailed properties' are not covered.

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 sentences with dense, relevant information. The main purpose and distinguishing motion-value detail are front-loaded, and the sequenceId guidance is placed where it naturally follows. No filler or repetition of the tool name.

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 there is no output schema and no annotations, the description provides the essential context for correct invocation: what the tool returns, the coordinate-space nuance, and when sequenceId is required. It is slightly incomplete in not listing the full property set or possible failure modes, but it is strong for a read-only property getter.

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 schema already documents both parameters at 100% coverage, so a baseline of 3 applies. The description adds useful context beyond the schema by explaining when sequenceId is needed (clip IDs coming from list_sequence_tracks) and why the pixel position distinction matters.

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 a specific verb and resource: it gets detailed properties of a clip and explicitly highlights current Motion values. It does not explicitly distinguish itself from similar sibling tools like get_full_clip_info or get_qe_clip_info, but the emphasized motion/position details give enough specificity.

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?

Provides a clear usage condition: pass sequenceId when the clip ID came from list_sequence_tracks for a non-active sequence. It also explains the fallback search order via the schema, but does not explicitly state when to prefer this tool over alternatives like get_full_clip_info.

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