add_shadow

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

Annotations already disclose the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false, openWorldHint=true), so the description isn't carrying that burden. It does add meaningful context that the output is a transparent-background composite rather than an in-place edit, but it says nothing about overwrite behavior, failure modes, or the fact that offset/blur are pixel-space operations subject to image size.

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?

A single twelve-word sentence with zero filler, leading with the operation and ending with the output characteristic. Nothing is redundant against the title or schema.

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 an output schema present and full parameter documentation, the description needn't explain return values or argument formats. What it does convey — implicit subject segmentation plus transparent-background shadow compositing — covers the surprising behavior. Minor gap: no hint about behavior when segmentation finds no subject, or that output_path controls whether an existing file is overwritten.

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 100%, and every parameter (offset_x/y, blur_radius, shadow_color, output_path, image_path) is documented with type, default, and units in the schema. The description adds no parameter-level meaning beyond that, which is the expected baseline 3 when the schema does the heavy lifting.

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 compound action: segment the subject out of the image and render a drop shadow behind it on a transparent background. That 'cut out the subject' framing also implies built-in background removal, which is the key detail an agent needs to distinguish this from siblings like blur_background or color_background. It stops short of naming an alternative explicitly, so it isn't a 5.

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?

There is no guidance on when to choose add_shadow over remove_background (which also produces a transparent cutout) or create_mask. No prerequisites, no exclusions, no mention of what happens on images without a detectable subject. The agent must infer the use case entirely from the verb.

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