Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@opentoonz-mcp Find the levels used in scenes/MyScene.tnz and validate their paths"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
opentoonz-mcp is a local, safety-first Model Context Protocol server for OpenToonz workspaces. It gives an MCP client useful, structured access to project and scene metadata, resource validation, level discovery, rendering, and level conversion without exposing a general-purpose shell.
The server is intentionally a sidecar. It does not patch or embed OpenToonz. Instead, it reads OpenToonz's XML-like project and scene files directly for fast inspection and invokes the existing tcomposer and tconverter command-line programs for operations that require OpenToonz's native runtime.
This repository contains the first usable read-mostly release:
Read-only project, scene, level, and artifact discovery.
Scene header inspection and serialized level/scanned-path extraction.
Alias-aware resource validation for +drawings, +scenes, $scenefolder, $scenepath, and $scenename paths.
Preview rendering and scene rendering through tcomposer.
Level conversion through tconverter.
Stdio transport for local MCP clients.
One static resource, one scene resource template, and a reusable scene-health prompt.
Tests for path sandboxing, symlink escape rejection, project discovery, and scene resource validation.
The server does not expose arbitrary command execution, arbitrary .toonzscript execution, tcleanup, render-farm administration, or direct scene mutation.
Related MCP server: workspace-mcp
Node.js 20 or newer.
A built OpenToonz checkout if rendering or conversion is needed.
An MCP client that supports stdio servers.
The OpenToonz source checkout used while designing this server is expected to have a layout similar to:
workspace/
├── toonz/ # OpenToonz source checkout
│ └── build/bin/
│ ├── tcomposer
│ └── tconverter
└── opentoonz_mcp/ # this repositoryThe MCP server can inspect an unbuilt workspace. Only the rendering and conversion tools require the corresponding binaries.
cd opentoonz_mcp
npm install
npm run typecheck
npm test
npm run buildThe executable is written to dist/index.js and is also exposed as the opentoonz-mcp npm bin entry.
Build the server first, then add a stdio server entry to the client. The exact settings file varies by client; the following is the portable shape:
{
"mcpServers": {
"opentoonz": {
"command": "node",
"args": ["/absolute/path/to/opentoonz_mcp/dist/index.js"],
"env": {
"OPENTOONZ_WORKSPACE": "/absolute/path/to/opentoonz_project_and_mcp/opentoonz",
"OPENTOONZ_BUILD_DIR": "/absolute/path/to/opentoonz_project_and_mcp/opentoonz/toonz/build",
"OPENTOONZ_ROOT": "/absolute/path/to/opentoonz_project_and_mcp/opentoonz"
}
}
}
}OPENTOONZ_WORKSPACE is the important setting. If it is omitted, the current working directory is used. When the server is started from a directory named opentoonz_mcp with a sibling opentoonz directory, the sibling is selected as a convenience fallback.
Variable | Default | Purpose |
| current directory, or sibling | Root directory that all paths must remain inside |
| workspace root | OpenToonz runtime root; the server seeds isolated |
|
| Directory containing |
| discovered build binary | Explicit |
| discovered build binary | Explicit |
|
| Default output directory for generated artifacts |
|
| Isolated |
|
| Optional native library path for build-tree binaries |
|
| Default subprocess timeout |
|
| Captured stdout/stderr limit per subprocess |
|
| Filesystem discovery limit |
|
| Maximum project, scene, and |
|
| Maximum concurrent metadata inspections |
Tool | Writes files? | Description |
| No | Workspace roots, discovered counts, and available binaries |
| No | Finds project descriptors and parses folder aliases |
| No | Inspects one project descriptor |
| No | Finds |
| No | Reads scene header and serialized resource references |
| No | Resolves aliases and reports missing/external resources |
| No | Lists recognized level and image files |
| No | Lists files produced by this server |
| Yes, artifact only | Renders one frame with |
| Yes, artifact/output | Renders a frame or frame range with |
| Yes, new output only | Converts a level with |
All generated outputs must be new paths inside the configured workspace. Existing files are rejected before OpenToonz starts, which prevents tconverter from blocking on its interactive overwrite prompt.
Rendering is stricter than inspection: render_preview and render_scene first validate that all discovered scene resources are present and resolve inside the configured workspace. Scenes that intentionally depend on external media must be copied into the workspace or handled outside this MCP server.
opentoonz://workspace/manifest — live JSON workspace manifest.
opentoonz://scene/{+path} — read-only scene summary resource template. The reserved URI expansion allows nested workspace-relative paths.
review-scene-health — prompt that directs an MCP client to inspect a scene and validate its resources before discussing changes.
Workspace sandbox: relative and absolute inputs are canonicalized and checked against OPENTOONZ_WORKSPACE.
Symlink escape protection: existing paths are resolved through the filesystem before the containment check.
No shell: subprocesses use spawn() with an argument array and shell: false.
Bounded execution: render and conversion calls have a timeout and bounded captured output.
No accidental overwrite: generated outputs must not exist before an operation starts.
No arbitrary scripts: .toonzscript execution is intentionally not exposed.
Read-only first: the initial API focuses on inspection and artifact-producing operations; it does not save scenes or levels in place.
See docs/architecture.md for the rationale and extension rules.
Useful commands:
npm run dev # start the stdio server with tsx
npm run typecheck # TypeScript validation, including tests
npm test # node:test suite through tsx
npm run build # production JavaScript in dist/Do not print diagnostics to stdout while the server is running: stdout is the MCP JSON-RPC channel. Operational diagnostics belong on stderr.
OpenToonz scene files are not a stable public JSON format. The server therefore limits direct parsing to stable, low-risk metadata patterns: the scene header and <path> / <scannedPath> values used by serialized level records. Rendering and conversion are delegated to OpenToonz's own binaries so codec and scene behavior remain native to the installed build.
The source repository contains upstream and origin remotes for OpenToonz. This MCP implementation remains in its own repository so it can evolve independently and avoid mixing MCP changes with the OpenToonz application history.
This MCP server is released under the MIT License. OpenToonz itself remains under its own license; see the OpenToonz checkout for its licensing terms and third-party notices.
Convert a level with tconverter into a new destination. Existing files are refused to avoid interactive overwrite prompts and accidental data loss.
| Name | Required | Description | Default |
|---|---|---|---|
| width | No | ||
| frameEnd | No | ||
| scenePath | No | ||
| timeoutMs | No | ||
| frameStart | No | ||
| sourcePath | Yes | ||
| destinationPath | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral burden. It usefully discloses that existing files are refused to avoid overwrite prompts and accidental data loss, which is important safety context for a mutation tool, but it omits dependencies such as tconverter availability, permission requirements, side effects, and failure 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 description is two tight sentences with the action front-loaded and no wasted wording. Its brevity is appropriate structurally, though it leaves important details unstated.
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 seven parameters, no annotations, no output schema, and 0% schema description coverage, the description is not complete enough for an agent to invoke the tool confidently. It covers the overwrite-refusal behavior but not parameter meanings, prerequisites, or expected results.
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% across seven parameters, so the description must compensate and does not. 'Level' and 'destination' only loosely imply sourcePath and destinationPath, while width, frameStart, frameEnd, scenePath, and timeoutMs receive no explanation at all.
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 states a specific verb and resource: 'Convert a level ... into a new destination.' It is clear what the tool does, but it does not differentiate the tool from any sibling, such as render_scene or render_preview, which could be confused with conversion-adjacent operations.
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?
The only usage-relevant statement is 'Existing files are refused,' which is a constraint rather than guidance on when to use this tool versus alternatives. There is no mention of prerequisites, when conversion is appropriate instead of other level/scene operations, or how it relates to siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Parse one OpenToonz project descriptor and report its version, logical folder aliases, resolved in-workspace paths, and warnings.
| Name | Required | Description | Default |
|---|---|---|---|
| projectPath | Yes | Workspace-relative or absolute project descriptor path |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description carries the burden. 'Parse ... and report' implies a read-only, non-mutating inspection and the mention of 'warnings' hints at tolerant parsing, but it says nothing about invalid-path behavior, error surfacing, or whether partial data is returned.
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?
One well-formed sentence with no filler, and the verb and scope lead. It stops short of 5 only because the enumerated return fields could be structured more crisply.
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 usefully enumerates what comes back (version, aliases, resolved paths, warnings), which is the key missing structured information. Minor gap: no guidance on failure or path-resolution rules for a single-param tool.
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 coverage is 100% and the single param already documents 'workspace-relative or absolute project descriptor path.' The description adds nothing about path resolution semantics beyond the word 'resolved,' so baseline 3 applies.
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?
Specific verb + resource: 'Parse one OpenToonz project descriptor and report its version, folder aliases, resolved paths, and warnings.' It clearly covers one project, which distinguishes it from list_projects and inspect_scene, though it never explicitly names those siblings.
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?
Usage is implied only: an agent infers this is the per-project inspection step after list_projects. There is no explicit when-to-use, when-not-to-use, or named alternative such as inspect_scene for scene-level details.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read scene header metadata and extract serialized level/scanned-path references without loading or mutating scene resources.
| Name | Required | Description | Default |
|---|---|---|---|
| scenePath | Yes | Workspace-relative or absolute .tnz/.tab path |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description does useful work by disclosing that the tool reads metadata and extracts references without loading or mutating scene resources. That clarifies the safety profile and lightweight nature of the operation, though it does not describe error behavior or output format.
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 definition is a single front-loaded sentence with no wasted words. It places the key read-only, non-loading constraint immediately after the core purpose.
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?
For a simple one-parameter inspection tool with no output schema, the description communicates the core return content (header metadata and serialized references) and the non-mutating behavior. It could be more complete by sketching the return shape, but it is adequate for correct invocation.
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 the single scenePath parameter is already fully documented with its accepted .tnz/.tab forms. The description adds no additional parameter semantics, which is acceptable given the schema coverage.
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 states a specific verb (read/extract) and specific resources (scene header metadata, serialized level/scanned-path references). It distinguishes the operation from heavier actions by saying it works without loading or mutating scene resources, though it does not explicitly name sibling tools.
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?
The phrase 'without loading or mutating scene resources' implies a lightweight inspection use case, but there is no explicit guidance on when to choose this over validate_scene_resources, list_scenes, or inspect_project. Usage is inferable rather than stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List files produced by MCP render and conversion operations in the configured artifact directory.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. 'List' implies a read-only operation and the configured directory is identified, but the description does not disclose return structure, ordering, recursion behavior, or what happens if the directory is empty or missing.
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?
A single efficient sentence that front-loads the action and resource with no wasted words.
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?
For a simple zero-parameter listing tool, the description covers what is listed and where, which is enough to select and invoke it. Because no output schema exists, a brief note about return contents would improve completeness, but the core need is met.
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?
The tool has zero parameters, and the schema is empty, so there is nothing for the description to clarify. Baseline 4 applies for a parameterless tool.
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?
States a specific verb ('List') and resource ('files produced by MCP render and conversion operations'), plus the location ('configured artifact directory'). This distinguishes artifacts from sibling tools like list_scenes or list_level_files, though it does not explicitly name an alternative.
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?
Usage is implied by the scope: use this to see outputs of render/conversion operations. However, there is no explicit when-to-use guidance, no when-not-to-use exclusions, and no mention of sibling alternatives such as render_preview or workspace_manifest.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List recognized OpenToonz drawing, vector, raster, palette-adjacent, and image level files under an optional workspace-relative directory.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| directory | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations at all, the description carries the full burden. It does disclose two real behaviors beyond the schema: results are limited to 'recognized' level file types (filtering semantics) and the directory is workspace-relative (path resolution rule). It says nothing about recursion, ordering, whether the limit truncates silently, or permission requirements.
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?
A single front-loaded sentence with no filler; the scoping information (optional directory) arrives before the file-type enumeration. Nothing in it could be cut without losing content.
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?
No output schema and no annotations, yet the description does not say what a result entry looks like, whether paths returned are absolute or workspace-relative, how ordering works, or how limit interacts with the listing. For a listing tool with two undocumented parameters, these gaps matter to correct invocation.
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 both parameters are undocumented in structured fields. The description explains only that directory is optional and workspace-relative; the limit parameter (max 10000, exclusiveMinimum 0, default behavior) is never mentioned, leaving half the surface unexplained.
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?
States a specific verb (List) and resource (OpenToonz level files) and even enumerates the level categories covered (drawing, vector, raster, palette-adjacent, image). It does not differentiate itself from nearby siblings such as list_artifacts or list_scenes, so an agent must infer whether 'level files' is a subset of artifacts.
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?
No statement of when to use this versus list_artifacts, list_scenes, or workspace_manifest, and no prerequisites or exclusions. The only usage hint is the implicit 'optional workspace-relative directory' scoping.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Discover OpenToonz project descriptors inside the workspace. Results are read-only and include project folders and parser warnings.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
There are no annotations, so the description carries the behavioral burden. It usefully says results are read-only and mentions that results include project folders and parser warnings, but it does not explain ordering, pagination, limit behavior, or error cases.
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 description is two compact sentences with no wasted language, and the core purpose is front-loaded before the result-content note.
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?
For a simple listing tool with no annotations and no output schema, the description covers purpose, read-only behavior, and partial return contents. However, it leaves the limit parameter and the exact result shape under-specified.
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?
The single parameter 'limit' has 0% schema description coverage and is not mentioned in the description at all. The schema provides type and bounds, but the description adds no meaning about how the limit affects listing behavior.
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 states a specific verb and resource: discovering OpenToonz project descriptors inside the workspace. It is clear what the tool does and implicitly contrasts with sibling inspection tools, though it does not explicitly name alternatives such as inspect_project.
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?
The description gives no explicit when-to-use guidance, no exclusions, and no routing to sibling tools like inspect_project or list_scenes. Workspace scoping is stated, but that is context rather than usage guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Discover .tnz and legacy .tab scenes. Optionally scope results to a project directory or descriptor.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| projectPath | No | Optional project descriptor or project directory |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral burden. It implies a read-only discovery operation but says nothing about the default scan scope when no projectPath is given, whether scanning is recursive, what the cap on 'limit' means in practice, or how results are ordered — all essential for a filesystem-scanning 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?
Two short sentences, front-loaded with the resource being listed and followed by the scoping option. Nothing is wasted, though 'Discover' is slightly opaque about whether it returns paths, names, or metadata.
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 and no annotations, the definition should explain what a result entry looks like and what happens when no scope is supplied. Neither is covered, and the undocumented limit parameter compounds the gap for a tool that may scan an entire workspace.
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?
Only projectPath is documented in the schema, and the description merely restates it as 'project directory or descriptor' while adding the useful hint that it is optional. The limit parameter (with a 5000 maximum) is undocumented in both schema and description, leaving half the parameters unexplained.
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 names a specific verb-plus-resource: discovering .tnz and legacy .tab scenes, including the file formats, which makes it concrete. It does not explicitly distinguish itself from siblings like list_projects, list_artifacts, or inspect_scene, so the agent must infer the boundary itself.
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?
'Optionally scope results to a project directory or descriptor' implies the two usage modes (workspace-wide versus project-scoped), but never states when to prefer this over inspect_scene or list_projects. The trade-off between a broad scan and a scoped one is left to the agent to work out.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Render one scene frame with tcomposer into a new .mcp-artifacts file. Existing files are never overwritten. Requires a built tcomposer executable.
| Name | Required | Description | Default |
|---|---|---|---|
| frame | No | ||
| shrink | No | ||
| threads | No | ||
| scenePath | Yes | ||
| timeoutMs | No | ||
| outputPath | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description does useful work by disclosing that output goes to a new .mcp-artifacts file, that existing files are never overwritten, and that a built tcomposer binary is required. It does not say what happens if outputPath already exists, what is returned, or how timeoutMs/shrink/threads affect behavior, so the burden is only partly met.
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 with zero filler; the action, the safety guarantee, and the prerequisite all appear up front. Nothing in the text is redundant with the title or with itself.
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?
For a six-parameter tool with no annotations and no output schema, the description covers purpose and safety but leaves parameter meaning and return values entirely unaddressed. An agent could call it, but not confidently configure frame, shrink, threads, or timeout.
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% across six parameters, and the description explains none of them — frame, shrink, threads, timeoutMs, and outputPath are all left for the agent to guess. The only hint is that output lands in a 'new' file, which loosely implies outputPath is never overwritten.
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?
States a specific verb and resource: render a single scene frame with tcomposer, writing to a new .mcp-artifacts file. The 'one scene frame' scope distinguishes it in spirit from render_scene, but it never names that sibling, so an agent must infer the split.
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?
Usage is only implied by 'Render one scene frame' and the stated prerequisite of a built tcomposer executable. There is no explicit when-to-use/when-not, and the obvious alternative render_scene is never mentioned or contrasted.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Render an image sequence or output file with tcomposer. The destination must be new and inside the configured workspace; no arbitrary shell commands are exposed.
| Name | Required | Description | Default |
|---|---|---|---|
| step | No | ||
| frame | No | ||
| shrink | No | ||
| threads | No | ||
| frameEnd | No | ||
| scenePath | Yes | ||
| timeoutMs | No | ||
| frameStart | No | ||
| outputPath | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure. It usefully states that the destination must be new and inside the configured workspace, and that no arbitrary shell commands are exposed, which adds security-related context. However, it omits important behavior such as overwrite handling beyond 'new', permission requirements, failure modes, and what the render produces.
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?
Two tight sentences with no wasted words. The core action is front-loaded, and the safety constraint follows immediately.
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?
For a 9-parameter rendering tool with no annotations and no output schema, the description is too thin. It should explain frame-range controls, timeout behavior, and output expectations, none of which are covered.
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% across 9 parameters, so the description must compensate. It only clarifies that outputPath must be new and inside the workspace; it says nothing about scenePath, frame, frameStart, frameEnd, step, shrink, threads, or timeoutMs, leaving most parameters semantically undocumented.
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 states a specific verb and resource: render an OpenToonz scene to an image sequence or output file using tcomposer. It is clear what the tool does, but it does not explicitly differentiate its purpose from the sibling render_preview tool.
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?
There is no explicit guidance on when to use this tool versus render_preview or the other sibling tools. The distinction between a full render and a preview is implied by the tool name only, leaving the agent to infer the appropriate context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Resolve scene path aliases and report missing or workspace-external level and scanned-image references. This is read-only.
| Name | Required | Description | Default |
|---|---|---|---|
| scenePath | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description must carry the behavioral burden, and it does disclose the read-only nature plus the non-obvious behavior that it resolves aliases before reporting. It does not say whether missing references cause an error or a report, nor anything about response shape or performance on large scenes.
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?
Two short sentences, front-loaded with the operation and followed by the read-only guarantee. No filler and nothing redundant.
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?
For a simple one-parameter read-only check with no output schema, the description covers what it does and its safety profile adequately. It stops short of describing what the report looks like or how an agent should interpret 'workspace-external', which matters for acting on the result.
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% for the single required scenePath, so the description has to compensate. It references 'scene path aliases', which hints that scenePath may be an aliased identifier, but it never states what form the path takes (absolute, project-relative, alias) or whether aliases are resolved from a workspace manifest.
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 pairs a specific verb ('resolve') with a concrete resource ('scene path aliases') and states the report content (missing or workspace-external level and scanned-image references). It clearly distinguishes a validation task from rendering or listing siblings, though it never names an alternative tool explicitly.
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?
Usage is implied rather than stated: an agent can infer this is a pre-flight check for broken/external references, and 'This is read-only' signals a safe inspection step. There is no explicit when-to-use versus siblings like inspect_scene or render_scene, nor any stated precondition or exclusion.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return a live manifest of the configured workspace, discovered projects/scenes/levels, runtime paths, and available OpenToonz command-line capabilities.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the behavioral burden. 'Return' and 'live manifest' imply a read-only, current-state discovery operation and disclose the categories returned, but the description does not explicitly confirm non-mutation, permission requirements, or scan cost.
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 description is a single front-loaded sentence with no filler. Every listed clause contributes to the scope of the returned manifest.
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 must carry the return-value explanation. It names the high-level categories in the manifest but does not describe their shape or level of detail. Combined with missing usage guidance against the many sibling tools, it is adequate but incomplete.
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?
The tool has zero parameters, and the description correctly describes a parameterless workspace inspection operation. Per the zero-parameter baseline, a 4 is appropriate.
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-resource pair: return a live manifest of the configured workspace. It also names the contents: projects, scenes, levels, runtime paths, and CLI capabilities. It is clear as an aggregate workspace-discovery tool, but it does not explicitly distinguish itself from sibling tools such as list_projects, list_scenes, or inspect_project.
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?
No sentence states when to use this tool rather than list_projects, inspect_project, list_scenes, or the other siblings. The aggregate-manifest phrasing implies broad workspace orientation, but that is left to inference and no exclusions or alternatives are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0convert_levelinspect_projectinspect_scenelist_artifactslist_level_fileslist_projectslist_scenesrender_previewrender_scenevalidate_scene_resourcesworkspace_manifestScored across 11 tools
Most tools target clearly distinct resources or actions: listing projects, scenes, levels, and artifacts is separate from inspecting and validating them. The main potential confusion is between render_preview and render_scene, and somewhat between workspace_manifest and the various list/inspect tools, though the descriptions clarify the intended boundaries.
The set is mostly consistent snake_case with verb_noun patterns such as list_projects, inspect_scene, render_scene, and convert_level. The notable deviation is workspace_manifest, which is noun-based rather than following the verb_noun convention.
Eleven tools is well within a reasonable range and each tool appears to earn its place by covering discovery, inspection, validation, rendering, conversion, or artifact listing. The surface is broad enough for the OpenToonz workflow without feeling excessive.
The server covers the core inspection and production lifecycle: discovering projects/scenes/levels, inspecting metadata, validating resources, rendering previews and sequences, converting levels, and listing artifacts. Minor gaps remain, such as direct inspection of individual level files or artifact management beyond listing, but agents can work around these.
Control Unreal Engine to browse assets, import content, and manage levels and sequences. Automate…
Give every project one workspace for its files, its team, and its AI agents.
Build and publish pages, manage collections, records and files in a Markerloop workspace.
Fast multi-format CAD previews, geometry checks and conversion; measure and share in the workspace.