execute_aseprite_script

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

With no annotations, the description carries the full burden, and it does disclose the important runtime model: headless batch execution and that the script itself must save the output. It says nothing about execution limits, timeouts, error/sandbox behavior for arbitrary Lua, or what happens when the expected output file is never produced, which are meaningful gaps for a code-execution 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?

Three short sentences, front-loaded with the core action, then the composition guidance, then the prerequisite. Every sentence carries distinct information and none restates the name or 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?

With no output schema, the description should ideally say what comes back (e.g. verification of output_filename, captured stdout). The output_filename schema hints at result verification, and the description covers the script/Save contract, so an agent can call it correctly, but return-value behavior is left implicit.

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

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

Schema description coverage is 100%, so both parameters are already documented in the schema, including path resolution and the save/verify contract for output_filename. The description adds no parameter detail beyond what the schema provides, which is the expected baseline when the schema does the work.

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 ('Run a complete Aseprite Lua script') and even names the underlying invocation ('aseprite --batch --script'), so the mechanism is unambiguous. It also distinguishes itself from the sibling tool by pointing at get_aseprite_lua_docs for API reference rather than execution.

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 states the key usage pattern explicitly: 'Write the whole drawing/animation/export as one script instead of many small calls,' and gives a prerequisite ('Call get_aseprite_lua_docs first if unsure'). It stops short of naming when NOT to use it or what a 'small call' alternative would actually be, so the routing advice is clear but not exhaustive.

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