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

No annotations are provided, so the description carries the full burden. It identifies the target as the active layer but does not disclose whether the change is destructive or non-destructive, whether values replace or increment existing adjustments, what happens with no active layer, or what the result is. For a mutating tool this is a significant 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?

Two short sentences with the core action front-loaded and no filler. The user-language list earns its place by helping agents map colloquial requests to this 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 tool with no annotations and no output schema, the description leaves important context unstated: mutability, active-layer prerequisites/error behavior, and how to choose among the many adjustment siblings. It is a clear but minimal definition that does not fully equip an agent to invoke it correctly in all relevant scenarios.

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 parameters are already well documented with names, ranges, required flags, and a detailed document_id note. The description adds no parameter-level detail beyond restating brightness/contrast concepts, so the 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 ('Adjust') and resource ('brightness and contrast of the active layer'), making the core action clear. The user-language aliases help intent matching, though it does not explicitly distinguish itself from close siblings like photoshop_adjust_exposure or photoshop_auto_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?

The 'Users often say: fix exposure, add contrast, brighten, darken' line provides useful trigger phrases for when to use the tool. However, it gives no exclusions or alternatives, and 'fix exposure' is ambiguous given that a dedicated photoshop_adjust_exposure sibling exists.

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?

No annotations are provided, so the description must carry the behavioral burden. It discloses side effects ('adds Curves adjustment layer'), preconditions ('active document'), and notes the operation is non-destructive. It could be more explicit about whether it modifies existing layers, but the description adequately covers key behavioral traits.

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 well-structured with clear sections (Use when, Do NOT use when, Returns, Preconditions, Side effects). It is concise, front-loaded with the main purpose, and every sentence adds value without 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 tool with 2 optional parameters and no output schema, the description covers all essential aspects: purpose, usage conditions, return format, preconditions, and side effects. It even provides example user intents and an explicit alternative, making it fully contextual for an agent.

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 both parameters (preset and document_id) are fully described in the schema. The description adds no extra parameter detail beyond what the schema provides, which aligns with the baseline of 3 for high schema coverage.

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 clearly states the action: 'Create a Curves adjustment layer on the active document.' It also lists common user intents (make it pop, S-curve, etc.) and explicitly names a sibling tool to avoid (photoshop_recipe_apply_color_grade), making its purpose distinct from other adjustment tools.

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 guidance: 'Use when: global tonal correction via a non-destructive Curves adjustment layer.' and 'Do NOT use when: stylistic cinematic grade — use photoshop_recipe_apply_color_grade.' This clearly differentiates when to choose this tool over 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?

With no annotations provided, the description carries the full burden. It explicitly states preconditions ('active document') and side effects ('adds an Exposure adjustment layer'), and it discloses the return format as a JSON object. This covers the key behavioral traits, though it does not mention whether the adjustment layer is inserted above the current selection or other fine-grained details.

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 compact and front-loaded: the first sentence states the action, then user phrasing, return format, preconditions, and side effects. Every sentence earns its place without redundancy or fluff.

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?

The description is complete for a straightforward adjustment tool: it states the purpose, gives example user intents, specifies preconditions and side effects, and describes the return JSON. Given the optional parameters and clear schema, nothing essential is missing, though it does not clarify whether the layer is added above the active layer or document root.

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 schema description coverage is 100%, with each parameter already described. The description adds minimal extra meaning—only the terms 'stops, offset, gamma correction' which map directly to parameter names. Since the schema already handles the semantics, the description adds little beyond that 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?

The description states a specific action ('Create an Exposure adjustment layer') with the resource (Exposure adjustment layer) and lists its parameters (stops, offset, gamma correction). It is clear and distinct from other adjustment tools by name, but it does not explicitly contrast with sibling tools like brightness/contrast or curves, so it lacks the sibling differentiation needed for 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?

It provides concrete usage context by listing typical user requests ('fix underexposed photo, brighten by a stop, gamma fix'), which tells an agent when to select this tool. However, it does not mention alternatives or conditions when not to use it, so it stops short of explicit exclusion 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?

With no annotations provided, the description carries the burden of disclosing behavioral traits. It does identify the operation as adjusting the active layer, which is useful, but it does not mention whether the change is destructive, reversible, requires a selected layer, or can silently retarget documents. This is a significant gap for a mutation 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?

The description is a single, efficient sentence with no filler or redundancy. It is appropriately sized for the simple operation, though it omits useful guidance that would make it more valuable.

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?

The description plus a fully documented schema is adequate for basic invocation, but the lack of annotations, output schema, and usage alternatives leaves gaps. An agent can call the tool correctly, but may struggle to choose it over similar adjustment tools or anticipate side effects.

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 input schema already documents the meaning and ranges for hue, saturation, lightness, and document_id. The description adds no parameter-level detail beyond naming the same concepts, matching the baseline of 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?

The description uses a specific verb and resource: 'Adjust hue, saturation, and lightness of the active layer.' This clearly states what the tool does and names the target layer. However, it does not explicitly differentiate it from sibling color-adjustment tools like adjust_vibrance or adjust_brightness_contrast, so it falls 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 description provides no guidance on when to prefer this tool over alternatives such as adjust_vibrance, adjust_brightness_contrast, or desaturate. It does not state prerequisites like requiring an active layer or explain scenarios where this tool is or is not appropriate.

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 no annotations, the description carries the behavioral burden. It discloses side effects ('adds a Vibrance adjustment layer') and preconditions ('active document'), and specifies the return JSON structure. This gives an agent a clear picture of the tool's non-destructive, layer-adding 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 definition is compact and front-loaded: purpose first, then user-intent mapping, then return/preconditions/side effects. Every sentence contributes useful 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 simple tool with optional parameters and no output schema, the description is complete: return shape, preconditions, and side effects are all stated. A small gap is the lack of explanation about what happens when no active document exists, but this is minor given the precondition is explicitly called out.

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 fully documents all three parameters with ranges, defaults, and document_id behavior. The description adds no extra parameter detail, so the baseline score of 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?

Description opens with a specific verb+resource: 'Create a Vibrance adjustment layer.' It defines the tool's function ('Vibrance boosts muted colors while protecting skin tones') and includes user phrasing ('make colors pop (safely), boost saturation without clown look') that clarifies intent. This clearly distinguishes it from sibling adjustment tools like photoshop_adjust_hue_saturation or photoshop_desaturate.

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 description provides usage context via user language ('Users often say: make colors pop...') and states a precondition ('active document'). It does not explicitly name sibling alternatives or conditions when NOT to use this tool, which would raise the score to 5.

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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It only names the action and target; it does not reveal whether the blur is destructive to pixels, whether it respects selections, or whether it can be undone. The document_id parameter description adds some retargeting context, but the main description lacks important side-effect transparency.

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. It conveys the action and target efficiently, and is appropriately sized 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 low-complexity tool with full parameter descriptions and no output schema, the definition is mostly sufficient to invoke correctly. The main gaps are the lack of usage differentiation and behavioral side-effect disclosure, which prevent it from being fully complete.

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%, with both radius and document_id already documented in the schema. The main description adds no additional parameter meaning, 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 states a precise verb and object: 'Apply Gaussian Blur filter to the active layer'. It clearly identifies the operation and the target, and the filter type distinguishes it from sibling tools like apply_motion_blur and 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?

The description implies the tool is used when a Gaussian blur is needed on the active layer, but it does not explicitly state when to use it over alternative filters or when not to use it. There is no exclusion or prerequisite guidance, so usage context is only 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?

No annotations exist, so the description carries the full burden. It explicitly states preconditions ('active document') and side effects ('adds a Gradient Map adjustment layer'), plus the return format (JSON with ok, summary, details). This discloses the non-destructive mutation and output structure, which is sufficient for an adjustment-layer 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?

The description is compact and well-organized: a main purpose sentence, user intent phrases, return format, preconditions, and side effects. Every line adds value and is front-loaded with the primary action. No redundant or filler text.

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 adjustment-layer tool, the description covers preconditions, side effects, and return structure. It does not mention whether the adjustment applies to the whole image or a selected layer, but since it creates a new adjustment layer, the behavior is standard. With no output schema, the explicit return format is helpful. Slightly more detail on the effect scope would push it to 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% – both 'reverse' and 'document_id' are documented in the schema. The description does not add extra meaning beyond the schema (it only mentions 'reverse' in the return details). Since the schema already explains the parameters, a baseline score of 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 uses a specific verb and resource: 'Create a Gradient Map adjustment layer' with a clear purpose 'for duotone/B&W tonal remapping.' It also specifies the default gradient (black→white). This clearly distinguishes it from other adjustment tools like curves or photo filter.

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 'Users often say: duotone look, gradient map B&W, remap tones' provides clear contextual signals for when an agent should select this tool. It does not explicitly name alternatives or state when not to use it, but the context is strong enough to guide 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?

With no annotations, the description carries full burden and does so thoroughly: it discloses preconditions (active document and layer), auto-creation of a reveal-all mask if none exists, and side effects (modifies mask pixels, two history steps when auto-created). It even specifies the return JSON structure, leaving no ambiguity about 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?

Every sentence earns its place. The core action is front-loaded, followed by user phrasing, a critical distinction (not a fill layer), usage conditions, return format, preconditions, and side effects. The structure with line breaks aids scanning 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?

