apply_drop_shadow

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

With no annotations supplied, the description carries the full behavioral burden and mostly does not meet it: it does not say whether the effect is applied destructively to layer pixels, whether it can be undone, what happens when layer_name matches nothing, or in what format color should be given. 'Returns status dict' is the only behavioral disclosure, and it is too vague to tell the agent what success/failure looks like.

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?

One front-loaded purpose sentence followed by a tight bulleted parameter list and a one-line return note; there is no filler. The defaults repeat the schema slightly, but that is the intended value-add given 0% schema description coverage.

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 seven-parameter mutation tool with no annotations and no output schema, the parameter documentation is solid but the effect's side effects, reversibility, and error conditions are absent. The return note is present but too thin to substitute for a missing output schema.

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, and it largely does: it gives units (offset in pixels), valid range (opacity 0-100), default values, and the meaningful semantic that layer_name falls back to the active layer and image_index targets a specific image. It leaves color's accepted format (name vs hex vs CSS) unstated, which is the one real 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?

States a specific verb and resource ('Apply a drop shadow effect to a layer'), which is instantly distinguishable from sibling effects such as apply_gaussian_blur, apply_vignette, and apply_emboss. It stops short of noting how it differs from the generic gegl_apply_filter route, but the core purpose is 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?

Usage is only implied by the target parameters ('layer_name: Target layer; defaults to active layer'). There is no statement of when to prefer this over gegl_apply_filter or apply_vignette-style siblings, and no prerequisites such as needing an open image, an existing layer, or a running server.

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