Sync external clock (tempo)

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

Description discloses that the tool writes the global tempo ('Bpm knob writes the global tempo (op('/').time.tempo)') and drives Beat CHOPs downstream. Annotations show readOnlyHint=false and destructiveHint=false, consistent with a mutation tool. However, no mention of side effects like resetting other nodes or permissions beyond the notes.

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 sentences with no wasted words. Purpose is front-loaded, followed by technical mechanism and future plans. Highly efficient structure.

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 2-parameter tool with no output schema, the description covers purpose, mechanism, downstream effects, and alternatives. It lacks explicit mention of error handling or what happens if parent_path is omitted, but overall contextual completeness is high.

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 covers 50% of parameters: bpm has a detailed description, but parent_path lacks description. The tool description adds no further meaning to parent_path. Schema already provides good guidance for bpm, so description adds limited value beyond 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 clearly states the action ('Lock project tempo to a live source') and the resource (project tempo), distinguishing it from sibling tools like create_tempo_sync and create_autopilot by noting they follow this tool's output. It also mentions planned alternatives like MIDI-clock/Ableton-Link, establishing clear 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 provides when-to-use context: for beat-synced visuals following live music. It explicitly notes planned alternatives ('Dedicated MIDI-clock / Ableton-Link sync is a planned follow-up') and advises to match DJ by tapping or dialing BPM, implying when not to use this for those sync methods.

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