The description is complete for a mutation tool: it covers preconditions, side effects, return format, and even history steps. There is no output schema, but the return JSON is fully specified. All parameters are documented in the schema, and the tool's behavior is unambiguous.

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% with descriptive text for each parameter, so baseline is 3. The description adds some contextual meaning (e.g., that the gradient applies to the mask, and direction/angle appear in the return), but does not elaborate on start_pct/end_pct beyond schema. It adds marginal value, not enough to exceed 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: 'Apply a linear black-to-white gradient on the active layer mask channel'. It clearly distinguishes from a Gradient Fill layer and lists common user phrasings, making the intent unmistakable and differentiating it from siblings like 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?

Explicitly provides 'Use when' and 'Do NOT use when' conditions, naming alternatives (photoshop_recipe_remove_background, photoshop_create_layer_mask) for the negative case. Also clarifies it operates on an existing mask, not a fill layer, so an agent knows when to select 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?

With no annotations, the description carries the full behavioral burden. It discloses preconditions (active document, normal raster layer selected) and a side effect (one history step). It also reveals the operation targets the active layer. It could go further by explicitly saying the pixel data is modified destructively and therefore undo/history is the recovery path, but the coverage 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?

The description is compact and front-loaded: the core action and purpose come first, followed by synonyms, usage guidance, exclusions, return format, preconditions, and side effects. Every line adds distinct value and none is redundant with 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?

Given no annotations and no output schema, the description provides the return JSON shape, precondition requirements, unsupported layer types, and side effects. This is sufficient for an agent to invoke the tool correctly and interpret the result. The main behavior of applying the filter to the active raster layer is fully explained.

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 does not add much parameter-level meaning beyond the schema, except indirectly through 'radius' appearing in the return details. The schema already documents radius range and document_id behavior, so this is adequate.

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: 'Apply the High Pass filter to the active raster layer.' It also gives the purpose (edge/detail extraction for sharpening or frequency separation), which clearly distinguishes it from the many other apply_* and filter tools in the sibling list. Even without naming a sibling, the intent is unambiguous.

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

Does the description explain when to use this tool, when not to, or what alternatives exist?

It explicitly says when to use the tool: 'sharpening via overlay blend, detail extraction, or prepping a high-frequency layer.' It also gives strong negative guidance: do not use on text, Smart Objects, or the Background layer, and points to the rasterize tool as the prerequisite. This is clear routing and exclusion 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?

There are no annotations, so the description carries the full burden of behavioral disclosure. It does not state that applying a mask is permanent/destructive, that the target layer must be active or selected, or that the operation is only reversible via undo. The word 'merge' hints at destructiveness but does not make it explicit.

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 brief, front-loaded, and free of filler. The parenthetical '(merge)' is useful clarification. It is efficient, though a bit too terse to carry the behavioral context needed for a destructive 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?

With no annotations and no output schema, the description leaves out important context: the operation is destructive, requires an existing mask, and affects the currently active layer. An agent would need background Photoshop knowledge or external information to invoke this safely and confidently.

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% coverage and fully documents the optional document_id parameter, including its role in activating the document. The tool description adds no additional parameter meaning, so the baseline of 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 names a specific verb ('Apply') and resource ('layer mask'), and the parenthetical '(merge)' clarifies that this is the destructive apply/merge operation rather than create, delete, or reveal. It clearly distinguishes itself from sibling tools like photoshop_create_layer_mask and photoshop_delete_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?

No guidance is given about when to use this tool versus alternatives, such as deleting a mask instead of applying it, or when a layer must already have a mask. The usage context is only weakly implied by the word 'merge'.

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 no annotations, the description carries the burden and does well: it states preconditions, side effects, return shape, and the Global Light behavior for drop shadow. It leaves minor ambiguity about whether existing layer styles are replaced or merged, but the disclosed side effect is clear.

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 action and uses compact labeled sections for use cases, exclusions, return, preconditions, and side effects. The user-phrase line is slightly extra but earns its place as intent-matching guidance.

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 mutation tool with no annotations and no output schema, the description covers the key operational context: when to use, when not to use, required preconditions, side effects, return shape, and parameter-specific caveats. Nothing essential for correct invocation 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 parameters. The description adds one useful behavioral detail (drop shadow uses the given angle with Use Global Light off) but mostly restates what the schema descriptions already convey.

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 names the exact action ('Apply a layer style'), specifies the target ('active layer'), and enumerates the four supported effects. It also names the sibling alternative (photoshop_execute_script) for full custom control, making the tool's scope unmistakable.

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' sections give selection criteria ('quick presentational effects') and explicitly route full custom layer-effects needs to photoshop_execute_script. The natural-language user phrases 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?

No annotations are provided, so the description carries the full burden. It discloses the key behavioral traits: an active document precondition, a side effect of adding a Color Lookup adjustment layer, and the non-destructive nature of the operation. It also states the return JSON shape. It does not cover failure modes or interaction with existing layers, but it covers the essentials well.

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 organized with clearly labeled sections (Users often say, Use when, Do NOT use when, Returns, Preconditions, Side effects), and it front-loads the core purpose. Although it is longer than the minimum, every section carries useful routing or behavioral information without 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 2-parameter tool with no output schema, the description is highly complete: it covers what the tool does, accepted input values, user intents, when to use and when not to use it, return format, preconditions, and side effects. An agent has everything necessary 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 baseline is 3. The description adds example built-in LUT names and file extensions, but these largely mirror the schema's lut description. It does not add significant meaning for document_id beyond what the schema already states.

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'), a specific resource ('Color Lookup (3D LUT) adjustment layer'), and a clear purpose ('cinematic color grading'). It also enumerates example LUT names and supported file formats, making it easy to distinguish from other color/filter tools at a glance.

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 provides 'Use when' (stylistic non-destructive color grade in one step) and 'Do NOT use when' (basic tonal fixes) with named alternatives (photoshop_adjust_curves or photoshop_auto_levels). It also lists natural-language user expressions, which helps an agent recognize when a user request maps to this 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?

No annotations are provided, so the description carries the full burden. It only states the action without disclosing side effects like layer modification being destructive, whether smart objects are handled differently, or if undo is supported. This is a significant gap for a mutation 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?

The description is a single, efficient sentence that front-loads the core purpose. Every word is essential, with no redundancy 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?

Given the tool's simplicity, the description adequately identifies the operation and target. However, with no annotations and no output schema, it would benefit from noting whether the filter is applied destructively or if it works on smart objects. Still, it is sufficient for basic use.

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 (angle, radius, document_id) has its own description. The tool description adds no extra meaning 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?

The description states a specific verb ('Apply'), a precise resource ('Motion Blur filter'), and the target ('active layer'). This clearly distinguishes it from sibling blur tools like gaussian blur or smart blur by naming the exact filter type.

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 guidance is given on when to use motion blur versus other filters (e.g., gaussian, smart blur) or other Photoshop tools. The description provides no context for selection or any 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?

With no annotations, the description carries the full behavioral burden, but it only states the action and target. It does not disclose that the filter directly mutates the active layer's pixels, that repeated applications compound noise, or how smart objects 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?

A single concise sentence that front-loads the verb, filter name, and target layer. There is no fluff or redundant wording.

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?

The schema fully explains all parameters and the description states the active-layer target, making invocation possible. However, with no annotations or output schema, the lack of operational context like destructiveness and expected side effects leaves the definition only minimally complete.

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?

All four parameters in the schema have descriptions, so the baseline applies. The tool description adds no parameter-level detail beyond what the schema already provides.

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: applying the Add Noise filter to the active layer. This clearly distinguishes it from sibling filter tools such as gaussian blur, sharpen, motion blur, and high pass.

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 about when to use this tool over other filter tools, nor any exclusions or prerequisites. The description does not mention alternatives or typical use cases, so the agent gets no selection help beyond recognizing the filter name.

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 no annotations provided, the description carries the full behavioral disclosure burden. It explicitly states preconditions ('active document') and side effects ('adds a Photo Filter adjustment layer'), and also discloses the return JSON shape. It does not detail effects on existing layers or failure modes, but the core behavioral contract is clearly communicated.

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 compact and front-loaded: the core action appears first, followed by user-intent examples, then return shape, preconditions, and side effects. Every sentence earns its place with no redundant 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?

Given 6 parameters, no output schema, and no annotations, the description provides a solid foundation: it covers the return shape, preconditions, side effects, and user intent. It does not mention layer placement or non-destructive behavior, but for this tool's complexity the description is adequately complete.

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 adds conceptual meaning by linking parameters to user intents (warming, cooling, tint, density), but it does not go beyond the schema's already-detailed parameter documentation. The description's value here is modest.

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 uses a specific verb-resource pair: 'Create a Photo Filter adjustment layer' with concrete variants (warming/cooling/custom tint with density control). It clearly distinguishes this from sibling adjustment tools by naming the exact Photoshop feature and mapping user intents like 'warm it up' or 'golden hour look' to 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?

The description gives clear usage context via natural-language triggers ('Users often say: warm it up, cool it down, add a tint, golden hour look'). It does not explicitly list alternatives or when-not-to-use cases, but the intent mapping is strong enough for an agent to select this tool appropriately.

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?

