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

With no annotations, the description carries the full burden. It does disclose the return shape ({layer_name, layer_id, text_width, text_height, position}), which is genuinely useful since there is no output schema. But it says nothing about mutation side effects: whether the new layer becomes active, whether it is undoable, or what happens if image_index is out of range.

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

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

Front-loaded one-line purpose followed by a clean parameter list and a return line. The parameter restatement is somewhat duplicative of the schema but is justified given 0% schema coverage. No filler or marketing language.

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

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

For a medium-complexity creation tool with no annotations and no output schema, the description covers purpose, all parameters, defaults, and return values. The main gap is the absence of any behavioral context about the mutation (target image resolution, layer stacking, undo), which an agent modifying a document would want.

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 0%, so the description must compensate, and it does. Every one of the seven parameters is explained with meaning beyond the schema: coordinate origin for x/y, accepted font families, pixel units for size, and accepted color formats (CSS name, hex, rgb()). Defaults are restated consistently with 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 opens with a specific verb and resource: 'Add a text layer to an image.' That is unambiguous and distinguishable from most siblings. It does not, however, differentiate itself from close alternatives such as edit_text or create_layer, which the agent would need to choose between.

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

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

There is no guidance on when to use this versus edit_text (modifying existing text) or create_layer. The reader must infer that this tool is for new text and edit_text is for existing text. No prerequisites (e.g. an open image) or exclusions are 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?

With no annotations, the description carries the full behavioral burden. It states the parameters and that a status dict is returned, but it does not disclose whether the adjustment is applied in place, whether it is destructive, whether undo is required, or how errors are handled when the layer is missing.

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 purpose and then presents parameters in a compact, readable list. Every sentence is useful and there is no unnecessary wording.

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

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

For a four-parameter mutation tool with no annotations and no output schema, the description is adequate for invocation because it documents all parameters. It is incomplete for safe and correct tool selection because it omits side-effect behavior, undo expectations, and sibling differentiation.

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 0%, so the description must compensate, and it does: it documents all four parameters with ranges and defaults, including brightness and contrast from -127 to +127 and layer_name defaulting to the active layer. This adds meaningful invocation detail beyond the bare 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: adjust brightness and contrast of a layer. It clearly identifies the target as a layer, but it does not distinguish this operation from sibling adjustments such as auto_levels, adjust_curves, adjust_hue_saturation, or adjust_color_balance.

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

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

No when-to-use or when-not-to-use guidance is provided. The description does not mention alternatives like auto_levels or adjust_curves, nor does it explain when a caller should choose this tool over other tonal adjustment tools.

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

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

No annotations are supplied, so the description carries the full behavioral burden. It does add one useful fact ('Returns status dict') and notes that layer_name defaults to the active layer, but it never says whether the edit is destructive or undoable, what happens when the named layer or image index does not exist, or what keys the returned status dict contains.

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

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

The purpose sentence is front-loaded and the parameter block is scannable, with no filler prose. It does repeat defaults and value types that also appear in the schema, but that repetition is justified at 0% schema description coverage.

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 six-parameter mutation tool with no annotations and no output schema, the description is adequate on inputs but thin on outcomes: 'Returns status dict' does not tell the agent what success or failure looks like, and nothing addresses permission, error, or undo behavior. It is minimum viable rather than 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 0%, so the description must supply all parameter meaning, and it does: it documents the three color axes with their -100 to +100 range and channel polarity, the three accepted 'range' values with their default, the image_index default, and the layer_name default-to-active-layer behavior. The only gap is that it does not clarify the interaction between image_index and layer_name or the allowed bounds of image_index.

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

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

States a specific verb and resource ('Adjust color balance ... of a layer') and names the tonal ranges it operates on, which tells an agent this is a tonal correction tool. It does not explicitly distinguish itself from sibling tonal tools like adjust_curves, adjust_brightness_contrast, or adjust_hue_saturation, so the agent must infer the difference.

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 never says when to reach for color balance versus the many sibling adjustment tools, nor does it state prerequisites such as an open image or an existing layer. Usage is only implied by the purpose sentence.

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

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

No annotations are supplied, so the description carries the full burden for a mutation tool. It discloses defaults and "Returns status dict." but says nothing about undoability, what happens if layer_name does not exist, whether the adjustment is destructive, or how errors surface.

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

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

The purpose statement is front-loaded and the parameters are a tight, scannable bullet list with no filler. The only waste is restating schema defaults (default 0, default s_curve), which the schema already carries.

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 five-parameter, no-annotation, no-output-schema mutation tool, the parameter coverage is genuinely good and the return is at least named. Missing are the behavioral facts an agent needs to call it safely: failure modes for a bad layer_name or image_index, and whether the operation is undoable.

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 0% and the schema declares no enums, yet the description supplies the effective enum values for preset (s_curve/lighten/darken/contrast) and channel (value/red/green/blue/alpha) plus the [[input, output], ...] shape and preset-override relationship for points. It stops short of documenting value ranges or whether the preset list is 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?

"Adjust tonal curves for a layer" states a specific verb and resource, and the mention of curves distinguishes it from sibling tonal tools like adjust_brightness_contrast and auto_levels. It does not name or exclude any sibling explicitly, so it stops short of a 5.

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

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

The description never says when to reach for curves instead of auto_levels, adjust_brightness_contrast, adjust_color_balance, or levels-style siblings. There are no prerequisites or exclusions, only a bare statement of what it does, leaving tool selection to inference.

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

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

With no annotations, the description carries the full burden and does not disclose whether the adjustment is applied destructively in place, whether it is affected by the current selection, or what happens when the named layer or image index is invalid. Only 'Returns status dict' hints at output, and the default-to-active-layer behavior is the one genuinely useful behavioral detail.

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

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

Front-loads the purpose in one sentence and then uses a compact parameter list that is justified by the 0% schema coverage. No filler, though the trailing 'Returns status dict' is thin enough to be almost noise.

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 six-parameter mutation tool with no annotations and no output schema, the definition covers parameter meaning well but omits error behavior, selection interaction, and any indication of whether edits are undoable. It is adequate to invoke the tool but not to predict its effects.

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

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

Schema description coverage is 0%, so the description must compensate, which it largely does: it lists numeric ranges (-180 to +180 for hue, -100 to +100 for saturation and lightness), defaults for all six parameters, and the full enum of color_range values that the schema leaves as a bare string. Units and interaction between hue/saturation/lightness are still unstated.

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

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

States a specific verb and resource: adjusting hue, saturation, and lightness of a layer. This is clearly distinguishable from siblings like adjust_brightness_contrast, adjust_color_balance, and desaturate, though the description never names those alternatives explicitly.

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

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

Provides no when-to-use or when-not-to-use guidance, and no routing to alternatives such as desaturate or adjust_color_balance for overlapping color work. It also omits prerequisites (an open image, an existing target layer), leaving the agent to infer context.

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

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

With no annotations supplied, the description carries the full behavioral burden and mostly does not meet it: it does not say whether the effect is applied destructively to layer pixels, whether it can be undone, what happens when layer_name matches nothing, or in what format color should be given. 'Returns status dict' is the only behavioral disclosure, and it is too vague to tell the agent what success/failure looks like.

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 front-loaded purpose sentence followed by a tight bulleted parameter list and a one-line return note; there is no filler. The defaults repeat the schema slightly, but that is the intended value-add given 0% schema description coverage.

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 seven-parameter mutation tool with no annotations and no output schema, the parameter documentation is solid but the effect's side effects, reversibility, and error conditions are absent. The return note is present but too thin to substitute for a missing output schema.

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

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

Schema description coverage is 0%, so the description must compensate, and it largely does: it gives units (offset in pixels), valid range (opacity 0-100), default values, and the meaningful semantic that layer_name falls back to the active layer and image_index targets a specific image. It leaves color's accepted format (name vs hex vs CSS) unstated, which is the one real 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?

States a specific verb and resource ('Apply a drop shadow effect to a layer'), which is instantly distinguishable from sibling effects such as apply_gaussian_blur, apply_vignette, and apply_emboss. It stops short of noting how it differs from the generic gegl_apply_filter route, but the core purpose is unambiguous.

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

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

Usage is only implied by the target parameters ('layer_name: Target layer; defaults to active layer'). There is no statement of when to prefer this over gegl_apply_filter or apply_vignette-style siblings, and no prerequisites such as needing an open image, an existing layer, or a running server.

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

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

With no annotations, the description must carry the behavioral load; it does disclose the mutation target (a layer) and the return shape ('Returns status dict'), plus the default-to-active-layer behavior. It does not say whether the effect is destructive or undoable, what happens if layer_name is not found, or whether an image must be open first.

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

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

Front-loaded one-line purpose followed by a compact bullet list of parameters and a one-line return note; nothing is padded. The bullets are slightly redundant with schema titles but earn their place by adding ranges and defaults.

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 five-parameter mutation tool with no annotations and no output schema, the definition covers parameters and return type adequately. It is missing safety and state context an agent would want: destructiveness/undo, required active image, and failure behavior for an unknown layer name.

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 0%, so the description carries the full burden and largely succeeds: it gives valid ranges for azimuth (0-360 degrees, default 315 = top-left) and elevation (0-90, default 45), explains depth as intensity, and clarifies that layer_name defaults to the active layer. Only depth units and image_index semantics remain thin.

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

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

