setEffect

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

Annotations already declare a non-read-only, non-destructive mutation. The description adds meaningful behavioral detail beyond that: only passed fields change, values equal to defaults are dropped, and the operation is refused if the new span collides with another effect (one runs at a time). It could have added more about prerequisites or return behavior, but the mutation semantics and failure mode are well disclosed.

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 tight sentences, front-loaded with the core action and followed immediately by mutation semantics and the conflict-refusal rule. Every sentence adds information and there is no filler.

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 mutation tool with six parameters, a nested object, no output schema, and sparse schema descriptions, the definition is largely complete: it covers purpose, partial-update behavior, default-omission, and conflict refusal. It leaves some parameter-level detail for the schema, but given the annotations and the complex input shape, it is adequate and helpful.

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?

With schema description coverage at only 17%, the description must carry more weight. It identifies the mutable groups (span, values, target) and notes span uses virtual seconds, plus the default-dropping behavior for values. But it does not explain the structure of the values object or clarify the target enum beyond its name, leaving much for the schema to describe despite the low coverage.

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 set (move, resize, re-tune), the resource (effect region), and the fields that can change (span, values, target). It clearly implies modification of an existing region by id, distinguishing it from creation tools like addEffect, but it does not explicitly name any sibling alternative.

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?

Usage is implied by the need for an effectRegionId and by the refusal condition when spans overlap, which tells the agent one effect runs at a time. However, there is no explicit when-to-use versus when-not-to-use guidance, and no alternative sibling is named for comparison.

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