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

Annotations declare destructive=true, readOnlyHint=false and idempotentHint=false, and the description goes well beyond them: it warns that Text and Smart Objects are rasterized first, that pixels are destroyed, that it consumes one history step, that repeated calls stack additional deltas, and that photoshop_undo reverses it. This is exactly the extra behavioral context the annotations cannot express.

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?

Front-loads the operation and the delta semantics, then uses tight labeled blocks (Users often say / Use when / Do NOT use when / Returns / Preconditions / Side effects). No sentence is filler; every clause either routes the agent or sets expectations.

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 no output schema, the description still states the return value (the applied brightness and contrast values) and covers preconditions (active document and layer), destructive side effects, reversibility, and the stacking behavior. Nothing needed to call 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 100%, so brightness/contrast ranges and the document_id resolution rules are already documented, setting the baseline at 3. The description adds genuine meaning beyond the schema by clarifying that the numbers are deltas applied to pixels rather than an adjustment-layer setting, which changes how an agent should reason about repeat calls.

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 Image > Adjustments > Brightness/Contrast once to the active layer') and immediately scopes the values as pixel deltas rather than an adjustment layer. This is enough to distinguish it from the many sibling adjustment tools without opening any 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?

Provides explicit when-to-use plus three when-not-to-use clauses, each naming the correct alternative sibling (photoshop_adjust_exposure for stops, photoshop_adjust_curves for tonal curves, photoshop_auto_levels for auto black/white points). It even captures the colloquial user phrasings ('fix exposure, brighten, darken') that trigger it.

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

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

Annotations already declare the safety profile (readOnly=false, destructive=false, idempotent=false). The description adds value beyond them by disclosing the precondition (active document), the side effect (adds a Curves adjustment layer), and the return shape. It does not cover undo/reversibility or interaction with existing layers, so not a 5.

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?

Front-loaded with the action, then structured into intent/use/do-not-use/returns/preconditions/side-effects blocks. Every line earns its place, though the 'Users often say' line is more helpful than strictly necessary.

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?

No output schema exists, but the description supplies the return JSON shape, preconditions, and side effects, which covers most of what an agent needs. Minor gaps around reversibility and how the layer interacts with existing layers keep it from a 5.

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%, so both parameters are already documented in the schema. The description mentions 'S-curve' and the returned 'preset', which loosely aligns with the auto_tone enum value but adds no syntax or format beyond the schema. Baseline 3 applies.

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 ('Create a Curves adjustment layer') and names the sibling it is not (photoshop_recipe_apply_color_grade). An agent can distinguish it from related tonal tools like photoshop_adjust_brightness_contrast or photoshop_auto_contrast via the 'non-destructive Curves adjustment layer' framing.

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?

Explicit 'Use when' and 'Do NOT use when' clauses with a named alternative, plus user-intent synonyms ('make it pop', 'S-curve', 'fix flat image'). This routes the agent correctly without inference.

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

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

Annotations already declare the safety profile (readOnly=false, destructive=false, idempotent=false), so the bar is lower, and the description adds real value beyond them: the precondition of an active document and the side effect of adding an adjustment layer. It could go further by noting that repeated calls stack new layers (non-idempotent behavior) or whether it is undoable, which is why it is not a 5.

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?

Four tight, front-loaded fragments covering purpose, user phrasing, return shape, preconditions and side effects. Every sentence earns its place and the most decision-relevant information (what it creates) leads.

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 no output schema, the description correctly supplies the return shape, and it also covers the precondition and side effect an agent needs before invoking a mutation. Nothing material is missing for a 4-parameter adjustment-layer tool.

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%, including units and ranges ('Exposure in stops (-20 to 20)', gamma/offset bounds), so the schema already carries the semantic load and the baseline is 3. The description's parenthetical '(stops, offset, gamma correction)' restates the same fields without adding format or interaction detail beyond the schema.

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+resource ('Create an Exposure adjustment layer') and names the three controlling parameters, which distinguishes it from generic layer creation. It does not explicitly contrast itself with near-neighbors like photoshop_adjust_brightness_contrast or photoshop_adjust_curves, so it stops short of 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?

The line 'Users often say: fix underexposed photo, brighten by a stop, gamma fix' gives trigger phrasing and implied intent, which is genuinely useful. However, it never states when to prefer this over the sibling exposure-related tools (brightness/contrast, curves, auto_levels) or any exclusions, so usage guidance remains implied rather than explicit.

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

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

Annotations already flag destructiveHint=true, but the description adds far more: values are baked into pixels rather than stored as an adjustment layer, text/Smart Objects are rasterized, a non-Normal blend mode is reset, it consumes one history step, and it is reversible via photoshop_undo. This is exactly the beyond-annotation detail a mutation tool needs.

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?

Front-loads the action, then uses labeled sections (Use when / Do NOT use when / Returns / Preconditions / Side effects), which makes it scannable. Slightly over-long with two separate 'Do NOT use when' lines and minor redundancy between 'Returns' and the opening sentence.

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 compensates by stating the return value, the preconditions (active document and layer), the destructive side effects, and the undo path. Nothing an agent needs to invoke it safely 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 100% — hue, saturation, lightness and document_id all carry ranges and semantics in the schema. The description adds no parameter-level detail beyond restating the three adjustment axes, so the baseline 3 applies.

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 ('Shift hue, saturation, and lightness on the active layer') and anchors it to the concrete Photoshop menu path. It explicitly distinguishes itself from siblings that could be confused with it (vibrance, curves, color-grade recipe).

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?

Gives an explicit 'Use when' condition plus two 'Do NOT use when' exclusions, each paired with the correct alternative tool. An agent can route between this, photoshop_adjust_vibrance, photoshop_adjust_curves and photoshop_recipe_apply_color_grade with no inference.

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

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

Annotations already declare this is a non-idempotent write that is not destructive, and the description adds value beyond them: an explicit precondition (active document) and the concrete side effect (adds a layer), which also reinforces the non-idempotent hint. It does not discuss permissions or how repeated calls stack layers, keeping it at a 4.

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?

Front-loaded with the action, then structured into short labeled lines (Returns, Preconditions, Side effects). The informal "Users often say" line is unconventional but earns its place as intent mapping; overall it is tight with little waste.

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 3-param mutation tool with no output schema, the description covers the return shape, precondition, and side effect, matching the complexity well. Only the non-idempotency/stacking behavior of repeated calls goes unstated.

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%, so vibrance, saturation, and the rich document_id semantics are already fully documented in the schema. The description adds no additional parameter meaning, so the baseline 3 applies.

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 first sentence gives a specific verb + resource ("Create a Vibrance adjustment layer") and adds the semantic distinction from plain saturation ("boosts muted colors while protecting skin tones"). It does not name any sibling such as photoshop_adjust_hue_saturation or photoshop_desaturate, so differentiation is implied rather than explicit.

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?

The "make colors pop (safely)" / "boost saturation without clown look" line gives clear natural-language context for when this is the right adjustment versus a harsher saturation move. It stops short of naming the alternative tools or an explicit when-not, so it is clear context without exclusions.

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

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

Annotations already declare destructiveHint=true, readOnlyHint=false, and idempotentHint=false, so the safety profile is covered externally. The description adds only the target ('active layer') and no further behavioral context such as irreversibility, undo behavior, or whether the filter is applied nondestructively, so it does not meaningfully extend the annotations.

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 description is a single front-loaded sentence with no filler, and it immediately states the operation, filter, and target. Every word earns its place for a simple filter operation.

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 straightforward filter tool with a complete input schema and annotations covering its destructive nature, the description is minimally sufficient. It omits distinguishing context relative to sibling blur filters and does not mention undo or outcome, leaving some gaps despite the low complexity.

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 both parameters are fully documented in the input schema (radius range, document_id behavior). The description adds no additional meaning beyond what the schema already provides, so the baseline score of 3 applies.

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 gives a specific verb (Apply) and a specific resource/filter (Gaussian Blur filter) and target (active layer). It clearly distinguishes this from vague processing tools, but does not explicitly differentiate it from sibling blur filters such as photoshop_apply_motion_blur or photoshop_apply_smart_blur.

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 explicit when-to-use guidance, no alternatives named, and no prerequisites or exclusions. The phrase 'to the active layer' implies a scope, but an agent gets no help choosing between Gaussian Blur and the other blur or filter tools in the same family.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=false, so the description's added value is the explicit side effect ('adds a Gradient Map adjustment layer'), the precondition, and the return shape. It does not explain that repeated calls stack additional layers (consistent with idempotentHint=false) or how existing pixel data is affected, so it is solid but not exhaustive.

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?

Front-loaded with the action and its purpose, then compact labeled lines for Returns and Preconditions/Side effects. The 'Users often say' line is slightly colloquial but earns its place as intent-matching aid; no sentence is pure filler.

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 no output schema, the description usefully documents the JSON return shape, and it covers preconditions and side effects for a mutation tool. Missing only edge-case behavior (layer stacking on repeat calls, whether it targets the active layer or the whole document), which is minor for a two-parameter adjustment tool.

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 the schema already documents both document_id (including the null/0 active-document behavior) and reverse. The description only adds the default gradient direction (black→white) and echoes 'reverse' in the return payload, so baseline 3 is appropriate.

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 precise verb + resource ('Create a Gradient Map adjustment layer') plus its functional intent ('duotone/B&W tonal remapping'), which implicitly separates it from pixel-level siblings like photoshop_fill_gradient and from photoshop_apply_lut or photoshop_desaturate. An agent can identify the operation 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?