No annotations are provided, so the description must fully disclose behavior. It states 'Apply' implying mutation but doesn't mention that the operation modifies the layer destructively, requires an active layer, or has any undo implications. No side effects or prerequisites are disclosed.

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 sentence with no extraneous content. The action and target are front-loaded, making it extremely concise and to the point.

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 annotations, no output schema, and four parameters including an optional document_id, the description is too sparse. It lacks critical context such as whether the operation works on the active layer (it does say that), what happens if no layer is selected, whether it affects smart objects differently, or any error conditions. The description is incomplete for a destructive filter operation.

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% with all parameters documented in the input schema. The description adds no additional parameter meaning beyond what the schema already provides. Baseline 3 is appropriate when the schema carries the semantic 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?

The description clearly states the action: apply the Unsharp Mask filter to the active layer. It names the specific filter and target, distinguishing it from sibling filter tools like gaussian blur or noise. However, it doesn't explicitly contrast with alternatives, so it doesn't earn 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?

No guidance on when to use this filter versus other sharpening or filter tools. There are no exclusions, prerequisites, or context about appropriate scenarios. The description is purely declarative with no usage advice.

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 no annotations provided, the description discloses preconditions (active document, normal raster layer), side effects (one history step), and return format (JSON with details). It also warns against using on certain layer types. This is comprehensive behavioral transparency.

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 well-structured with separate sections for purpose, aliases, usage, returns, preconditions, and side effects. Every sentence adds value, and the key information is front-loaded.

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?

The description covers all aspects needed for correct invocation: purpose, selection criteria, restrictions, return shape, preconditions, and side effects. Given the output schema is absent, the return description compensates adequately.

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?

Input schema has 100% description coverage, so the baseline is 3. The description does not add parameter-level semantics beyond what the schema provides, but it doesn't need to.

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?

Clearly states the tool applies the Smart Blur filter to the active raster layer, with an explicit description of its edge-preserving nature and typical use cases. It also differentiates from gaussian blur by stating when not to use this tool. The aliases help recognize user phrasing.

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' conditions, 'Do NOT use' exclusions (text, Smart Objects, Background) with a pointer to rasterize first, and an alternative tool for uniform blur. This fully guides 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?

No annotations are provided, so the description carries the full behavioral burden. It names the operation but does not disclose whether pixel changes are destructive, whether the edit is recorded in history/undoable, how selections are treated, or what the call returns. This is an actionable but sparse disclosure for a mutating 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?

One short sentence front-loads the operation and target with no filler. Every word earns its place, and no restructuring is needed.

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, no-output-schema tool, the core operation is complete enough to invoke, but the missing usage differentiation and behavioral caveats on a mutating operation prevent a higher score. It is a minimum-viable description rather than a fully contextual one.

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 document_id parameter is already described with its source and purpose. The tool description adds no additional parameter-level detail, so the schema is doing the heavy lifting and 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 description uses a specific verb ('apply') and a specific adjustment ('auto contrast') scoped to 'the active layer', leaving no ambiguity about what the tool operates on. It is immediately distinguishable from sibling tools like photoshop_auto_levels by naming the exact adjustment, even though it does not explicitly call out alternatives.

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

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no guidance on when to choose this over photoshop_auto_levels, photoshop_adjust_brightness_contrast, or other adjustment tools, and no prerequisites or selection requirements are mentioned. The only context is the target 'active layer', which comes from the operation itself rather than explicit usage direction.

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 no annotations, the description must disclose behavioral implications, but it only restates the operation and target layer. It does not say that pixels are modified, that the adjustment may be destructive without undo, or how it differs from auto contrast, which is important safety information for an image-edit 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?

Two short sentences front-load the core action, then add practical user-phrase triggers. No wasted words, and the quoted phrases earn their place by aiding tool selection.

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 one-parameter tool with no output schema, the description covers the target (active layer), the operation, and common user phrasings. It is slightly incomplete only in not clarifying side effects or when to prefer auto contrast.

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 optional document_id parameter is already documented in the input schema. The description adds no parameter-level detail beyond that, matching the baseline for a fully covered 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?

The description states a specific verb ('Apply') and resource ('auto levels adjustment') and targets the active layer. It is clear but does not explicitly differentiate from sibling tools like photoshop_auto_contrast, 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?

It provides natural-language triggers ('fix flat image, auto tone, make it pop (mild)') that help an agent recognize when a user wants this tool. However, it gives no exclusions or explicit comparison to alternatives such as auto contrast or brightness/contrast, leaving selection partly 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?

With no annotations, the description carries the full burden of disclosing behavioral traits. It states that the tool closes the active document but does not warn that closing without saving (save=false, the default) will discard unsaved changes. This is a potentially destructive operation that should be flagged. Additionally, it does not explain the side effect of activating a document when document_id is provided. The description lacks critical behavioral transparency.

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 zero redundancy. It states the core action immediately and contains no filler. This is an example of appropriate conciseness for a simple 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?

Given the tool's destructive potential (closing without saving) and the absence of annotations or an output schema, the description is incomplete. It does not explain the default behavior of the save parameter, the risk of data loss, or the effect of document_id on activation. An agent needs this context to use the tool safely and correctly. The schema provides parameter details, but the description should summarize the behavioral implications, which it fails to do.

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 schema provides 100% coverage of both parameters (save and document_id) with descriptive text. The description adds no additional meaning beyond what the schema already offers. According to the rubric, when schema coverage is high (>80%), the baseline is 3. The description does not enhance parameter understanding, so a score of 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 clearly states the action: 'Close the active Photoshop document'. It specifies the verb (close) and the resource (active Photoshop document), and it distinguishes this from sibling tools like photoshop_save_document (which saves without closing) and photoshop_set_active_document (which only changes active state). The purpose is unambiguous and specific.

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 description gives no guidance on when to use this tool versus alternatives. It does not mention that this tool is for closing a document while photoshop_save_document is for saving, or that setting document_id activates a document first. There is no explicit when/when-not guidance, and the only usage hint comes from the parameter schema, which is not part of the description. The agent is left to infer the use case.

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 no annotations provided, the description carries the full behavioral burden and does so thoroughly. It states preconditions (active document and active pixel selection), side effects (modifies pixels inside selection, deselects afterward), and return shape (JSON with ok, summary, details). This is more transparent than most descriptions.

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 provides user phrasing, usage conditions, exclusions, return format, preconditions, and side effects in a compact, scannable structure. 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?

For a one-parameter tool with no output schema, the description covers everything an agent needs: preconditions, side effects, return value, when to use it, and when to use a different tool. No critical operational context 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 only parameter, document_id, is fully described in the input schema itself. The description adds no parameter-specific detail, but with full schema coverage the baseline of 3 is appropriate; nothing is missing.

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 clearly states the action ('Fill the current pixel selection using Content-Aware Fill') with a specific verb and resource, and is differentiated from related tools by explicitly naming when it should not be used (generative remove). It also lists common user phrasings, making it easy for an agent to match intent.

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 description gives explicit when-to-use guidance ('a rectangular or other selection covers the area'), explicit when-not-to-use conditions (no selection, generative remove requested), and names the alternative tool (photoshop_select_rectangle) when a selection is missing. This is model guidance 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?

No annotations are present, so the description carries the behavioral disclosure burden. It compensates well by stating preconditions (active document and active pixel selection), side effects (modifies selection), and the return shape. It doesn't describe failure behavior or reversibility, but the core mutation semantics are disclosed.

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 compact and well-structured, with scannable sections for operation, usage, returns, preconditions, and side effects. Every sentence adds useful 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 2-parameter selection mutation with no annotations and no output schema, the description covers preconditions, side effects, return format, and use context. An agent has enough information to call it correctly and interpret the result.

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 already have clear descriptions in the schema. The description adds only the phrase 'pixel amount' and reuses 'pixels' in the return shape, so this is the baseline-3 case where the schema does the heavy lifting.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb and resource: 'Contract (shrink) the active pixel selection inward by a pixel amount.' This unambiguously identifies the operation and distinguishes it from sibling selection tools like expand, feather, or select_rectangle.

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 description gives explicit 'Use when' contexts (tightening a loose selection, trimming halo after expand) and a clear 'Do NOT use when' precondition (no selection exists). It stops short of naming an alternative tool such as photoshop_expand_selection, so it doesn't fully satisfy the alternatives criterion.

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 no annotations, the description carries the full behavioral burden and meets it: it discloses the return JSON shape, preconditions (active document; layer selected or named), side effects (one history step), and the idempotent edge case (already_smart_object success flag). This is unusually complete behavioral disclosure for a tool with zero annotation coverage.

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-structured with labeled sections that each earn their place: core purpose first, then aliases, usage rules, return format, and preconditions/side effects. Zero redundancy; the 'Users often say' line adds matching value rather than 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 mutation tool with no annotations and no output schema, the description compensates well by specifying the return JSON and side effects. The only gaps are error behavior for the excluded cases (background layer, layer not found when layer_name is given), which are implied but not explicitly stated.

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 both parameters (layer_name, document_id) are already fully described in the input schema, establishing the baseline of 3. The description adds only marginal param value — mapping 'named layer' to layer_name and reiterating the selection precondition — without introducing new parameter semantics 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 ('Convert the active layer (or a named layer) to an embedded Smart Object') and the qualifier 'embedded' distinguishes it from the sibling photoshop_create_smart_object_via_copy. The explicit exclusion 'Do NOT use when: the layer is already a Smart Object' further separates it from edit/replace smart-object tools. Natural-language aliases aid agent intent matching.

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 ('non-destructive transforms/filters are needed on a raster or shape layer') and two explicit when-not-to-use conditions (already a Smart Object; background layers). However, it never names the alternative tools (e.g., photoshop_edit_smart_object_contents or photoshop_rasterize_layer), stopping short of full alternative 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?

