Fusion (destructive)

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

Annotations already declare destructiveHint=true and non-idempotent, but the description adds real context beyond them: the two-phase plan/confirm_token flow needed to actually apply a change, that delete_tools is a single undo step, that clear_keyframes preserves the current value, and that install_fuse executes Lua requiring code execution to be enabled. It stops short of stating irreversibility guarantees beyond snapshot.

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 purpose sentence, then a compact per-action parameter ledger, then the confirm-flow and batch_run rules. Telegraphic notation is dense but every line carries information an agent needs to construct a call.

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?

With an output schema present, return format need not be described, and dry_run/snapshot/confirm_token semantics are covered. Minor gap: it does not say how dry_run interacts with the confirm_token loop or what happens if snapshot is omitted under server policy.

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 100% for the four top-level fields, and the nested op object is deliberately opaque in schema (additionalProperties with a pointer to the description), so the per-action parameter list with asterisk-marked required args is genuine added meaning. Above the baseline 3 because the description carries the enum-to-params mapping the schema does not.

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+resource ("Remove fusion objects") and enumerates the four concrete actions with their required parameters, so an agent knows exactly what the tool can do. It does not explicitly contrast with fusion_write/fusion_read siblings, but listing delete-style operations makes the scope readable.

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?

Gives actionable routing: use ONE batch_run when calls are known in advance, and consult describe_action for per-action params. It also flags the install_fuse precondition (code execution enabled + confirmation). No explicit when-not-this-tool guidance against fusion_write, so not a 5.

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