Supplies concrete user-intent triggers ('duotone look, gradient map B&W, remap tones') that make routing decisions easy, and states the precondition of an active document. It stops short of naming alternatives (e.g., desaturate or LUT for B&W conversion) or when-not to use it, so it is clear context without exclusions.

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

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

Goes well beyond the destructiveHint=true annotation by disclosing preconditions (active document and layer), the auto-creation of a reveal-all mask, the exact side effect (modifies layer mask pixels), and history behavior (two history steps when mask is auto-created). It also clarifies it paints on an existing mask rather than creating a Gradient Fill layer.

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?

Front-loaded with the core action, then cleanly sectioned into synonyms, Use/Do-not-use, Returns, Preconditions, and Side effects. Minor redundancy in the synonym lists ('fade/blend', 'fade into background') but every section is purposeful and well organized.

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 destructive mask operation with no output schema, the description supplies the return shape (ok, summary, details), preconditions, and side effects, leaving nothing an agent needs in order to invoke it correctly.

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%, so the schema already documents document_id, direction, angle_deg, start_pct and end_pct with ranges and defaults. The description adds only marginal param context (direction/angle implied via the returns block), so the baseline of 3 is appropriate when the schema carries the load.

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 (Apply), resource (linear black-to-white gradient), and target (active layer mask channel), plus a parenthetical clarifying the intent as fade/blend. It explicitly distinguishes itself from a Gradient Fill layer, so an agent can tell it apart from siblings like photoshop_fill_gradient and photoshop_apply_gradient_map.

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?

Provides explicit 'Use when' (softening edges, fading a layer into background through its mask) and 'Do NOT use when' (subject not isolated) guidance, and names concrete alternatives (photoshop_recipe_remove_background, photoshop_create_layer_mask) to route the agent correctly.

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

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

Annotations already flag destructiveHint=true, readOnlyHint=false and non-idempotency, so the safety profile is covered. The description adds genuinely new context: preconditions (active document, normal raster layer selected) and side effects (exactly one history step), which tells the agent the change is a single undoable operation. It doesn't state whether the filter clobbers existing pixel data beyond the layer itself, but that is largely implied.

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?

Front-loaded with the core action, then labeled sections for user phrasing, usage, exclusions, returns, preconditions and side effects. Every line carries information; nothing is repeated from the schema or annotations.

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 two-param mutation with no output schema, the description covers purpose, when/not-when, precondition state, side effects and the return shape ({ok, summary, details}). An agent has everything needed to call it correctly without probing.

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%, so radius (0.1-250 px edge retention) and document_id semantics are already fully documented in the schema. The description adds no syntax, units, or trade-off guidance beyond that, so the baseline 3 applies.

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 (Apply) and resource (High Pass filter on the active raster layer) plus the intent (edge/detail extraction for sharpening or frequency separation prep). It also disambiguates from the closely related sibling photoshop_apply_sharpen by describing the underlying mechanism rather than the end goal.

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?

Explicit 'Use when' conditions (overlay-blend sharpening, detail extraction, prepping a high-frequency layer) and explicit exclusions (text, Smart Objects, Background layer) with the remediation path named via photoshop_rasterize_layer. An agent knows both when to call this and when to call something else first.

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

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

Annotations already declare destructiveHint=true and idempotentHint=false, but the description adds what is destroyed (masked-out pixels and the mask itself), the precondition (active doc plus masked layer), and the recovery path (photoshop_undo while history holds it). This is rich behavioral detail beyond the annotation flags.

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?

Front-loaded with the core action and consequence, then organized into tight labeled lines for condition, exclusions, return, and side effects. Every sentence carries distinct information with no padding.

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 destructive single-param tool with no output schema, the description covers return, preconditions, side effects, and reversibility. An agent has everything needed to decide and call correctly.

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?

Only one parameter and schema description coverage is 100%, so the schema already documents document_id, null/0 semantics, and activation behavior. The description adds nothing about the parameter, which is the expected baseline for a fully-covered single-param tool.

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 precise verb and resource ('bake the active layer mask into its pixels and remove the mask') plus the pixel-level consequence. It explicitly names the two sibling masks tools it is not (create_layer_mask, delete_layer_mask), so an agent can route without opening schemas.

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?

Provides explicit 'Use when' plus two 'Do NOT use when' branches, each naming the alternative tool or action to take instead. The decision boundary between applying, keeping, and deleting a mask is fully specified.

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

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

Annotations already declare non-read-only, idempotent, non-destructive behavior, so the bar is lower, but the description adds real value: preconditions (active document with active pixel/text layer), side effects (sets the chosen effect on the active layer), and the significant caveat that drop shadow uses the given angle with Use Global Light off. It also documents the return payload despite no output schema.

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?

Front-loaded purpose sentence, then clearly labeled Use/Do-not-use/Returns/Preconditions blocks — easy to scan. The mixed-language user-phrase list is slightly noisy but arguably earns its place for natural-language intent matching.

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 9-parameter, no-output-schema mutation tool, the definition covers preconditions, side effects, the return shape, and routing to the alternative. Nothing essential to invoking it correctly appears to be 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 100%, so the baseline is 3, but the description adds meaning beyond the schema by clarifying that angle governs the drop shadow because global light is off, and by tying size semantics (stroke width) to the effect chosen. It does not, however, explain how color/opacity interact across the four styles.

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 (apply) and resource (layer style) and enumerates the concrete effects covered (drop shadow, outer glow, stroke, bevel & emboss). It also names the sibling route for advanced cases, photoshop_execute_script, so an agent can distinguish it from the generic escape hatch.

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?

Explicit 'Use when' (quick presentational effects on the active layer) and 'Do NOT use when' (needing full custom layer-effects control, use photoshop_execute_script) sections give both the trigger condition and the named alternative. The paraphrased user intents further help intent matching.

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

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

Annotations cover the safety profile (destructiveHint=false, idempotentHint=false). The description goes further by disclosing the precondition (active document), the concrete side effect (adds a Color Lookup adjustment layer), and the non-destructive nature — real value beyond structured fields.

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?

Well front-loaded with labeled blocks (Use when / Do NOT use when / Returns / Preconditions / Side effects) that are easy to scan. Minor redundancy between the opening sentence and the 'Use when' line, but the synonym list earns its place.

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?

Despite no output schema, the description spells out the return JSON shape, preconditions, and side effects, so an agent has everything needed to invoke it correctly.

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%, so the schema already documents both parameters including the built-in-name vs absolute-path distinction. The description adds a few concrete example filenames but largely restates the schema; baseline 3 applies.

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 (Apply) and resource (Color Lookup / 3D LUT adjustment layer) with a scope qualifier (cinematic color grading). It clearly distinguishes itself from neighboring adjustment tools like curves and auto_levels.

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?

Explicit 'Use when: stylistic non-destructive color grade in one step' and 'Do NOT use when: basic tonal fixes — use photoshop_adjust_curves or photoshop_auto_levels' names both the condition and the alternative siblings. Nothing is left to inference.

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

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

Annotations already declare destructiveHint=true and idempotentHint=false, but the description goes further: it names the precondition (active document plus a normal raster layer), discloses that text/Smart Objects get rasterized first, and quantifies the footprint as destructive pixels plus one history step that photoshop_undo reverses. That is substantive context beyond the boolean hints, though it stops short of describing failure modes or exact return shape nuance.

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?

Front-loaded with the core action, then organized into short labeled lines for usage, returns, preconditions and side effects. Every sentence carries an actionable fact; no filler.

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?

Although there is no output schema, the description states what is returned (angle and radius applied) and covers preconditions, mutation scope and reversibility. For a destructive, non-idempotent layer operation this is complete enough for an agent to call it correctly and recover from it.

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 each parameter already carries its type, min/max range and meaning (including the detailed document_id semantics). The description only restates units for angle and radius, adding nothing the schema does not already provide, so the baseline 3 applies.

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+resource (Apply Motion Blur to the active raster layer) and immediately gives units for both key inputs, so the agent knows exactly what operation this is. It differentiates itself from siblings by name, explicitly routing round blur to photoshop_apply_gaussian_blur and edge-preserving blur to photoshop_apply_smart_blur.

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?

Provides explicit 'Use when' and two 'Do NOT use when' clauses, each paired with the named alternative tool. The agent can select between the three blur tools without opening any schema.

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

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

Annotations already declare destructiveHint=true and idempotentHint=false, but the description goes further: it states pixels are destructively modified, that it consumes one history step, that Text/Smart Objects are rasterized first, and that a second call stacks more noise. It also notes reversibility via photoshop_undo, which the annotations do not cover.

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?

Front-loaded with the core action, then organized into labeled sections (Use when / Do NOT use when / Returns / Preconditions / Side effects). Every sentence carries distinct information; there is no filler.

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?

Despite no output schema, the description states what is returned (amount, distribution, monochromatic flag), covers preconditions, side effects, idempotency, and reversibility. Nothing an agent needs to call this mutation 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 100%, so the schema already documents amount, document_id, distribution, and monochromatic in detail. The description only restates the amount range, the UNIFORM/GAUSSIAN choice, and the monochromatic flag without adding syntax or behavioral nuance beyond the schema. Baseline 3 applies.

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 verb+resource (Apply Add Noise to the active raster layer) and immediately scopes it against siblings by naming photoshop_apply_gaussian_blur and photoshop_apply_sharpen as the wrong tools for blur/sharpen goals. An agent can distinguish this tool from the other filter tools without opening any 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?