With no annotations provided, the description carries full responsibility for behavioral disclosure. It covers preconditions, the already_clipping success case, return JSON shape, and side effects (one history step). This is thorough and gives an agent a realistic model of what will happen.

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 well-structured and front-loaded: the core action comes first, followed by user phrasings, usage conditions, return shape, preconditions, and side effects. Every section contributes actionable information without redundant 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 tool with two optional parameters and no output schema, the description provides all necessary context: what the tool does, when to use it, when not to use it, preconditions, and the exact return contract. There is no obvious missing information an agent would need to call it successfully.

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 input schema. The description adds little beyond what the schema provides, which matches the baseline of 3. The mention of 'named layer' reinforces the layer_name parameter but does not meaningfully extend 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?

The description starts with a specific verb and resource: 'Create a clipping mask on the active layer (or a named layer).' It also includes common user phrasings that help disambiguate intent, and the behavior is clearly distinct from siblings like photoshop_create_layer_mask and 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?

The description provides explicit 'Use when' and 'Do NOT use when' conditions, including edge cases like already-clipped layers and bottom-most layers. It does not name a specific alternative tool, but the contraindications are clear enough to guide an agent away from misuse.

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?

No annotations are present, so the description carries the full burden. It clearly discloses the side effect ('makes it active'), returns (id and name), and preconditions (none). This goes well beyond a generic 'creates a document'; a small gap is that it doesn't explicitly state what happens to any currently open document, though 'makes it active' implies the new one becomes the active tab.

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 compact and well-structured: a one-sentence purpose, followed by labeled 'Use when', 'Do NOT use when', 'Returns', 'Preconditions', and 'Side effects' lines. Every sentence earns its place, and the most important info is front-loaded.

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 tool with no output schema and no annotations, the description covers the essential context: usage, returns, side effects. The one oddity is the `document_id` parameter, which is not mentioned in the description; while the schema explains it, the description could briefly note that it only activates an existing document before creation. This is a minor gap, so a 4 is appropriate.

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 schema has 100% parameter description coverage, so the baseline is 3. The description itself adds no per-parameter detail beyond what the schema already provides, so it neither improves nor degrades the 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?

The description states a specific action ('Create a new empty Photoshop document') with explicit scope (dimensions and color mode) and differentiates from the sibling `photoshop_open_image` by naming when NOT to use it. This makes the tool's purpose instantly distinguishable from its 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' and 'Do NOT use when' guidance is provided, including a direct pointer to the alternative tool (`photoshop_open_image`) for opening existing files. No guesswork is left for 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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It covers the side effect ('adds layer to history'), the precondition ('active document'), and the return value ('created layer name and context'). This is strong, though it does not delve into failure modes or what happens if no document is active.

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 compact and well-structured, with the core action front-loaded followed by crisp 'Use when', 'Do NOT use when', 'Returns', 'Preconditions', and 'Side effects' sections. Every sentence adds useful information without 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?

Given that there is no output schema and no annotations, this description provides a complete operational picture: what the tool creates, where, when to use it, what it requires, what it returns, and what side effects it has. An agent has enough context to invoke it correctly in most scenarios.

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 parameter descriptions already explain 'name' and 'document_id' thoroughly, including the document activation behavior. The tool description adds no parameter-specific semantics, so the baseline of 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 opens with a specific verb and resource: 'Create a new empty layer above the active layer,' which clearly states what the tool does and where the layer appears. It also distinguishes itself from the sibling photoshop_create_text_layer by naming it and stating the difference. No ambiguity remains about the tool's purpose.

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 description explicitly states when to use the tool ('when user needs a blank layer for painting, fills, or stacking content') and when not to use it ('adding text — use photoshop_create_text_layer'). This gives an agent direct routing guidance without needing to infer from context.

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 no annotations, the description carries the full behavioral burden. It discloses preconditions ('active document and active selection'), side effects ('adds mask to active layer'), and the return signal ('maskCreated confirmation'), while also noting the operation is non-destructive. It could go further by describing failure behavior when preconditions are unmet, but the key behavioral traits are present.

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 compact, front-loaded with the core definition, and each subsequent line adds distinct value: user phrasing, usage boundaries, returns, preconditions, and side effects. There is no redundant 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 tool with one optional parameter and no output schema, this description covers everything an agent needs to invoke it correctly: what it does, when to use/avoid it, required preconditions, side effects, and the confirmation return. The alternative recipe reference also provides broader context.

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 optional document_id parameter is already well documented in the schema. The description does not repeat parameter details, which is appropriate; it adds minor context by mentioning 'active document' as a precondition, but the schema already does the substantive 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?

The description opens with a specific verb and resource: 'Create a layer mask on the active layer from the current selection (reveal selection).' It distinguishes the operation from siblings by emphasizing 'layer mask' and 'reveal selection,' and user phrasing like 'mask this' and 'non-destructive cutout' reinforces what the tool does without ambiguity.

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' guidance is provided, including a concrete alternative ('create selection first or use remove_background recipe'). This makes the selection condition unmistakable and routes agents away from invalid calls.

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?

No annotations are provided, so the description carries the full burden. It discloses preconditions ('Smart Object layer active or named'), side effects ('adds a new Smart Object layer'), and the return shape. The 'unlinked duplicate' phrasing clarifies the independence behavior. It could also mention that the original is untouched, but the independence statement covers this implicitly.

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 well-organized with line breaks, front-loading the core action. The 'Users often say' list is slightly extra but useful for natural-language matching, and every other sentence (usage, return, preconditions, side effects) earns its place. Not overly verbose for the amount of context it provides.

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 or annotations, the description includes the return JSON shape, preconditions, side effects, and alternative routing. For a tool with two optional parameters and clear semantics, 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. The description mostly restates what the schema already says (optional layer name defaults to active layer, document_id activates the document). It adds no new semantic meaning beyond the schema, so a 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 clearly states the verb and resource: 'Create an independent Smart Object via Copy — unlinked duplicate with its own embedded contents.' It explicitly differentiates from sibling photoshop_duplicate_layer by noting the difference between linked and independent instances, so an agent can distinguish it 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' and 'Do NOT use when' clauses that name the alternative tool (photoshop_duplicate_layer). This leaves no ambiguity about the appropriate context for selecting this tool over its 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?

No annotations are supplied, so the description carries the burden. It states 'Preconditions: active document' and 'Side effects: adds text layer', and lists return fields. It does not detail every edge case or the document-switching behavior of document_id, but the schema already covers that, and the transparency is adequate.

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 compact and clearly segmented with scannable labels: Use when, Do NOT use when, Returns, Preconditions, Side effects. Every sentence adds operational value; the repetition of 'adds text layer' is minor and does not hurt readability. It front-loads the core purpose.

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 or annotations, the description covers purpose, usage boundaries, return fields, preconditions, and side effects. It does not define 'context' or enumerate error conditions, but given the already-rich input schema and the referenced sibling tools, the remaining gaps are minor. It is complete enough for correct invocation.

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 mention of 'optional font' and font-related tool references adds a little guidance, but it mostly restates schema information rather than enriching parameter meaning. Therefore 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 opening sentence names the verb (create), the resource (text layer), and the key inputs (content, position, font size, optional font). The 'Do NOT use when' line distinguishes it from photoshop_update_text_content, so an agent can separate create from edit. This is specific and sibling-aware.

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 provides an explicit 'Use when' scope (adding labels, titles, or typography) and a 'Do NOT use when' condition with the alternative tool (editing existing text -> photoshop_update_text_content). It also routes to photoshop_list_fonts and photoshop_set_text_font for related font operations. This leaves little ambiguity about when to invoke the 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?

No annotations are provided, so the description must disclose behavioral traits. It only says 'Crop the document' without specifying whether the crop is destructive, whether it applies to a selection, units of the bounds, undo behavior, or confirmation. For a mutation tool, this is a significant gap; the agent cannot anticipate side effects.

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, concise sentence with no extraneous words. It front-loads the core purpose. However, it is so brief that it lacks detail, which is a trade-off; still, for a simple tool, it is appropriately sized and well-structured.

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?

