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

Annotation Contradiction: The annotation idempotentHint=true claims the operation is idempotent, but the description says 'Create a non-destructive adjustment layer' — each call would create a new layer, which is not idempotent. While the description adds rich behavioral details (placement hoisting, masking, return context), the direct contradiction with the annotation forces a score of 1.

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

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

The description is very long, but each section serves a purpose: purpose, placement nuance, supported types, alternatives, masking, and return value. It is front-loaded with the core purpose. A small deduction for listing all adjustment types that are already in the schema enum, making it slightly redundant.

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 71 parameters and an output schema, the description is exceptionally complete. It explains non-obvious placement behavior (hoisting vs into_active_group), selection-based masking, return of parent_path, and explicitly differentiates from sibling tools in key scenarios. The output schema exists, and the description adds context beyond structured fields without needing to re-explain return values in detail.

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 each of the 71 parameters is already documented in the schema. The description adds a high-level summary of the supported types but largely repeats the enum values already present. It does add some context (e.g., 'Exposure (stops + offset + gamma)'), but the baseline of 3 is appropriate because the schema already carries the parameter semantics.

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

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

The description opens with a specific verb+resource: 'Create a non-destructive adjustment layer above the active layer.' It clearly distinguishes this from siblings by explicitly naming the canonical entry point for tonal/color adjustments, contrasting with ps_apply_adjustment for destructive ops and ps_merge for pixel baking.

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 usage guidance: 'This is the canonical entry point for tonal/color adjustments' plus an EXCEPT clause for raw-sourced documents. It gives alternatives: ps_merge for pixel bake, ps_apply_adjustment for Shadows/Highlights, and notes the removal of old destructive bake tools. Very clear when-to-use 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?

Beyond the minimal annotation (idempotentHint=false), the description discloses key behavioral traits: the fill layer is 'non-destructive', 'becomes active', and is 'hoisted out of the active layer's group by default' unless into_active_group:true is passed. It also explains the distinction from ps_fill_layer, which bakes color into the pixel layer, and explicitly mentions the layer's editable content nature.

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 6 sentences and each sentence earns its place, front-loading the core purpose and then adding differentiation, use cases, alternatives, and placement behavior. It is detailed enough for a 14-parameter tool without being verbose or redundant.

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 (14 params, multiple modes, placement nuance), the description is fully complete: it covers purpose, alternatives, parameter semantics, default behavior, and side-effects (layer becomes active). The presence of an output schema means return values are covered elsewhere, and no further context is needed.

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?

Even though schema description coverage is 100%, the description enriches parameter understanding by explaining conditional usage: 'fill_type=gradient is the go-to for sky fades, color washes, and vignettes', 'combine with opacity_stops 100→0 for fade-to-transparent', and 'gradient_type linear for skies/fades, radial for vignettes/glows'. It also clarifies the placement default and override via into_active_group.

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: 'Add a non-destructive SOLID COLOR or GRADIENT fill layer (an editable content layer)', clearly distinguishing ps_add_fill_layer from ps_fill_layer, which 'bakes color into the active pixel layer'. This immediately clarifies the tool's unique role among sibling 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 usage guidance with alternatives: 'fill_type=gradient is the go-to for sky fades, color washes, and vignettes (radial + reverse + multiply blend)' and 'For fading a layer out via its MASK use ps_layer_mask op=gradient instead'. It also suggests combining with ps_bake_layer to rasterize, giving clear when-to-use and when-not-to-use scenarios.

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?

The description discloses that the style is non-destructive and editable, complementing the idempotentHint annotation. It also reveals blend modes for specific styles, the background layer restriction, and that applying a style modifies the Lefx descriptor, all of which add behavioral context beyond what annotations alone provide.

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 approximately 100 words, yet every sentence earns its place: purpose, non-destructive nature, photo workflow examples, blend modes, background restriction, and return behavior. It is front-loaded with the core verb/resource, then organized hierarchically from general to specific use cases.

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 (11 parameters, nested color object, and an output schema), the description covers all essential operational facts: what it does, when to use each style, the background limitation, and the return context (Lefx descriptor). A minor gap is that it doesn't state whether applying a style replaces an existing style or stacks, but overall it is sufficiently complete for an agent to confidently select and invoke the tool.

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

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

All 11 parameters are thoroughly documented in the input schema with style-specific coverage, so the description does not need to repeat them. The text adds only marginal context (e.g., blend modes for drop_shadow/outer_glow/stroke) that overlaps with the schema's style parameter description, resulting in limited additional value beyond the structured data.

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 'Apply a layer style' and lists all six supported styles, making it unmistakable that this tool adds layer effects, not filters or fill layers. It also specifies 'to the active layer,' which clearly distinguishes it from sibling tools like ps_add_fill_layer or ps_apply_adjustment that create new layers.

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

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

It provides explicit photo workflow scenarios—stroke as a print-style border, outer_glow for atmospheric lift, drop_shadow for depth on text overlays—telling the agent exactly when each style is appropriate. It also gives a clear exclusion (cannot apply to a background layer, duplicate/convert first), though it does not explicitly name alternative sibling tools for other use cases.

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?

The description adds substantial context beyond the destructiveHint annotation: it discloses auto-duplication, original preservation, revert-by-deleting-copy, auto-rasterization of text/smart-object layers, and per-type parameter defaults (e.g., shadow amount 35, +20 color correction). No contradiction with annotations exists.

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 dense but well-structured: it front-loads the core purpose with DESTRUCTIVE emphasized, then covers behavior (auto-duplicate/rasterize) and type-specific semantics in a logical flow. Despite the length, each clause earns its place given the 13-parameter complexity.

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 tool with 13 parameters, an output schema, and annotations, the description covers purpose, safety, alternatives, per-type behavior, defaults, and parameter requirements. It provides complete guidance without needing to explain return values because an output schema exists.

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 detailed per-parameter descriptions, so the baseline is 3. The description adds valuable extra semantics: how `type` drives parameter relevance, that `equalize` is parameter-free, and that `cl_lut_name` is required for color_lookup. However, it does not describe every parameter's role beyond what the schema already provides, so the value is strong but not exhaustive.

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 resource ('tonal adjustment'), enumerates the three concrete types, and explicitly distinguishes itself from the editable alternative by name (ps_add_adjustment_layer). This clearly differentiates it from siblings.

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

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