Explicit 'Use when: grain or noise on one raster layer' and 'Do NOT use when: the goal is blur or sharpen' with the correct alternative tools named. This is the full when/when-not/alternatives pattern with no inference required.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=false, and the description adds genuinely useful context beyond them: the precondition (active document), the observable side effect (adds a new adjustment layer), and the return shape. It stops short of noting non-idempotency behavior or what happens when no document is active, keeping it out of the top tier.

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?

Four short lines, front-loaded with the action, then intent examples, then return/preconditions/side effects. No filler sentences; every line carries distinct information.

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 mutation tool with no output schema, the description supplies the missing return contract (ok, summary, details with layer_name/color/density), the precondition, and the side effect. An agent has everything needed to call it correctly against its annotated safety profile.

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 100% and each parameter already carries a description with defaults and warm-color hints (e.g. red ≈ 236). The description only restates 'density control' and warming/cooling, adding no syntax or semantics beyond what the schema documents, so the baseline of 3 applies.

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 ('Create a Photo Filter adjustment layer') plus its scope (warming/cooling/custom tint with density control). This distinguishes it from the many sibling color tools (adjust_vibrance, adjust_exposure, apply_lut) without needing to open 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?

Maps concrete user phrasings ('warm it up, cool it down, add a tint, golden hour look') to invocation, which is strong intent-matching guidance. It does not, however, state when to prefer this over alternative color tools like recipe_apply_color_grade or apply_lut, so exclusion guidance is absent.

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

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

Annotations declare destructive/non-readonly/non-idempotent, and the description goes well beyond them: it warns that text and Smart Objects are rasterized first, dropping live type and smart-object edits, notes the change occupies one history step, and states it is reversible via photoshop_undo. This is the kind of side-effect disclosure annotations cannot carry.

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?

Front-loads the core operation, then uses clearly labeled Use/Do NOT use/Returns/Preconditions/Side effects blocks. Every sentence conveys actionable information with no filler.

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 no output schema, the description supplies the return values, the preconditions on document/layer state, and the destructive side effects plus reversal path. An agent has everything needed to decide and to call correctly.

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%, so amount, radius, threshold and document_id are fully documented in the schema. The description's parenthetical (amount, radius, threshold) simply restates them, adding no new syntax or format detail. Baseline 3 is appropriate 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?

States a specific verb (Apply Unsharp Mask) and resource (the active raster layer) with the exact parameters named, and explicitly distinguishes itself from a web-export sharpen pass. An agent can tell this apart from photoshop_recipe_prepare_for_web and photoshop_apply_high_pass without opening any 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?

Provides explicit 'Use when' and two 'Do NOT use when' clauses, each routing to a named alternative (photoshop_recipe_prepare_for_web, photoshop_apply_high_pass). This is the strongest tier of when/when-not guidance.

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

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

Annotations already declare the mutation profile (readOnlyHint=false, destructiveHint=true, idempotentHint=false), so the description adds real value beyond them: it states preconditions (active document, normal raster layer selected) and side effects (one history step). Returning the JSON shape also clarifies behavior. It doesn't contradict the destructive hint — the operation rewrites pixels, even if undoable in one history step.

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?

Front-loaded with the core action, then cleanly segmented into synonyms, use/don't-use, returns, and preconditions. The 'Users often say' line is slightly extra but earns its place as natural-language routing cues. Overall tight with no filler sentences.

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 5-parameter destructive filter with no output schema, the description covers preconditions, side effects, return shape, and exclusion cases, so an agent has everything needed to invoke it correctly. Nothing material 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 100%, so the schema already documents all five parameters, including enum values and numeric ranges. The description only echoes field names in the returns list (radius, threshold, mode, quality) without adding syntax or semantics beyond the schema. Baseline 3 is appropriate when the schema carries parameter meaning.

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 precise verb+resource (apply Smart Blur filter to the active raster layer) and explains what it does functionally (edge-preserving blur for smoothing skin or simplifying backgrounds). It explicitly distinguishes itself from photoshop_apply_gaussian_blur, so an agent can separate the two blur siblings without opening either 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?

Provides explicit 'Use when' (subtle smoothing that respects edges) and 'Do NOT use' clauses naming concrete blockers (text, Smart Objects, Background layer — rasterize first via photoshop_rasterize_layer). It also routes the agent to the correct alternative (photoshop_apply_gaussian_blur) when uniform blur suffices. This is about as complete as routing guidance gets.

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

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

Annotations already flag destructiveHint=true and non-idempotent, but the description goes well beyond them: it discloses preconditions (active document and layer), that text and Smart Objects are rasterized first, that pixels are destructively altered, that one history step is consumed, and that photoshop_undo reverses it.

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?

Front-loads the action in the first sentence, then organizes the remaining information into labeled lines (Use when / Do NOT use / Returns / Preconditions / Side effects). No filler sentences; every line carries decision-relevant content.

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?

Despite having no output schema, the description covers the return value ('confirmation that Auto Contrast ran'), preconditions, side effects, and reversibility. Nothing an agent needs to invoke this destructive one-parameter tool 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 100% and the single document_id parameter is fully documented in the schema, including the null/0 active-document convention. The description adds only the useful negative fact that no amount parameter exists, so the baseline 3 applies with a small bump for that clarification.

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 ('Run Auto Contrast on the active layer') and immediately characterizes the operation ('Photoshop picks the contrast; there is no amount parameter'), which separates it from parametric siblings like photoshop_adjust_brightness_contrast.

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?

Provides an explicit 'Use when' plus three 'Do NOT use when' cases, each naming the alternative tool (adjust_brightness_contrast, auto_levels, adjust_curves) and the condition that selects it. Routing is fully determined without inference.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, but the description adds substantial context beyond them: text and Smart Objects are rasterized first, the edit is destructive to pixels, it consumes one history step, it is reversible via photoshop_undo, and it has no amount parameter. That is exactly the kind of pre-call behavioral disclosure an agent needs before a destructive 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?

Front-loads purpose, then layers intent phrasing, usage routing, return value, preconditions, and side effects in labeled blocks. Every line is actionable; no filler or repetition of the tool name.

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?

Though there is no output schema, the description states the return ('confirmation that Auto Levels ran'), the preconditions (active document and layer), the side effects, and the undo path. Nothing an agent needs to call this safely 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 100% and the single document_id parameter is fully documented in the schema, so the baseline is 3. The description adds value by explicitly stating 'there is no amount parameter', preempting an agent from searching for an intensity control — a real clarification beyond the schema.

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+resource ('Run Auto Levels on the active layer') and immediately defines the operation's semantics (Photoshop sets black, white, and gray points). It explicitly distinguishes itself from three close siblings (auto_contrast, adjust_brightness_contrast, adjust_curves), so an agent can route correctly without opening any 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?

Provides explicit 'Use when' plus three 'Do NOT use when' clauses, each naming the alternative tool and the condition that selects it. It also maps colloquial user phrasings ('fix flat image', 'auto tone', 'make it pop') to the tool, closing the intent-matching gap.

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

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

Annotations already declare destructiveHint=true and idempotentHint=false, so the description adds value by disclosing preconditions (target document must be open), side effects (closes that tab), and the save=true semantics (writes unsaved changes first). It stops short of stating that unsaved changes are discarded when save=false, which is the key irreversible consequence of a destructive 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?

Front-loaded with the action and default, then organized into labeled lines (Use when / Do NOT use when / Returns / Preconditions / Side effects). Every sentence carries actionable information with no filler.

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 two-parameter closing tool with no output schema, the description covers purpose, routing, preconditions, side effects, and the return value, and annotations carry the safety profile. An agent has everything needed to invoke it correctly.

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 100%, and the schema description already covers the null/0 active-document convention and stale-id behavior, so baseline 3 applies. The description's note that document_id targets a specific open file is largely redundant with the schema and does not resolve the oddity that document_id is marked required while being described as optional-defaulted.

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+resource (close a Photoshop document tab) and immediately clarifies scope: defaults to the active document unless document_id is passed. The distinction from photoshop_set_active_document is explicit, so an agent can route without opening either 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?

Provides explicit "Use when" (user is done with a file, cleanup after photoshop_list_documents) and "Do NOT use when" clauses, naming the correct alternative (photoshop_set_active_document) for the switch-tabs case. Nothing is left to inference.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, and the description adds genuinely new behavioral context: preconditions (active document AND active pixel selection), the concrete side effect of deselecting after fill, and that pixels inside the selection are modified. It also discloses that generative remove is not scriptable, which shapes agent behavior.

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?

Front-loaded with the core action, then structured into use/when-not/returns/preconditions/side-effects blocks with no wasted sentences. The 'Users often say' synonym list is slightly padding but aids natural-language matching, so it earns its place reasonably.

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?

Despite having no output schema, the description spells out the return shape (JSON { ok, summary, details: { filled } }), plus preconditions and side effects, leaving nothing an agent needs to invoke it correctly undocumented.

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 100% and the single document_id parameter is fully documented in the schema (null/0 for active doc, positive number activates). The description adds no additional parameter meaning, so the baseline 3 for schema-documented params applies.

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+resource ('Fill the current pixel selection using Content-Aware Fill') and immediately distinguishes the tool from the generative-remove sibling by noting that path is not scriptable. An agent can tell exactly what this does versus photoshop_generative_remove or photoshop_fill_layer.

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?

