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

The annotations already declare destructive=true, idempotent=true, openWorld=true and readOnly=false, so the write/replace profile is largely covered structurally. The description adds genuinely useful context beyond that – the named channel is replaced, output is soft-edged, runtime is ~5-10 s, a second object is faster, and select mode=channel accumulates objects – but it does not describe recovery of a replaced channel or permission requirements.

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 purpose is front-loaded and essentially every clause carries operational information (mode-specific rules, defaults, fallbacks), so there is little filler. The tradeoff is that it is delivered as one dense run-on paragraph with mixed topics, which slightly hurts scannability.

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 eight parameters, three modes and no output schema, the description covers the full operational surface: per-target rules, layer handling, defaults, fallback paths, and even a hint at result feedback. Nothing an agent needs to invoke this correctly is missing.

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 already 100%, which sets the baseline at 3. The description nonetheless adds real meaning beyond the schema: how word resolves through find_objects, that the result reports which box was used, the default naming rule (Subject/Sky/Object by target), and that subject_up only applies to target=subject.

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 opening states a specific verb and resource: an AI-driven selection written into a NAMED channel with soft edges. It then enumerates the three distinct modes (subject, sky, object) and what each selects, so an agent can immediately tell this apart from find_objects or modify_selection.

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 explicit when-to-use guidance per target, including the layer workflow (place photo, select subject, then layer_mask op=create), the sky workflow (use as add_adjustment mask or invert via modify_selection), and box-vs-word selection for objects. It names concrete alternative tools and the conditions that select them.

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