stemlab_beat_offset

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

The description adds behavior beyond the annotations by disclosing that the tool returns a retained background job, requires polling via danceflow_job_status, and may involve write/inference/download effects. This is consistent with readOnlyHint=false and gives the agent important execution context.

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 brief and front-loads the main purpose before adding job and effect notes. The sentences are dense but well structured, with little unnecessary wording.

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?

The description covers the async job lifecycle and effect flags, and an output schema exists, so return-value explanation is not required. Still, for a tool with nested arguments and several required inputs, the definition leaves important input semantics under-explained.

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 only 50%, and the description does not explain key inputs such as results, output, audio, canonical_bpm, or the alignment options. It mentions saved results and canonical timing in prose, but does not map that meaning clearly to the nested parameters an agent must supply.

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 action and resource: compare detected beats against canonical timing in saved results. It also identifies the async job behavior, making the tool distinguishable from a simple read operation, though it does not explicitly contrast with sibling analysis tools.

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 gives useful post-call guidance by saying to poll danceflow_job_status, and it points to danceflow_component for conditional effects. However, it does not state when to use this tool versus alternatives or when not to use it.

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