photoshop_apply_gradient_mask
Apply a black-to-white linear gradient to the active layer mask, creating soft edge fades and blending the layer into the background. Use it to fade edges or blend subjects when a layer mask is already present.
Instructions
Apply a linear black-to-white gradient on the active layer mask channel (fade/blend).
Users often say: fade into background, gradient mask, blend subject, soft edge fade.
This paints on an existing layer mask — not a Gradient Fill layer. Use when: softening edges or fading a layer into the background through its mask. Do NOT use when: subject is not isolated — use photoshop_recipe_remove_background or photoshop_create_layer_mask first.
Returns: JSON { ok, summary, details: { applied, direction, angle, mask_auto_created? } }. Preconditions: active document and active layer. Creates a reveal-all mask if none exists. Side effects: modifies layer mask pixels; two history steps when mask is auto-created.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| end_pct | No | Gradient end along fade axis (0-100) | |
| angle_deg | No | Override gradient angle in degrees (optional) | |
| direction | No | Gradient fade direction on the mask (default bottom_to_top) | bottom_to_top |
| start_pct | No | Gradient start along fade axis (0-100) | |
| document_id | No | Optional Photoshop document id from photoshop_get_state / photoshop_list_documents. When set, the tool activates that document before running so a UI tab switch cannot retarget the edit. |