stemlab_match_clip

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

Annotations only declare the generic hints (readOnlyHint=false, destructiveHint=false, openWorldHint=false, idempotentHint=false); the description adds the crucial non-obvious behavior that the call returns a retained background job rather than a result, and that effect scope is 'write' at base with inference/download conditionally inferable. That is real value beyond the structured fields. It stops short of saying what happens to a pre-existing output file or how failures surface.

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 short sentences, front-loaded with the core action and side effect, with no filler. The telegraphic style ('Base effect flags: write') is efficient but slightly compressed, reading more like a spec fragment than guidance.

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 tool with nested arguments, a permissions object, and an async job model, the description covers the two things an agent would most likely get wrong: that the return is a job to poll, and that effect scope extends conditionally. An output schema exists so return values needn't be spelled out. Missing is any statement of what the evidence JSON is used for or whether output must be a fresh path.

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 50% and the description names no parameter at all, so the agent gets nothing about what 'source', 'clip', or 'output' should be (paths? ids? formats?) or what clip_start/clip_end/sample_rate windows mean. The one compensating piece is the semantics of the permissions effect flags ('base effect flags: write', conditional inference/download), which the schema does not explain.

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+resource pair ('Match an audio clip to source audio') plus the side effect ('retain a new evidence JSON file'), which is far more informative than the bare name. It does not explicitly differentiate itself from the many other stemlab_* tools (analysis_actions, snap_cues, beat_offset), so the agent must infer the boundary from the name alone.

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 concrete follow-up guidance ('poll danceflow_job_status', 'inspect danceflow_component for conditional inference/download effects'), which is genuinely useful routing. However, it never says when to choose this tool over sibling stemlab tools that also produce evidence, and no prerequisites or preconditions are stated.

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