States a specific verb and resource ('Apply an emboss (bas-relief) effect to a layer') and disambiguates the effect type from the many sibling filters such as apply_noise, apply_drop_shadow, and apply_gaussian_blur. An agent can tell exactly which effect this produces and what it targets without opening the schema.

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

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

There is no guidance on when to choose this over alternatives like gegl_apply_filter or the other apply_* filters, and no prerequisites or exclusions are stated. Usage is only implied by the effect name.

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

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

With no annotations supplied, the description carries the full burden, and it does disclose the most important trait — the operation is destructive. It stops short of stating whether the change is undoable, whether it applies only to the active layer's pixels, or what the status dict contains on failure, leaving real risk information unstated.

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

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

The purpose sentence is front-loaded and the parameters follow as a compact bulleted list, so the reader gets the operation before the details. Nothing is padded, though the closing 'Returns status dict' line is thin and could carry slightly more substance.

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 three-parameter mutation tool with no annotations and no output schema, the description covers the operation, all parameters, and the return shape. It is still missing the routing guidance against same-family blur tools and any reversibility or failure-mode information an agent would want before mutating an image.

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 0%, so the description must compensate, and it does: all three parameters are named with meaning and defaults, including the units for radius (pixels) and the fallback for layer_name (active layer). It omits a valid range or practical bounds for radius and the expected format of layer_name.

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

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

States a specific verb and resource ('Apply Gaussian blur') plus a key modifier ('destructive filter operation'), so the agent knows exactly what happens to pixels. It does not distinguish itself from the sibling tool 'blur' or the generic 'gegl_apply_filter', which an agent must disambiguate on its own.

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

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

There is no guidance on when to prefer this over the sibling 'blur', 'gegl_apply_filter', or 'gegl_filter_action', nor any prerequisite such as an image needing to be open or a layer selected. Usage is only implied by the parameter list.

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

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

No annotations are supplied, so the description carries the full behavioral burden, yet it only says "Returns status dict." It does not say the layer is modified destructively in place, whether the operation is undoable, whether a prior selection is respected, or what happens if layer_name does not resolve — all material for a mutation tool with zero annotation coverage.

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

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

The effect sentence is front-loaded and the parameter list is easy to scan. The default values restated in the parameter list duplicate the schema, which is mild redundancy rather than confusion.

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?

Parameters are fully covered, but for a destructive image-editing mutation with no annotations and no output schema, the definition should still disclose undo/edit-state implications and failure behavior. What is present is adequate; what is absent is the risky part.

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 0%, and the description compensates well: it documents all three parameters, including the 0.0–1.0 range for amount and the active-layer fallback for layer_name. It loses a point because it does not explain how layer_name is matched (exact name vs. index vs. partial) or what an out-of-range amount does.

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?

"Add noise/grain to a layer" states a specific verb and resource plus the visual effect, which is enough to separate it from siblings like blur, denoise, or sharpen. It stops short of naming any sibling or clarifying the boundary with the other stylize filters (e.g. apply_pixelate, apply_emboss).

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 never says when to reach for this tool versus apply_gaussian_blur, apply_pixelate, or the generic gegl_apply_filter. The only guidance is a metaparameter default ("defaults to active layer"), which is about targeting, not about tool selection.

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

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

With no annotations supplied, the description must carry the full behavioral burden; it does disclose that the operation targets a layer and returns a status dict, and that layer/image default to the active layer and index 0. However, it never states whether the pixelation is applied destructively in place, whether it affects the whole layer or only the selection, or whether it is undoable — key facts for an image mutation.

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

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

The purpose sentence is front-loaded and the parameter list is easy to scan, with no filler prose. The default values in the list duplicate the schema defaults, which is minor but 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 three-parameter, no-required-args mutation tool with no annotations and no output schema, the definition covers parameters and return type adequately but omits side-effect, scope (selection vs full layer), and undoability information. An agent could call it correctly but not predict its impact.

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 0%, so the description must compensate, and it does: all three parameters are explained with units ('block_size in pixels'), default values, and the layer_name fallback to the active layer. That is meaningful added meaning beyond the bare schema, though the interaction between layer_name and image_index is not spelled out.

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 ('Pixelate a layer') plus the effect mechanism ('mosaic/block effect'), which is unambiguous. It does not distinguish itself from neighboring filter tools such as apply_noise, apply_emboss, or blur, so differentiation among siblings is left to the reader.

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

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

There is no guidance on when to choose this tool over alternatives like blur, apply_noise, or gegl_apply_filter, and no preconditions are stated. The only usage hint is implicit in the parameter defaults (active layer, image 0).

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

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

No annotations are supplied, so the description carries the full burden. It conveys that the operation is a mutation of layer pixels, but does not say whether the effect is destructive or reversible, whether it creates a new layer or edits in place, whether an alpha channel or selection matters, or what 'Returns status dict' actually contains. The mention of the return type is the only extra behavioral hint.

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 effect statement is front-loaded, followed by a compact bulleted parameter list and a one-line return note. No filler sentences, though the bullet block is somewhat list-like rather than integrated prose.

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

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

For a four-parameter, zero-required mutation tool with no output schema, the description covers every argument and states the return shape. The remaining gap is the lack of disclosure about destructive-ness and layer/target selection behavior, which matters for an image-editing mutation.

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 0% — properties have only titles and defaults — but the description compensates by documenting all four parameters with meaning and defaults, including the non-obvious shape semantics (1.0 = elliptical, >1 = more rectangular) and softness as fade width. This is genuinely additive over the raw 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 first sentence states a specific verb and resource — 'Apply a vignette darkening effect around the edges of a layer' — which is unambiguous and clearly distinct from sibling effects such as apply_noise, apply_emboss, or apply_drop_shadow. It does not explicitly name alternatives, but the effect name alone is specific enough for an agent to identify it.

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

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

There is no guidance on when to use this tool versus other edge or filter effects (e.g. apply_gaussian_blur, gefl_apply_filter), and no stated prerequisites such as whether a layer must exist or be selected. Usage is only implied by the notion of targeting 'the active layer' by default.

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

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

No annotations are provided, so the description carries the full behavioral burden. It says the tool adjusts a layer and returns a status dict, but it does not disclose whether the change is destructive or undoable, how the active layer default interacts with the target image, or what conditions cause errors.

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 short and front-loaded with the operation, followed by a compact parameter list and return note. Every sentence conveys useful information and there is no redundant wording.

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

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

For a two-parameter image adjustment tool, the description covers the operation, parameters, defaults, and return type. However, with no annotations and no output schema, it leaves out mutation safety, undo behavior, and the contents of the status dict, so it is only minimally complete.

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

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

Schema description coverage is 0%, so the description must compensate. It documents both parameters with useful meaning beyond the schema titles: image_index identifies the target image and defaults to 0, while layer_name identifies the layer to adjust and defaults to the active layer.

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: automatically stretch the tonal range of an image, with the synonyms auto levels and auto stretch contrast. This is clear, but it does not explicitly distinguish the tool from nearby siblings such as adjust_curves or adjust_brightness_contrast.

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

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

The description states what the operation does but gives no when-to-use guidance. It does not mention alternatives like adjust_curves or adjust_brightness_contrast, nor does it say when auto levels is preferable or inappropriate.

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

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

No annotations are supplied, so the description carries the full burden. It does disclose the return payload (exported, count, errors) and partial-failure reporting, which is genuinely useful given there is no output schema. It omits whether existing files are overwritten, whether the extension is appended automatically, and whether unsaved edits are included.

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

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

Front-loaded with a one-line purpose, then two scannable blocks for parameters and returns; no filler sentences. The labeled list is slightly mechanical, but every entry carries information the schema lacks.

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 export tool with no annotations and no output schema, the description covers scope, all inputs, and the return shape, which is close to sufficient. The remaining gap is file-collision/overwrite behavior and whether writes require a writable directory or elevated permissions.

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?

With 0% schema description coverage, the description fully compensates: every one of the 5 parameters gets meaning beyond its bare title, including the allowed format values, quality defaults and its JPEG/WEBP-only scope, and the {name}/{index} placeholders in name_pattern. The image_index note about omitting it to export all is a semantic rule the schema cannot express.

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

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

States a specific verb and resource ('Export all open images ... to a directory') plus the scope toggle (all vs. a single image), so the agent can tell this is a bulk operation. It does not name the obvious single-image sibling (export_image), so differentiation is inferred rather than stated.

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 through the image_index semantics ('omit to export all open images'), which tells the agent how to switch between batch and single export. However, it never names export_image as the alternative for one-off exports, nor does it state prerequisites such as having images open or an existing/writable output_dir.

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

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

With no annotations, the description carries the full burden; it does disclose the return payload and how conflicting parameters resolve, which is real value. It omits mutation semantics that matter here: whether images are resized in place versus copied, whether the operation is undoable, and what happens when no images are open or no sizing parameter is supplied.

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

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