It states exactly when to use the tool (for destructive adjustments not available as adjustment layers) and explicitly recommends the editable alternative: 'For EDITABLE tonal/color work, prefer ps_add_adjustment_layer.' It also clarifies the default auto-duplicate behavior and the apply_to_active_layer opt-in, so usage context is unambiguous.

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 only sparse annotations (idempotentHint=false, destructiveHint=true), the description carries the burden and delivers richly: auto-duplication preserving the original with a 'Brush Stroke (<name>)' copy, tool-option mutation restored in `finally`, sampled brushes silently ignoring hardness/diameter mutations, background auto-promotion, and gate-verified placement that strokes only on pass. The destructive `apply_to_active_layer=true` path is explicitly disclosed, so there is no contradiction with destructiveHint — the annotation is merely conservative.

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 long, but for a 14-parameter, 16-tool surface every section earns its place: family inventory, when-to-use block, layer prerequisite, auto-duplication, and the sampled-brush caveat. Structure is logical — capability → input modes → tool list → use cases → prerequisites → side effects → dynamics — and the key 'Reach for this when' guidance is bolded and prominent. The only mild redundancy is echoing the tool enum, but the family-grouping angle justifies 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?

An output schema exists, so return-value explanation is unnecessary, and the description covers the major behavioral contracts: dual input modes (placement vs path), gate-failure semantics for placement, layer prerequisites, auto-duplication default, and user-state restoration. All nested objects (placement, source_placement, source_point, foreground_color) are addressed. Minor gaps such as exact error behavior on gate failure are left to schema/output, which is acceptable at this complexity.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds cross-cutting semantics the schema lacks: which tools REQUIRE source_point, which families honor foreground_color vs ignore it, and the brush-dynamics interaction order (preset loads first, then hardness_pct overrides). The family grouping (retouch/paint/specialty) enriches the flat enum meaningfully. Per-parameter detail rightly lives in the schema, so this is a solid 4 rather than a 5.

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

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

Opens with a specific verb+resource: 'Paint along a path with one of PS's 16 brush-family tools,' and enumerates the full tool families (retouch, paint, specialty). The four 'Reach for this when' scenarios pin down concrete use cases, making it unambiguous how this differs from siblings like ps_filter, ps_apply_adjustment, or ps_fill_layer. 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 bolded '**Reach for this when**' block lists four concrete scenarios (clone-out a distraction, heal a scratch/seam, dodge/burn a contour, paint a freehand line), and the placement-vs-path guidance states which input mode is preferred and why. It also gives a clear prerequisite: rasterize adjustment/shape/text/smart-object layers first. It does not explicitly name sibling tools it is NOT for, so exclusions remain implicit rather than spelled out.

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?

The description goes beyond the destructiveHint annotation by explaining that the tool defaults to running on a duplicate of the active layer, preserving the original, with an opt-in flag to bake in place. It also discloses the 'AM-only' environment and version verification, adding useful behavioral context without contradicting the annotations.

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

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

The description is succinct, with six sentences each serving a purpose: main action, use cases, source explanation, safety behavior, prerequisite, and environment note. It is front-loaded with the primary operation and uses bold for 'Reach for this' to draw attention to usage guidance without waste.

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

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

Given the tool's complexity (6 parameters, multiple channels, blend modes) and the presence of a detailed input schema and output schema, the description adds the necessary context: purpose, use cases, default safety behavior, and prerequisites. It is complete enough for an agent to decide when to use it and what to expect.

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 with detailed descriptions for all six parameters, including the blend mode enum and apply_to_active_layer behavior. The main description adds only a high-level summary of source and channel, which is already well-covered in the schema, so it provides minimal additional semantic value beyond the structured fields.

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 tool composites a source layer and channel onto the active layer using a calculation blend mode, explicitly naming 'Image ▸ Apply Image'. It also lists specific use cases like luminosity blends and channel pulling, which distinguishes it from the sibling tool ps_calculations by focusing on the active layer target.

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 'Reach for this' use cases (luminosity blends, frequency-separation, texture overlays, channel pulling) and mentions prerequisites like the active layer must be a normal pixel layer. However, it does not explicitly mention alternatives such as ps_calculations or scenarios where this tool should not be used, so it lacks a crisp when-not guidance.

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

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

The description provides rich behavioral detail beyond annotations: it explicitly states the operation is non-destructive, creates a new pixel layer with a specific naming pattern, includes clipping and styles, and works for lone layers. It also discloses the requirement that the active layer be top-level. This goes well beyond the minimal idempotentHint annotation and gives the agent a full understanding of 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 bit lengthy but every sentence earns its place: it explains the core action, the non-destructive nature, an explicit usage recipe, and a key constraint. It is front-loaded with the main purpose, and while it could be trimmed slightly, the extra detail aids usability.

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 are no parameters and an output schema exists, the description covers all essential context: what the tool does, why to use it, how it works in common scenarios, and its constraints. There is no missing information that would prevent an agent from selecting and invoking it correctly.

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

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

The tool has zero parameters, so schema coverage is trivially 100%. The description adds no parameter-specific info because none exists, but it explains the tool's behavior in a way that makes the lack of parameters clear. Baseline 4 for 0 params is appropriate; the description doesn't leave any ambiguity about inputs.

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 'Flatten' and the exact resource: the active layer's current appearance, including clipped adjustment layers and layer styles, into a new pixel layer. It distinguishes from sibling tools (like ps_rasterize_layer) by emphasizing non-destructive creation of a new layer, and provides concrete examples that clarify its unique role.

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 explains when to use this tool: 'This is how you get real baked pixels out of a non-destructive stack' with a specific example (desaturating via Hue/Saturation or Invert). It also states it works on a lone layer. However, it does not explicitly name alternative tools or say 'use this instead of X,' though the context implies the distinction. The constraint that the active layer must be top-level is clearly stated.

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

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

