Skip to main content
Glama
MalloyTheDev

Aseprite MCP

by MalloyTheDev
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

merge_layer_down

Destructive

Combine a layer with the one directly below it, returning the target layer name and refusing when no mergeable layer exists beneath.

Instructions

Merge a layer down into the layer directly beneath it.

Refuses rather than doing nothing when there is nothing to merge into. Aseprite's
`MergeDownLayer` is a no-op in five cases, and it raises in none of them, so this used
to report a result indistinguishable from a merge that happened. Measured, naming the
layer stack before and after:

    bottom layer of the sprite        ['only']                   -> ['only']
    lowest layer inside a group       ['Layer 1', 'grp/a', 'b']  -> unchanged
    the layer below is a group        ['Layer 1', 'grp', 'a']    -> unchanged
    the layer named is a group        ['Layer 1', 'grp/a']       -> unchanged
    the layer below is a tilemap      ['Layer 1', 'tiles', 'px'] -> unchanged

All five returned sprite info describing the stack they had failed to change, which is
the same shape a successful merge returns. Only the ordinary case worked, so an agent
flattening a stack by merging downward in a loop was told the loop had finished when it
had stopped.

Returns `merged_into`, the name of the layer the artwork went into, so the result says
what happened rather than only what the sprite now looks like.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
layerYes
filenameYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed3 schema fields changedv0.10.0
    • removedInput schema / properties / filename / title
      Removed value: -"Filename"
    • removedInput schema / properties / layer / title
      Removed value: -"Layer"
    • removedInput schema / title
      Removed value: -"merge_layer_downArguments"
  2. First observedv0.7.0

TDQS

A4.1/5.0
Behavior5/5

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

Annotations already declare destructiveHint=true and readOnlyHint=false, but the description adds rich behavioral context beyond that: it explains the refusal behavior, lists five no-op cases with measured layer-stack examples, and describes the returned merged_into field. This is exactly the kind of disclosure that helps an agent trust and correctly interpret the tool.

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

Conciseness4/5

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

The first sentence front-loads the core operation clearly. The remaining detail is useful for behavioral transparency, though the measured table and extended explanation are somewhat lengthy. Most sentences earn their place, but the definition could be tightened without losing essential meaning.

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

Completeness3/5

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

For a destructive tool with no output schema, the description does well by explaining failure modes and the merged_into return value. However, it leaves the two required parameters essentially undocumented despite 0% schema coverage, which is a notable gap for correct invocation.

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

Parameters2/5

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

Schema description coverage is 0% for two required parameters (filename and layer). The description discusses the concept of a layer but never explains parameter syntax, accepted layer identifiers, filename format, or any constraints. It does not compensate for the schema's complete lack of parameter documentation.

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

Purpose5/5

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

The description states a specific verb, resource, and direction: 'Merge a layer down into the layer directly beneath it.' This is unambiguous and distinguishes the operation from sibling tools like flatten_sprite or duplicate_layer without needing to name them explicitly.

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

Usage Guidelines4/5

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

It gives clear when-not guidance by listing five cases where Aseprite's MergeDownLayer is a no-op and explaining that this tool refuses instead. However, it does not explicitly name alternative tools or conditions for choosing them, so it falls short of full when/when-not/alternatives guidance.

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

Deploy Server

Other Tools