Opentoonz Import Images As Level

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 additivity (existing scene is loaded first), the RGBA PNG conversion and the <level_name>.%04d.png naming, 1:1 centred compositing, and — critically — that re-importing a level_name overwrites its drawings. It still omits permissions/workspace requirements and any failure or ordering-validation behavior.

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 purpose is front-loaded in one sentence, and the following paragraphs each carry distinct information (additivity/naming/compositing, then re-import semantics). It is slightly longer than necessary but every paragraph earns its place.

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?

An output schema exists, so return values need not be described. The description covers the non-obvious behaviors an agent needs — additivity, naming, compositing scale, and overwrite-on-reimport — but leaves workspace and start_row unexplained, which for a 6-parameter tool is a modest 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%, so the description must compensate for six undocumented parameters. It explains level_name (reuse/overwrite semantics), column (via repeated calls), scene (existing scene is loaded), and ordering of image_paths, but start_row and workspace are never mentioned, leaving real gaps.

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 ('import an ordered image sequence as a raster level') plus the side effect ('place it on the xsheet'). This clearly separates it from siblings like opentoonz_extract_frames, opentoonz_draw_frames, and opentoonz_set_cells, which write content by other means.

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 gives concrete when-to-use context: call repeatedly with different level_name/column to build a multi-level scene, and re-import the same level_name to iterate on art. It does not name an alternative tool or state when *not* to use this (e.g. vs. drawing frames directly), so it falls short of a 5.

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