Front-loaded purpose sentence, then a compact bulleted parameter block, then a returns line — no filler. The Returns line earns its place because there is no output schema.

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 four undocumented parameters, no annotations, and no output schema, the description covers the essential contract: sizing options, precedence, default, and response shape. It falls short only on the zero-parameter case and on in-place/undo behavior for a destructive bulk 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 0%, so the description must do all the work, and it largely does: width/height units in pixels, scale_factor as a proportional multiplier with an example, its override precedence, and the meaning of maintain_aspect. The gap is that all four parameters are optional and the description never states the behavior when none are provided.

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

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

The first sentence gives a specific verb and resource ('Resize') with an explicit scope ('all open images'), which separates it from the single-image siblings like scale_image and scale_to_fit. It stops short of a 5 because no sibling is named, so the agent must infer that scale_image is the per-image counterpart.

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 communicates precedence rules inside the invocation ('scale_factor ... overrides width/height if set') and the aspect-ratio default, which is genuine usage guidance for choosing among parameters. However, it never says when to prefer this tool over scale_image, scale_to_fit, or batch_export, and gives no prerequisites such as needing images open.

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

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

No annotations exist, so the description carries the full behavioral burden, yet it only notes "Returns status dict." It does not say whether the blur is applied destructively to layer pixels, whether it is undoable, whether it respects selections, or what permissions/state the image must be in.

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

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

Front-loaded one-line purpose followed by a compact parameter list; every line earns its place. The quoted multi-line formatting is slightly verbose but not wasteful.

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

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

For a 4-parameter mutation tool with no annotations and no output schema, the parameter coverage is good but behavioral coverage is thin — nothing about side effects, layer targeting when multiple images are open, or return dict contents beyond "status dict." Adequate as a minimum-viable definition, not 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 0%, so the description must compensate, and it does: it documents all four parameters including units (pixels), defaults (5.0, 5.0, 0), and the non-obvious semantics that `layer_name` defaults to the active layer. Minor gap: no guidance on valid ranges or whether non-integer radii are accepted.

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?

"Apply Gaussian blur to a layer" gives a specific verb and resource, so the core action is unambiguous. However, the sibling list contains `apply_gaussian_blur` (and `gegl_apply_filter`), and the description makes no attempt to say how this tool differs from those, leaving a real selection ambiguity.

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

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

There is no when-to-use or when-not-to-use guidance, and no mention of the near-duplicate sibling `apply_gaussian_blur`. The agent must infer from the name alone that this is the preferred blur path versus the GEGL filter tools.

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

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

With no annotations, the description carries the full burden and does disclose key behavior beyond the schema: commands execute in a persistent context where imports and variables survive between calls, results/errors come back as a JSON string, and GIMP 3.2-specific API changes apply. It stops short of warning that this is arbitrary code execution with potentially irreversible effects on open images, which keeps it from a 5.

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

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

Headers and front-loading are good — purpose first, then protocol, then parameters — but the body is very long and a large fraction of the 'Common Operations' recipes duplicate functionality already offered by dedicated siblings. Several tips (displays_flush, Selection.none) are repeated across examples, adding length without new information.

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

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

For a three-parameter arbitrary-code execution tool with no annotations and no schema descriptions, the definition covers the essentials: argument encoding, persistent interpreter state, error return format, and version-specific API gotchas. An output schema exists so return values need little explanation. The main omission is any caution about destructive operations or preferring dedicated tools.

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

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

Schema coverage is 0%, so the description must compensate and does: it explains api_path="exec", that args[0] must be "pyGObject-console" (or "pyGObject-eval"), that args[1] is an array of Python code strings, and that kwargs are a rarely-used keyword dictionary. Without this the zero-coverage schema would be nearly unusable; it adds the format meaning the schema lacks.

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

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

The opening line states a specific verb and resource: execute GIMP 3.2 API methods via the PyGObject console, with the concrete transport ('api_path="exec"', 'pyGObject-console') spelled out. It is clearly distinguishable as a raw escape hatch from the ~90 dedicated siblings (draw_line, fill_layer, etc.), but the definition never explicitly names that relationship, so the agent must infer it.

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

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

Usage is implied rather than framed: it offers 'Common Operations' recipes and points to the gimp_best_practices and gimp_iterative_workflow prompts, but never says when to use this tool instead of the dedicated sibling tools that perform the same operations (draw_line, fill_ellipse, select_ellipse). No when-not-to-use or exclusion guidance is given, which is a real gap given the sibling set.

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

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

With no annotations, the description carries the full burden and does well: it discloses that the tool only probes connectivity, enumerates the returned status dict keys (connected, host/port, gimp_version, error), and tells the agent what to do on failure. It does not mention timeouts or latency, so an agent can't tell whether a call may hang, but the safety profile is effectively conveyed ('check' implies a read-only probe).

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

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

Front-loaded with the purpose in the first sentence, then a compact bulleted return-value contract, then usage guidance. Since there is no output schema, the enumerated return fields earn their place rather than padding.

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

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

For a zero-parameter connectivity probe with no output schema and no annotations, the description supplies everything missing from structured fields: what it returns, what failure looks like, and the first-step usage rule plus recovery instructions. Nothing needed to call it correctly is absent.

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 takes zero parameters, so there is nothing for the description to disambiguate; the schema coverage is 100% and empty. Baseline 4 applies.

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

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

States a specific verb and resource: 'Check whether the GIMP MCP plugin socket is reachable and responding.' This is unambiguous and clearly distinct from siblings such as restart_server, pdb_run, or call_api, which operate on GIMP itself rather than on the socket connection.

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

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

Gives explicit placement in the workflow ('Use this before any other operation to verify the GIMP plugin is running') plus a concrete remediation path ('open GIMP and run Tools > Start MCP Server'). It stops short of naming restart_server as the alternative when the server hangs rather than being down, which is the one remaining routing gap.

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

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

With no annotations supplied, the description carries the full behavioral burden and does not meet it: it never says whether unsaved edits are discarded, whether closing the last image terminates or changes application state, where the XCF is written, or what happens if image_index is invalid. The only disclosure is "Returns status dict." For an operation that destroys in-memory state, this is a serious gap.

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

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

One front-loaded sentence states the action, followed by a compact parameter list and a one-line return note. It is tight overall, with slight redundancy between the parameter list and the schema's own defaults.

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, zero-required tool with no output schema or annotations, the definition covers the mechanics but omits the consequences of closing (loss of unsaved data), the XCF destination, and the shape of the returned status dict. Adequate to invoke, not adequate to invoke safely.

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

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

Schema description coverage is 0%, so the description must compensate, and it does explain both parameters in prose (index of the image to close with default 0; save as XCF before closing when true). It adds meaning beyond the bare titles, though it doesn't say how to obtain a valid image_index (list_images/get_image_metadata) or where the XCF path comes from.

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?

"Close an image, optionally saving as XCF first" gives a specific verb plus resource, making it easy to separate from siblings like open_image, save_xcf, and export_image. It stops short of a 5 because it never explicitly contrasts itself with those siblings (e.g., whether closing with save_first is preferred over save_xcf then close).

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

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

There is no when-to-use or when-not-to-use guidance, no mention of alternatives such as save_xcf followed by close, and no prerequisites (is an active image context required?). The only conditional hinted at is the save_first flag, which is parameter behavior rather than usage 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?

No annotations are supplied, so the description carries the full behavioral burden, and it discloses almost nothing. It never says whether the conversion happens in place or on a copy, how the alpha channel or transparency is handled when converting to GRAY or INDEXED, whether the operation is undoable, or what 'status dict' contains. Only the return type is mentioned, and only in a single vague phrase.

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

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

The definition is short, front-loads the purpose, and then uses a clean parameter list, which makes it easy to scan. The only wasteful line is 'Returns status dict.', which adds little value without saying what the status contains.

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?

Parameter documentation is solid, but for a mutation tool with no annotations and no output schema, the description leaves out behavior the agent needs: whether it mutates in place, what the 'status dict' reports, and how INDEXED quantization interacts with the existing palette. It is adequate but clearly incomplete for a write 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 0% and the schema declares no enums, so the description does real work: it enumerates the allowed mode values (RGB, GRAY, INDEXED), explains that num_colors applies only to INDEXED mode, and clarifies the role and default of image_index. The main gap is that it doesn't say what happens to num_colors when a non-INDEXED mode is passed.

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

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

States a specific verb and resource: 'Convert an image to a different color mode.' That is unambiguous about the operation. It does not distinguish itself from nearby siblings like desaturate or invert_colors, which also change pixel values, so the agent gets no explicit differentiation.

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

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

No when-to-use guidance at all: nothing says when a color-mode conversion is preferred over desaturate, invert_colors, or adjust_color_balance. There is also no mention of prerequisites, such as needing an open image or an active image context, that would help the agent pick this tool 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?

No annotations are provided, so the description carries the full behavioral burden. It does disclose defaults and value domains for every parameter, which is genuinely useful for a mutation tool, but it says nothing about permissions, whether the layer becomes active/selected, error behavior when no image exists, or whether the action is undoable — notable gaps given that an undo tool exists alongside 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?

