pr_razor

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

Annotations already declare this is a mutation (readOnlyHint=false) that is non-destructive (destructiveHint=false). The description adds useful scope behavior by saying cuts apply across all tracks or only the listed tracks, but it does not describe side effects, sequence requirements, or return behavior beyond what annotations and schema provide.

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 a single front-loaded sentence with no wasted words. It identifies the application, action, timing input, and track scope efficiently.

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 simple timeline-cutting tool, the description plus annotations and schema give enough to invoke it correctly. The sequence default and time format are covered by the schema, and the non-destructive mutation profile is covered by annotations, though the description could say more about expected editing behavior.

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 (33%), so the description must compensate. It partially does by clarifying that 'times' is one or more cut points and that 'tracks' optionally limits cutting to listed tracks, but it does not mention the 'sequence' parameter or time format, leaving those to the schema.

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 verb and resource ('razor (cut)') and scopes it to 'one or more times across all tracks or the listed tracks.' It is clear what the tool does, though it does not explicitly differentiate itself from nearby editing siblings such as pr_trimClip or pr_removeRange.

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 implies the use case (cut at specified times) but gives no explicit guidance on when to choose this over alternatives like pr_removeRange or pr_trimClip. There are no prerequisites, exclusions, or alternative-routing instructions.

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