Ase Set Cel Opacity

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

With no annotations, the description carries the full burden of behavioral disclosure. It adds useful context: the opacity range (0-255) and the special behavior that a null layer resolves to the first image layer. However, it does not disclose side effects like overwriting existing cel opacity, or any error conditions, which are relevant for a mutation tool.

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 a single, front-loaded sentence: the verb and object come first, followed by the range, then a parenthetical with the layer-null behavior. There is no redundant wording, and the special-case clarification is placed efficiently without bloating the text.

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 four-parameter setter with no annotationsasi, the description covers the core operation and one key parameter quirk, but it leaves frame semantics undefined and does not explicitly differentiate from ase_set_layer_opacity. The presence of an output schema reduces the need to describe return values, but the missing frame context and sibling differentiation are noticeable gaps.

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 0%, so the description must compensate. It clarifies the opacity constraint (0-255) and the layer null default, but it says nothing about the frame parameter, which remains opaque despite having a default. sprite_path is left to the reader's inference from the tool name. The description adds value for two of the four parameters but misses frame entirely.

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 verb ('Set'), the resource ('a single cel's opacity'), and the valid range (0-255). The phrase 'single cel' distinguishes this tool from sibling ase_set_layer_opacity, which operates on layer opacity, making its purpose unambiguous.

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 implies usage context by specifying 'single cel' and noting that layer None means the first image layer, but it does not explicitly name alternatives or state when to use this tool over layer-level opacity tools. The absence of exclusions leaves the agent to infer the routing decision.

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