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 provided, the description carries the full burden of behavioral disclosure, and it succeeds. It states preconditions (target document open), side effects (closes the tab), the save behavior ('save=true writes unsaved changes first'), and the return value. It also reveals a nuanced behavior: passing document_id activates the document before closing to prevent UI tab-switch retargeting.

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 uses five short, labeled sections (use when, do NOT use, returns, preconditions, side effects), front-loading the core action and default behavior in the first sentence. Every sentence earns its place; there is no filler or repetition of structured fields.

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 mutation tool with two optional parameters and no output schema, the description covers everything an agent needs to call it correctly: what it does, when to use it, what to avoid, prerequisites, side effects, and return. The sibling tool list provides further disambiguation, and the description resolves the most likely confusion points directly.

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 documents both parameters with 100% coverage, so the baseline is 3. The description adds value by explaining the default active-document behavior not fully in the schema, and by connecting save=true to the side effect of writing unsaved changes. It clarifies the document_id parameter's role in closing a specific open file, complementing the schema's activation detail.

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: 'Close a Photoshop document tab.' It clarifies the default target (active document) and the optional document_id override, and explicitly distinguishes itself from photoshop_set_active_document. An agent can confidently tell this apart from the closely related save and tab-switching 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 description provides explicit 'Use when' and 'Do NOT use when' guidance, including the exact alternative (photoshop_set_active_document) for the non-closing case. It also gives a practical cleanup scenario after photoshop_list_documents. This leaves no 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?

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, the description carries the full burden and it does well: states preconditions (active document), side effects (adds an artboard layer group), and a key conversion behavior (first artboard turns a regular canvas into an artboard document). It also specifies the return shape. It stops short of describing error behavior or reversibility, but covers the essential 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 line breaks, front-loaded summary, and clearly separated sections for examples, usage, returns, and side effects. It is slightly verbose with example phrases, but each section contributes useful operational context.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with no annotations and no output schema, the description covers the important operational needs: what it creates, when to use it, what it returns, preconditions, and side effects. It could add explicit failure modes (e.g., no active document), but the given context is enough 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?

Schema description coverage is 100%, so baseline is 3. The description does not add significant parameter-level meaning beyond the schema; it restates origin defaults and document_id behavior that the schema already documents. No compensation needed, but also no extra semantic value.

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 Photoshop artboard') and explicitly scopes the behavior (explicit origin or to the right of existing artboards). It names the sibling tool it is not (photoshop_create_document), so an agent can disambiguate 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' guidance, and names the exact alternative (photoshop_create_document) for the excluded case. Also gives user-phrase examples, helping map natural language 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?

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 provided, so the description carries the burden and does well: it declares the precondition (active document), the side effect (adds a text layer), and the return envelope { ok, summary, details }. It does not mention undo/reversibility or whether the new layer becomes the active selection, which are the remaining behavioral facts an agent might want.

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

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

Front-loaded with the core action, then tightly labeled sections (Users often say / Use when / Do NOT use when / Returns / Preconditions / Side effects). No filler sentences; the multilingual keyword line is unusual but directly serves retrieval.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 16-parameter creation tool with no output schema, the description supplies the return shape, preconditions, side effects and sibling routing. Minor gaps remain: x/y coordinate reference frame is unspecified and there is no note on when point vs. paragraph text is appropriate beyond the schema's default inference rule.

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 already 100%, so the baseline is 3; the description earns above baseline by mapping colloquial user phrasings onto parameters (letter spacing→tracking, line height→leading, text box→box_width/height) and by directing font discovery to photoshop_list_fonts. It does not clarify the coordinate space of x/y or the interaction between auto_leading and leading.

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

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

Specific verb+resource (create a text layer) with the exact settable facets enumerated: content, position, font, optional typography. It explicitly distinguishes itself from photoshop_update_text_content and photoshop_set_text_style, so an agent can route new-text vs. edit-text without opening a schema.

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

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

