find_glitches

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

With no annotations, the description carries the full burden and does well: it discloses the output form (onion-skin, previous red / next blue, boxed and labelled), the comparison rules (neighbour frames, loop wrapping, master reference), and the defect taxonomy. It omits whether the tool writes files or is read-only, which is a real gap for side-effect awareness.

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?

Front-loaded with the purpose and output form, then progressively more detail. The defect-kind enumeration is long but each term earns its place by defining a distinct class the agent will see in results.

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 7-parameter analysis tool with no output schema, it explains the comparison model, master semantics, and the full glitch taxonomy so an agent can interpret results. Missing documentation of path/layer/frames and of read-vs-write behaviour keeps it from a 5.

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 coverage is 0%, so the description must compensate. It adds real meaning for loop (wraps round), master (default is the first frame), and master_frames (transition start/end keys whose content is design), but leaves path, layer, and frames entirely unexplained despite being callable parameters.

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?

States a specific verb and resource ('find what animating broke, frame by frame') with a clear notion of the artifact produced (an onion-skin problem view). It is easy to tell apart from abstract siblings like 'lint' or 'compare' from the description alone, though it never names those siblings to make the distinction explicit.

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?

'Run it after every animate/edit pass; fix until ok' gives a clear trigger and lifecycle. It does not, however, contrast itself with apparent neighbours such as check_animation or lint, so the agent must infer when this is preferred over them.

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