Explicit 'Use when' (a selection covers the area) and two 'Do NOT use when' clauses that name the required prerequisite alternative (photoshop_select_rectangle first) and the unsupported generative-remove request. This is full when/when-not/alternative coverage.

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

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

With annotations covering the safety profile (readOnly=false, destructive=false), the description still adds real value: stated preconditions (active document and active pixel selection), an explicit side effect (modifies selection), and the JSON return shape. It could go further on whether repeated calls compound (idempotentHint=false) or how the operation interacts with undo, keeping it short of a 5.

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?

Front-loaded verb+resource, then labeled Use when / Do NOT use when / Returns / Preconditions / Side effects lines. Every line carries distinct information with no filler.

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?

No output schema exists, yet the description supplies the return shape, preconditions, and side effects, which is what an agent needs to invoke this selection-mutating tool correctly. Nothing material is missing given the rich schema and annotations.

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%, so both parameters (pixels, document_id) are already documented in detail, including the null/0 active-document behavior. The description only echoes 'by a pixel amount', adding no syntax or constraint detail beyond the schema; baseline 3 applies.

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 precise verb (contract/shrink), the resource (active pixel selection), and the direction/quantity (inward by a pixel amount). The 'inward' direction cleanly separates it from the sibling photoshop_expand_selection without needing to name it.

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?

Explicitly gives when-to-use (tightening a loose selection, trimming a halo after expand) and when-not-to-use (no selection exists — create one first), pointing the agent at the fix. This is exactly the when/when-not/alternative structure the rubric rewards.

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

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

Annotations only declare the safety profile (readOnly=false, destructive=false, idempotent=false). The description goes further, disclosing the already_smart_object no-op path, the background-layer restriction, preconditions (active document, layer selected or named) and side effects (one history step), which the annotations cannot express.

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?

Front-loaded with the core action, then segmented into Use when / Do NOT use / Returns / Preconditions / Side effects. Every sentence carries actionable information and none is filler.

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?

No output schema exists, but the description supplies the return shape (ok, summary, details with layer_name, kind, already_smart_object?), plus preconditions and side effects. Nothing needed to call this mutation 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 100%, so layer_name and document_id are fully documented in the schema itself. The description restates the active-layer default but adds no format or edge-case detail beyond what the schema provides, so the baseline 3 applies.

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 (convert) and resource (active or named layer to embedded Smart Object), which cleanly separates it from siblings like photoshop_create_smart_object_via_copy and photoshop_rasterize_layer. An agent can identify the operation 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?

Explicit 'Use when' (non-destructive transforms/filters on raster or shape layers) plus two 'Do NOT use' exclusions (already-Smart-Object layers, background layers), each with the resulting behavior or remedy. It also lists common user phrasings, which aids intent matching.

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

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

Annotations cover the mutation profile (readOnly=false, destructive=false, idempotent=false), and the description adds genuinely new behavioral facts: preconditions ('active document'), side effects ('adds an artboard layer group'), and a non-obvious state transition ('First artboard converts a regular canvas into an artboard document').

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?

Front-loaded verb+resource, then labeled sections (Use when / Do NOT use when / Returns / Preconditions / Side effects). Every line carries distinct information; no filler sentences.

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?

Although there is no output schema, the description specifies the return shape ({ ok, summary, details: { artboard, count } }), preconditions, and side effects. For a 6-parameter mutation tool, an agent has everything needed to call it correctly.

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 100%, so parameters are already fully documented in the schema. The description adds only the high-level notion of 'explicit origin or placed to the right of existing artboards', which largely restates the schema's left/top defaults. Baseline 3 is appropriate 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?

States a specific verb+resource ('Create a Photoshop artboard (AM artboardSection)') and immediately distinguishes it from the neighboring sibling by giving the alternative explicitly (photoshop_create_document). The scope is clear enough that an agent can select it 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?

Contains explicit 'Use when' (multi-device/multi-screen documents, first artboard converting a canvas) and 'Do NOT use when' (need a new document tab → photoshop_create_document) sections. Also supplies trigger phrases users actually say, which is directly actionable for routing.

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

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

Annotations already declare non-destructive/idempotent, but the description goes further: it names the already_clipping success case, spells out preconditions (active document, target must sit directly above its base in the same group), and discloses the side effect (one history groupEvent step). This is rich context beyond structured fields.

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?

Front-loaded with the action, then synonym phrases for user intent, then when/when-not, then returns, preconditions, and side effects in labeled blocks. Every sentence carries distinct information with no waste.

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 no output schema, the description supplies the return JSON shape (ok, summary, details with layer_name, is_clipping, already_clipping). Combined with preconditions, side effects, and exclusions, an agent has everything needed to call it correctly.

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%, so both parameters are fully documented in the schema. The description repeats that layer_name defaults to the active layer but adds no syntax or format detail beyond what the schema provides, so baseline 3 applies.

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 (Create) and resource (clipping mask) with scope (on the active layer or a named layer). It is immediately distinguishable from the sibling photoshop_release_clipping_mask.

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?

Explicit 'Use when' condition (layer should be visible only where the layer below has opaque pixels) and two explicit 'Do NOT use when' exclusions (already clipped; bottom-most layer) with the resulting behavior noted. Nothing is left to inference.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=false, so the mutation profile is partly covered; the description adds genuinely new context by stating there are no preconditions and that the tool makes the new document active. It does not address edge behavior such as what happens if a document is already open, so it falls short of a 5.

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?

Four labeled, front-loaded lines covering purpose, routing, returns, and side effects with zero filler. The alternative tool is called out early enough to redirect an agent before it reads further.

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 no output schema, the description compensates by naming the return values (document id and name), and it closes the two remaining gaps an agent would care about — preconditions and side effects. Nothing needed to invoke this tool 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 100% and every parameter (including defaults and the intentionally-ignored document_id) is documented in the schema itself. The description only echoes 'dimensions and color mode' without adding format or unit detail, so the baseline 3 applies.

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 ('Create a new empty Photoshop document') plus the configurable axes (dimensions, color mode). It explicitly differentiates itself from the nearest sibling by naming photoshop_open_image as the tool to use for existing files.

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?

Provides explicit 'Use when' (starting from scratch, no document open) and 'Do NOT use when' (opening an existing file) clauses, and routes to the correct alternative by name. Nothing about tool selection is left to inference.

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

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

Annotations already declare the mutation profile (readOnlyHint=false, idempotentHint=false, destructiveHint=false), so the description's job is added context. It does add real value: preconditions (active document) and a side effect (adds layer to history), which tells the agent the action is undoable. It stops short of describing failure modes when no document is open, so not a full 5.

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?

Five short labeled lines, each carrying distinct information (action, when, when-not, return, preconditions/side effects), with the core action front-loaded in the first sentence. No filler.

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?

No output schema exists, so the explicit 'Returns: created layer name and context' line is necessary and present. Preconditions and side effects are covered, and the schema handles the parameters, leaving nothing an agent needs 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 100% and both parameters (name, document_id) are thoroughly documented in the schema, including the null/0 active-document convention. The description adds no parameter-level guidance beyond what the schema already provides, so the baseline 3 applies.

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 (create) plus resource (empty layer) and the placement rule (above the active layer). It also implicitly distinguishes itself from the text-layer sibling, so an agent can differentiate it 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?

Explicit 'Use when' clause names the concrete scenarios (painting, fills, stacking content) and the 'Do NOT use when' clause names the exact alternative (photoshop_create_text_layer) for the text case. Nothing is left to inference.

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

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

Annotations already declare the safety profile (not read-only, not destructive, not idempotent). The description adds genuinely non-structured context: preconditions (active document + active selection), the side effect (adds a mask to the active layer), and the return confirmation. It does not spell out what happens on repeated invocation, which is the one remaining gap.

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?

Front-loaded verb sentence, then clearly labelled blocks (use / do not use / returns / preconditions / side effects). The 'Users often say' line is slightly unconventional but earns its place by mapping natural language to the tool.

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 single-parameter mutation with no output schema, the description covers preconditions, side effects, return value, and routing to alternatives — everything an agent needs to call it correctly.

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 the sole parameter (document_id) is fully documented in the schema, including null/0 semantics and stale-id behavior. The description adds no parameter detail, so the baseline 3 applies.

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+resource ('Create a layer mask') plus the source (current selection) and target (active layer), which distinguishes it cleanly from siblings like photoshop_create_clipping_mask, photoshop_apply_gradient_mask, and photoshop_apply_layer_mask.

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?

Explicit 'Use when' and 'Do NOT use when' clauses, plus a named fallback ('create selection first or use remove_background recipe'). It also lists colloquial user phrasings ('mask this', 'hide the background', 'non-destructive cutout'), which directly aids intent matching.

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

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

Annotations already establish the safety profile (readOnly=false, destructive=false, non-idempotent), and the description adds preconditions ('Smart Object layer active or named') and the side effect ('adds a new Smart Object layer'), plus the return shape. It stops short of noting irreversibility/undo behavior, so not a 5, but it clearly exceeds the annotation baseline.

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?

Front-loaded with the core action, then cleanly partitioned into synonyms, Use/Do NOT use, Returns, Preconditions, and Side effects. Slightly verbose due to the 'Users often say' synonym line, but each block serves retrieval or invocation and nothing is buried.

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?

Despite having no output schema, the description supplies the return shape, preconditions, side effects, and the alternative tool. An agent has everything needed to decide and invoke correctly.

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 the schema already documents both layer_name (default active layer) and document_id. The description only echoes 'active or named' for the layer parameter and adds no new syntax or format detail, so the baseline 3 applies.

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 (create) and resource (Smart Object via Copy) with the distinguishing scope 'independent... unlinked duplicate with its own embedded contents.' It explicitly contrasts with linked instances, so an agent can distinguish it from photoshop_duplicate_layer 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?