Given a simple crop operation with 4 numeric params and no output schema, the description is too minimal. It omits behavioral details (destructive, undo), coordinate system assumptions, and any note about the optional document_id parameter's effect. An agent cannot fully understand the tool's behavior or failure modes without additional context.

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 each parameter has a minimal description (type, name). The description adds no extra meaning about coordinate origin, order, or semantics beyond 'specified bounds'. Since coverage is high, baseline 3 is appropriate; the description does not add value over the schema but does not need to.

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 clear verb ('Crop') and resource ('the document') with an explicit scope ('to specified bounds'). Among siblings like photoshop_resize_image, which changes overall dimensions, crop is a distinct operation. The verb and resource combination unambiguously identifies the tool's purpose without ambiguity.

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 tool versus alternatives. No mention of exclusions (e.g., 'use resize instead if you need to scale') or prerequisites (e.g., active document, selection). The agent must infer context from the tool name alone, which is insufficient given the many related operations in the sibling list.

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?

No annotations are provided, so the description must fully disclose behavior. It only says 'Delete' which implies destructiveness, but does not mention side effects (e.g., whether the deletion is irreversible, if the background layer is protected, or if the operation can be undone via photoshop_undo). It also does not clarify that it operates on the active layer selected in the UI, which is a key behavioral constraint.

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, clear sentence with no unnecessary words. It is appropriately sized for a tool with a single optional parameter and a simple action. It front-loads the primary purpose.

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 operation with no annotations and no output schema, the description is insufficiently informative. It does not disclose constraints like the active layer requirement, whether background layers are protected, or any return behavior. An agent may call it without understanding the risks or prerequisites. The tool's simplicity does not excuse the lack of critical context.

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 description does not mention the document_id parameter at all. However, the input schema fully describes it with 100% coverage, including its purpose and behavior. Per the rubric, when schema coverage is high, the baseline is 3; the description adds no additional meaning beyond what the schema already provides.

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 (Delete) and a specific resource (the active layer). It clearly distinguishes itself from other layer-related tools, especially the delete_layer_mask sibling, by naming the resource explicitly. There is no ambiguity about what the tool does.

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 description implies when to use it (to remove a layer) but provides no explicit context about prerequisites, such as requiring an open document or a non-background layer. There are no alternative delete-layer tools, so differentiation is not needed, but the description does not mention when not to use it or any preconditions.

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 no annotations, the description carries the burden of behavioral disclosure, and it does state the mutating action ('Delete') and its target ('layer mask'). However, it does not disclose whether the action is irreversible, what happens if there is no mask, or whether any other layer state is affected.

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, clear sentence with no filler. The action and target are front-loaded, and the description is appropriately sized for the simplicity of 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 simple tool with one optional parameter, no output schema, and no nested objects, the description is mostly complete. It could mention the precondition of an active layer with a mask, but the core call is fully understandable from the given text plus schema.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the single optional document_id parameter is already well documented in the schema. The description adds no new meaning about the parameter, which is acceptable but not additive.

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: 'Delete the layer mask from active layer.' It clearly distinguishes this from related siblings like photoshop_delete_layer (deletes an entire layer), photoshop_create_layer_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?

There is no guidance about when to choose this tool over alternatives, nor any mention of prerequisites such as having an active layer with an existing mask. The agent must infer usage context entirely from the tool name and description.

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 no annotations provided, the description carries the full burden. It states that the active layer is desaturated but does not disclose whether the operation is destructive, whether the original color data is preserved, whether it is reversible via undo, or any side effects. For a pixel-mutating tool, this is a significant 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?

The description is a single, compact sentence with no filler. The core action is front-loaded, making it immediately scannable and easy to parse.

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 tool with one optional parameter and no output schema, the description adequately conveys the operation. However, it omits prerequisite context (e.g., requires an open document) and any mention of result or undo behavior. These gaps are minor given the tool's simplicity, but a note on reversibility would improve completeness.

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 document_id is fully described in the schema (100% coverage), explaining its purpose and when to set it. The tool description itself adds no additional parameter context, so the baseline of 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 clearly states the action (desaturate), the resource (active layer), and clarifies the result (convert to grayscale). This distinguishes it from siblings like photoshop_invert (color inversion) and photoshop_adjust_hue_saturation (controlled saturation adjustment).

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 description implies usage by naming the target ('active layer'), but it does not explicitly state when to use this tool versus alternatives, nor does it mention when not to use it. There is no guidance on selecting between this and other color-adjustment tools.

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 no annotations, the description carries the full burden, and it does state the core behavior: all selections are cleared. However, it does not mention whether an active document is required, whether the action is reversible, or that it only affects the selection state and not layer content.

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 concise phrase with no filler or repetition. Every word contributes to the meaning, and the verb is front-loaded.

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 operation with one optional, well-documented parameter, the description is usable, but it leaves out surrounding context such as when a deselect is needed, its effect on subsequent selection operations, and behavior when no selection exists. The tool is minimal but complete in syntax, not in explanatory context.

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 only parameter, document_id, is already fully described in the input schema, including how to obtain it and why it prevents UI retargeting. The description adds no additional parameter semantics, 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 gives a specific verb ('deselect') and resource ('all selections'), so an agent can tell this clears the active selection rather than selecting or inverting it. It doesn't explicitly tie the action to the active document, but the sibling set contains no competing deselect tool, so the purpose is unambiguous.

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

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no guidance about when to invoke this tool versus alternatives such as select_all, invert_selection, or undo. The intended usage is only implicit in the action name; no explicit context or exclusion is provided.

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 no annotations, the description carries the full burden and does disclose useful behavioral facts: the duplicate becomes the active layer orientation gives the layer name and id when available. Yet it omits other relevant traits, such as where the duplicate is placed, what happens if there is no active layer, or whether the operation is undoable. The disclosed info is valuable but not comprehensive.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

One sentence with no filler. It front-loads the core action ('Duplicate the active layer') and then adds the two most important consequences (new active layer, return value). Every clause 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?

For a simple single-action tool, the description covers the key postcondition (duplicate becomes active), return value, and the one parameter that affects naming. It does not mention edge cases or error behavior, but the absence is not crippling given the tool's simplicity and the fully descriptive schema. Slightly incomplete because no output schema exists, so the described return info is the only guide the agent gets.

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% — both newName and document_id are already documented in the input schema. The description adds no parameter-level detail, but since the schema fully explains the parameters, a baseline score of 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 ('Duplicate') and a specific resource ('the active layer'), which clearly distinguishes this tool from all 100+ siblings. No other sibling duplicates a layer; the closest alternatives (create_smart_object_via_copy, create_layer) are conceptually different, so an agent can tell them apart immediately.

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 intended use is implied: call this when you need a duplicate of the active layer in the current document. However, the description does not state when not to use it, mention alternatives (e.g., smart object via copy), or give any disambiguating context. It is adequate but relies on the agent to infer the scenario.

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 no annotations, the description fully carries the behavioral disclosure burden. It states the side effect that the active document switches to the embedded .psb, instructs that save/close is required to return, and specifies the JSON return shape plus preconditions.

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 well-structured and front-loaded, with the core action in the first sentence. Sections for user phrasing, usage guidance, return format, preconditions, and side effects each earn their place without unnecessary 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?

The tool is fully specified for an agent: it explains what the tool does, when to use it, what to avoid, what it returns, what must be true beforehand, and what state changes occur. No output schema exists, but the description explicitly provides the return structure.

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. The description adds useful operational context by stating that a Smart Object layer must be active or named, which clarifies when layer_name is needed. The schema already explains document_id's activation behavior, so the extra contribution is moderate but meaningful.

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 opens with a specific verb and resource: 'Open a Smart Object for editing' and clarifies it operates on the embedded .psb. It also distinguishes itself from the sibling photoshop_replace_smart_object_contents, so there is no ambiguity about what this tool does.

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 description provides explicit 'Use when' and 'Do NOT use when' guidance, directly naming the alternative tool for replacement. It also lists preconditions, making it clear when this tool is appropriate versus when a sibling should be chosen.

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 no annotations, the description carries the full behavioral disclosure burden. It explains the IIFE wrapper, the need for explicit `return`, the serialization via toSource(), automated parsing on macOS/Windows, the active-document precondition, and that side effects depend on the code. This is substantial and honest transparency for an arbitrary-code 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?

The description is organized into short labeled sections: use, do-not-use, returns, important IIFE note, preconditions, and side effects. Every sentence adds necessary operational information with no filler, and the critical return quirk is prominently highlighted.

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 high-complexity arbitrary-code tool with no output schema and no annotations, the description covers what an agent needs: return format, execution semantics, serialization behavior, preconditions, and safety caveats. Nothing essential for correct invocation 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 does not add extra meaning for the `code` parameter beyond the schema, though it does describe important execution context such as IIFE and return semantics. The `document_id` parameter is adequately documented in the schema itself.

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: 'Execute custom ExtendScript (JSX) code inside Photoshop' and frames it as an 'advanced escape hatch'. It clearly differentiates this tool from the many atomic photoshop_* and photoshop_recipe_* 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?

It explicitly says 'Use when: no existing tool covers the operation and you can write safe JSX' and 'Do NOT use when: a recipe or atomic tool exists — prefer photoshop_recipe_* or photoshop_* tools.' This is direct routing guidance with named 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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It does so admirably by stating preconditions (active document and active pixel selection), side effects ('modifies selection'), and the return format. It stops short of covering edge behaviors like what happens when expansion exceeds document bounds, but covers the essential safety profile.

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?

Perfectly structured and front-loaded: purpose sentence first, then usage guidance, then return format, then preconditions/side effects. Every sentence earns its place with zero filler or repetition of schema 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?