A single front-loaded purpose sentence followed by a compact parameter list and a Returns line; nothing is padded. The list format is appropriate for eight parameters, though a few entries only restate schema defaults rather than adding new meaning.

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 an eight-optional-parameter mutation tool with no output schema, the definition covers purpose, every parameter, and the return shape, which is close to sufficient. What remains missing is precondition/error context (open image, image_index validity) and any note on side effects to the active layer or undo 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 0%, yet the description documents all eight parameters with defaults, accepted values, and semantics — fill color options including CSS colors, opacity range 0-100, blend_mode examples, and the crucial meaning of position (-1 = top, 0 = bottom). This fully compensates for the barren 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 opening sentence gives a specific verb and resource ('Create and insert a new layer into an image') and the position parameter implies it produces an empty layer rather than importing one. It never names the nearest alternatives (import_layer, duplicate_layer), so an agent must infer the distinction from the sibling list alone.

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 only implied: 'create a new layer' suggests this is the tool for adding an empty layer, and the defaults hint at the common case. There is no explicit statement of when to prefer this over import_layer or duplicate_layer, nor any prerequisite such as requiring an open 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?

With no annotations, the description carries the full behavioral burden. It says the canvas is cropped and lists the returned keys, but never discloses that pixels outside the rectangle are discarded, whether the operation is undoable, how it interacts with multiple images/layers, or what happens if the rectangle exceeds canvas bounds.

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?

Short, front-loaded with the action sentence, then a compact parameter list and a return shape. Every line carries information; only minor tightening is 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 5-parameter mutation tool with no annotations and no output schema, the description covers parameters and return keys adequately. It is incomplete on the destructive side of the operation — irreversibility, undo, and multi-image effects — which an agent needs before invoking a canvas crop.

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 0%, so the description must supply all parameter meaning, and it does: it defines x/y as the top-left corner, width/height as dimensions, and image_index as the target index with a default of 0. It still omits units (pixels), coordinate origin relative to the image, and behavior for out-of-bounds or non-positive values.

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

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

The first sentence names a specific verb and resource ('Crop the image canvas') and adds the scoping qualifier 'explicit rectangle', which implicitly separates it from the sibling crop_to_selection. It stops short of naming that sibling, so the agent must infer the distinction from the sibling list.

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 only implied: the phrase 'explicit rectangle' hints that this is the coordinate-based alternative to crop_to_selection, but no sentence states when to prefer one over the other. No prerequisites, no note about whether a selection affects the result, and no mention of undo.

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

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

No annotations are provided, so the description carries the full behavioral burden. It indicates that cropping occurs and reports the applied crop region, but it does not disclose that cropping is a destructive canvas mutation, whether the change can be undone, or what happens to existing layers or image state.

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 short and front-loads the main action before listing parameters and return values. The parameter defaults repeat the schema, but the structure remains efficient and appropriate for a two-parameter tool.

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

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

For a simple two-parameter tool, the description covers purpose, parameter meanings, and return shape without requiring an output schema. However, it omits the selection prerequisite, the destructive nature of cropping, and guidance against the closely related crop_to_rect sibling.

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 0%, but the description compensates by explaining both parameters: autocrop means auto-detect crop bounds instead of using the selection, and image_index selects the target image. The image_index explanation is thin, but overall the description adds meaningful semantics beyond the bare schema titles and defaults.

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: crop the image canvas to the current selection bounds. It is clear about what the tool does, but it does not distinguish it from the sibling crop_to_rect or explain how it relates to selection 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?

Usage is only implied by the phrase "current selection bounds" and by the autocrop parameter, which says to auto-detect bounds instead of using the selection. The description does not explicitly say when to choose this versus crop_to_rect, nor does it state prerequisites such as having an active selection.

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

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

With no annotations at all, the description carries the full behavioral burden and mostly fails it. It does not state that deletion is destructive or whether it is undoable via the undo sibling, what happens to pixels in the removed layer, or what occurs if the named layer does not exist. Only "Returns status dict" hints at the outcome, and even that is vaguer than an output schema would be.

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 one-line purpose is front-loaded, followed by a tight parameter list that adds information rather than echoing the schema. Every sentence earns its place and there is no filler.

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

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

For a zero-annotation mutation with no output schema, an agent still lacks the safety picture: reversibility, failure modes, and side effects on the image state are unaddressed. The address-mode logic and defaults are complete, so the definition is usable but not sufficient on its own.

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 0%, so the description must compensate, and it largely does: all three parameters are explained, the mutual exclusivity of layer_name and layer_index is made explicit, and both defaults (image_index=0, fall back to active layer) are stated. Gaps remain on whether layer_index is 0-based and whether layer_name must be unique.

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?

"Delete a layer from an image" states a specific verb and resource, and the target (a layer within an image) is unambiguous. It separates cleanly from sibling layer tools like create_layer, duplicate_layer, rename_layer, and reorder_layer purely by verb, though it never names them.

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

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

The description gives within-call selection guidance ("Provide either layer_name or layer_index. Defaults to active layer if neither given"), which is genuinely useful for choosing an address mode. It gives no broader when-to-use context: nothing about preferring flatten_image or merge_visible_layers, nothing about prerequisites, and no warning that this is a destructive 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 annotations are supplied, so the description carries the full burden. It discloses only that it uses GEGL and returns a status dict; it does not say whether pixels are modified destructively in place, whether the operation is undoable, whether it requires the GIMP server to be running, or what happens if the named layer is missing. For a mutation tool with zero annotation coverage this is a meaningful gap.

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

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

Front-loaded with the one-sentence purpose, followed by a compact, scannable parameter list and a return note. No filler sentences. Slightly under-structured only in that the parameter block lacks any note on error behavior, but nothing is 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 simple three-parameter filter with no output schema, the definition covers purpose, parameters, and return type, which is close to sufficient. However, with no annotations and no output schema, the missing behavioral details (in-place mutation, failure modes, undo) leave the agent guessing about side effects before invoking it.

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

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

Schema description coverage is 0%, so the description must compensate, and it largely does: it documents all three parameters with semantics the schema lacks — the 0-100 range and default 50 for strength, the default-0 target image index, and the fact that layer_name falls back to the active layer when omitted. Minor gap: no clarification of what image_index means when multiple images are open or what layer_name matching rules apply.

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

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

States a specific verb and resource ('Reduce noise in a layer') plus the underlying mechanism (GEGL noise-reduction), which distinguishes it from nearby siblings like sharpen, blur, and especially apply_noise (which adds rather than removes noise). It stops short of explicitly contrasting itself with gegl_apply_filter or apply_gaussian_blur, so an agent must infer the boundary.

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

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

There is no when-to-use or when-not-to-use guidance. With siblings such as apply_gaussian_blur, sharpen, and the generic gegl_apply_filter available, the description never says why an agent should pick denoise over running the GEGL op through the generic filter tool, nor does it state preconditions like a selected/active image or an existing layer.

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

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

With no annotations, the description carries the full burden and does disclose the default target (active layer), per-parameter defaults, and that a status dict is returned. It omits whether the pixel change is destructive/undoable, whether it applies only to the layer or to any selection, and how missing layers are reported.

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-line purpose followed by a compact parameter list; front-loaded and free of filler. The mode default is restated in both the description and the schema, a minor redundancy, 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 three-parameter pixel-mutation tool, the description covers purpose, every parameter, defaults, and the return type. The main gap is the absence of any note about destructiveness or undo, which matters most for a tool with no annotations and no output schema.

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

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

Schema coverage is 0%, so the description must compensate, and it does enumerate the mode values (luminosity, luma, average, lightness) plus defaults for all three parameters — real value the schema lacks. However it never explains what image_index indexes (multiple open images) or how layer_name is matched when duplicated, so the compensation is partial.

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

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

States a specific verb and resource: "Convert a layer to grayscale (desaturate)", which is unambiguous. It does not distinguish itself from convert_color_mode, a sibling that also produces grayscale output via a different mechanism, so it falls short of full sibling differentiation.

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

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

No when-to-use or when-not-to-use guidance is given, and no alternatives are named. An agent cannot tell from this text whether to use desaturate or convert_color_mode for a grayscale result, nor what preconditions (an open image, an existing layer) apply.

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

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

With no annotations supplied, the description carries the full behavioral burden. It discloses useful traits — stroke-only rendering, foreground-color fallback, active-layer fallback, and a status-dict return — but says nothing about undo semantics, whether it respects the active selection, anti-aliasing, or what fields the status dict contains.

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 one-line summary followed by a scannable per-parameter list is well front-loaded and wastes little space. The repeated default values (line_width 2.0, image_index 0) duplicate the schema and are the only clearly expendable 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 an eight-parameter drawing primitive with no annotations and no output schema, the definition covers every parameter and states the return type. The gaps are minor: 'Returns status dict' is not expanded, and no note about requiring an open image or selection behavior is given.

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 0%, so the description must compensate, and it largely does: it explains that x/y are the top-left corner of the bounding box (the schema only says 'X'/'Y'), that color falls back to foreground, that layer_name falls back to the active layer, and that line_width is in pixels. The defaults it repeats are already in the schema, and units for x/y/width/height are never stated.

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

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