Uses explicit 'Use when' and 'Do NOT use when' clauses, and names the alternative tool (photoshop_duplicate_layer / Layer via Copy) for the linked-instance case. Selection criteria are fully spelled out rather than implied.

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

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

Annotations already declare the safety profile (not readOnly, not destructive, not idempotent), so the description builds on that by disclosing preconditions (active document) and side effects (adds a text layer) plus a return shape. It stops short of richer behavioral detail such as how the layer is named or how conflicts with the active document selection are handled, but the added context is solid.

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?

Front-loaded with the core purpose, then layered with user-phrase synonyms, when/when-not rules, return shape, related tools, and pre/post conditions. Dense but every block is functional; only the synonym line ('Users often say…') is slightly filler, keeping it just under the top mark.

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 16-parameter mutation tool with no output schema, the description supplies the missing pieces: an explicit return shape (JSON { ok, summary, details }), a precondition, side effects, and pointers to sibling tools for fonts and later edits. 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 100%, so the baseline is 3, but the description adds value beyond the schema: font resolution is routed through app.fonts via photoshop_list_fonts, and it flags that tracking/leading/box should be passed here rather than scripted. These are semantic aids the schema alone does not supply.

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+resource (create a text layer) and enumerates the domain fields it controls: content, position, font, and optional typography (tracking, leading, paragraph box, alignment, color). The agent can distinguish this from photoshop_create_layer and the various text-editing siblings without opening a 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?

Explicit 'Use when' (labels, titles, typography) and 'Do NOT use when' clauses that name the exact alternatives (photoshop_update_text_content / photoshop_set_text_style) for editing existing text. It further warns against routing tracking/leading/box through execute_script, closing off a plausible wrong path.

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

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

Annotations already flag destructiveHint=true and readOnlyHint=false, but the description adds substantial behavioral context: the crop is destructive to every layer, consumes one history step, is reversible via photoshop_undo, and requires right > left and bottom > top. It also states the return values (new width and height).

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 description is tightly structured with a front-loaded purpose statement followed by labeled sections for usage, returns, preconditions, and side effects. Every sentence carries concrete information about scope, validation, or reversibility.

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 destructive crop tool with no output schema, the description covers the operation, required parameters, validation constraints, side effects, reversibility, and what the tool returns. An agent has everything needed to call it correctly and safely.

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%, so the baseline is 3, but the description adds a validation rule not present in the schema ('right > left and bottom > top') and reinforces the pixel-coordinate nature of the rectangle. The schema already documents document_id behavior, so the description does not need to repeat it.

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 ('Crop the active document') plus the exact geometric scope (pixel rectangle left/top/right/bottom) and the consequence (canvas shrinks, outside pixels deleted). It clearly distinguishes itself from sibling operations like fit_layer_to_document, scale_layer, and resize_image.

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?

Provides explicit 'Use when' and two 'Do NOT use when' clauses, each naming the correct alternative tool and the condition that selects it. This leaves no ambiguity about when to choose crop versus layer scaling or image resampling.

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

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

Annotations already declare destructive=true, but the description adds materially more: preconditions (active document and a deletable active layer), the exact side effect (destroys pixels, mask, and effects), and reversibility ('Reversible with photoshop_undo while history holds it') — the last being behavior no annotation conveys.

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?

Front-loaded purpose, then tightly labeled sections (Use when / Do NOT use when / Returns / Preconditions / Side effects). Each Do NOT line carries distinct routing value, so there is no filler.

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 destructive one-param mutation with no output schema, the description covers purpose, routing, preconditions, side effects, reversibility, and the return shape. Nothing an agent needs to invoke it safely 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?

Only one parameter (document_id) and schema description coverage is 100%, so the schema fully documents fallback-to-active-document semantics. The description adds nothing about the parameter, making 3 the correct baseline.

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+resource ('Delete the active layer') and immediately qualifies the scope ('including its pixels, mask, and effects'), which differentiates it from sibling destructive operations like photoshop_delete_layer_mask and photoshop_flatten_image.

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?

Three explicit 'Do NOT use when' clauses each name the correct alternative sibling (set_layer_visibility, delete_layer_mask, flatten_image) with the condition that selects it. This is textbook when/when-not/alternative guidance.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the agent knows this is a destructive write. The description adds the useful scope fact that the target is the active layer (not a parameter-selected one), but says nothing about irreversibility, undo, or what remains of the layer afterward.

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 front-loaded sentence with no filler; the scope qualifier ('from active layer') comes after the core action, which is appropriately tight for a one-parameter tool.

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 simple destructive toggle with full schema coverage and clear annotations, the description is adequate but thin: it omits whether the mask is recoverable, what happens if no mask exists, and how it relates to sibling mask tools.

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%, so document_id is already fully documented. The description adds only the implicit note that the affected layer is the active one rather than a parameter, which is a minor clarification. Baseline 3 applies when the schema carries the parameter semantics.

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 gives a specific verb and resource ('Delete the layer mask'), and 'from active layer' scopes where the operation lands. It is inherently distinguishable from photoshop_delete_layer, though it never names that sibling or any alternative explicitly.

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 use this versus photoshop_delete_layer, photoshop_apply_layer_mask, or photoshop_create_layer_mask. The only scoping cue is 'active layer', with no prerequisites or exclusions stated.

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

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

Annotations declare destructiveHint=true, readOnlyHint=false, and idempotentHint=true, covering the safety profile. The description adds that the effect applies to the active layer, which is useful scoping, but doesn't explain permanence, undoability, or behavior on non-pixel layers, so it adds modest value beyond annotations.

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 efficient sentence with the effect front-loaded in parentheses. No wasted words, though the brevity comes at the cost of missing usage context.

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 simple one-parameter mutating tool with no output schema, the description is minimally adequate. It lacks guidance on when to prefer this over related adjustments and gives no note on scope (active-layer requirement, effect on locked/hidden layers).

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?

The single parameter is fully documented in the schema (100% coverage), including null/0 handling and stale-id behavior, so the schema carries the semantic load. The description adds no parameter detail, which is acceptable given the high coverage; baseline 3 applies.

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 ('Desaturate') and resource ('the active layer'), with a parenthetical clarifying effect. It is distinguishable from siblings like photoshop_adjust_hue_saturation, though it doesn't explicitly differentiate from them.

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?

No when-to-use guidance, no prerequisites, no mention of alternatives such as photoshop_adjust_hue_saturation for more controlled desaturation. The description assumes the agent already knows it wants this operation.

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

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

Annotations already declare idempotentHint=true and destructiveHint=false, but the description adds substantial context: pixels are unchanged, side effects are limited to selection, it is safe when nothing is selected, and it is reversible via photoshop_undo if a selection existed. These details go well beyond the annotations and align with readOnlyHint=false without contradiction.

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 in the first sentence, followed by clearly labeled usage, return, precondition, and side-effect sections. Every line is useful, especially the return note since no output schema exists.

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 simple selection-clearing tool, the description covers purpose, sibling routing, return value, preconditions, side effects, and reversibility. Nothing an agent needs in order to invoke 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?

The single document_id parameter has 100% schema description coverage, so the schema already explains accepted values and active-document behavior. The description adds only the precondition 'active document,' which is already implied by the schema, so baseline 3 is appropriate.

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: 'Clear the current pixel selection.' It explicitly distinguishes itself from photoshop_invert_selection and photoshop_select_all, so an agent can route correctly without opening sibling schemas.

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?

Provides explicit 'Use when' guidance and two 'Do NOT use when' exclusions with named alternatives. This fully covers when to use this tool versus alternatives.

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

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

Annotations already declare it is a non-read-only, non-destructive, non-idempotent mutation. The description adds meaningful context beyond that: the active-layer selection changes as a side effect, and the call returns the new layer's name and (when available) its id. It stops short of saying what happens if no layer is active or where the duplicate is inserted in the stack.

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?

Two short clauses, zero filler, with the core action and its result front-loaded. Every phrase carries information.

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 two-parameter, no-output-schema tool, the description covers action, side effect, and return values, which is nearly everything an agent needs. Minor gaps remain around failure modes (no active layer) and duplicate placement, but nothing critical 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 100%, and the schema itself richly documents document_id (null/0 semantics, activation behavior, stale-id handling). The description adds nothing about parameters, so the baseline 3 applies – the schema is doing all the work.

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 ('duplicate the active layer') and immediately adds the observable result (the duplicate becomes active and returns its name/id). This is distinct from siblings like photoshop_create_layer or photoshop_merge_visible_layers without needing 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?

Usage is implied by the phrase 'active layer' – the agent must first ensure a layer is selected – but the description never states prerequisites or when to prefer this over photoshop_create_layer or photoshop_apply_layer_mask workflows. No exclusions or alternatives are named.

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

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

Annotations only declare the generic safety profile (readOnly=false, destructive=false, idempotent=false); the description goes well beyond them by disclosing the document-state side effect (active document switches to the embedded .psb, requiring save/close to return), a precondition, and the return payload shape. This is exactly the kind of context annotations cannot carry.

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?

Front-loads the action and effect in the first sentence, then organizes usage, routing, returns, preconditions and side effects into scannable labeled lines. The 'Users often say' paraphrase line is retrieval-oriented filler but short enough to be defensible.

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?

