Skip to main content
Glama
MalloyTheDev

Aseprite MCP

by MalloyTheDev
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

set_color_mode

Destructive

Convert sprites between RGB, indexed, and grayscale modes. For indexed output, builds the palette from the artwork and refuses conversions that would erase drawn pixels.

Instructions

Convert a sprite between colour modes ("rgb", "indexed", "gray").

Converting **to indexed** builds the palette from the sprite's own colours first,
which is what the editor does and what makes the art survive. Mapping art against
whatever palette the sprite happened to carry is how this tool used to empty a
sprite: a saved RGB sprite carries a single transparent entry, so every pixel
resolved to it and the whole image became transparent while the call reported ok.

Args:
    color_mode: "rgb", "indexed", or "gray".
    dithering: "none" (default), "ordered", or "old". How a colour between two
        palette entries is resolved. Indexed conversions only.
    palette_source: "from_art" (default) quantizes the sprite's colours into a new
        palette and maps onto that, so flat colours convert exactly. "keep" maps
        against the palette the sprite already has, for when you loaded or built one
        deliberately; snapping the art to that palette is the point, so expect
        colours to shift, and expect two art colours to merge where the palette has
        only one entry near them. Indexed conversions only; the other modes have no
        palette to choose.

**Refuses** a conversion to indexed that would make drawn pixels disappear, naming
how many, and leaves the file untouched when it does. Losing colour accuracy is what
indexed mode is for and is allowed; losing pixels is not recoverable and is the one
thing a mode change must never do quietly. `set_palette` or `add_palette_color` fix a
palette that has nothing to draw with.

That check counts every pixel of every frame, twice. Past `MAX_VERIFY_PIXELS` the
conversion still runs and reports `verified: false` with the reason, rather than
being refused: a capability that declines to work on a large sheet because the check
is unaffordable is worse than one that works and says what it did not check.
`diff_sprites` against a copy taken beforehand answers the same question by hand.

Returns the sprite's structured info, plus `drawn_pixels` and `verified` (whether
that count was actually compared across the conversion) and the `palette_source`
used, for indexed targets.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
filenameYes
ditheringNoDefault: "none".none
color_modeYes
palette_sourceNoDefault: "from_art".from_art

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed6 schema fields changedv0.10.0
    • removedInput schema / properties / color_mode / title
      Removed value: -"Color Mode"
    • addedInput schema / properties / dithering / description
      Added value: +"Default: \"none\"."
    • removedInput schema / properties / dithering / title
      Removed value: -"Dithering"
    • removedInput schema / properties / filename / title
      Removed value: -"Filename"
    • addedInput schema / properties / palette_source
      Added value: +{
+  "default": "from_art",
+  "description": "Default: \"from_art\".",
+  "type": "string"
+}
    • removedInput schema / title
      Removed value: -"set_color_modeArguments"
  2. First observedv0.7.0

TDQS

A4.7/5.0
Behavior5/5

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

Annotations declare destructiveHint=true, and the description goes well beyond that: it documents the refusal precondition (indexed conversions that would erase drawn pixels, with a count reported and the file left untouched), the large-sheet fallback where MAX_VERIFY_PIXELS is exceeded and the call proceeds with verified:false, and the historical failure mode that motivates the check. This is exactly the kind of behavioral context annotations cannot carry.

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?

It is front-loaded with the conversion itself and then uses a clear Args block, so structure is good. It runs long, however, and the aside about how the tool 'used to empty a sprite' plus the doubled pixel-count detail could be trimmed without losing the operational guarantee.

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

Completeness5/5

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

With no output schema present, the description still specifies the return payload (structured sprite info plus drawn_pixels, verified, palette_source for indexed targets) and covers the refusal path, the unverified-large-sheet path, and the palette_source default. Nothing an agent needs to call it safely is missing.

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

Parameters5/5

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

Schema coverage is 50% - filename and color_mode have no schema descriptions and dithering/palette_source only carry a default string. The description compensates fully, documenting each value of color_mode, the three dithering behaviours and their indexed-only scope, and the two palette_source strategies including when colours will shift or merge.

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 first sentence gives a specific verb (Convert) and resource (a sprite between colour modes) and enumerates the three target modes, which pins the operation precisely against palette-oriented siblings like set_palette, quantize_palette and cycle_palette. An agent can tell what changes and what the input domain is 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.

Usage Guidelines4/5

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

It gives real guidance on option selection - dithering applies to indexed only, palette_source=from_art vs keep with the consequences of each - and routes agents to set_palette/add_palette_color when a palette is unusable and to diff_sprites for manual verification. It never states explicitly when to choose this tool over a sibling conversion/quantization tool, so it stops short of full when/when-not coverage.

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