The first sentence gives a specific verb and resource ('Draw an ellipse outline') and the parenthetical '(stroke only)' distinguishes it from the sibling fill_ellipse without needing the schema. It does not explicitly name fill_ellipse or select_ellipse, so the differentiation is implied rather than stated.

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?

'Stroke only' hints that a filled shape requires fill_ellipse instead, and 'on a layer' implies an image must be open. There is no explicit when-to-use or when-not-to-use statement, no mention of selection interaction, and no prerequisite guidance, so usage must be inferred.

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

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

With no annotations, the description carries the full burden. It does add real behavioral detail beyond structured fields: the color fallback to the current foreground, the width unit (pixels) and default, the pencil-vs-paintbrush edge semantics, and "Returns status dict." However, it never states that this mutates pixel data permanently, whether it is undoable, what happens on an invalid layer_name, or whether it errors with no open image — significant omissions for an unannotated write 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?

One-sentence purpose followed by a scannable per-parameter list ordered roughly by importance, with required coordinates first and optional styling last. Every line carries information, including "Returns status dict." which is needed because no output schema exists.

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

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

For a nine-parameter drawing tool with no annotations and no output schema, the definition covers all inputs, their defaults, and the return shape, which is enough to call it correctly. What it lacks is the operational frame — coordinate origin, layer type constraints, and mutation/undo semantics — so it stops short of fully complete.

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

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

Schema description coverage is 0%, so the description must compensate, and it largely does: all nine parameters are explained with meaning and defaults, and the `tool` parameter gets enum semantics ("pencil" hard edge vs "paintbrush" soft edge) that the schema lacks entirely. The remaining gap is the coordinate space for x1/y1/x2/y2 — image pixels vs canvas coordinates and origin — which is never specified.

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?

"Draw a straight line on a layer" gives a specific verb (draw) and resource (a straight line on a layer). The shape term alone separates it from siblings draw_rectangle, draw_ellipse, and fill_rectangle without opening any schema.

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

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

Usage is only implied by the parameter list: layer_name "defaults to active layer" and image_index "default 0" hint at the multi-image/active-layer context, but there is no explicit when-to-use guidance, no alternative named (e.g. paintbrush soft-edge via a different tool), and no stated prerequisites such as an image or layer needing to exist.

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

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

No annotations are provided, so the description carries the full burden. It usefully discloses defaults (foreground color fallback, line_width 2.0, active layer fallback, image_index 0) and that it returns a status dict, but it does not state that this mutates the image, whether it is undoable, or what happens if the named layer does not exist.

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

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

A single front-loaded purpose sentence followed by a compact per-parameter list. Every line adds information; nothing is redundant and the structure is easy to scan.

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

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

For a mutation tool with no annotations and no output schema, the description covers purpose, all parameters, key defaults, and the return shape ('status dict'). It could be more complete by noting the coordinate space and undo implications, but nothing essential to calling it correctly is missing.

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

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

Schema description coverage is 0%, yet the description documents every one of the 8 parameters, including defaults that the schema only encodes as JSON defaults. It falls short of a 5 because the color format (hex vs. name) and the coordinate units for x/y are left unspecified.

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, 'Draw a rectangle outline (stroke only) on a layer,' and the '(stroke only)' qualifier distinguishes it from fill_rectangle and fill_ellipse without naming them. It stops short of explicitly naming the alternative siblings, so an agent must infer the contrast.

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

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

Usage is implied rather than stated: 'stroke only' suggests when to prefer this over fill_rectangle, and the layer_name default implies the active-layer case. There is no explicit when-to-use/when-not guidance and no mention of prerequisites such as an open image or an existing layer.

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

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

With no annotations, the description carries the full disclosure burden. It helpfully states that the copy is inserted above the original and what fields are returned, but it does not describe whether the original remains unchanged, which layer properties are copied, or what happens if the layer is not found.

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 short and front-loaded with the core operation. The parameter list and return fields are structured efficiently, with no unnecessary wording.

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

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

For a simple two-parameter duplication tool, the description covers purpose, parameter defaults, insertion behavior, and return values. It is missing explicit sibling-tool routing and error-case behavior, but otherwise gives enough context to invoke the tool correctly.

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

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

Schema description coverage is 0%, so the description must compensate, and it does document both parameters with defaults. It clarifies that layer_name defaults to the active layer and that image_index targets an image and defaults to 0. This adds meaningful semantics beyond the bare 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: duplicate a layer. It also adds the useful positional behavior that the copy is inserted above the original. It does not explicitly distinguish this from sibling tools such as create_layer or import_layer, so it stops short of a 5.

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

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

There is no explicit guidance on when to use duplicate_layer versus create_layer, import_layer, or other layer-creation tools. The description only states what the tool does, leaving the agent to infer the appropriate context and any exclusions.

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

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

No annotations are supplied, so the description carries the full behavioral burden. It usefully discloses partial-update semantics and that a status dict is returned, but says nothing about what happens with a missing layer_name, whether the edit is undoable, needed permissions, or what the status dict contains on failure.

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?

It is front-loaded with a single purpose sentence followed by a scannable parameter list, with no filler. The repeated '(omit to leave unchanged)' on four entries is slightly redundant, though it does reinforce the optionality.

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 six-parameter mutation tool with no annotations and no output schema, the description covers the inputs adequately but omits error conditions and meaningful return detail, saying only 'Returns status dict'. An agent can call it, but cannot anticipate failure modes.

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

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

Schema description coverage is 0%, so the description is the only documentation for these six parameters, and it does supply each one plus the image_index default of 0 and the units for size (pixels). It falls short on value formats, e.g. what form color takes (hex, name) or where valid font families come from (list_fonts is never referenced).

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

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