Beyond annotations (which only mark non-idempotent and non-destructive), the description adds rich behavioral detail: it states the operation is 'Non-destructive: adds a new channel (delete it to revert)' and explains the result can be loaded as a selection. It also discloses the environment constraint 'AM-only; verified live on PS 27.2.0', which annotations do not cover.

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

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

The description is only three sentences, front-loaded with the core function, then use cases, then behavior. Every sentence adds value: the function, the practical examples, and the non-destructive/revert behavior. 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 an output schema exists, the description need not explain returns, and it covers all necessary context: what the tool does, when to use it, how it behaves (non-destructive, new channel), and how to follow up. It also mentions the AM-only environment. The tool's complexity is well-supported by the rich schema and this description.

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 already has 100% descriptive coverage for all 8 parameters, including enum explanations of blend modes and channel options. The description provides conceptual guidance (e.g., 'multiply two channels for a luminosity mask') but does not add details beyond what the schema already states, so the baseline of 3 applies.

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

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

The description clearly states a specific verb and resource: 'Blend TWO sources... into a NEW alpha channel via a calculation blend mode' and differentiates from siblings by focusing on channel math for masks ('difference of two channels to isolate edges'). It names the actual Photoshop menu (Image ▸ Calculations), making the purpose 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?

The description gives explicit when-to-use context: '**Reach for this** to build advanced selections/masks from channel math' and provides concrete examples. It also references the follow-up operation (ps_selection_channel op=load) but does not explicitly state alternatives to avoid for simpler operations, so it falls just short of a 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?

The description goes well beyond the idempotentHint annotation, revealing that the operation is non-destructive, that create no-ops with already_clipped:true and release no-ops with released:false, and that the active layer is unchanged. This behavior is not evident from the annotations alone.

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 concise yet thorough, front-loading the core operation and then supporting details in a logical order: action, create, release, idempotency note. Every sentence contributes meaning, with no filler or repetition of the tool name.

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

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

Given a single parameter fully documented in the schema and an output schema that can convey return details, the description covers everything needed for correct selection and invocation: operands, effect, no-op behavior, and alternative tools. Nothing material is missing.

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

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

The schema already rules the single op parameter with a 100%-coverage enum description. The tool description enriches this by explaining the mechanics (layer below becomes alpha source), the inverse behavior, and the practical consequence, adding value beyond the schema's dry definition.

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 ('Clip or un-clip the active layer against the layer directly below it') and explicitly names the two modes, create and release. It clearly distinguishes this tool from siblings like ps_layer_mask and ps_add_adjustment_layer, so an agent can identify its unique role.

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 contexts for use (constraining a texture/photo to a shape, masking an effect to a single underlying layer) and explicitly directs the agent away from this tool when an adjustment-layer-specific case exists, naming the add_adjustment_layer tool as the alternative. This is explicit when-to-use and when-not-to-use 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?

The description goes beyond the destructiveHint annotation by specifying the exact condition under which closing is destructive (save=false with unsaved changes), and it discloses the duplicate-name failure mode and the returned context block. This is valuable behavioral detail an agent needs before calling.

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?

Three dense sentences cover purpose, targeting options, destructive risk, ambiguity handling, and return value without redundancy. The most important content is front-loaded and every sentence 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?

The description covers the default behavior, all targeting modes, failure on ambiguous names, destructive conditions, and the post-close context update. Combined with full parameter schema coverage, the output schema, and annotations, nothing important is missing for an agent to invoke this correctly.

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

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

Schema coverage is 100% and each parameter is already well described. The description adds meaningful context beyond the schema, especially the active-by-default targeting and the guidance to prefer id over name when names collide, which helps an agent choose 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?

The description states a specific verb and resource ('Close a Photoshop document'), immediately distinguishes the active-by-default behavior from targeting by name or id, and makes the tool's scope clear relative to document-focused siblings. It fully answers 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?

It gives clear context for choosing the active document versus a specific one, and explicitly advises using id when names collide. It does not name alternative sibling tools or state when not to use this tool, but the guidance provided is sufficient for correct invocation.

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

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

Annotations already declare readOnlyHint and idempotentHint, so the description adds value by explaining the output structure (per-channel mean/stdev/median, deltas) and the supported single-pixel sampling. It does not contradict annotations and provides useful behavioral context beyond the hints.

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: the first sentence states the core purpose, the next gives technical detail, then a bolded 'Reach for this when' section with three examples, plus a final note on single-pixel support. Every sentence earns its place and 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?

Given the output schema and strong annotations, the description is complete. It explains the purpose, usage scenarios, and key constraints (same document, 1x1 sampling). Missing details like error handling are not essential for a read-only comparison tool with output schema defined.

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 each parameter is already documented. The description adds overall context about what the regions represent and the comparison nature, but does not elaborate on individual coordinate semantics, units, or edge cases. Baseline 3 is appropriate.

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

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

The description has a specific verb and resource: it captures histograms of two regions and reports per-channel statistics with deltas. It clearly distinguishes itself from get_preview by framing itself as the numeric verification counterpart for subjective visual checks.

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 'Reach for this when' section lists three concrete use cases with examples, and directly contrasts with get_preview. This gives the agent clear actionable guidance on when to select 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?

Annotations already indicate destructiveHint/idempotentHint, and the description adds critical behavioral details: document-wide flattening, auto-accepting the confirmation prompt, and color discard for grayscale. This goes well beyond the annotations and is consistent with them.

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?

Three purposeful sentences, front-loaded with the action and destructiveness warning, followed by usage guidance and return value. 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?

The tool has a rich input schema and an output schema. The description covers the destructive scope, when to use which mode, and what is returned ('updated document context'). Any omitted details like bitmap are fully handled by the schema, making this 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 detailed parameter descriptions, including bitmap-specific parameters and defaults. The description's prose covers mode at a high level but omits bitmap and the angle/shape/frequency parameters; however, the schema already provides full semantics, so a baseline score is appropriate.

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

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