Gives an explicit 'Use when' (labels, titles, typography) and 'Do NOT use when' (editing existing text) with named alternative tools, plus a negative routing rule telling the agent not to fall back to execute_script for tracking/leading/box. That is the full when/when-not/alternative triad.

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 provided, the description carries the full behavioral burden and does so well: it discloses the custom warp mesh/homography implementation, exactness on pixel layers, and that Smart Objects must be rasterized with rasterize:true, which is destructive and should be preceded by duplication. It also warns to save a copy of the document before running.

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 dense paragraph rather than structured bullets, but it front-loads the purpose and every sentence adds operational detail about prerequisites, rasterization, or saving. There is little 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 complex, mutating transform tool with no output schema and no annotations, the description covers the important invocation context: bounds discovery, corner computation, rasterization behavior, and saving a copy. It does not describe return values or failure modes, but is largely complete 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 coverage is 83%, so most parameter meaning is already documented in the schema. The description reinforces the coordinate convention and destructive rasterization warning, but does not add much beyond the schema for mode, interpolation, or document_id.

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

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

States a specific verb and resource: corner-pin/perspective distort of a layer, mapping its bounding box to four target corners. This distinguishes it clearly from sibling transform tools such as move, scale, and rotate.

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?

Explains it is a headless replacement for Free Transform -> Distort / Perspective Warp and instructs the agent to read current bounds with get_layers/get_state, compute target corners, and save a copy first. It gives clear usage context, though it does not explicitly name sibling tools or state when not to use 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 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 burden and does so thoroughly: it explains the IIFE wrapper, the need for explicit return, serialization via toSource() and automatic parsing, timeout behavior with defaults and max, preconditions, and that side effects depend on the code. This far exceeds typical behavioral disclosure for an arbitrary execution 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 well organized: purpose first, then usage rules, return behavior, timeout guidance, and preconditions/side effects. Each sentence earns its place, and key warnings are 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 high-complexity escape-hatch tool with no output schema and no annotations, the description covers selection logic, execution semantics, return serialization, timeout mitigation, preconditions, and side-effect variability. An agent has enough context to invoke it correctly and avoid common failure modes.

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 met; the description goes beyond by explaining the return-value contract for the code parameter (explicit return required, bare expression returns undefined, toSource serialization) and reinforcing when to pass timeout_ms. This adds meaning that the schema alone does not 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?

States a specific verb and resource ('Execute custom ExtendScript (JSX) code inside Photoshop') and explicitly frames itself as an 'advanced escape hatch,' which differentiates it from the many atomic photoshop_* and recipe tools. The name sibling list makes clear this is the generic fallback, not a single-purpose operation.

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

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

Gives explicit use criteria: '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 directly tells the agent when to select this tool versus any of the many 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 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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It states side effects ('writes files; does not modify the original'), preconditions ('document with at least one artboard'), the 600s script timeout for long jobs, and the return shape. This is comprehensive for a non-destructive export 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 well-structured with labeled sections ('Use when', 'Do NOT use when', 'Returns', 'Preconditions', 'Side effects') and is front-loaded with the core purpose. It is slightly longer than necessary due to the multilingual user-phrase examples, but those aid intent recognition without bloating it.

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 correctly explains the return JSON. It covers the core operation, the sibling alternative, preconditions, side effects, timeout behavior, and parameter-relevant output details, so an agent has what it needs to invoke 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 per the baseline the schema already documents all four parameters. The description adds slight context by listing the supported formats and mentioning the output folder, but it does not substantially expand on the schema's own parameter descriptions.

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: 'Export every artboard in the active document to a folder,' and includes the mechanism (duplicate + crop to artboardRect, then PNG/JPEG/WebP/AVIF). It also distinguishes itself from the sibling photoshop_export_as by explicitly saying that tool is for exporting the whole canvas once.

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: 'delivering one file per artboard.' It also provides a clear exclusion and alternative: 'Do NOT use when: exporting the whole canvas once — use photoshop_export_as.' This leaves little ambiguity for an agent selecting among 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 provided, so the description carries the full burden. It discloses side effects ('writes one file to path'), non-destructive behavior ('without changing the open document'), preconditions ('active document'), version requirements for WebP/AVIF, and the duplicate+crop behavior for artboard_id. This is exceptional transparency for an unannotated 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 with labeled sections (use when, do not use, returns, preconditions, side effects) and every sentence adds operational value. It is longer than average, but the length is justified by the tool's branching behaviors and the absence of 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 output schema and no annotations, the description fully covers the return shape, side effects, preconditions, format constraints, and artboard-specific behavior. The input schema handles parameter details, and the description supplies the operational context an agent needs to call this tool safely and correctly.

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

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