The description gives a specific verb and resource ('Edit an existing text layer's content or formatting'), which separates it from sibling mutation tools like set_layer_properties and from add_text, since it operates on an existing text layer. It never names those alternatives explicitly, so differentiation is implied by the resource rather than stated.

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

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

Use is only implied: the 'omit to leave unchanged' notes convey that this is a partial-update tool, but there is no guidance on when to choose it over add_text or set_layer_properties, and no stated precondition that the text layer must already exist.

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

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

With no annotations, the description carries the burden well: it enumerates the exact output artifacts per platform, states defaults for platform/format/source index, and discloses the return shape {exported, count, platform}. It omits whether existing files in output_dir are overwritten, whether the directory is created, and what happens on failure, which keeps it out of 5 territory.

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

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

Front-loaded one-line summary followed by a compact size table and a parameter/return block; the size enumeration is long but earns its place by telling the agent exactly what files result. No filler sentences.

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

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

For a filesystem-writing tool with no annotations and no output schema, the definition covers purpose, all parameters, defaults, and the response shape. The remaining gaps are operational (overwrite policy, directory creation, error cases), which are real but secondary.

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 0%, so the description must supply meaning, and it documents all four parameters including the enum-like values for platform (android/ios) and the indexing semantics of source_image_index. The format parameter only says "png" (default), leaving open whether other values are accepted.

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

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

States a specific verb and resource (export an image as a complete icon set) and narrows scope to Android/iOS with exact pixel size lists, which separates it from generic siblings like export_image, batch_export, and export_web_optimized.

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 the use case clear (producing platform icon sets) and gives defaults, but never says when not to use it or names an alternative such as export_image or batch_export for non-icon output. Usage is implied rather than routed.

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

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

With no annotations, the description carries the full burden; it usefully discloses defaults and conditional behavior (quality ignored for PNG/TIFF, flatten defaults to True). It does not say whether flattening mutates the in-document image, whether an existing file at file_path is overwritten, or what happens if no image is active, which are material for a write-to-disk operation.

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

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

Front-loaded purpose sentence followed by scannable parameter and return lists with no filler. The parameter block duplicates schema field names, but that is justified given zero schema description coverage.

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

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

There is no output schema, yet the description lists the return fields (status, file_path, format, file_size_bytes), and all parameters are documented. Missing only edge-case behavior around overwriting files and document mutation, which keeps it from a 5.

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

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

Schema description coverage is 0%, and the description fully compensates: every one of the five parameters gets meaning, accepted values, defaults, and the format-dependent rule for quality. This is well beyond what the bare schema 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 opens with a specific verb and resource ('Export the current image to a raster file') and enumerates supported formats, so the agent knows exactly what the tool produces. It does not differentiate from near-siblings like batch_export or export_web_optimized, which limits it to a 4.

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

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

Usage is implied by 'current image' (as opposed to a batch or multi-sibling flow), but there is no explicit statement of when to choose this over batch_export, export_web_optimized, save_xcf, or when the image must already exist. The agent must infer the routing decision.

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

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

With no annotations, the description carries the full burden; it does disclose that files are written into output_dir and specifies the exact return shape ({exported: [{platform, file_path, width, height}], count}). It omits important behavior for a write tool: overwrite behavior for existing files, whether the full kit is atomic, and what happens with invalid platform names (the schema's array items are untyped, so bad input is plausible).

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

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

Front-loaded with the purpose, then structured into platform sizes, parameters, and return value, all of which earn their place. The only mild redundancy is repeating platform names in both the size table and the parameters section, though the repetition serves different purposes.

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?

Because there is no output schema, the explicit Returns line is genuinely valuable, and the platform size table resolves the untyped array parameter. What keeps it at a 3 is the unresolved ambiguity around image_index and the absence of any statement about the source document state or file-overwrite semantics for a multi-file write 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 0%, so the description must compensate, and it does: it documents all three parameters and, critically, supplies the valid platform identifiers that the schema leaves as an untyped array. The one weak spot is image_index, described only as 'Source image index (default 0)' without saying which collection or ordering the index refers 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?

States a specific verb and resource ('Export an image resized for multiple social media platforms') and enumerates the exact platform variants produced, which distinguishes it from the many other export tools in the sibling list. It stops short of naming which sibling to prefer for non-social exports, so the differentiation is implicit rather than explicit.

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

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

Usage is inferable from the name and platform list, and the description does give one routing hint by parameter ('omit for all five'). However, it never says when to use this versus export_image, batch_export, export_web_optimized, or export_icon_sizes, and never states prerequisites such as needing an open 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?

With no annotations supplied, the description carries the full disclosure burden and does well: it makes clear a PNG file is written to an absolute output_path and documents the returned fields (file_path, columns, rows, frame sizes, count). It omits whether an existing file is overwritten or whether any permissions/state requirements exist, which is the main remaining gap.

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

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

Front-loaded purpose sentence followed by a tight parameter list and a return-shape line; every entry earns its place given the empty schema descriptions. Slightly repetitive for an agent that also reads the schema titles, but justified here.

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 five-parameter export tool with no annotations and no output schema, the description covers purpose, all parameters with defaults, source-mode semantics, and the return object. Only overwrite behavior and any preconditions are unaddressed.

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 0%, so the description must compensate, and it does: every one of the five parameters is explained, including the default for columns (square root of frame count), padding default, the enumerated values for source, and the meaning of image_index relative to source="layers".

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

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

States a specific verb and resource: 'Combine multiple frames into a sprite sheet PNG', which an agent can distinguish from generic exporters like export_image or batch_export by the sprite-sheet resource. It does not explicitly differentiate itself from near neighbors such as export_icon_sizes or export_social_media_kit, which keeps it short of a 5.

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

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

The description explains the two source modes ('layers' vs 'images') and their defaults, which implies when each mode applies, but it never states when to prefer this tool over export_image, batch_export, or export_icon_sizes. Usage is inferable rather than explicit.

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

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

No annotations are supplied, so the description carries the full burden. It does useful work by disclosing the return shape and the default quality/compression values, but it never says whether both files are always written regardless of which is smaller, whether existing files in output_dir are overwritten, or whether scaling affects the source document or only the exported copies. For a write-to-disk tool with zero annotation coverage, those gaps matter.

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

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

The purpose sentence is front-loaded, then a compact parameter block, then the return shape. Nothing is wasted and the bulleted format is easy to scan. The parameter block largely mirrors the schema's property names, but with 0% coverage that restatement is earned rather than 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?

With no output schema, the explicit 'Returns: {jpeg_path, jpeg_size, png_path, png_size, recommendation}' line is valuable and completes the picture for a caller. All six parameters are covered. Remaining gaps are behavioral rather than structural: overwrite policy and whether max_width/max_height mutate the live image.

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 0%, so the description is the only source of parameter meaning, and it documents all six: output_dir, jpeg_quality (1-100, default 85), png_compression (0-9, default 9), max_width/max_height as optional pre-export scaling, and image_index (default 0). The only weak spot is image_index, which does not explain what the index refers to or how to obtain valid values.

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

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

States a specific verb and resource (export an image) plus the distinguishing behavior: produces both JPEG and PNG so the caller can pick the smaller. That differentiates it from export_image, batch_export, and export_icon_sizes without naming them. The phrase 'choosing the smaller format' slightly overstates the tool, since the Returns list shows both files plus a recommendation rather than a single chosen 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?

The 'web optimized' framing implies when to reach for this over export_image, but there is no explicit statement of when to use it versus export_image or batch_export, and no prerequisites or exclusions. Usage has to be inferred from the tool's name and the dual-format behavior.

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

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

No annotations are provided, so the description carries the full burden, and it does disclose two useful behaviors: the return is a status dict, and layer_name resolves to the active layer when null. It says nothing about permission requirements, interaction with an active selection, or whether the fill is destructive/undoable, which are real gaps for a pixel-mutating tool.

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

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

The purpose sentence is front-loaded and the parameter list is compact with no filler. The trailing "Returns status dict" is terse but earns its place given there is no output schema.

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?

Parameter coverage is strong and the return type is mentioned, but with no annotations, no output schema, and no usage context, an agent still lacks guidance on preconditions and side effects. Adequate but visibly incomplete for a destructive drawing 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 0%, and the description compensates by documenting all seven parameters, including that x/y are the top-left of a bounding box, that color accepts CSS names, hex, or rgb() strings, and the fallback semantics for layer_name and image_index. Only the units/type expectations for width and height remain implicit.

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

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

States a specific verb and resource ("Fill an elliptical region with a solid color"), which clearly separates it from paint-like siblings such as fill_rectangle, draw_ellipse, and select_ellipse. It does not explicitly name any sibling or state the distinction, so it stops short of a 5.

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

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

There is no when-to-use guidance, no prerequisites, and no mention of when to prefer fill_selection or fill_layer over this tool. The agent must infer the context entirely from the verb and the fact that coordinates are bounding-box based.

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

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

With no annotations, the description carries the full behavioral burden. It discloses that the result is a "status dict" but never states whether existing layer pixels are destroyed, whether an active selection clips the fill, whether the operation is undoable, or if it requires an editable layer. For a destructive mutation on a layer, these are material omissions.

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-line purpose statement followed by a compact parameter list — appropriately front-loaded and free of filler. The parameter list is justified because the schema provides no per-field documentation of its own.

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

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

There is no output schema, so the tool should say what "status dict" contains, and with no annotations the destructive/undo behavior should be spelled out. The description covers the operation and its parameters adequately but leaves those behavioral questions open for a 3-parameter mutation tool.

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

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

Schema description coverage is 0%, so the description must compensate and largely does: it gives accepted color syntaxes (CSS name, hex, rgb()), explains that layer_name defaults to the active layer, and that image_index targets a specific image. This adds genuine meaning the bare schema lacks, though it does not clarify what image_index means when multiple images are open or the semantics of a null layer_name.

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

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

The description opens with a specific verb and resource: "Fill an entire layer with a solid color." The word "entire" implicitly distinguishes it from selection-scoped siblings like fill_selection and shape-scoped ones like fill_rectangle, though neither is named explicitly. An agent can grasp the operation without opening the schema.

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

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

No explicit when-to-use or when-not-to-use guidance, and no named alternatives among the many fill-related siblings (fill_selection, fill_rectangle, gradient_fill). Usage is only implied by the defaults stated for layer_name ("defaults to active layer") and image_index ("default 0"), which does help an agent call it correctly but does not route it against alternatives.

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

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

No annotations are supplied, so the description carries the full burden. It reveals only that the call returns a "status dict" and that layer_name and image_index default to the active layer and 0. It omits that this is an in-place canvas mutation, whether prior pixel content is destroyed, whether it respects the current selection, and whether the change is undoable.

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

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

A single front-loaded purpose sentence followed by a tight bulleted parameter list, with no filler. The return value is noted in one line. Structure is appropriate for a tool with seven parameters and a 0% schema description coverage.

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 parameter-heavy mutation tool with no annotations and no output schema, all parameters are at least defined, which is the minimum needed to call it correctly. However, interaction with selections, layer targeting semantics, and failure modes are absent, leaving an agent unable to predict the effect on the document.

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 0%, and the description compensates well by documenting all seven parameters: x/y as the top-left corner, width/height as dimensions, color accepted as CSS name, hex, or rgb() string, plus the defaults for layer_name and image_index. It still does not state the unit or coordinate space for x/y/width/height, nor whether color supports alpha.

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

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

The first line states a specific verb and resource: "Fill a rectangular region with a solid color." That separates it from fill_layer, fill_selection, and fill_ellipse by naming both the shape and the fill type. It stops short of explicitly naming those siblings, so the differentiation is implicit rather than spelled out.

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

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

There is no guidance on when to use this versus fill_selection, fill_layer, fill_ellipse, or draw_rectangle, all of which are close siblings in this toolset. The description never states prerequisites either, such as whether an image must be open, whether an active selection alters the fill region, or how this interacts with the 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?

No annotations are supplied, so the description carries the full behavioral burden and mostly does not meet it. It does not say what happens when no selection exists, whether the fill is destructive/undoable, whether it respects layer locks or transparency, or what the 'status dict' contains beyond its name.

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

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

One-sentence purpose followed by a compact parameter list, each entry a single line. Front-loaded and free of filler; the only weakness is that the 'Returns status dict.' line adds almost nothing.

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 tool with no annotations and no output schema, the description covers the inputs well but leaves out failure modes and side effects an agent needs. It is adequate to attempt a call but not sufficient to predict what happens in edge cases like no active selection or a transparent fill on a non-alpha layer.

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 0%, so the parameter block is doing real work: it gives accepted color formats (CSS name, hex, rgb()), enumerates the fill_type values 'foreground'/'background'/'transparent' that the bare string schema lacks, and states defaults (image_index 0, layer_name = active layer). Only the interaction between color and fill_type is left slightly fuzzy.

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?

Names a specific verb plus resource ('Fill the current selection') and clarifies the fill can be a color or a fill type. An agent can distinguish it from fill_layer and fill_rectangle by the 'current selection' scope, though the description never explicitly contrasts with those 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?

Usage is only implied: 'current selection' tells the agent a selection must exist first, and the color/fill_type wording hints at two modes. There is no explicit when-to-use versus fill_layer, fill_rectangle, or gradient_fill, and no stated precondition about creating a selection first.

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

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

With no annotations, the description carries the full burden. 'All layers into a single background layer' does disclose that every layer is collapsed, but it omits that hidden layers are also discarded, that the result is effectively irreversible apart from undo, and whether alpha/transparency is preserved. A precise but incomplete behavioral picture.

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

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

The core sentence is front-loaded and wasteful phrasing is absent. The 'Parameters' and 'Returns' blocks are small, though 'Returns status dict' adds little information.

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

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

For a one-parameter, destructive tool with no annotations and no output schema, the definition is minimal but not misleading. It should say more about irreversibility and the return value than 'status dict'.

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 0%, so the description must compensate; it lists image_index and its default of 0, which matches the schema but adds no interpretation — such as whether the index refers to the position in the image list from list_images or the active image.

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

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

States a specific verb and resource — 'Flatten all layers into a single background layer' — so the agent knows exactly what operation is performed. It does not differentiate from the sibling merger, merge_visible_layers, which is the most likely competing choice.

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

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

There is no guidance on when to flatten versus merge_visible_layers, no precondition that an image must exist or be active, and no mention that the operation should be paired with save/export. The only usage hint is the parameter default.

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

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

With no annotations supplied, the description carries the full burden. It does disclose the mutation scope ("entire image"), the default direction, and that a status dict is returned, which is more than nothing. However it is silent on permissions/prerequisites, whether the operation is undoable, and whether it applies per-image or per-layer.

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

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

Front-loaded one-line purpose followed by a compact parameter list and a note on the return value; nothing is padded. The parameter block largely restates schema defaults, which is mild redundancy but useful given the 0% schema coverage.

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 two-optional-parameter tool with no output schema, the description covers purpose, parameters, defaults, and return shape. What is missing is operational context a caller needs: required preconditions (open/active image), undo semantics, and effect on selections or layers.

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

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

Schema description coverage is 0%, so the description must compensate, and it does list both parameters with their defaults. Crucially it adds the allowed values "horizontal" (default) or "vertical" for direction, which the schema lacks entirely (no enum). It says nothing meaningful about image_index beyond restating the default, so it only partially fills the 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?

States a specific verb and resource ("Flip the entire image") plus the axis of operation ("horizontally or vertically"), which is enough to distinguish it from geometry siblings like rotate_image or scale_image. It stops short of explicitly naming an alternative, so a 4 rather than a 5.

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

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

There is no guidance on when to reach for flip_image versus rotate_image, transform_layer, or the selection-based operations, and no stated preconditions (e.g. an active/open image). The phrase "entire image" hints that it is whole-canvas rather than selection-scoped, but that is inference, not instruction.

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

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

With no annotations provided, the description still discloses important behavior beyond the schema: the filter is appended rather than replacing existing filters, and it is editable and non-destructive. However, it omits prerequisites, layer-targeting behavior, failure cases, and what the call returns.

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

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

The description is a single front-loaded sentence with no filler. Every phrase contributes to the core meaning: append, named, editable, non-destructive, GEGL filter, and layer target.

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 six parameters, a nested properties object, no annotations, and no output schema, so the description carries a heavy documentation burden. It states the high-level effect but leaves out the operational and parameter details needed to invoke a GEGL filter confidently.

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

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

Schema description coverage is 0% for six parameters, including the required operation and nested properties object. The description only obliquely hints at name and layer_name through "named" and "to a layer," and does not explain valid operation values, properties structure, opacity, or image_index.

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: "Append a named, editable, non-destructive GEGL filter to a layer." It clearly identifies the action and target, though it does not explicitly distinguish this tool from nearby siblings such as gegl_filter_action or the specific apply_* filter 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 implies it is used to add a filter to a layer, but gives no explicit when-to-use guidance, no exclusions, and no comparison to alternatives like gegl_filter_action or apply_gaussian_blur.

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

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

No annotations are supplied, so the description carries the full burden. "Inspect" and "live" imply a read-only call requiring a running instance with an actual loaded image, but the description never states that this is non-destructive, what happens if layer_name is omitted or the layer is missing, or whether the schema reflects instance-specific values. For a tool with zero annotation coverage these are material gaps.

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

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

A single front-loaded sentence with no wasted wording; the purpose and the motivating workflow both land immediately. It is arguably too terse given the parameter burden, but it is structurally clean.

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 takes three parameters with no documented schema, has no annotations and no output schema, yet the description is one short sentence. An agent would not know what the returned schema looks like or how image_index and layer_name interact, which is insufficient for a live-instance inspection tool.

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

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

Schema description coverage is 0% across three parameters, so the description must compensate and largely does not. It hints that a layer is involved, loosely mapping to layer_name, but says nothing about the meaning of operation (the filter identifier) or image_index (how to choose among open images, and what the default 0 implies).

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 ("Inspect") and resource ("a live GEGL filter's property schema") scoped to a layer, which distinguishes it from sibling mutators like gegl_apply_filter and from enumerators like gegl_list_operations. It does not explicitly name those siblings, but the read-of-a-schema framing is clear enough to separate it.

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

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

The trailing clause "before applying it" implies a workflow position: call this prior to scheduling a GEGL filter. That is useful implied usage, but there is no explicit statement of when not to use it, nor a named alternative such as gegl_list_filters for discovery versus this per-operation schema lookup.

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

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

No annotations are provided, so the description carries the full behavioral burden for a mutation tool. It does not say whether removal is irreversible, whether opacity/visible changes are reversible via undo, what happens when action is an unrecognized value, or what the call returns.

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 compact sentence with the resource and identifier scheme front-loaded and no filler. It is efficient, though the brevity is a contributing factor to the missing action semantics.

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 tool with zero annotation coverage, no output schema, and no documented parameter descriptions, one sentence is thin. The two most consequential unknowns — valid action values and removal irreversibility — are absent.

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 0%, so the description must compensate. It loosely maps opacity and visibility to the two optional parameters and clarifies filter_id as GIMP's identifier, but the required, enum-less "action" string — the parameter that actually selects the operation — has no documented vocabulary anywhere, which is a serious 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?

"Change a filter's visibility/opacity or remove it" gives a specific verb set and resource, and "by its GIMP filter ID" fixes the addressing scheme. It stops short of naming how it differs from gegl_apply_filter or gegl_list_filters, so an agent must infer the modify-vs-create 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 possessive "a filter's" implies this operates on an already-applied filter, contrasting with gegl_apply_filter, but that routing is never stated. There is no explicit when-to-use, no prerequisite (e.g., needing a filter ID from gegl_list_filters), and no 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?

No annotations are provided, so the description carries the full behavioral burden, yet it says nothing about whether this is a safe read-only call, what happens if layer_name is omitted or invalid, or whether an empty result is possible. Only the verb 'list' weakly implies a non-mutating operation.

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

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

A single front-loaded sentence with no filler, but it is so terse that it borders on under-specification rather than efficiency. Structure is fine; there is nothing extraneous.

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

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

For a tool with two undocumented parameters, no annotations, and no output schema, the description should explain what a returned filter entry looks like and how defaults resolve. It does neither, leaving the agent reliant on guessing about the default layer and image selection.

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 0% for both parameters, and the description only loosely maps 'a layer' to layer_name without explaining the null default (presumably the active layer) or the meaning of image_index. Neither parameter's format, default behavior, or selection semantics are clarified beyond the bare schema titles.

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

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

The description gives a specific verb+resource (list filters attached to a layer) and adds a meaningful qualifier ('editable non-destructive'), so the agent knows exactly what is being enumerated. It does not differentiate itself from sibling GEGL tools such as gegl_list_operations or gegl_describe_operation, so the agent must infer the boundary.

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

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

There is no when-to-use guidance, no prerequisites, and no mention of alternatives such as gegl_apply_filter or gegl_list_operations. The agent must guess whether this tool is for discovering existing filters on a layer versus the catalog of available GEGL operations.

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

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

With no annotations supplied, the description carries the full behavioral burden. It discloses that results are paged, which is useful, but says nothing about ordering, what an invalid regex does, whether defaults apply, or what the call returns; a read-only listing is only implied by 'Discover'.

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 compact sentence with the resource and the two most decision-relevant qualifiers (paging, regex semantics) front-loaded. Nothing is redundant, though the semicolon clause is dense enough that it reads as two ideas compressed into one line.

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

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

For a simple read-only listing tool this is close to adequate: paging and pattern semantics are covered, and no output schema exists to describe. However, with zero annotation coverage and zero schema descriptions, the absence of return-shape and pagination-default details leaves a real 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 0% across three parameters, so the description must compensate and mostly does not. It clarifies that 'pattern' is a case-insensitive regex, but 'limit' and 'offset' are only hinted at via the word 'paging', leaving their meaning and defaults undocumented outside the schema's bare defaults.

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

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

The description gives a specific verb and resource: 'Discover installed GIMP 3.2 GEGL filters'. The version pin and paging mention make the scope concrete, but it never distinguishes itself from the near-identical sibling 'gegl_list_filters', which an agent could easily confuse it with.

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

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

There is no explicit when-to-use or when-not-to-use guidance and no mention of alternatives such as gegl_list_filters, gegl_describe_operation, or gegl_apply_filter. The only implied usage cue is the regex-pattern filtering, which the agent must infer.

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

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

With no annotations, the description carries the full burden and does reasonably well: it warns that state can be mutated externally by the user at any time, which is genuine behavioral context an agent cannot get from structured data. It also discloses the failure mode (raises an exception if the context cannot be read). It does not explicitly state it is a non-mutating read, though 'Get' implies 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 critical warning about user-driven state changes is well placed near the top, and the bulleted field list is scannable. However, content is duplicated: the 'Returns information about' bullets and the separate 'Returns:' section restate the same payload description, and the use-case bullets largely repeat the field list. Trimming one of those blocks would make it materially tighter.

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

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

There is no output schema, so the description must describe the return value, and it does — a dictionary of the listed fields, plus the exception behavior. Combined with the schema being empty, an agent has enough to call this correctly; only the sibling differentiation and explicit read-only framing are absent.

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 is empty, so there are no parameters whose semantics need explanation. The baseline of 4 applies; nothing is added or missing on this dimension.

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

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

States a specific verb and resource ("Get the current GIMP context state") and enumerates exactly what state is covered (colors, brush, opacity, blend mode, feather, antialiasing). It is clear what the tool does, but it never distinguishes itself from related siblings such as get_state_snapshot, get_gimp_info, or get_pixel_color, leaving the agent to infer the boundary.

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

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

Provides an explicit 'Use cases' list and a strong conditional rule: check context state before operations that depend on specific settings. What is missing is the negative side — it never says when not to call it, or which alternative to use instead when the agent wants a broader snapshot or a single pixel value.

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

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

With no annotations at all, the description carries the full burden, and it does disclose one important behavior: it 'raises exception if GIMP connection fails,' which tells the agent this call can fail on a dead connection. However, it says nothing about cost/latency (the plugin and procedure enumeration could be large), side effects, or whether results are cached, so the behavioral picture is only partially covered.

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

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

The bullet list is front-loaded and informative, but the separate 'Returns:' block largely restates the bullets ('Dictionary containing comprehensive GIMP environment information'), and the sentence about helping AI assistants troubleshoot is padding. Trimming the duplicate Returns block would make it tighter without losing meaning.

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

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

For a zero-parameter diagnostic tool with no annotations and no output schema, the description does the necessary work: it enumerates the categories of data returned and names the failure mode. The main remaining gap is not saying how large/expensive the returned payload is, which matters for a tool that lists plugins and procedures.

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 takes zero parameters, so there is nothing for the description to disambiguate; baseline 4 applies. The description correctly frames this as a no-argument environment query.

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

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

States a specific verb and resource ('Get comprehensive information about the GIMP installation and environment') and enumerates the concrete content (version/build, install paths, plugins, system config, runtime). It does not explicitly differentiate itself from near-neighbors like check_server, get_state_snapshot, or get_context_state, so an agent must infer that this one is the static environment/config view rather than a connectivity or state probe.

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 only implied: the description says the information 'helps AI assistants provide better support and troubleshooting,' which is a rationale rather than a directive. There is no explicit 'call this before X' or 'use check_server instead if you only want to verify connectivity,' leaving the choice among several related diagnostic siblings to inference.

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

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

No annotations are supplied, so the description carries the full burden. It does disclose the return fields and defaults, but says nothing about whether statistics cover the whole layer or the selection, what happens with no active image/layer, or cost on large images.

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 front-loaded purpose sentence followed by compact parameter and return blocks; every line adds information and nothing is padded.

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 only two optional parameters and no output schema, the description supplies the return shape and default values, which is most of what an agent needs. It falls short only on edge-case behavior (no active layer, selection scope, error responses).

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 0%, and the description compensates well: it enumerates the valid channel values ("value" default, red, green, blue, alpha) and explains image_index as a target image index defaulting to 0, adding real meaning beyond the bare title-typed schema properties.

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

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

States a specific verb and resource ("Get histogram statistics") plus scope ("for a channel of the active layer"), which cleanly separates it from siblings like get_image_metadata, get_pixel_color, and get_image_bitmap.

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 only implied – an agent can infer this is for analyzing tonal/luminance distribution, but the description never says when to prefer it over get_pixel_color or get_image_metadata, nor any prerequisites such as requiring an open image with an 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?

No annotations exist, so the description carries the full burden, and it does well: it discloses the return format (PNG, base64, MIME type per MCP spec), states there are no size restrictions, and enumerates failure conditions ('RuntimeError if no image is open, region is invalid, or export fails'). It stops short of stating performance/resource implications of full-resolution export on very large images, which an agent planning calls would benefit from.

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

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

Well front-loaded with the core action first, then use cases, parameters, examples, returns, and raises. The examples and returns sections earn their place given the absent output schema, though the two closing sentences about automatic base64/MIME handling restate the same point twice.

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

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

For a 3-parameter, zero-annotation, no-output-schema tool with 0% schema description coverage, the description supplies everything needed: object shape, nested region keys, scaling semantics, concrete call examples, return payload contents, and error conditions.

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 0%, and the description fully compensates: it defines max_width/max_height as target dimensions with aspect ratio preserved, and unpacks the untyped region dict into origin_x, origin_y, width, height plus optional nested max_width/max_height. This is meaning the schema literally cannot convey, since region is only an open object type.

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

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

States a specific verb+resource ('Get the current open image in GIMP as an Image object') plus the two capabilities (scaling, region selection). It is clearly distinguishable from siblings like get_image_metadata (metadata only) and export_image (writes to disk) without opening any schema.

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

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

Gives explicit usage scenarios ('Full image with optional scaling' vs 'Region extraction') and a sizing hint ('For large images, omit max_width/max_height'). It does not explicitly say when to prefer this over siblings such as get_image_metadata, export_image, or get_pixel_color, so routing guidance is implied 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?

With no annotations supplied, the description carries the full burden and does well: it discloses that no bitmap data is exported, that the result is a dictionary, and that an exception is raised if no images are open — an error condition an agent must anticipate. It does not explicitly confirm the operation is non-mutating, which is the main residual gap.

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

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

Front-loaded with the core statement and the performance distinction, then a scannable bullet list of returned fields. The trailing 'Returns:' block partially restates the bullets ('comprehensive image metadata'), which is mild redundancy but also the only return documentation since no output schema exists.

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

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

For a parameterless read tool with no output schema, the description supplies the field inventory, the error case, and the cost comparison — enough to call it correctly. What is missing is a statement of state effect (read-only vs. any side effects), which matters since no annotations declare 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 tool takes zero parameters (empty schema, 100% coverage by definition), so there is nothing for the description to disambiguate. Baseline 4 applies; no misleading parameter language is present.

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

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

States a specific verb and resource ('Get metadata about the current open image in GIMP') and immediately scopes it ('without the bitmap data'), which distinguishes it from the sibling get_image_bitmap. An agent can tell the two apart without opening either schema.

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

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

Explicitly routes the agent away from the heavier alternative: 'much faster than get_image_bitmap() since it doesn't export the actual image data' and 'Perfect for when you only need to know image properties for decision making.' Clear selection context, though it never states when this tool is the wrong choice (e.g., when pixel data is actually needed).

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

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

With no annotations supplied, the description carries the full burden; it does disclose useful defaults (image_index 0, layer_name falls back to the active layer) and the exact return shape {color_hex, color_rgb, alpha}. However it says nothing about out-of-bounds coordinates, missing layers, color-mode differences, or whether sampling is affected by selection/visibility.

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

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

Front-loaded purpose sentence followed by a compact Parameters block and a Returns line; every element earns its place. Minor loss for not labeling the coordinate system in the x,y bullet.

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 four-parameter read tool the description is largely sufficient, and it compensates for the absent output schema by spelling out the return object. It still omits error/failure behavior for invalid coordinates or layers, which matters because there are no annotations to fall back on.

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 0% (properties carry only bare titles like 'X' and 'Layer Name'), yet the description explains all four parameters, including the non-obvious fallback semantics of layer_name and the default of image_index. Only the coordinate origin/space is left unstated.

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: 'Get the color of a single pixel.' That is unambiguous and clearly distinct from the other sampling/inspection siblings such as get_histogram or get_image_metadata. It stops short of naming an alternative or scoping when a single pixel vs a region is appropriate, so it is clear but not sibling-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?

There is no guidance on when to use this rather than get_histogram, select_by_color, or get_image_metadata, and no stated preconditions (e.g., an image must be open, the layer must exist). The only implied usage comes from the parameter list itself.

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