Description explicitly states 'Convert the document color mode' and lists specific target modes. This clearly distinguishes it from sibling tools like resize/crop by focusing on color mode conversion.

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 concrete usage context: 'Use grayscale as the base for halftone / line-art workflows, or rgb to bring a CMYK/Lab doc back for normal editing.' It doesn't state when not to use or name alternatives, but the use cases are clear.

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

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

The description goes beyond the minimal annotations by explaining key behavioral traits: wrapping is non-destructive, background auto-promotion, creation of nested Smart Objects when wrapping an existing SO, and the unlinked nature of new_via_copy. It also clarifies that new_via_copy requires the active layer to already be a Smart Object.

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 relatively long but every sentence contributes meaning—covering modes, use cases, supported layers, background promotion, edge cases, and alternatives. It is well-structured with `convert` and `new_via_copy` separated, though slightly dense for a quick read.

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 only one optional parameter, the tool's behavior is nuanced and depends on current layer state. The description covers prerequisites, side effects (nested SO, background promotion), and both modes comprehensively. Since an output schema exists, the lack of return-value explanation 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?

Schema coverage is 100% and the mode parameter has a detailed description in the schema, providing a baseline of 3. The main description adds extra semantic nuance beyond the schema, such as the nested Smart Object behavior and explicit contrast with ps_duplicate_layer, elevating it to 4.

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 ('Convert') and resource ('active layer to a Smart Object'), and distinguishes between the default 'convert' mode and 'new_via_copy'. It also explicitly differentiates from sibling tools by mentioning 'Use ps_rasterize_layer to go the other direction' and contrasts with ps_duplicate_layer in the schema description.

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 guidance: 'PREREQUISITE for Camera Raw Filter, non-destructive frequency separation, and any workflow where filter parameters need to stay adjustable after the fact.' Also specifies supported layer types, auto-promotion of background, and an alternative tool (ps_rasterize_layer) for the reverse operation.

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

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

No readOnly/destructive annotations are present, so the description carries the full burden. It thoroughly discloses the default hoisting behavior, the underlying CpTL event's lack of placement target, the effect of into_active_group, that the source is left untouched, that the new layer becomes active, and the selection edge cases. This is exemplary 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 long but every sentence earns its place, progressing from the core action to edge cases to usage. It is front-loaded with 'Copy the current selection...' and contains no redundant or filler content, making it appropriately sized for the complexity.

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 one optional parameter, an output schema, and only idempotentHint annotation, the description fully covers selection behavior, group placement, return context, and intended use cases. It leaves no significant ambiguity for an agent trying to decide whether and how to call it.

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

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

Schema coverage is 100%, but the description goes beyond the schema by explaining the 'why' behind the parameter: the CpTL event carries no placement target and would otherwise nest the new layer inside the active group. This rationale is not in the schema, adding genuine meaning for correct invocation.

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+behavior: 'Copy the current selection into a NEW layer above the active one — Photoshop's "Layer via Copy" (Ctrl+J)'. It clearly distinguishes this from sibling tools by explaining the selection semantics and the group-nesting nuance, which makes the tool's unique purpose 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?

The description gives direct usage guidance: 'Reach for this to isolate a region for independent transforms or filters' and explains behavior with and without a selection. It does not explicitly name alternative sibling tools or state when not to use this tool, but the context is clear enough for an agent to decide.

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

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

Annotations only provide title and idempotentHint=false, so the description carries most of the behavioral disclosure burden. It adds value by noting the return value ('Returns the new document id and name plus active context'), which hints at side effect of becoming active. It does not contradict annotations.

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

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

Two sentences: first states purpose and returns, second gives usage guidance and alternative. No wasted words, front-loaded with the core action.

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

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

With an output schema present, return value details are already covered. The description fully covers the tool's purpose, when to use it, and how it differs from siblings. It is complete for a straightforward create operation.

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

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

Schema description coverage is 100% with well-described parameters (width, height, color_mode, resolution). The description merely lists parameter categories ('dimensions, resolution, and color mode') without adding new meaning beyond the schema, so baseline 3 is appropriate.

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

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

The description uses a specific verb ('Create') and resource ('new empty Photoshop document') with explicit parameters (dimensions, resolution, color mode). It clearly distinguishes from sibling ps_open_document by stating 'prefer ps_open_document to load an existing 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?

Explicitly states when to use this tool: 'Use this when starting from scratch' and provides an alternative: 'prefer ps_open_document to load an existing file.' This gives clear context and 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?

The description adds meaningful behavioral context by stating 'Non-destructive' and specifying the created layer's position relative to the currently active layer. Annotations only provide idempotentHint: false, so the description carries the burden of safety disclosure and handles it well, though it does not explain what happens if no document/active layer exists.

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 provide the core action, positioning, safety behavior, and alternative routing with no filler. The most important information is front-loaded and 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 operation with one optional parameter and no required fields, the description fully covers what the agent needs to know: what is created, where it is created, that it is non-destructive, and what to use instead for text or adjustment layers. The existing output schema covers return behavior, so the description does not need to duplicate it.

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

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

The input schema already contains a complete description of the only parameter: 'Name for the new layer (optional),' giving 100% schema description coverage. The description does not need to restate this, and it adds no meaning beyond the schema, 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 states a specific verb and resource: 'Create a new empty raster layer above the currently active layer.' It clearly distinguishes itself from sibling creation tools like ps_text and ps_add_adjustment_layer, and the phrase 'empty raster layer' removes ambiguity about what kind of layer is created.

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 tells the agent when to use this tool and when to choose an alternative: 'Use ps_text (op=create) for text, ps_add_adjustment_layer for adjustments.' This gives direct routing guidance without requiring the agent to infer it from the schema or 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?