Schema description coverage is 100%, so the schema already documents each parameter. The description adds meaningful context beyond the schema, such as the version requirement tied to format, the 'duplicate + crop' semantics of artboard_id, and the path/extension matching expectation, which helps an agent invoke parameters correctly.

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 ('Export a copy'), the resource ('active document'), and the supported formats. It explicitly says the open document is unchanged, which distinguishes it from save operations, and names sibling alternatives like photoshop_save_document and photoshop_export_artboards.

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 photoshop_save_document for saving the working document and photoshop_export_artboards for exporting every artboard. It also includes natural-language user phrasings like 'export for web' and 'save as webp' that help an agent recognize intent.

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, the description carries the full burden. It discloses the return shape ('{ ok, summary, details }') and critical preconditions (generative_fill capability, Adobe generative credits). It does not detail side effects like document modification, but the core generative behavior is 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?

Four terse, purposeful lines: action, use triggers, returns, and preconditions. The core purpose is front-loaded, and every sentence earns its place with no 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 return shape and preconditions are clearly given, compensating for the missing output schema. The use-when triggers cover selection, and the optional document_id parameter is described in the schema so the agent knows about activation behavior. Minor gap: no explicit mention of whether the tool creates a new document or modifies an existing one, but the width/height 'if creating new doc' hints imply both cases.

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 minimal parameter insight beyond calling prompt a 'text prompt' and does not clarify width/height/document_id semantics, which are left entirely to the schema. No additional value is provided.

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 image from a text prompt' with the explicit feature name 'ImageGen (Firefly ImageGen)'. This clearly distinguishes it from siblings like photoshop_generative_fillretical and leaves no ambiguity about 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?

Provides explicit 'Use when' triggers: user asks for ImageGen, text-to-image, or a new picture from a description. It does not mention alternatives or exclusions, but these conditions are sufficient for an agent to select this tool among the many Photoshop 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?

With no annotations, the description carries the full burden and does well: it lists preconditions (active document, generative_fill capability) and side effects (canvas enlarged with generated content). It doesn't explicitly flag reversibility/undo or rate/cost limits, which keeps it from a 5.

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

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

Front-loaded with the core action, then labeled Use-when, Returns, Preconditions, and Side-effects blocks. Every line carries information with no filler 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?

No output schema exists, but the description documents the return shape (ok, summary, details with direction/prompt/wait) plus preconditions and side effects. An agent has everything needed to call it correctly.

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

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

Schema coverage is 100%, so the schema already documents all four parameters including defaults and the document_id activation rationale. The description restates amount_px and direction semantics rather than adding new meaning, so baseline 3 applies.

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

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

States a specific verb and resource (extend canvas via Generative Expand) and describes the mechanism (enlarge by amount_px, fill with outpainting Generative Fill). Distinguishes it clearly from siblings like resize_image, crop_document, generative_fill, and generative_upscale.

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

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

'Use when: outpainting, extending background, or expanding composition' gives clear triggering scenarios. It stops short of naming alternatives (resize_image, generative_upscale) or exclusions, so the routing is implied by the scenario rather than by explicit contrast with 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?

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?

With no annotations, the description carries the full behavioral burden and does so well: it describes the return shape, the generative_timeout case, the 1–3 minute progress-dialog behavior, polling photoshop_get_state, and the fact that the result opens as a new active document with a predictable name. It also discloses capability and authentication 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 front-loaded and efficiently structured into purpose, use conditions, exclusion, return behavior, and preconditions. Every sentence contributes actionable information with no filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no annotations and no output schema, the description supplies the critical missing context: expected return shape, timeout behavior, new-document outcome, and preconditions. Nothing essential for correct invocation appears to be missing.

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

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

Schema description coverage is 100%, so document_id and target_scale are already fully documented in the schema. The description adds context about operating on the active document but does not add parameter-specific meaning beyond the schema.

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

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

The description states a specific verb and resource: upscale the active document using Generative Upscale. It also names the Photoshop version and distinguishes the operation from the sibling alternative photoshop_resize_image in the do-not-use clause.

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

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

It gives explicit when-to-use and when-not-to-use guidance, including the exact alternative (photoshop_resize_image) for the excluded case. It also states the required capability and Adobe sign-in precondition.

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?