For a tool with no output schema, the description compensates by stating the return format. It covers preconditions, side effects, and usage conditions. The return format description is somewhat generic (ok, summary, details) and could specify failure states, but it is complete enough for an agent 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%, so the schema already fully documents both parameters. The description's 'pixel amount' phrasing reinforces the pixels parameter but adds no meaning beyond the schema. Baseline 3 is appropriate since the schema does the heavy lifting.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb ('Expand') plus a clearly-scoped resource ('the active pixel selection') and the control parameter (pixel amount). It naturally distinguishes itself from the sibling inverse tool photoshop_contract_selection without needing to name it, since expanding vs contracting are unambiguous opposites.

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' guidance (growing a tight subject selection, adding padding before feather/fill) and an explicit 'Do NOT use when' exclusion (no selection exists, create one first). This is textbook routing guidance that tells an agent exactly when to invoke 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?

No annotations are provided, so the description carries the full behavioral burden, and it delivers: it discloses side effects ('writes one file to path'), preconditions ('active document'), version requirements (Photoshop 23.2+ for WebP/AVIF), error behavior ('return a clear error when unsupported'), and the non-destructive guarantee. There is no contradiction with annotations because none exist.

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 line-broken into scannable segments, front-loads the core purpose, and every line earns its place. It is on the longer side, but the user-phrasing mapping, return format, and preconditions/side-effects notes are all non-redundant additions.

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 and no annotations, the description compensates fully: it specifies the JSON return shape, preconditions, side effects, version constraints, and usage boundaries. For a 4-parameter export tool, nothing an agent needs to call it correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the baseline is 3; the schema already documents path, format, quality, and document_id in detail. The description adds only modest param-adjacent context (WebP/AVIF version requirement tied to format), which does not meaningfully exceed what the schema provides.

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 opens with a precise verb+resource statement: 'Export a copy of the active document as PNG, JPEG, WebP or AVIF without changing the open document.' It names concrete formats, clarifies the non-destructive nature, and explicitly differentiates from the sibling photoshop_save_document ('Do NOT use when: saving the working document itself').

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 ('web-ready delivery formats are needed'), explicit when-not-to-use ('saving the working document itself'), and names the alternative tool. It also maps common user phrasings ('export for web', 'save as webp', 'quick export png') to this tool, which helps an agent recognize intente and avoids misrouting.

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 no annotations, the description carries full burden and succeeds: it lists preconditions (active document and active pixel selection), side effects (modifies selection edges), and even the return JSON shape. No contradictions.

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?

Every sentence is purposeful and the description is front-loaded with the definition. The use/when-not/returns/preconditions/side-effects structure packs a lot of actionable information into a compact form.

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 2-parameter tool with no output schema, this description covers the action, usage criteria, return shape, preconditions, and side effects. Nothing an agent needs to decide on or invoke the 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 both parameters already have meaningful descriptions (radius minimum, optional document_id with use-case). The tool description adds no extra parameter semantics, so the baseline of 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 opens with a specific verb-resource pair: 'Feather (soften) the edges of the active pixel selection', which precisely states the action and scope. This differentiates it from siblings like expand/contract selection and image blur 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 'Do NOT use when' conditions are given ('soft transitions before fill, mask, or delete operations' vs 'hard edge is required or no selection exists'). This gives the agent concrete decision criteria, even though no alternative sibling is 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?

No annotations are provided, so the description carries the full behavioral disclosure burden. It does not state whether the fill overwrites the existing layer pixels, respects the current selection, or is reversible via undo. This is a significant gap for a mutating operation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single focused sentence with no filler. The core action and target are stated immediately, making it easy to scan.

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 annotations and no output schema, the description is incomplete. It omits behavioral details such as whether the fill replaces layer content, how selections are handled, and what the tool returns or reports on success/failure.

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%, with clear documentation for red, green, blue, and document_id. The tool description adds no parameter-level detail 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 clearly states a specific verb ('fill'), a resource ('active layer'), and a value ('a color'). This distinguishes it from sibling fill-like tools such as content_aware_fill and generative_fill, which do not fill with a solid color.

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 tool versus alternatives, no exclusions, and no mention of prerequisites such as having a layer active. The intended context is only implied by the phrase 'active layer'.

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 no annotations provided, the description carries the full burden of behavioral disclosure. It states the core scaling behavior and aspect ratio preservation, but omits important details such as the mutating/destructive nature of scaling, effects on layer contents, potential cropping implications, or whether the operation is reversible via undo.

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, focused sentence that front-loads the primary action and constraint. Every word contributes to understanding the tool's purpose, with no redundant or marketing language.

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?

Given that this is a mutating operation with no annotations and no output schema, the description is incomplete for an AI agent. It lacks guidance on when to choose this tool versus related scaling tools, does not disclose side effects or safety considerations, and does not explain what happens when no valid layer is active or when a document is not specified.

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 tool description itself adds no parameter-specific meaning, but the schema already documents document_id activation behavior and the fillDocument fit-vs-fill distinction clearly.

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 operation: scale the active layer to fit the document canvas while maintaining aspect ratio. This clearly distinguishes the tool from generic layer scaling tools like photoshop_scale_layer by specifying the fit-to-canvas behavior, and from image-level operations like photoshop_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?

The description provides no guidance on when to prefer this tool over alternatives such as photoshop_scale_layer or canvas resizing. It also does not mention prerequisites like having an active layer selected or how document_id activation should influence usage.

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?

No annotations are provided, so the description carries the full burden. Flattening is implicitly destructive, but the description does not disclose that all layer structure will be discarded, that hidden layers are included, or that the operation may be irreversible. This is a significant gap for a mutating 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?

The description is a single, front-loaded sentence with no filler. Every word is functional, and the action is immediately clear.

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 operation with no annotations and no output schema, the description is too sparse. It does not mention side effects, reversibility, hidden layer behavior, or what happens if no document is active. A more complete description would at least warn about the irreversible loss of layer structure.

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% because the only parameter, document_id, has a detailed description in the schema. The tool description adds no additional parameter meaning, 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 states a specific verb ('flatten') and resource ('all layers') and the outcome ('a single background layer'). It is distinct enough from sibling tools like photoshop_merge_visible_layers, though it does not explicitly name or contrast that alternative.

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 tool versus alternatives such as merge_visible_layers or delete_layer. The description does not mention prerequisites, hidden layer handling, or when flattening is appropriate, leaving the agent to infer usage.

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 no annotations, the description carries the full burden and does well: it discloses side effects ('writes files to output_dir'), preconditions, and the return JSON structure. However, it doesn't state whether the active document is left in its original state after each data set is applied, or if the process is destructive to the document state – a minor gap for a mutation-style 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?

The description is front-loaded with the core purpose, then provides analogies, usage conditions, return info, and side effects in a logical order. It's slightly longer than necessary but every sentence contributes value. The structure aids quick scanning.

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?

Given no annotations and no output schema, the description covers the essential operational contract: what it does, when to use it, what it returns, and side effects. It leaves out details about document state and error handling, but the presence of a clear return format and preconditions makes it fairly complete for an agent to 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?

The input schema already has 100% description coverage, so the baseline is 3. The description does not add extra meaning to parameters beyond the schema – it mentions output_dir only indirectly in the side effects and doesn't clarify format or dataset_names further. It's acceptable but not additive.

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 opens with a precise verb–resource pair: 'Batch-export the active document once per data set'. It adds the 'Mail merge for images' analogy and user phrasing ('generate all variants'), making the intent unmistakable and distinct from sibling tools like photoshop_export_as which exports a single static file.

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 explicitly states when to use ('data sets are already imported... and you want one file per row') and gives preconditions ('active document with data sets'). It also references the prerequisite tool (photoshop_import_datasets), which is a clear routing signal. No alternative is mentioned, but the condition is specific enough that an agent won't confuse it with other batch operations.

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 no annotations provided, the description carries the full burden of behavioral disclosure. It does disclose preconditions (generative_fill capability and Adobe credits) and the return shape, which is useful. However, it does not clarify side effects on an active document, such as whether a new layer is created or existing content is replaced.

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 compact and well-structured: a one-line definition, a use-when clause, return shape, and preconditions. 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?

The description includes the use case, document scope, return format, and preconditions, which covers most operational needs. It lacks explicit guidance on when not to use it or how it differs from alternative sibling tools, but it is still mostly complete for a straightforward text-to-image operation.

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 parameters. The description adds minimal param-level meaning beyond the schema, so the baseline score of 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 clearly states 'Generate image content from a text prompt (text-to-image)', giving a specific verb, resource, and mode. It also scopes the operation to blank or active documents. It does not explicitly name sibling alternatives, but the text-to-image framing helps distinguish it from related generative tools.

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: creating new imagery from a description' line provides clear context for when the tool should be used. It does not provide explicit exclusions or mention alternative tools, so it falls just short of full 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?