Annotations already declare destructiveHint and idempotentHint, and the description adds operational detail: pixels outside the crop are permanently lost, placement-based crops are gate-verified and only executed when the gate passes, and the operation returns updated document context. This goes beyond the bare hints without contradicting them.

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: one front-loaded sentence covers the two modes, and the next covers consequences and return value. There is no filler, and every clause contributes operational or safety 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 five parameters including a nested placement object, the description plus schema covers modes, coordinate space, gate behavior, destructive impact, idempotency, and result. The only minor weakness is the repeated 'when this build has one' caveat, but it does not prevent correct invocation.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds useful meaning by framing placement as the preferred approach and clarifying that raw bounds are expressed in document space, helping the agent choose between the two parameter groups.

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 operation: 'Crop the document to a region' and enumerates the two supported modes. It is unambiguous about the resource and action, but it does not explicitly contrast with sibling tools like ps_transform_canvas or ps_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 gives concrete mode-selection guidance, saying anchor-relational placement is 'preferred' over raw pixel bounds and noting that raw bounds are ignored when placement is set. It does not name alternative sibling tools to use instead, but the in-tool guidance is clear and actionable.

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?

The description adds valuable behavior beyond the destructiveHint annotation: it warns that deletion is recoverable only via Edit > Undo, explains recursion into groups, and discloses that group-name matches are refused. This level of detail is especially useful for a destructive operation.

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

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

The description is compact and front-loaded with the critical destructive warning. Every sentence carries useful information: the two behavior modes, the group-match exception, the alternative tool, and the recovery path. 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 single-parameter destructive tool, the description is complete: it covers both parameter states, the recursion behavior, refusal semantics, recovery expectations, and the correct alternative for groups. The output schema exists, so return-value explanation is not needed from the description.

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 input schema already documents the `name` parameter well. The description adds extra meaning by emphasizing that matching is first-match, happens recursively through groups, and that group names will not be deleted. This goes beyond the schema's baseline and helps the agent understand edge behavior.

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 the verb and resource precisely ('Delete a layer') and distinguishes the two invocation modes: no-argument deletes the active layer, while `name` deletes the first matching layer in groups. It also explicitly differentiates from `ps_group` by stating that groups are refused rather than deleted.

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 when-to-use guidance: use no-arg for backward-compatible active-layer deletion, and use `name` for cleanup when the target layer is not active. It also provides an explicit alternative — `ps_group(op=delete)` — for deleting groups, which prevents 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?

Beyond the readOnlyHint and idempotentHint annotations, the description adds valuable behavioral context: it is local on-device vision, the image is never sent anywhere, it renders a throwaway duplicate and never modifies the working document, and coordinates are always in full document pixels. This goes well beyond the annotations and helps the agent predict side effects and trust boundaries.

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: scope, privacy, use case, sibling alternative, target selection, read-only behavior, coordinate format, and annotate guidance are all packed in without redundancy. The key differentiators are front-loaded with 'cheap, narrow read' and 'labeled bounding boxes only.'

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 six parameters and an output schema, the description covers all needed context: what it returns, coordinate space, privacy, side effects, when to use it, and how to visually verify results. The output schema handles return-value details, so no critical guidance is missing.

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

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

The schema already covers all six parameters with 100% description coverage, so the baseline is 3. The description adds extra meaning by explaining the relationship between max_dimension and speed/coordinate accuracy, by framing annotate as a visual-confirmation aid, and by noting that target selects faces/objects/both. This enriches, rather than merely restates, 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: detecting faces and/or COCO-80 objects and returning labeled bounding boxes in document-pixel space. It clearly distinguishes this tool from ps_read_scene by calling it 'the cheap, narrow read' and contrasting it with the 'full scene model.'

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 this tool: 'Use this for real coordinates before a spatially-targeted edit when boxes are all you need.' It also names the alternative, ps_read_scene, and explains when that sibling should be used instead, providing clear routing guidance.

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

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

The description states 'Read-only with respect to pixels,' clarifying that even the activate operation does not modify image content, and highlights that op=list works when nothing is open. It also notes the duplicate-name failure behavior via the parameter description. While the idempotentHint annotation covers repeat-safety, the description adds meaningful context about scope and pixel-read-only 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 description is dense but efficiently organized, front-loading the core purpose before explaining the two operations and sibling alternatives. A few phrases like 'which is the point' add flavor but do not bloat the content; every substantive point 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?

The description covers both operations, their failure/recovery contexts, the pixel-read-only guarantee, and explicitly points to sibling tools for load and close. With an output schema present, return-value details are not required. The only minor gap is that op=activate implicitly requires at least one open document, though this is reasonably inferable from the list/activate 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%, so the baseline is 3, but the description adds real value beyond the schema: it explains what op=list returns conceptually ('what is open, which one is active, and does it have unsaved changes'), frames op=activate as the fix for editing the wrong document, and reinforces the id-vs-name disambiguation. This goes beyond repeating schema property names.

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 — 'See and steer WHICH documents are open' — and immediately distinguishes itself from content-mutating tools by saying it is 'without touching their content.' It also names the two operations, op=list and op=activate, making the tool's purpose concrete and distinguishable from ps_open_document and ps_close_document.

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 gives usage context: op=list answers 'what is open, which one is active, and does it have unsaved changes,' and is called the 'recovery read' after a 'No document is open' failure. It also names alternatives explicitly — 'use ps_open_document to load a file and ps_close_document to close one' — so an agent knows exactly when to choose this tool over siblings.

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

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

The description goes beyond the idempotentHint annotation by explicitly stating 'Not idempotent (each call creates another copy).' It also discloses behavioral side effects: 'The new layer becomes active' and that it returns context. This adds valuable context beyond the structured annotation.

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

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

The description is concise, with each sentence serving a purpose: action, side effect, return behavior, and idempotency. It is front-loaded with the primary action and contains 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?