Covers everything an agent needs to call this stateful tool correctly: precondition, side effect on the active document, the required save/close follow-up, and the return JSON shape in lieu of an output schema. No meaningful gap remains.

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%, so both document_id and layer_name are already fully documented in the schema, making 3 the baseline. The description adds only the 'Smart Object layer active or named' precondition, which is a precondition rather than added parameter meaning.

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 concrete verb+resource ('Open a Smart Object for editing') and immediately disambiguates from the closest sibling by naming photoshop_replace_smart_object_contents. An agent can distinguish it from convert_to_smart_object, create_smart_object_via_copy, and replace_smart_object_contents without opening any 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?

Explicit 'Use when' condition (modifying pixels inside an embedded Smart Object non-destructively) paired with an explicit 'Do NOT use when' that routes to the correct alternative tool. Nothing about tool selection is left to inference.

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

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

Annotations already flag destructive/openWorld/idempotent=false, and the description adds substantial context beyond them: the IIFE wrapping requirement, the explicit-return semantics, toSource() serialization, timeout budget override behavior, and preconditions/side-effects caveat. This is the rare case where a description genuinely augments the safety profile rather than restating it.

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?

Front-loaded with purpose, then labeled Use/Do NOT use/Returns/Preconditions blocks that are easy to scan. The Document.gradients aside is a niche gotcha that is useful but slightly tangential to the core definition.

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 no output schema, the description carries the return-value burden and does so ('script return value serialized as text/JSON'), plus preconditions, side-effect caveat, and timeout behavior. Nothing an agent needs to invoke 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 coverage is 100%, so the schema already documents all three params, setting the baseline at 3. The description still adds operational meaning: guidance to pass timeout_ms for long scripts so the default 30s budget does not kill the job, and the active-document precondition for document_id.

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 (execute) and resource (ExtendScript/JSX code) plus its role as an 'advanced escape hatch'. This framing immediately distinguishes it from the ~100 atomic and recipe siblings that do bounded operations.

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?

Explicit 'Use when' and two 'Do NOT use when' clauses naming the preferred alternatives (photoshop_recipe_*, photoshop_fill_gradient) with a concrete failure case for gradients. An agent has a complete routing rule for picking this over siblings.

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

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

Goes well beyond the annotations by naming the return envelope (JSON with ok, summary, details.pixels, bounds, context), the preconditions (active document and active pixel selection), and the side effect (modifies selection). The annotations only cover safety hints; the description carries the operational burden.

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?

Five short labeled lines, front-loaded with the core action, then when/when-not, then return shape, preconditions and side effects. Every sentence adds distinct information with no filler.

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?

Although there is no output schema, the description describes the return envelope, the preconditions, and the mutation side effect, which is everything needed to invoke a two-parameter selection tool correctly. No meaningful gap remains.

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%, so both parameters (pixels, document_id) are already fully documented in the schema, including the null/0 active-document convention. The description only restates 'by a pixel amount' and adds no syntax or constraint detail beyond the schema, so baseline 3 applies.

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 (expand) on a specific resource (the active pixel selection) with the direction of change made explicit by 'outward'. This immediately distinguishes it from the sibling photoshop_contract_selection, which does the inverse operation.

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?

Provides an explicit 'Use when' clause (growing a tight subject selection, adding padding before feather/fill) and a 'Do NOT use when' exclusion with the required remedy (create a selection first). No inference is left to the agent.

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

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

Annotations only cover the generic safety profile (non-readonly, non-destructive, non-idempotent). The description adds real behavioral context beyond that: a 600s script timeout for long jobs, preconditions (document must have at least one artboard), and side effects (writes files, does not modify the original).

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?

Front-loaded with the action, then labelled Use/Do-not-use/Returns/Preconditions/Side-effects blocks that are easy to scan. The multilingual trigger phrases earn their place for intent matching. No filler sentences.

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 no output schema, the description supplies the return shape (JSON { ok, summary, details: { exported[], failed[], folder } }), preconditions, side effects, and timeout behavior. An agent has everything needed to invoke it correctly.

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%, so the schema already documents folder, format, quality, and document_id semantics in detail. The description only restates the supported formats, adding nothing beyond the enum. Baseline 3 is appropriate.

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+resource+scope: 'Export every artboard in the active document to a folder,' and even names the implementation (duplicate + crop to artboardRect, then PNG/JPEG/WebP/AVIF). This clearly distinguishes it from photoshop_export_as and the artboard siblings.

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?

Explicit 'Use when: delivering one file per artboard' and 'Do NOT use when: exporting the whole canvas once — use photoshop_export_as' names the alternative and the condition that selects it. Nothing left to inference.

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

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

Annotations cover the safety profile (readOnly=false, destructive=false, idempotent=false), and the description adds version gating for WebP/AVIF ('Photoshop 23.2+' with a clear error), side effects ('writes one file to path'), preconditions (active document), and the return shape — well beyond the annotations. Minor gap: it doesn't warn that an existing file at path may be overwritten, which matters for a file-writing tool.

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?

Well front-loaded — purpose, then when/when-not, then returns and preconditions. Slightly padded by the 'Users often say' search-phrase line and some redundancy between the prose and the parameter descriptions, but every section is scannable and earns most of 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?

With no output schema, the description compensates by spelling out the JSON return shape, the side effect of writing to path, the active-document precondition, and the version constraints for modern formats. An agent has everything needed to invoke it correctly.

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%, so all five parameters are already documented, which sets the baseline at 3. The description adds only marginal meaning ('optional artboard_id exports only that board (duplicate + crop)' and the quality/format interaction are already implied by the schema), so it does not elevate beyond baseline.

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 ('Export a copy of the active document') plus supported formats, and explicitly distinguishes itself from photoshop_save_document and photoshop_export_artboards. An agent can pick this over its closest siblings without opening a 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?

Has explicit 'Use when' and 'Do NOT use when' blocks that name the two alternatives and the exact conditions selecting each (web-ready formats, single artboard vs. all artboards, saving the working document). Nothing is left to inference.

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

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

Annotations declare a non-read-only, non-idempotent, non-destructive mutation, and the description adds preconditions (active document and active pixel selection) plus the side effect that selection edges are modified. That goes beyond the annotations. It stops short of 5 only because it doesn't say whether the operation is repeatable/accumulative on an already-feathered selection.

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?

Front-loads the core action, then uses tight labeled lines (Use when / Do NOT use when / Returns / Preconditions / Side effects). Every sentence carries information; no filler.

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?

Despite no output schema, the description names the return shape and the key fields, and covers preconditions and side effects. For a two-parameter selection-mutation tool, an agent has everything needed to invoke it correctly.

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%, so both parameters (pixels radius, document_id resolution rules) are already fully documented in the schema. The description adds no parameter-level meaning beyond that, so the baseline 3 applies.

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 ('Feather (soften) the edges of the active pixel selection'), which clearly separates it from sibling selection tools like photoshop_expand_selection or photoshop_contract_selection. The parenthetical gloss removes any ambiguity about what feathering means.

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?

Explicit 'Use when' (soft transitions before fill, mask, or delete) and 'Do NOT use when' (hard edge required, or no selection exists) clauses give both positive and negative routing conditions. Nothing is left for the agent to infer.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, but the description goes further: it names preconditions (active document, unlocked non-text layer), side effects (overwrites pixels, one history step), confirms idempotency for identical colors/pixels, and states reversibility via photoshop_undo. Consistent with, and additive to, the annotations.

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?

Front-loaded one-line purpose followed by labeled sections (Use when / Do NOT use when / Returns / Preconditions / Side effects). Every sentence carries distinct operational value; no padding.

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?

Despite having no output schema, the description states the return value, preconditions, side effects, idempotency, and reversibility — everything an agent needs to call and reason about a destructive pixel operation correctly.

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%, so all 8 parameters (RGB channels, direction enum, document_id) are already documented in the schema. The description adds only 'two colors and direction' at a high level, which matches the schema without adding format or edge-case detail. Baseline 3.

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?

Specific verb (Paint) + resource (two-color linear gradient) + scope (active layer pixels). Clearly distinguishable from photoshop_fill_layer and photoshop_recipe_gradient_fade, both of which are named.

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?

Explicit 'Use when' with concrete triggers (gradient/blend/color ramp) and three 'Do NOT use when' clauses that each route to a specific alternative (photoshop_fill_layer for flat color, photoshop_recipe_gradient_fade for fading into background). Nothing is left to inference.

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

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

Annotations already declare destructive/idempotent, but the description adds substantial context beyond them: the selection-vs-whole-layer branching and whether the selection is preserved or cleared, that smart objects are rasterized in place with no extra layer, preconditions (active document, unlocked non-text layer), and that photoshop_undo reverses it. No contradiction with annotations.

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?

Front-loaded core behavior in the first sentence, then labeled blocks (Use when / Do NOT use when / Returns / Preconditions / Side effects). Dense but every line carries routing or safety information; nothing is padding.

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 destructive mutation with no output schema, the description supplies the return value ('the RGB color applied'), preconditions, side effects, idempotency note, and undo path. Nothing an agent needs to invoke it safely 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 100% and all four params are self-documenting (RGB ranges, document_id null/0 semantics), so the schema carries this dimension. The description only restates that an RGB color is applied and adds no syntax or format detail beyond the schema, so baseline 3 applies.

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+resource ('Fill the active layer with a solid RGB color') and immediately distinguishes itself from the three near-neighbor siblings (photoshop_fill_gradient, photoshop_content_aware_fill, photoshop_generative_fill). An agent can route correctly without opening any 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?