With no annotations provided, the description carries the full burden. It discloses side effects ('enlarges canvas with generated content'), preconditions, and the return shape. It does not mention whether the operation is reversible or whether it consumes Firefly credits, but the disclosed side effect and return contract are meaningful behavioral context.

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 compact and front-loaded: the core action is in the first sentence, followed by use cases, return shape, preconditions, and 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 3-parameter tool with no output schema, the description covers the action, use cases, return contract, preconditions, and side effects. It does not explain what 'wait' means in the return or how long generation may take, but the essential information for calling the tool correctly is present.

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 three parameters. The description adds no parameter-level detail beyond what the schema provides, which is acceptable per the baseline. The return shape mention ('details: { direction, prompt, wait }') adds some context but does not deepen 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 states a specific verb ('Extend the canvas beyond its edges') and resource ('using Generative Expand (Firefly)'), and distinguishes it from siblings like photoshop_generative_fill and photoshop_crop_document by naming the outpainting use case. An agent can tell exactly what this tool does without opening the schema.

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

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives explicit use cases ('outpainting, extending background, or expanding composition') and lists preconditions ('active document; generative_fill capability'). It does not explicitly name alternative tools to use instead, but the use-case framing plus sibling names makes the intended context clear.

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 no annotations, the description carries the full burden of disclosure. It states side effects ('modifies pixels in selection; may consume Adobe generative credits'), preconditions ('PS 24+ with generative credits; active pixel selection'), and provides the return shape. This is exemplary behavioral disclosure for a mutating 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?

The description is compact, uses labeled sections (Use when, Do NOT use when, Returns, Preconditions, Side effects), and front-loads the core purpose in the first sentence. Every line earns its place without 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?

Despite having no annotations and no output schema, the description provides all essential operational context: selection prerequisite, version/credit requirement, exclusion conditions, side effects, and exact return format. It routes the agent to relevant sibling tools for missing preconditions, making it fully actionable.

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 already have detailed descriptions in the input schema. The tool description adds no meaning beyond noting that a text prompt is used and that the prompt appears in the return object. This meets the baseline for schema-documented parameters but does not exceed 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?

The description opens with a specific verb and resource: 'Fill the current selection using Adobe Generative Fill (Firefly) with a text prompt.' It clearly distinguishes the operation from sibling tools like generative_remove or generative_expand by scoping to the active selection. The 'Use when' clause reinforces the exact capability (adding/replacing content in a selection).

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' instructions are provided, including concrete alternative actions: create a selection first or use photoshop_select_subject, and check photoshop_get_capabilities for version support. This leaves no ambiguity about when the tool is appropriate.

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?

No annotations provided, so the description carries the full burden. It discloses side effects (inpaints selected region, consumes generative credits), preconditions (selection or auto_select_subject, generative_fill capability), and return format. It could mention reversibility or auth, but for this context it is sufficiently transparent.

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 compact and well-structured, with the main purpose front-loaded followed by usage conditions, returns, preconditions, and side effects. Every sentence adds value and no fluff.

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?

Given the tool's complexity (generative AI, selection requirements, side effects) and lack of output schema, the description covers all essential aspects: purpose, when to use, return shape, preconditions, side effects, and fallback. 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 coverage is 100%, so the schema already documents all three parameters (feather_px, document_id, auto_select_subject). The description does not add any extra semantics beyond what the schema provides, so the baseline of 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 clearly states the action (remove content), the tool used (AI Remove tool with generative fill fallback), and the target (current selection). It also distinguishes from the sibling by naming the fallback recipe tool, so an agent can differentiate.

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' sections with a specific alternative tool (photoshop_recipe_remove_distraction). This leaves no ambiguity about when to invoke this tool vs. 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?

No annotations are present, so the description carries the full burden. It discloses the return format and preconditions (capability, account), but does not specify whether the operation is destructive or reversible, or whether it modifies the active document in place. This is a moderate gap for a mutation 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?

Extremely efficient: the main action is front-loaded, followed by use cases, exclusions, return type, and preconditions in a clear structure. Every sentence adds value without 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 tool with only two optional parameters and no output schema, the description covers purpose, usage guidance, return shape, and preconditions. An agent has everything needed to decide and 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% with clear descriptions for both parameters. The description adds no extra parameter-level detail beyond what the schema already provides, so a 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?

Clearly states the action (upscale) and the specific method (Generative Upscale), and distinguishes it from the sibling photoshop_resize_image by noting AI detail recovery. The verb and resource are explicit, and it names the alternative directly.

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 and when-not-to-use conditions, including a specific flag check and the alternative tool to call. This leaves no ambiguity for an agent deciding between upscale and resize.

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?

Description discloses return format JSON with version and features, states preconditions: none and side effects: none. No annotations are provided, so the description carries the behavioral burden; it adequately covers safety and idempotence, though it could mention network/host overhead or failure modes.

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-structured with clear headings for use, non-use, return format, preconditions, and side effects. Each line adds value and the essential context is front-loaded.

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?

Given zero parameters and no output schema, the description provides enough for an agent to call it correctly and interpret the result. Minor gap: what happens if Photoshop is not running or the call fails isn't specified, but for a capability discovery tool this is acceptable.

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 tool has zero parameters, so there is no parameter ambiguity. The description explains what is returned, effectively compensating for the absence of schema details.

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?

Description clearly states it returns 'version-aware feature flags for the installed Photoshop' with specific example features. This is a specific verb and resource that distinguishes it from siblings like photoshop_get_version and photoshop_ping.

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 says '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.' This provides clear when-to-use guidance and names the alternative.

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 no annotations, the description must carry the full behavioral burden. It implies a read-only operation but does not explicitly state that, and it fails to disclose that providing a document_id can switch the active document – a side effect that could impact subsequent operations. The parameter description mentions this, but the tool description itself omits 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?

The description is a single, front-loaded sentence with no redundant words. It is appropriately sized for the tool's simplicity.

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?

The description does not explain what information is returned (no output schema exists), and it omits the activation side effect of the optional document_id. For a tool that might be used to gather document metadata, the absence of return details and side-effect disclosure leaves an incomplete picture for an agent.

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 schema provides 100% coverage of the single parameter, so the description adds no additional semantic value. Per the baseline, a score of 3 is appropriate when the schema already documents the parameter adequately.

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 clear verb and resource ('Get information about the active Photoshop document'), which is distinct from sibling get-tools like photoshop_get_layers or photoshop_get_version. However, it does not specify what kind of information is returned, leaving some ambiguity about its exact scope.

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 description offers no guidance on when to use this tool versus alternatives such as photoshop_get_state or photoshop_get_layers. There is no mention of exclusions or conditions, leaving the agent to infer usage solely from the name.

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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It only states the operation and scope, omitting side effects (e.g., document activation when document_id is set), whether the operation is read-only, or the return format. The schema mentions activation behavior, but the description itself does not.

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 concise sentence that directly states the action and resource. There is no unnecessary information or redundancy, making it easy to parse.

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?

Since there is no output schema, the description should clarify what 'history states' are or what the return value looks like, but it does not. It also omits the optional document_id activation behavior from the description itself, although the schema covers it. The tool is simple, but this lack of output and usage context leaves gaps for an agent.

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 the document_id parameter, including its activation behavior. The description adds no additional meaning beyond what the schema provides, 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 clearly identifies the action ('get') and the resource ('history states of the active document'), with a specific scope. It does not explicitly differentiate from sibling tools like photoshop_get_state, but the wording is specific enough that an agent can understand the tool's function.

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 tool versus alternatives such as photoshop_get_state or photoshop_get_document_info. No conditions, exclusions, or prerequisites are provided, leaving the agent to infer the appropriate context.

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 no annotations provided, the description carries the full burden of behavioral disclosure. It clearly states 'Side effects: none' and 'Preconditions: active document', and it lists the return structure. It does not go into edge cases (e.g., behavior with no active document) but covers the essential safety and effect profile for a read-only list 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?

The description is a tight, well-organized block: purpose, usage guidance, return summary, preconditions, and side effects are each given one concise line. It front-loads the core action and avoids fluff. Every sentence contributes to the agent's decision-making.

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?

Given there is no output schema, the description explains the return values (layerCount, layers array, context) at a summary level. It also states preconditions and side effects. It could be more explicit about the shape of 'layers' or error conditions, but for a simple list tool with one optional parameter, it provides sufficient context for correct invocation.

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 sole parameter, document_id, is fully documented in the input schema (including its purpose and when it activates the document). Schema coverage is 100%, so the description does not need to add parameter details. The description itself adds no parameter-specific information, which is acceptable given the schema's thoroughness.

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 opens with a specific action ('List all layers') and a concrete resource ('in the active document'), then enumerates the exact fields returned (kind, visibility, opacity). It also differentiates itself from photoshop_get_state in the usage section, so an agent can tell them apart without inspecting 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?

Explicit 'Use when' and 'Do NOT use when' guidance is provided, with a named alternative (photoshop_get_state) and the condition that selects it. This leaves no ambiguity about when to invoke this tool versus lighter or heavier options.

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?