For a simple tool with one optional parameter and an output schema, the description covers all essential behavioral aspects: what it does, the resulting active layer change, return context, and non-idempotency. The presence of an output schema means return values need not be detailed.

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% for the single parameter new_name, so the description does not need to add parameter details. The schema already explains the naming behavior. The description adds no extra parameter semantics but also 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 clearly states the action: 'Duplicate the active layer.' It is specific with a verb and resource, and distinguishes itself from similar tools like ps_create_layer or ps_copy_to_new_layer by focusing on duplicating the existing active layer.

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

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

The usage context is implied: use this tool to duplicate the active layer. However, it does not explicitly compare with alternatives or state when not to use it. No direct mention of sibling tools or exclusions, so it earns a baseline implied usage score.

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?

The description states 'Operates on a duplicate, so the working document is unchanged,' which directly contradicts the annotation destructiveHint: true. This is a fundamental inconsistency: the annotation implies the tool may be destructive, while the description explicitly claims non-destructive behavior for the document. No other behavioral details can compensate for this conflict.

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, starting with the core purpose, then the duplicate behavior, downscaling, and format-specific details. Every sentence adds value, and there is no redundancy or unnecessary elaboration.

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 (8 parameters) and the presence of an output schema, the description is largely complete. It covers the main export logic, duplicate operation, downscaling, and all format-specific parameters. It omits overwrite behavior and error handling, but these are not necessarily required, especially with the output schema present. The contradiction with the annotation lowers completeness slightly, but overall it is sufficiently complete for a well-documented 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?

The input schema has 100% coverage with very detailed descriptions for all 8 parameters, including specifics like quality mapping and compression levels. The description adds a concise high-level summary of the format options and the long_edge_px behavior, but largely restates the schema. Since the schema carries the heavy lifting, a baseline of 3 is appropriate, with the description providing only marginal additive 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 clearly states the tool exports the active document to a flattened image file (JPEG or PNG), using a specific verb and resource. It distinguishes itself from siblings like ps_save_psd and ps_get_preview by focusing on raster export, making its purpose 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?

The description gives clear context about when to use the tool (when exporting to JPEG/PNG) and notes it operates on a duplicate, implying safe use. However, it does not explicitly mention alternative tools or exclusions, such as 'for PSD use ps_save_psd', so it lacks explicit when-not guidance.

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

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

Beyond the idempotentHint annotation, the description discloses important error behavior (throws on locked/text layers) and a remediation (rasterize text first). It also clarifies scope (active layer or selection). These are valuable details not present in annotations.

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

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

Two concise sentences front-load the primary action, then add important qualifications. No waste; every clause serves a 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 simple tool with three well-documented parameters and an output schema, the description provides the essential scope and error handling. The note about text layers and locked layers covers the main edge cases an agent would encounter.

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

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

The input schema has 100% description coverage with each color component defined in its own property ('Red component (0-255)', etc.). The description adds no extra parameter context, but the schema is self-sufficient, 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 ('Fill'), a clear resource ('the active layer or the current selection within it'), and the action (with a solid RGB color). It clearly distinguishes from sibling tool ps_add_fill_layer, which creates a new fill layer rather than filling an existing one.

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 a practical precondition: 'Throws on fully-locked or text layers — rasterize text first if needed.' This tells the agent when the tool cannot be used and what to do before use. However, it does not explicitly mention alternatives like ps_add_fill_layer, though the difference is implied by '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?

Annotations already signal destructiveHint=true and idempotentHint=false, and the description substantially enriches the safety picture: it discloses the non-destructive duplicate-by-default behavior, the reversal path (delete the copy), the destructive bake-in path via apply_to_active_layer:true, and the non-rasterizing smart-filter path. This is exactly the kind of behavioral nuance agents need beyond the annotation flags.

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

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

The description is long but earned: it front-loads the critical safety/destructive behavior first, then the op dispatch, then the index convention, then the coverage scope. Given 95 parameters and 5 operations, the density is justified, though a lighter touch around the filter-coverage list would have been possible.

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 95 params, 5 dispatch modes, and an output schema, the description covers everything needed to call it correctly: op semantics, index sourcing, smart-object prerequisites, the duplicate-vs-bake-in decision, and the supported filter repertoire. Nothing an agent needs to decide between apply/list/remove or duplicate vs. destructive is left to inference.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description adds narrative meaning beyond the schema: it explains what each op does in prose, codifies the index convention (index 1 = bottom/first-applied), and maps type values to their parameter families. This reduces the cognitive load of parsing 95 schema entries.

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+resource: apply Photoshop filters and manage the re-editable Smart Filter stack (list/set_visibility/set_blend/remove). It also enumerates the exact filter families covered (blur, sharpen, noise, high_pass, pixelate, distort, displace, oil_paint), so an agent knows precisely what this tool does and does not do relative to siblings like ps_apply_adjustment or ps_retouch.

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 operational guidance: op=apply is the default for new filters, management ops require a 1-based index obtained from op=list first, and as_smart_filter requires a prior Smart Object conversion. It does not explicitly contrast against sibling tools, but the internal op-routing conditions are unambiguous and enough to prevent misselection.

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?

Beyond the readOnlyHint and idempotentHint annotations, the description discloses latency, composite-vs-per-channel reading behavior, required document mode, transparent layer fallback behavior, and the exact luminosity weighting with its non-Rec.709 caveat. It also explains what a marginal fallback value means and how the result's channel field annotates it. No contradiction with annotations.

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

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

The description is dense but well-structured and front-loaded: one-sentence purpose, cost/read-only note, bolded use-case list, then channel-specific edge cases. Every clause carries operational value for a tool with non-obvious fallback behavior, so the length is justified.

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 one optional parameter, full schema coverage, an output schema, and read-only/idempotent annotations, the description covers selection criteria, return values, channel constraints, fallback paths, and interpretation caveats. Nothing an agent needs to call or interpret 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?