Explicit 'Use when' plus four 'Do NOT use when' clauses, each naming the correct alternative tool and the condition that selects it (create_layer for an empty layer, fill_gradient for two-color, content_aware_fill for surround-content fill, rasterize_layer/set_text_color for text). This is the textbook shape for routing guidance.

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

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

Annotations already declare destructiveHint=true and idempotentHint=false, but the description goes further: it states preconditions (active document and active layer), the exact side effect (transforms that layer, does not change document dimensions), that the operation is reversible via photoshop_undo, and that fillDocument=true may crop the layer — consistent with the destructive annotation.

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?

Front-loaded with the core action, then a clean labeled block (Use when / Do NOT use when / Returns / Preconditions / Side effects). Every sentence carries distinct, actionable information with no padding.

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 mutating tool with no output schema, the description covers return value ('confirmation of the fit'), preconditions, side effects, reversibility, and the destructive crop case. Nothing an agent needs to invoke 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 100%, so the baseline is 3. The description's explanation of fillDocument (fits inside and may letterbox vs covers the canvas and may crop) largely restates what the schema already documents for that parameter, adding only a framing of the default's consequences.

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 (scale) plus resource (active layer) and scope (to the document canvas, keeping aspect ratio), and explicitly names the sibling tools it is not (photoshop_scale_layer, photoshop_resize_image, photoshop_crop_document). An agent can distinguish it from the ~120 siblings without opening a 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?

Provides explicit 'Use when' and two 'Do NOT use when' clauses, each routing to a named alternative (photoshop_scale_layer for a specific percent; photoshop_resize_image / photoshop_crop_document for changing canvas size). Nothing is left to inference.

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

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

Annotations already declare destructiveHint=true, but the description goes well beyond them by disclosing exactly what is destroyed (every layer, mask, and hidden pixel) and that photoshop_undo can restore the stack while history still holds it. It also states the precondition (active document) and the return confirmation.

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 description is front-loaded with the core action, then organized under explicit 'Use when', 'Do NOT use when', 'Returns', 'Preconditions', and 'Side effects' cues. Every sentence carries actionable information with no redundancy.

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 destructive single-parameter tool with rich annotations and no output schema, the description covers purpose, routing alternatives, preconditions, side effects, reversibility, and return value. Nothing an agent needs to invoke it safely 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 100% and the document_id parameter is thoroughly documented in the schema, including null/0 behavior and stale-id handling. The description adds no parameter-level detail, so baseline 3 is appropriate.

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 verb and resource ('Flatten the active document into a single Background layer') and immediately adds the non-obvious scope detail that hidden layers are discarded. It clearly distinguishes the operation from sibling tools like photoshop_merge_visible_layers.

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 'Use when' and two 'Do NOT use when' conditions, including the precise alternative to choose when hidden layers must survive or editability must be preserved. An agent can route between flatten and merge_visible_layers without inference.

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

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

Annotations cover safety hints (readOnly=false, destructive=false, idempotent=false, openWorld=false), and the description adds real value beyond them: file-writing side effects to output_dir, the precondition of an active document with data sets, and the return payload shape. It stops short of saying whether existing files in output_dir are overwritten or how name collisions are handled.

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?

Front-loaded with the core operation, then tiered into user phrasings, use-when, returns, preconditions and side effects. Every sentence carries distinct information and there is no filler.

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 4-param mutation tool with no output schema, the description supplies preconditions, side effects, and a return shape, which is close to complete. Minor gaps remain around overwrite/name-collision behavior and what happens to skipped rows.

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%, so the schema already documents output_dir, document_id, format, and dataset_names in detail (including null/0 active-document behavior). The description adds only the row-to-file framing and does not expand on format choices or dataset subsetting, so the baseline 3 applies.

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, resource and mechanism: batch-export one file per data set by applying each set, saving, and moving on. The 'mail merge for images' analogy plus the explicit per-row semantics distinguish it from photoshop_export_as, photoshop_export_artboards, and photoshop_recipe_batch_mockup_replace, which could otherwise look similar.

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?

Explicit 'Use when' clause names the prerequisite tool (photoshop_import_datasets) and the goal condition ('one file per row'). It also lists the user phrasings that should route here, which is directly actionable for tool selection.

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

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

Annotations already declare the mutating, non-idempotent, open-world, non-destructive profile, and the description adds value beyond that: a preconditions block naming the generative_fill capability and Adobe generative credit consumption, plus an explicit return shape. It doesn't clarify whether the result lands in a new document or a new layer, which is the main behavioral unknown.

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?

Four short labeled lines (purpose, Use when, Returns, Preconditions) with the purpose front-loaded and zero filler. The labeled format is slightly mechanical but every line carries information an agent would otherwise have to infer.

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 4-parameter, no-output-schema tool the description covers purpose, triggers, return shape, and capability/credit prerequisites, so the calling agent has enough to invoke it. The remaining ambiguity is whether output goes to a new document (implied by width/height) or the active document, which the description never resolves.

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%, so prompt, document_id, width, and height are already documented in the schema, including the null/0 active-document convention and stale-id tolerance. The description adds no extra parameter meaning, so the baseline 3 applies.

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 ('create an image from a text prompt') and adds the engine qualifier (Firefly ImageGen / text-to-image), which separates it from generic image tools. It does not explicitly contrast with the nearest siblings such as photoshop_generative_fill or photoshop_place_image, so an agent still has to reason about whether it wants generation or placement.

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?

The 'Use when' clause gives concrete trigger conditions (user asks for ImageGen, text-to-image, or a new picture from a description), which is clear routing guidance. It stops short of stating when NOT to use it (e.g., inpainting inside a selection should use photoshop_generative_fill instead), so the sibling boundary is left implicit.

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

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

Annotations already declare destructiveHint=true, openWorldHint=true and non-idempotency; the description adds value beyond them by stating preconditions (active document, generative_fill capability) and a concrete side effect ('enlarges canvas with generated content'). This meaningfully explains what the destructive annotation implies, though it omits any note on reversibility/undo or rate/cost behavior.

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 text is tightly organized into front-loaded purpose plus labeled 'Use when', 'Returns', 'Preconditions' and 'Side effects' lines. Every sentence carries distinct information with no repetition of the tool name or filler.

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 3-parameter outpainting tool with no output schema, the description supplies the return shape, preconditions and side effects, which covers most of what an agent needs. Minor gaps remain (e.g. the unexplained 'wait' return field, no guidance on prompt quality or canvas-size limits), keeping it below a 5.

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%, so the schema already documents prompt, direction (with enum) and document_id in detail. The description only echoes 'direction' and 'prompt' inside the return shape and adds no syntax, defaults or format guidance beyond the schema, so the baseline of 3 applies.

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 names a specific verb and resource — 'Extend the canvas beyond its edges using Generative Expand (Firefly)' — so the agent immediately knows this is outpainting. It distinguishes itself implicitly from generative_fill/remove/upscale by the 'beyond its edges' scope, but never names or contrasts a sibling explicitly, which keeps it short of 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?

'Use when: outpainting, extending background, or expanding composition' gives clear triggering contexts that an agent can match against user intent. It stops short of a 5 because it names no exclusions or alternative tools (e.g. when generative_fill would be preferred instead).

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

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

Goes well beyond the annotations (destructive/openWorld/non-idempotent) by stating preconditions (PS 24+ with generative credits, active pixel selection), concrete side effects (pixel mutation, credit consumption), and the return shape. The credit-consumption warning is operationally important and is nowhere in the structured fields.

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?

Labeled sections (Use when / Do NOT use when / Returns / Preconditions / Side effects) put the action first and the caveats after. Every sentence carries distinct information; no filler.

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?

Despite no output schema, the description supplies the return shape, required environment, destructiveness, and cost implications. An agent has everything needed to call this safely without further discovery.

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 the document_id semantics (null/0 fallback, stale-id tolerance) are fully documented in the schema. The description only restates 'with a text prompt', adding no syntax or constraints beyond the schema, so the baseline 3 applies.

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?

Specific verb (fill) + resource (current selection) + mechanism (Adobe Generative Fill/Firefly) + input (text prompt). This clearly separates it from photoshop_content_aware_fill and photoshop_generate_image, which an agent must choose between.

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?

Explicit 'Use when' plus two 'Do NOT use when' clauses, each naming the alternative to reach for instead (photoshop_select_subject for creating a selection, photoshop_get_capabilities for version checks). Routing is fully determined.

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

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

Annotations already flag destructive/openWorld/non-idempotent, and the description goes further by naming preconditions (existing selection or auto_select_subject; generative_fill capability) and side effects (inpainting the selected region, consuming generative credits on cloud-backed runs) that the annotations cannot express.

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?

Five labeled, front-loaded lines (action, use when, do not use when, returns, preconditions, side effects) with no filler; each sentence carries distinct operational information.

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 destructive generative tool with no output schema, the description still supplies the return shape ({ ok, summary, details }), preconditions, fallback routing, and side effects — everything needed to invoke it safely.

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 100%, so document_id, feather_px, and auto_select_subject are already documented in the schema. The description only echoes auto_select_subject in the precondition line and adds no format or interaction detail beyond it, matching the baseline for fully covered schemas.

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 ('Remove content using the AI Remove tool ... on the current selection') and explicitly notes the generative-fill fallback path, which separates it from the many other fill/selection siblings.

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?

