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

Annotations already indicate this is a mutating, non-idempotent, non-destructive operation. The description adds that the folder is empty and acts as a group, but does not disclose side effects, conflict behavior (e.g., above+below), or whether duplicate names are allowed. Since annotations carry the safety profile, a mid score is appropriate.

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 sentence with the action and object front-loaded. There is no filler or redundant repetition of the tool name, so every word 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 5-parameter creation tool with no output schema, the description is minimal. It does not explain return values, placement behavior when optional parameters are omitted, or conflict handling. However, the schema covers most parameters and annotations cover safety, so it is not wholly inadequate.

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 80%, so the schema documents path, above, below, and parent. The description adds no parameter-specific meaning, and 'name' lacks a schema description, but the high coverage keeps this at the baseline of 3.

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

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

The description uses a specific verb ('Creates') and resource ('empty layer folder (group)'), making the tool's function clear. It does not explicitly differentiate from sibling add_image_layer, but 'folder (group)' versus image layer is implicit, so it stops short of a full 5.

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

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

No guidance is provided on when to use this tool versus alternatives like add_image_layer, move_layer, or set_layer. There are no exclusions, prerequisites, or context clues beyond the name itself, leaving the agent to infer usage.

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

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

The sentence 'The pixels are stored as-is; the placement only sets the layer's transform' adds meaningful behavioral context beyond the annotations: placement does not modify pixel data. The annotations are all consistent with the described mutation, so there is no contradiction.

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

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

Two concise sentences, front-loaded with the core action and supported formats. There is no wasted wording or redundant restatement of schema fields.

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

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

For a tool with 11 parameters and no output schema, the description plus schema cover required inputs and the key behavioral guarantee about pixel preservation. It does not describe the success return value, but no output schema is provided and the operation type makes the result reasonably predictable.

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 82%, so the schema already documents most parameters. The description adds useful context about placement not altering pixel data, but it does not clarify the few schema-underspecified parameters such as opacity or blendMode. A 3 is appropriate since the schema carries most of the load.

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

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

The description names a specific operation: importing an image file as a new pixel layer, and lists supported formats. The word 'new' and 'pixel layer' clearly distinguish this from sibling tools like replace_layer_image and set_layer_mask.

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

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

The description clearly implies when to use the tool: when an image file should be added as a new layer. It does not explicitly name alternatives or state when not to use it, but the 'new pixel layer' wording gives enough context for an agent to select it over replace_layer_image.

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 mark this as destructive, and the description adds specific destructive context: 'Overwrites the manifest of an existing package at that path.' This is useful beyond the boolean hint. It also discloses the optional background behavior, though it does not detail other side effects such as file preservation or return values.

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, front-loaded sentences cover the core action, an optional behavior, and the destructive edge case. Every sentence adds distinct information with no filler.

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

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

The description is largely complete for an agent to understand what action will be performed Duff, especially with annotations and schema fields covering constraints. The main gaps are lack of explicit return-value information and no mention of what happens to other existing files besides the manifest, but these are minor given the schema and annotations.

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

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

Schema description coverage is 60%, and the description only substantively adds meaning for the background parameter by calling it a 'solid background layer.' Width and height have no description in the schema or the tool description, leaving their units and exact purpose implied rather than explicit.

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

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

The description uses a specific verb and resource: 'Creates a new empty .comp project.' It also clarifies optional behavior (adding a background layer) and the overwrite behavior, which distinguishes it from sibling tools like replace_layer_image or export_flattened.

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 clearly implies the tool is for creating a new project or resetting/initializing one at a path. However, it does not explicitly state when to use this tool versus alternatives, nor does it provide any '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 already provide the key safety profile: not read-only, not destructive, idempotent. The description adds useful context by specifying 'full resolution' and 'whole project,' which implies a potentially expensive operation, but it does not disclose file overwrite behavior, output side effects, or performance considerations. 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?

One tight sentence that front-loads the core purpose with no filler. Every word adds meaning: renders, whole project, full resolution, PNG/JPEG.

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

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

For a straightforward export tool, the description plus fully documented schema and annotations are largely sufficient to select and invoke it correctly. Minor omissions are around usage differentiation and return/output behavior, but the file destination and format semantics are already present in the schema.

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

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

Schema description coverage is 100%, with path, quality, and outputPath all documented clearly. The description does not add parameter-level detail, but the schema already carries the semantic weight, so the baseline score of 3 is appropriate.

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

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

The description names a specific operation: rendering the whole project at full resolution to a PNG or JPEG file. It clearly identifies the resource scope ('whole project') and distinguishes itself from sibling tools like export_layer or render_preview by meaning, even though those alternatives are not named.

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

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