The schema already fully documents the channel enum at 100% coverage, and the description adds substantial meaning beyond the schema: how composite reads fall back to a pixel layer, when red/green/blue/gray are valid, the exact luminosity weighting formula, and the fallback semantics. This far exceeds the baseline expectation.

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 ('get histogram') and defines it as the quantitative complement to get_preview, listing the concrete return values (256 bin counts plus mean/stdev/median). This clearly distinguishes it from sibling inspection/read tools like ps_get_preview and ps_inspect.

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 'Reach for this when' section explicitly enumerates four concrete use cases: clipping detection, exposure verification, neutral-gray checking, and confirming a destructive op had an effect. It also contrasts directly with get_preview, saying it answers questions get_preview can't reliably answer by eye. This gives an agent explicit selection criteria.

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?

Beyond the readOnlyHint and idempotentHint annotations, the description adds meaningful behavioral context: it computes 'actual − target' deltas, uses boundsNoEffects for measurement, and searches layers recursively in groups. It also explains the verdict mechanism and reinforces read-only behavior. No contradiction with annotations exists.

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, starting with the category 'Numeric verification' before stating the verb and resource. It packs outputs, usage guidance, and behavioral notes into a tight paragraph with no wasted words. Every sentence contributes unique value.

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 full input schema, read-only/idempotent annotations, and presence of an output schema, the description covers purpose, outputs, timing, and search behavior very well. Minor omissions like error handling for missing layers or explicit unit confirmation are not critical because the schema and output schema fill most gaps. It is nearly complete for an AI 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 input schema already provides 100% coverage with clear descriptions for all six parameters, including the tolerance threshold for the verdict. The description adds the overall computation formula and the role of tolerance, but does not clarify individual parameters beyond the schema. This aligns with the baseline expectation 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 opens with 'Numeric verification: compute the per-edge pixel deltas between a layer's actual bounds and a target rectangle,' which names a specific verb and resource. It lists exact outputs (left/top/right/bottom deltas, scale ratio, centroid offset, verdict) and frames it as a verification tool distinct from visual previews. This clearly distinguishes it from siblings like ps_get_preview and ps_compare_regions.

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 it: 'AFTER place_image / scale_layer / move_layer to confirm the operation produced the intended result.' It also contrasts with 'eyeballing a preview,' implying a better alternative for numeric checks. However, it does not name an alternative tool or provide explicit when-not-to-use conditions, so it stops short of a 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?

Annotations already declare readOnlyHint=true and idempotentHint=true. The description adds the mechanism: 'renders a duplicate that is closed immediately,' and confirms no side effects on the working document. It also notes the fallback behavior without annotations. This is useful context beyond the structured hints, though it doesn't address rate limits or payload 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 a single dense paragraph but front-loads the core purpose and usage. Every segment earns its place, covering annotation types, intended use, and alternatives. It is long but matches the tool's complexity; minor structural improvements (e.g., paragraph breaks) would enhance scannability but are not essential.

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 (three parameters, one highly flexible annotations array), the description is complete: it explains what the preview shows, how to use overlays, how to avoid misusing grid annotations, and what happens with no annotations. Since an output schema exists, the description need not explain return values.

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 detailed per-parameter descriptions, so the baseline is 3. The description goes further by explaining the strategic use of the annotations parameter: spatial verification vs compositional evaluation, and explicitly warns against using grid overlays for coordinate reading. This adds meaning beyond the JSON schema alone, especially for the complex annotations array.

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+outcome: 'Render the active Photoshop document as a flattened, downscaled image and return it inline so the calling AI can see the current visual state.' It clearly differentiates from sibling preview tools by emphasizing the current visual state and read-only nature, and the closing note about a plain preview clarifies its default behavior.

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

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

Explicit when-to-use guidance: 'Use this to verify edits visually, judge whether adjustments went too far or not far enough, and decide what to do next.' It also provides exclusions and alternatives: 'To place or select precisely, do NOT read a pixel off a grid (unreliable) — NAME the intent to the on-device perception tools instead: ps_detect, ps_select_by_reference.' This is textbook when/when-not plus named alternatives.

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

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

Beyond the readOnlyHint/idempotentHint annotations, the description adds meaningful behavioral context: the operation is heavy (~2-4s), selection_info is always returned regardless of the image parameter, the rendering is inline JPEG, and it explicitly reassures 'Does NOT modify the source document.' It could add details like output encoding, but the additive context is substantial.

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 dense but front-loaded: purpose and default behavior first, then alternates, then cost/when-to-call guidance, then a safety reassurance. Every sentence earns its place; it could be marginally tightened (e.g., the parenthetical enum explanations slightly overlap the schema), but nothing is wasted.

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

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

For a two-parameter, read-only preview tool with a fully documented schema, an output schema, and safety annotations, the description covers everything needed to decide and invoke: rendering modes, latency tradeoff, invocation conditions, always-returned selection_info, and non-destructive behavior. There is no meaningful gap.

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

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

Schema description coverage is 100%, so the schema already fully documents image and max_dimension, including the enum meanings and defaults. The description reinforces the key enum behavior in prose ('pass `image:'mask'` for a B/W MASK') but adds no genuinely new parameter semantics 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 names a specific verb and resource ('Render an inline JPEG so the agent can visually verify what is currently selected') and immediately explains the default rendering mode and two alternates. The focus on selection preview with overlay/mask options clearly differentiates it from the sibling ps_get_preview, which presumably covers general document preview.

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 an explicit when-to-call directive: 'call this when the stats look off or before committing a mask.' It also implies the alternative — the lighter 'selection_info bundle alone' — by contrasting latency (~2-4s). It stops short of naming the exact sibling tool to use when the lightweight stats suffice, but the context is clear enough for an agent to route correctly.

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

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