No annotations are provided, so the description carries the full burden. It discloses side effects ('creates and deletes a temp file; does not modify the document'), preconditions ('active document required'), and return format ('MCP image content block (JPEG) plus metadata text'). This is strong behavioral disclosure for a read-only preview tool, though it could mention failure behavior if no document is active.

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 compact and well-structured: a one-sentence purpose, a clear 'Use when'/'Do NOT use when' pair, and a concise 'Returns/Preconditions/Side effects' block. Every sentence earns its place, and the most important routing information is front-loaded.

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 preview tool with 3 optional parameters, 100% schema coverage, and no output schema, the description covers purpose, usage, preconditions, side effects, and return format. It is complete enough for an agent to call correctly. The only minor gap is not describing what happens when no document is active (error vs. no-op), but the precondition statement implies the requirement.

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 three parameters (quality, document_id, max_dimension_px). The description adds context for document_id ('activates that document before running so a UI tab switch cannot retarget the edit'), which is valuable. However, quality and max_dimension_px are fully covered by the schema, so the description doesn't need to add more. 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: 'Export the active document as a base64 JPEG preview for visual verification.' This clearly distinguishes it from sibling tools like photoshop_get_state (numeric state) and photoshop_export_as (full export). The purpose is immediately understandable and differentiated.

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 description explicitly provides when-to-use ('after visual edits to confirm result before reporting success') and when-not-to-use ('Do NOT use when: you only need numeric state — use photoshop_get_state (much cheaper)'). It names the alternative tool directly, giving the agent a clear decision rule.

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 no annotations provided, the description carries the full behavioral burden and meets it: it declares read-only status, 'Side effects: none', the precondition (active document), and the return shape. This fully discloses the operational profile an agent 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?

Purpose is front-loaded in the first sentence, followed by structured Use/Do NOT Use blocks and a compact Returns/Preconditions/Side effects section. Every sentence adds distinct value with zero waste or 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?

Despite having no output schema and no annotations, the description covers purpose, usage, return format, precondition, and side effects. For a single-optional-parameter read tool, nothing an agent needs to call it correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% for the single optional parameter, so the baseline is 3. The description does not add semantic detail about document_id beyond what the schema already provides, but the schema itself is thorough, so no compensation is 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?

The description states a specific verb (read) with a precise resource (active pixel selection bounds) and unit (document pixels). It distinguishes itself from sibling selection tools like photoshop_select_rectangle and photoshop_select_subject by explicitly framing itself as a read operation on an existing selection.

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' (verifying selection existence/size/position before mask, fill, or recipe steps) and 'Do NOT use when' (creating/modifying a selection) guidance, naming the specific sibling alternatives. No ambiguity remains about when to invoke this 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?

With no annotations provided, the description carries the full burden. It explicitly states 'read-only', 'cheap', 'Preconditions: none (safe on empty session)', and 'Side effects: none'. It also outlines what the return JSON contains. This is thorough behavioral disclosure.

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 short sections: purpose, use-when, do-not-use, returns, preconditions, side effects. Every sentence earns its place with no filler or repetition.

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?

The description is complete for the tool's complexity. It covers the return shape, the optional parameter semantics, preconditions, side effects, and routing to an alternative. Nothing an agent needs to invoke it correctly is missing, even without an output schema.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, but the description adds actionable semantics beyond the schema: 'Capture document.id and pass it as document_id on later mutating calls.' It explains why the parameter exists and how to use it, going beyond the schema text.

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 opens with a specific verb and resource: 'Return a cheap read-only snapshot of Photoshop session state (active document, layer, selection).' It clearly distinguishes the tool from siblings by scoping it to session state and explicitly excluding visual preview use cases.

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' / 'Do NOT use when' structure gives explicit conditions and names a concrete alternative (photoshop_get_preview). This leaves no ambiguity about when to invoke this tool versus a sibling.

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 no annotations, the description carries the full burden. It explicitly states 'Preconditions: none' and 'Side effects: none,' which is valuable for a getter. It does not discuss failure modes if Photoshop is not running, but for a simple version query the disclosed information is sufficient.

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 compact and well-structured: purpose first, then usage guidance, then return/preconditions/side effects. Every sentence serves a clear function 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 zero-parameter, simple getter with no output schema, the description covers return value, preconditions, side effects, and sibling differentiation. 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?

The tool has zero parameters, which the schema already reflects completely. Baseline for 0 params is 4; the description adds nothing about parameters, but none is needed.

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 ('detected Photoshop version string'), and explicitly names the sibling it is not (photoshop_get_capabilities) for feature flags. An agent can immediately understand what this tool does and how it differs from related tools.

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 conditions ('user asks about compatibility or before version-gated features') and a clear exclusion ('Do NOT use when: you need feature flags') with a named alternative. No inference is 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?

With no annotations present, the description carries the full burden and does well: it discloses side effects (opens files, stacked result becomes active document), preconditions (2+ existing image files), return shape, and the non-generative nature of the operation. It does not detail potential failure modes or constraints like matching image dimensions, but the main behavioral traits are covered.

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 well-structured with clear sections for use cases, exclusions, return value, and side effects. The user-phrase block is slightly redundant but still useful for intent matching; overall every section 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?

Given there is no output schema, the description appropriately explains the return format and provides preconditions and side effects. It covers the core context an agent needs to invoke the tool correctly, though it could add a note that the input images should be aligned or similarly sized for meaningful stack results.

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 three parameters thoroughly. The description reinforces the semantic difference between median and mean and repeats the min-2 file requirement, but adds little beyond what the schema already states.

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 operation: load 2+ image files, convert to a smart object, and apply a statistical stack mode. It clearly distinguishes itself from generative tools by saying 'no generative AI involved' and by naming the classic use cases like 'remove tourists' and noise reduction.

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 alternative tools photoshop_generative_remove and photoshop_content_aware_fill for single-object removal. It also lists common user phrasings, making it easy for an agent to recognize when this tool is requested.

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 no annotations provided, the description carries the full burden. It discloses the target of the operation (active document), the precondition, and the return shape. However, it does not state whether importing replaces/merges existing datasets in the document, whether the operation is reversible via undo, or how the active-document requirement interacts with document_id activation. Some behavioral context is present, but not the full mutation picture.

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-organized with labeled sections (core statement, user phrasings, when to use, returns, preconditions), front-loaded with the purpose. Every sentence earns its place — the 'Users often say' line supports query matching, and the exclusion clause prevents mis-selection. No wasteful prose.

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?

Given a 2-param tool with 100% schema coverage and no output schema, the description fills the important gaps: it explains the return format (JSON with ok/summary/details), states preconditions, and differentiates among a very large sibling family (100+ tools). Minor gap: it doesn't specify whether existing datasets are overwritten or merged upon import, which an agent would want to know before calling.

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 well-documented. The schema's document_id explanation is unusually thorough (explains why it activates the document to avoid UI tab-switch issues). The description adds only marginal context about the 'active document' requirement already implied by the schema. Baseline 3 is appropriate when the schema carries the param documentation weight.

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: 'Import a Photoshop variables/data-sets XML file into the active document', and anchors it to the exact UI menu path (Image > Variables > Data Sets > Import) for precision. The synonym list ('load data sets, import variables XML') helps match varied user phrasing, and the CSV/batch alternative is explicitly named as the thing this tool is not.

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' (template PSD has variable-bound layers and you want to load XML rows) and 'Do NOT use when' (generating a batch from CSV directly) conditions, naming the alternative photoshop_recipe_csv_to_cards. It also states the precondition (active document with variables defined), leaving no ambiguity about when to select this over its 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?

There are no annotations, so the description carries the behavioral disclosure burden. It states the core effect and target layer, but does not mention mutability, reversibility, what happens if no active layer exists, or whether the operation applies to pixel data only.

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, clear, front-loaded sentence with no filler. It conveys the essential operation and target efficiently.

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 operation with no output schema, the description is mostly complete: it identifies the action and the target layer. It could add a note about requiring an active document/layer, but the optional document_id schema helps fill that 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 document_id parameter is already well documented in the schema. The tool description adds no additional parameter meaning, so the baseline score of 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 names a specific verb ('Invert') and a clear resource ('colors of the active layer'). It also distinguishes itself from the sibling photoshop_invert_selection by targeting layer colors rather than a selection.

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: an agent should call this when it needs to invert the colors of the active layer. However, it does not explicitly mention when not to use it or contrast it with alternatives like invert_selection or desaturate.

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 no annotations provided, the description carries the full burden of explaining behavior beyond the one-line action. It does not disclose that it swaps selected and unselected regions, whether it affects pixels, what happens with no active selection, or that it mutates selection state as opposed to document content.

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 very short and contains no filler; every word contributes to the purpose. However, it is arguably under-specified for behavioral and usage guidance, so it earns high marks for brevity without achieving full completeness.

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?

The tool is simple and has only one optional parameter, so the minimal description is close to adequate. Still, for an AI agent it lacks essential context: when the operation is appropriate, how it interacts with the current selection, and whether it is safe/non-destructive to pixel content.

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 only parameter, `document_id`, is already fully described in the input schema with its source and purpose. Since schema description coverage is 100%, the description does not need to repeat parameter detail; 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 ('invert') and a clear resource ('current selection'), unambiguously identifying the operation. The sibling tool `photoshop_invert` is implicitly distinguished by the 'selection' qualifier, and the action is distinct from other selection-manipulation 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?

No guidance is given on when to use this tool versus alternatives such as `photoshop_select_all`, `photoshop_deselect`, or `photoshop_invert`. There is no mention of prerequisites like an active selection, nor any explicit or implicit note about when this selection operation is the right choice.

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