No guidance is given about when to use this tool versus siblings such as export_layer or render_preview. An agent can infer it is for whole-project exports, but the description does not state any exclusions or alternatives, which is a notable gap given the closely related sibling tools.

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

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

Annotations already establish idempotence and non-destructiveness; the description adds meaningful behavior by specifying that transforms are not applied and resolution is original, and that either the image or mask may be copied. It does not contradict the annotations, and the file output aligns with readOnlyHint=false.

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

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

A single sentence that front-loads the verb and resource and packs in the two most decision-relevant qualifiers ('untransformed, original resolution' and 'mask'). 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 is simple, has idempotent/non-destructive annotations, and the description covers the core selection of what gets exported. The absence of output schema and sparse outputPath description are minor gaps because the purpose is a straightforward file export, but they keep this from being fully complete.

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

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

Schema coverage is 50%, and the description adds some meaning by tying 'what' values to source PNG versus mask and by making clear the layer must be a pixel layer. However, outputPath and path semantics are not expanded beyond the sparse schema, so the description only partially compensates for the coverage gap.

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 ('Copies') and resource ('a pixel layer's source PNG ... or its mask') and clarifies the output is written 'to a file'. The qualifier 'untransformed, original resolution' distinguishes it from flattened or rendered exports without ambiguity.

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

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

The description makes clear this tool is for raw source pixels or masks at original resolution, which tells an agent when it is appropriate. It does not explicitly name alternatives like export_flattened or state when not to use it, so it stops short of full routing guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds no additional behavioral traits (e.g., performance, error handling, side effects) beyond stating that it 'reads' the project, which is consistent with the annotations. It does not contradict them, but also provides little extra transparency.

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

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

The description is a single, well-structured sentence that front-loads the core action and immediately enumerates the returned data. It contains no redundant words or filler, making it both concise and information-dense.

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 lists the key data categories returned (canvas info, layer stacking order, folder depth, visibility, opacity, blend mode, transform), which is substantial given that no output schema exists. It does not specify the exact return format or error conditions, but for a read-only tool with a single parameter, this covers most practical needs. A 4 is appropriate because it could be slightly more explicit about the structure of the response.

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 'path' parameter, which already explains it should be a path to a .comp project directory. The description reiterates that it reads a .comp project but adds no new meaning beyond the schema. Since coverage is high, this is an appropriate baseline of 3.

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

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

The description clearly states the tool reads a .comp project and returns specific details (canvas info, layers in stacking order with folder depth, visibility, opacity, blend mode, transform). It is specific in verb and resource, and the level of detail distinguishes it from siblings like list_layers, which likely only lists names or basic info.

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

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

The description implies this is for detailed inspection due to the comprehensive return list, but it does not explicitly compare to alternatives such as list_layers, nor mention when to prefer one over the other. There is no explicit 'use this when' or 'instead of' guidance, only an implied use case.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds useful behavioral details beyond that: it returns a compact subset of fields, and it orders layers from top to bottom, which clarifies what an agent can expect from the output.

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

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

The description is a single focused sentence that conveys the resource, returned fields, ordering, and visual reference without any 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?

With one fully documented required parameter, annotations covering the safety profile, and a description that explicitly states the output fields and ordering, the tool is fully specified for an agent to invoke correctly. No output schema exists, but the description compensates by describing the return shape.

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 describes the only parameter (path) fully, with 100% schema description coverage, so the baseline applies. The description does not add extra parameter semantics beyond what the schema already conveys.

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 ('List') with a clear resource ('layers') and enumerates the exact fields (id, name, kind, visibility), making the tool's purpose unmistakable. It also distinguishes itself from sibling mutation tools like set_layer or remove_layer by framing this as a read-only enumeration operation.

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

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

The description provides clear context: it returns a compact, top-to-bottom layer list in the same order as the Compositor's Layers panel. It does not explicitly name alternatives or exclusion conditions, but the intended use case—reading the current layer stack—is strongly implied and easy for an agent to act on.

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 this is a non-read-only, idempotent, non-destructive mutating operation. The description adds useful context beyond those flags: moving a folder carries its subtree, and the possible destinations are top/bottom or relative to another layer. It does not contradict the annotations.

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

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

The description is a single, well-structured sentence that front-loads the core action and then compresses the three placement modes into a clear list. No filler or repetition of schema content.

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

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

For a mutating reorder operation, the description covers the core behavior and the three placement modes without requiring the agent to open the schema. It does not mention return values or error cases, but with no output schema and high schema coverage this is a minor gap for a tool whose effects are visible in the layer stack.

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

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

Schema description coverage is 100%, so the schema already documents the meaning of path, layer, to, above, below, and parent. The description reinforces the role of to/above/below as alternate positioning modes but adds little beyond the structured field 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 uses a specific action verb ('reorders') with a clear resource ('a layer') and specifies the scope ('with its subtree if it is a folder'). It also enumerates the distinct reordering modes (top/bottom of folder/root, or above/below another layer), which differentiates it from sibling tools like set_layer or remove_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 description clearly implies when to use this tool: whenever a layer's stacking order needs to change. However, it does not explicitly name alternatives or state when not to use it, such as using set_layer for property changes or remove_layer for deletion, leaving exclusion logic to the agent.

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

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

Annotations already cover readOnly, idempotent, and non-destructive. The description adds the behavioral detail that 'Compositor reads the package from disk on open', which explains why changes are reflected. This goes beyond annotations and helps the agent understand the open behavior. No contradiction.

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

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

Two concise sentences with no fluff. The primary action is front-loaded, and the additional sentence about reading from disk is relevant and brief. 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?

For a simple tool with one parameter and no output schema, the description is sufficient. It explains the action, purpose, and a key behavioral nuance. It does not mention any prerequisites like Compositor being installed, but that is likely assumed. Overall, nothing critical is missing.

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

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

Schema coverage is 100%, so the path parameter is fully described in the schema. The description does not add additional meaning about the parameter, such as format or constraints, beyond what the schema already provides. Baseline of 3 is appropriate.

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

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

The description clearly states the action ('Opens (or reloads) the project in the Compositor app') and the resource (project, .comp package). It distinguishes itself from siblings like render_preview and inspect_project by specifying the Compositor app as the target. The verb and resource are specific and not a tautology.

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 clear context for when to use it: to see the result in the Compositor app. However, it does not explicitly mention alternatives or when not to use it, such as preferring render_preview for a quick preview. This is a minor gap, but the purpose is clear enough.

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?

While annotations already indicate destructive and idempotent behavior, the description adds crucial specifics: recursive deletion for folders and removal of image/mask files. This goes beyond the annotations and sets clear expectations.

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

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

A single, information-dense sentence front-loads the main action and then specifies the extent of deletion. No filler words.

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 core behavior and destructive scope. It does not mention error handling or return values, but given the simple delete operation and no output schema, this is acceptable.

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

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

Schema coverage is 100% with both parameters well-described. The description does not add new parameter details, which is acceptable given the high schema coverage, 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 clearly states the action (deletes a layer), the resource (layer), and additional detail (folder recursion, image and mask files). It distinguishes from siblings like move_layer and set_layer by focusing on deletion.

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 purpose is obvious: use when you want to remove a layer. It does not explicitly mention alternatives or exclusions, but the unique 'delete' action among siblings makes the context clear.

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

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

The description adds substantial behavioral context beyond the annotations: it flattens the project, optionally writes a file, excludes clipping masks/adjustment layers/layer effects, and reports what was skipped. This is rich, useful disclosure and does not contradict 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?

Three concise sentences deliver purpose, option, and limitations without redundancy. The key behavior 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?

For a simple 3-parameter tool with full schema coverage, the description adequately covers purpose, behavior, limitations, and response content. The only notable gap is lack of explicit guidance on choosing this over export_flattened, which is a minor omission.

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

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

Schema description coverage is 100%, so the schema already documents all parameters. The description adds minimal parameter-specific meaning beyond noting the optional file save, which aligns with outputPath. This matches the baseline of 3 for full 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 states a specific verb and resource ('Flattens the project') and the output (a PNG preview image). It is clear and understandable, though it does not explicitly differentiate itself from the sibling export_flattened, relying instead on the 'preview' framing to imply distinction.

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 phrase 'so the model can see the composition' implies the use case, but the description does not explicitly state when to use this tool versus alternatives like export_flattened or open_in_compositor, nor does it mention exclusions.

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

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

Annotations already flag the operation as destructive and idempotent; the description adds what is destroyed (source pixels) and what survives (transform, mask, properties). This behavioral precision goes beyond the annotation 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?

Two sentences: the first states the core operation and invariants, the second gives the intended workflow. Every sentence contributes and there is no redundant filler.

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

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

The description covers purpose, scope (pixel layer), preservation semantics, and a motivating use case, with the schema covering required parameters. A small gap is the lack of any statement about what the call returns or side effects for unsupported layer types.

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 75% because imagePath has no description, and the description only refers to it as 'another image file.' It adds some meaning but does not fill the gap with formats, path semantics, or other constraints.

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 ('Swaps'), identifies the exact resource ('source pixels of a pixel layer'), and specifies what is preserved ('transform, mask and properties'). This clearly separates it from layer-structure siblings such as set_layer_mask and add_image_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?

It gives an explicit trigger ('Use it to round-trip a layer through an external editor or a generated image'), which tells an agent when to select this tool. It does not, however, state exclusions or name alternative tools.

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

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

Annotations only declare mutating, idempotent, non-destructive behavior. The description adds the key behavioral detail that layers are not resampled and are offset according to the anchor, which is exactly the non-obvious side effect an agent needs. It does not over-elaborate.

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 tight sentences lead with the main effect and then the key layer-preservation caveat. No filler or repetition of the title.

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 four-parameter mutation with no output schema, the description covers the core outcome and anchor behavior. It could add unit clarity or mention what happens to layers outside the new bounds, but with annotations covering safety/idempotency this is fairly 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 only 25%, so the description must compensate. It does clarify the anchor parameter's role in offsetting layers, but width and height units/semantics and path are not elaborated beyond the schema, leaving a gap.

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 ('Changes the document size') and clarifies the exact behavior ('without resampling layers'), which distinguishes it from the layer-manipulation and export siblings. There is no tautology or vagueness.

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

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

The description implies the use case: resizing the canvas while preserving layer pixels. It does not explicitly state when to prefer this tool over alternatives or when not to use it, though no sibling directly competes with this operation.

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

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

The annotations already provide readOnly=false, destructive=false, and idempotent=true; the description adds a valuable behavioral guarantee beyond those flags: only the supplied fields are modified, so unspecified properties are not reset. This is especially useful for a 14-parameter mutation tool. There is no contradiction with 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?

Two sentences with no filler, front-loaded with the action and target resource. The property list is compact but informative, and the crucial 'only given fields change' clause is placed clearly at the end.

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 14-parameter setter with no output schema, the description covers the core function and patch semantics, and the annotations address safety and idempotence. But it omits some parameters (active, sampling), does not describe return behavior, and leaves failure semantics to inference. The description is adequate but not complete enough for a complex setter.

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 only 43%, so the description needed to compensate for the many parameters lacking schema-level explanations. Instead, it largely restates parameter names in categories without clarifying semantics for terms like sampling, active, or the exact flip behavior. The partial-update statement is the only real added semantic value.

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

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

The description names a specific verb and resource ('Changes... of a layer') and enumerates the property families it covers: name, visibility, opacity, blend mode, mask enablement, and transform. This scope implicitly distinguishes it from siblings like set_layer_mask, replace_layer_image, and move_layer. The sentence 'Only the given fields change' adds precision about the mutation semantics.

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 property enumeration implies when to use the tool: when you need to modify any of these layer attributes in a targeted way. However, it does not explicitly route around siblings such as set_layer_mask, move_layer, or replace_layer_image, nor does it state when not to use it. The usage context is inferred rather than stated.

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

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

Annotations already provide readOnlyHint=false, destructiveHint=true, and idempotentHint=true. The description adds value beyond them by disclosing the luminance-to-coverage mapping ('white reveals, black hides') and the sizing behavior ('stretched over the layer's own rectangle'). 'Removes the existing mask' aligns with destructiveHint, and nothing contradicts 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?

Two sentences with no filler. The first sentence front-loads the core action and both operation modes (attach/remove) plus the key luminance rule; the second adds the stretch detail. 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 moderate-complexity tool (4 params, no output schema) with safety already covered by annotations, the description covers purpose, mask behavior, and sizing. Minor gaps remain: it does not state whether attaching a new mask replaces an existing one, nor how invert interacts with the white/black luminance rule.

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

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

Schema coverage is 75% (path, layer, and maskPath documented; invert undocumented). The description's white/black luminance rule adds meaning beyond the schema's maskPath description ('luminance becomes coverage') and partially compensates for the undocumented invert parameter, but it never explicitly explains invert or how replacing an existing mask behaves.

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: it 'attaches a raster mask from a grayscale image' or 'removes the existing mask.' The white/black luminance rule clarifies the mask semantics, and no sibling tool (replace_layer_image, set_layer, add_image_layer) handles masks, so it is clearly differentiated.

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

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

Usage is implied: use this tool when attaching or removing a mask on a layer. However, it never names alternatives, exclusions, or prerequisites (e.g., what to use instead for editing layer content), despite 13 siblings being present. The unique purpose keeps ambiguity low, but no explicit routing guidance is given.

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