warp_region

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

With no annotations, the description carries the behavioral burden and does disclose implementation details (GEGL warp with plug-in-iwarp fallback) and the return value, which is real added context. However, it never states that this mutates the target layer in place, whether the edit is undoable, or how failures behave — meaningful gaps for a pixel-mutating operation.

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?

It is front-loaded with purpose and mechanism, then a parameter block, then one example — a sensible hierarchy. The three-vector example is verbose relative to the rest, but it demonstrates a non-obvious coordinate-based workflow that text alone could not convey, so it largely earns its space.

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?

There is no output schema, and the description supplies the return shape ({"warped_vectors": N}), plus defaults for every optional parameter and target selection rules. For a single-operation pixel-warp tool, nothing an agent needs to call it 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 description coverage is 0% and the vectors array is untyped (items: {}), so the description must do all the work — and it does, documenting x, y, dx, dy, radius (default 40), and amount (0–1, default 0.3) with directional semantics such as "negative dy = push upward." It also explains image_index and layer_name fallback to the active/top layer, fully compensating for the schema gap.

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?

"Warp / liquify a region of the image by pushing pixels in a direction" is a specific verb plus resource plus mechanism, and it clearly separates this tool from siblings like transform_layer (whole-layer transforms) or gegl_apply_filter (generic filter application). An agent can tell what this does without opening the schema.

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 a concrete usage context (subtle facial expression edits, e.g. turning a neutral mouth into a smile) with a worked three-stroke example, which is unusually actionable. It stops short of explicit exclusions — nothing says when to prefer transform_layer or gegl_apply_filter instead — so it is strong but not a full when/when-not/alternatives statement.

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