Create scheduler

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

Annotations already indicate a mutating, non-destructive, open-world tool, and the description adds specific side effects: it creates a scheduler COMP with a shared Callbacks DAT, fires callbacks on onDone/onSegmentEnter, and reuses manage_cue's tdmcp_cues storage. This gives the agent awareness of dependencies and created artifacts without contradicting the 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?

Three dense sentences front-load the core purpose and then add dependency and usage context. Every sentence contributes distinct value: what is built, how it fits in the automation stack, and its storage dependency. No filler or repetition of the input schema.

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 complex constructor tool, the description covers the essential conceptual model (timers, segments, callbacks), the dependency on manage_cue, and the distinction from create_scene_timeline. The schema provides complete parameter-level detail, and the description adds the missing architectural context. The tool's output is a built COMP, which is implicitly clear, so no return-value explanation is needed.

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 input schema covers all 8 parameters with detailed descriptions (100% coverage), so the description doesn't need to restate parameter syntax. It adds high-level context about timer/segment structure and the manage_cue dependency for 'cue' actions, but this doesn't materially exceed what the schema already communicates. Baseline of 3 is appropriate.

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 opens with a specific verb and resource: 'Build a Timer-CHOP scheduler COMP' and details its core components (named timers, optional segments, shared Callbacks DAT, cue/param/script actions). It clearly distinguishes itself as 'atomic timer primitive that create_scene_timeline and other automation rides on', separating it from higher-level timeline/sequencer siblings.

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 frames this as a foundational primitive for automation, implying use when building lower-level timer logic rather than higher-level scenes/timelines. It also gives a concrete prerequisite: 'store target cues first with manage_cue' for the default cue action. It doesn't explicitly name alternative tools or state when not to use it, but the context is clear.

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