Beyond the destructiveHint annotation, the description discloses exactly what each destructive operation does: delete removes the group AND everything inside it, while ungroup dissolves the group but promotes contents to the parent level. It also clearly states the confirm:true requirement, giving agents the information needed to avoid catastrophic mistakes.

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 and routes the agent immediately to the `op` enum for lower-level details. It is slightly longer than needed because it repeats some destructive behavior that is also present in the `op` field description, but the redundancy is purposeful and conflict-worthy for a destructive group 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 multi-operation tool with 8 parameters, an output schema, and rich per-field descriptions, the description is complete enough for an agent to select the correct operation and understand the major risks. The main missing piece is explicit routing advice for related sibling tools, but the schema and annotations carry the remaining burden well.

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 input schema already documents every parameter in rich detail, so the description itself does not need to carry much parameter meaning. The free-text summary restates important behavioral semantics for delete/ungroup but does not materially extend 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 clearly defines the tool as "Layer group (LayerSet) lifecycle and membership" and explicitly lists the five `op` dispatch values: create/delete/ungroup/add_layer/set_blend_mode. This gives a specific resource, a clear operation set, and enough signal to distinguish it from sibling single-layer 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 directly explains when to use ungroup versus delete: "use ungroup, not delete, to keep the layers," and it tells the agent to "See the `op` enum for per-operation params." It does not explicitly contrast this tool against sibling tools like ps_create_layer or ps_delete_layer, so it stops short of a perfect usage guide.

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?

Beyond annotations (idempotentHint: false), the description discloses key behaviors: guides are 'non-printing layout aids', 'editor-only chrome', and 'do NOT render into ps_get_preview'. It also warns that 'clear removes all guides', which is important destructive behavior. No contradiction with annotations.

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

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

Four sentences, front-loaded with the core purpose, then each sentence adds distinct value: rendering behavior, op selection, add/layout syntax, and clear semantics. No wasted words, perfectly 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?

The description fully covers all three operations, parameter semantics, use cases, and exclusions. Output schema is present, so return value details are unnecessary. Complete for a tool of this complexity.

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

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

Schema coverage is 100%, providing baseline 3. The description goes further by reinforcing parameter meaning ('position in px', orientation horizontal|vertical) and adding usage semantics like 'evenly-spaced grid' and the concrete 'rule-of-thirds at 3×3' example. This adds value 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?

Clearly states 'Manage document guides' with specific operations (add, layout, clear), and distinguishes from sibling ps_get_preview by explicitly noting guides do not render into the exported preview. The description is a specific verb+resource with clear 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?

Explicitly explains when to use the tool: 'place them when a person will open the PSD and wants alignment/composition marks', and when not to: 'not a model-perception tool'. It also names the direct alternative ps_get_preview and clarifies the non-effect on it, fully addressing usage 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?

Annotations already declare readOnlyHint, openWorldHint, and idempotentHint, and the description reinforces those. It adds valuable behavioral/cost context: the `context` block is always returned, and using sections=["context"] skips IPTC traversal and source-file reads, which helps the agent reason about probe cost and freshness.

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, starting with the core purpose and then quickly adding usage rules, alternatives, and behavioral caveats. A bit dense in places, but everything earns its place for a multi-mode inspection tool.

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

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

Given the output schema exists, the input schema is complete, and sibling tools are explicitly named with their expected use, the description covers orientation and behavior thoroughly. It even explains fresh-state, cheap-probe, and read-only properties, so an agent can invoke it correctly with minimal ambiguity.

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 `what` and `sections` are thoroughly described in the schema with per-enum behavior. The main description adds higher-level routing and a cheap-probe strategy, but doesn't need to re-document parameter semantics; the schema handles that.

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 states a specific verb + resource (inspect document state) and differentiates itself from image-based or numeric sibling tools by enumerating exactly what `what` can return. It is immediately clear this is the general read-only orientation/assessment tool, not a preview or histogram tool.

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 to call at the start of a workflow and whenever fresh state is needed, and gives concrete alternative routing: use ps_get_preview for image checks, and ps_get_histogram / ps_compare_regions / ps_get_layer_bounds_diff for numeric checks. This gives the agent both when-to-use and when-not-to-use guidance.

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

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

Annotations provide destructiveHint: true, and the description goes further by detailing side effects: apply is DESTRUCTIVE and permanently bakes the mask with outside pixels lost; gradient replaces existing mask content and clears any active selection first; delete preserves layer pixels. This adds behavioral context beyond the annotation and is consistent with 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 dense but well-organized, starting with a summary line and then breaking out each `op` with relevant details and a strong closing note about avoiding manual AM scripts. Every sentence serves a purpose, and the structure aids quick comprehension without unnecessary 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 (4 operations, 5 parameters), the description is remarkably complete. It covers all operations, side effects, prerequisites (selection needed for create), the relationship to preview verification, and best-practice guidance. The presence of an output schema means return values don't need explanation, so nothing 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?

Even though schema coverage is 100%, the description adds meaningful context beyond field names and types. It explains the semantics of `op` operations (e.g., 'create' reveals selection, adjustment layers load selection into built-in mask), and for gradient it clarifies that the tool auto-creates the mask, replaces existing content, and clears the active selection—details not fully captured in schema 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 clearly states the tool's purpose: managing the active layer's mask via the `op` parameter, with specific sub-operations (create, delete, apply, gradient). It distinguishes itself from sibling tools by focusing on masks and explicitly cross-references ps_get_preview and execute_script, making its role 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?

Provides rich usage guidance: when to use each op (e.g., gradient for reflections, sky blends, edge falloff), preference for non-destructive masks unless flattening for export, and an explicit warning not to write `Mk Chnl At=Msk` or `Grdn` scripts in execute_script because the tool already handles them. This clearly frames when to use the tool and when not to.

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

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

Annotations already declare readOnlyHint and idempotentHint. The description adds 'cheap' (lightweight/efficient) and 'live' (shows current state of exposed tools), which are useful behavioral traits beyond the annotations. No contradiction or hidden 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?

Three sentences, each earning its place: first defines the tool's output and format, second gives usage context, third differentiates from two similar tools. It is front-loaded with the core purpose and avoids any filler or repetition.

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

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

For a simple, zero-parameter listing tool, the description fully covers what it does, how to use it, and how it differs from related tools. The existence of an output schema means return-value details don't need to be in the description.

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 and the schema has full coverage, so there is nothing to explain. The baseline for 0 params is 4, and the description doesn't need to compensate for any missing parameter information.

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