Skip to main content
Glama
aseprite-claude-connector

aseprite-claude-connector

run_lua

Destructive

Execute custom Lua scripts inside Aseprite to automate pixel art edits, query canvas data, and return JSON results as a single undoable step.

Instructions

Run arbitrary Lua inside Aseprite and return its result (advanced escape hatch — equivalent to local code execution). J(value) is available for JSON returns; wrap your own edits in app.transaction for clean undo. The prelude also provides editCel(fn) and findLayer(s, name). Set save=true (headless) to persist changes to file. Your code must return a value. Set edit=true when the code only edits the active sprite: it then runs as one undo step, under the pixel cap and dry run. Without edit the rails don't apply, and in a dry run this tool refuses to run.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "code": "<code>"
    },
    "name": "run_lua"
  }
}

Input Schema

NameRequiredDescriptionDefault
codeYes
editNo
fileNo
saveNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.4.0

TDQS

A4.4/5.0
Behavior5/5

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

Annotations already flag destructive and open-world, and the description layers substantial extra behavior on top: single undo step under edit=true, pixel cap and dry-run rails, refusal in dry runs without edit, headless save semantics, mandatory return value, and the app.transaction wrapping convention. This is exactly the context an agent needs before executing arbitrary code.

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

Conciseness3/5

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

The purpose is front-loaded and every sentence carries information, but the edit/dry-run semantics are split across non-adjacent sentences, forcing the reader to reassemble the rule. Parenthetical asides and doubled backticks add visual noise to an otherwise dense but accurate block.

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

Completeness4/5

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

For a destructive, 4-parameter, no-output-schema tool, the definition covers return values, undo behavior, safety rails, and persistence. Minor gaps remain around what file does outside headless mode and how failures surface, but the essential execution contract is present.

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

Parameters4/5

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

Schema description coverage is 0%, so the description must carry the burden, and it does for code (must return a value, J() helper), edit (undo step, pixel cap, dry run), save (persist to file, headless), and file (save target). The file parameter's expected format/path semantics are only implied by 'persist changes to file,' leaving a small gap.

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?

States a specific verb (run) and resource (arbitrary Lua in Aseprite), plus the return behavior and the explicit framing as an 'advanced escape hatch — equivalent to local code execution.' That framing distinguishes it cleanly from the specialized editing siblings like add_fire or box_blur.

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?

Gives concrete conditional guidance: set edit=true when the code only edits the active sprite, set save=true (headless) to persist to file, and dry runs refuse to run without edit. It implies fallback usage via 'escape hatch,' but never explicitly says to prefer a specialized sibling tool when one exists for the operation.

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