Gives explicit 'Use when' (erasing distractions, people, objects with generative AI) and 'Do NOT use when' (generative unavailable) clauses that route the agent to a named alternative, photoshop_recipe_remove_distraction.

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

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

Annotations already declare destructiveHint=true, idempotentHint=false and openWorldHint=true, so the safety profile is covered structurally. The description adds value beyond that with the PS 27+ version gate, the generative_upscale capability precondition and the Adobe account sign-in requirement, plus an inline return shape for a tool with no output schema. It stops short of saying whether the original pixels are overwritten in place.

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?

Front-loads the action in one sentence, then labels each remaining line (Use when / Do NOT use when / Returns / Preconditions). No sentence is redundant or padding.

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 two-parameter mutation with no output schema, the description supplies the return shape, the capability and account preconditions, and the sibling routing rule. Nothing an agent needs to select or invoke 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 100%, including detailed semantics for document_id (null/0 for active document, stale ids tolerated) and the 2/4 enum for target_scale. The description adds nothing beyond the schema, so the baseline of 3 applies.

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 (upscale), resource (active document) and named technology (Generative Upscale, PS 27+). It is unambiguously distinguishable from the nearest sibling, photoshop_resize_image, which it names explicitly.

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?

Gives explicit 'Use when' (increasing resolution with AI detail recovery) and 'Do NOT use when' (generative_upscale flag is false) with the alternative tool named. The routing decision is fully specified.

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

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

Announces preconditions (none) and side effects (none), and adds the 'once per session' caching/usage rhythm, which is behavioral context beyond the structured fields. Some of this overlaps with readOnlyHint/destructiveHint, but the session-cadence advice is genuinely additive.

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?

Front-loaded one-line purpose followed by labeled Use/Do-not-use/Returns/Preconditions/Side effects sections. Every line earns its place; no filler.

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?

No output schema exists, yet the description supplies the return shape (JSON with version and a features map), and preconditions/side effects cover the operational envelope. Nothing needed to call this tool 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?

Zero parameters, so the schema carries nothing to disambiguate and the baseline of 4 applies. The description correctly implies no inputs are required.

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 (Return) and resource (version-aware feature flags) with concrete examples (Select Subject v2, Generative Fill). It is clearly distinguished from the sibling photoshop_get_version by describing capabilities rather than version info.

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?

Explicit 'Use when: once per session before suggesting AI-powered features or gated recipes' and 'Do NOT use when: Photoshop version is already known from photoshop_get_version' — names both the condition and the alternative sibling tool.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description adds real value on top: a stated precondition (an open document), an explicit 'Side effects: none', and the non-goal of not changing pixels or the active tab. Minor tension: the parameter doc says a positive document_id activates that document, which sits awkwardly with 'does not change ... which tab is active' – worth flagging, though it concerns the schema rather than the annotations.

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?

Front-loaded summary sentence, then tightly labelled Use / Do NOT use / Returns / Preconditions / Side effects blocks. Every line carries information an agent needs; no filler.

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 no output schema, the description compensates reasonably by naming the returned fields and characterizing the payload as 'document context JSON', and it states preconditions and side effects. A slightly fuller note on the return shape would close the last gap.

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 the single document_id parameter is fully documented in the schema (including the null/0 and activation semantics). The description says nothing about the parameter and its 'active document' framing is narrower than what the schema allows, so it adds no meaning beyond the schema.

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?

Opens with a specific verb (Read) and enumerates exactly which document attributes are returned (id, name, size, resolution, color mode), which immediately separates it from sibling readers like photoshop_list_documents or photoshop_get_state.

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?

Explicit when/when-not structure with two named alternatives and the precise condition selecting each: multi-tab enumeration goes to photoshop_list_documents, layer/selection needs go to photoshop_get_state. Nothing is left to inference.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds useful context beyond those annotations: the 'active document' precondition, the return format (history state list as text), and a no-side-effects statement. The 'does not change pixels' line is somewhat redundant with the annotations, keeping this from a 5.

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?

Front-loads the core purpose, then structures the remainder into compact labeled sections (Use when, Do NOT use when, Returns, Preconditions, Side effects). Every sentence earns its place with no filler.

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 simple, read-only, single-parameter tool with no output schema, the description covers purpose, usage conditions, alternatives, return shape, and preconditions. An agent has everything needed to call it correctly.

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?

The input schema has 100% description coverage, fully documenting the single document_id parameter including null/0 behavior and activation semantics. The description adds no parameter-level detail, so the baseline of 3 is appropriate when the schema carries the burden.

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: 'Read the history stack of the active document, including which state is current.' It also explicitly distinguishes its scope from sibling tools photoshop_undo and photoshop_redo, so an agent can tell what this tool is for without opening its 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?

Provides explicit 'Use when' and 'Do NOT use when' guidance, naming the alternatives (photoshop_undo, photoshop_redo) and the condition that selects them. Nothing about tool selection is left to inference.

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

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

Annotations already declare this as read-only, idempotent, non-destructive, and not open-world, so the safety profile is covered. The description adds useful context with 'Preconditions: active document' and 'Side effects: none,' plus the returned layer structure, though it does not discuss rate limits or pagination.

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 description is front-loaded with purpose, then structured into concise sections for usage, returns, preconditions, and side effects. Every sentence earns its place and there is no filler.

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?

Although there is no output schema, the description summarizes the key return fields (layerCount, layers array, context) and notes LayerSet artboard behavior. Combined with the rich annotations and complete parameter schema, an agent has enough information to call the tool correctly.

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 the single document_id parameter is thoroughly documented in the schema, including null/0 behavior and document activation. The description mentions the active document but does not add parameter semantics beyond what the schema already provides, so the baseline score is appropriate.

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 verb and resource: list all layers in the active document, including the fields returned (kind, visibility, opacity). It also implicitly distinguishes itself from broader state inspection by noting LayerSets and artboards in the return structure.

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 'Use when' guidance and a clear 'Do NOT use when' exclusion pointing to photoshop_get_state as the lighter alternative. This directly helps an agent choose between inspecting layer detail and fetching only session summary.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=true, destructiveHint=false, but the description explains WHY it is not read-only (creates and deletes a temp file) and explicitly reassures that the document is not modified, plus a precondition (active document required). That is meaningful context beyond the boolean flags, though it omits things like latency or size limits.

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?

Front-loaded purpose sentence followed by clearly labeled Use when / Do NOT use when / Returns / Preconditions / Side effects blocks. Every sentence carries distinct information; no filler.

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 no output schema, the description fully covers the return shape (MCP image content block plus metadata text, and the MCP Apps UI render), plus preconditions and side effects. An agent has everything needed to call and interpret it correctly.

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 the schema already documents quality, max_dimension_px and the document_id resolution rules in detail. The description adds no parameter-level detail (e.g., how quality affects verification fidelity), so the baseline 3 applies.

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+resource ('Export the active document as a base64 JPEG preview') with an explicit rationale ('for visual verification'). It is clearly distinguishable from retrieval/state siblings like photoshop_get_state and photoshop_get_layers.

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?

Provides explicit 'Use when' and 'Do NOT use when' clauses, and names the cheaper alternative (photoshop_get_state) with the condition that selects it. Nothing about routing is left to inference.

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

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

Annotations already cover readOnly, idempotent, and non-destructive hints, and the description's '(read-only)' plus 'Side effects: none' partly restate them. It does add value beyond the annotations by stating the precondition (an active document must exist) and disclosing the return envelope shape.

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?

Sectioned and front-loaded: purpose first, then Use when / Do NOT use when, then Returns and Preconditions. Every line carries distinct information with no filler.

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?

Despite having no output schema, the description discloses the return JSON shape (ok, summary, details with has_selection, bounds, context) and the precondition. Combined with full annotation coverage, an agent has everything needed to call and interpret this tool.

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 100% and the single document_id parameter is fully documented in the schema itself (active-document fallback, stale-id behavior). The description adds no parameter-level detail, so the baseline 3 applies.

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 (Read) plus resource (active pixel selection bounds) with units (document pixels) and a read-only qualifier. An agent can distinguish it from selection-creating siblings like photoshop_select_rectangle without opening any 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?

Explicit 'Use when' clause names the verification scenario before mask/fill/recipe steps, and the 'Do NOT use when' clause names two concrete alternatives (photoshop_select_rectangle, photoshop_select_subject) for the excluded case. Both the triggering and excluding conditions are given.

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

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

Annotations already declare readOnly/idempotent/non-destructive/closed-world, and 'Preconditions: none / Side effects: none' largely restates them. The description does add genuinely new behavior: the 40 top-level layer truncation cap, that path is omitted until the file is saved, and that it is 'cheap' and safe on an empty session.

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?

Labeled sections (Use when / Do NOT use when / Returns / Preconditions / Side effects) make it front-loaded and scannable. The Returns block is a long enumeration and partly repeats the opening parenthetical, but it substitutes for the absent output schema so the length is largely earned.

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 no output schema, the description carries the full return-value burden and does so thoroughly (field list, truncation cap, conditional path field). Preconditions, side effects, and downstream parameter usage are all covered, leaving nothing an agent needs to call it correctly.

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 100%, so the baseline is 3, and the description goes beyond it by explaining the workflow contract: capture document.id and pass it as document_id on later mutating calls, and artboard ids come from document.artboards[].id.

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+resource ('Return a cheap read-only snapshot of Photoshop session state') and enumerates the scope (active document, layer, selection). It explicitly separates itself from the nearest confusable sibling, photoshop_get_preview, so an agent can route correctly without opening schemas.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.