3D New Era AI

Overview Schema Source Related Servers Discussions Admin

Run a plugin

run_plugin

Destructive

Execute a named plugin with JSON arguments to apply external edits via the HTTP API, returning status, output, edits, revision, resource usage, and applied limits.

Instructions

Run a plugin (an external program editing through the HTTP API) by name, with args as JSON: {ok,code,stdout,stderr,edits,revision,usage {peak_mb,cpu_s,measured},limits,not_applied}. A plugin as heavy as a modeler gets the limits its plugin.json declares (cores, memory, priority, time) that this system can apply, not_applied naming the rest, and runs alone, never beside a photo render. The plugins tool lists them.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`args`	No	Arguments passed to the plugin as JSON
`name`	Yes	Plugin to run, by name (the plugins tool lists them)

Output Schema

TableJSON Schema

Name	Required	Description	Default
`ok`	Yes
`code`	No
`edits`	Yes
`usage`	No
`limits`	No
`stderr`	Yes
`stdout`	Yes
`revision`	Yes
`timed_out`	No
`not_applied`	No

Schema Changelog

Changes observed during successful MCP inspections.

Changed10 schema fields changedv3.0.0Sep 30, 2026
- removedOutput schema / properties / code / description
```
Removed value: -"Exit code; null when it was stopped"
```
- removedOutput schema / properties / edits / description
```
Removed value: -"Changes it made"
```
- addedOutput schema / properties / limits
```
Added value: +{
+  "items": {
+    "type": "string"
+  },
+  "type": "array"
+}
```
- addedOutput schema / properties / not_applied
```
Added value: +{
+  "items": {
+    "type": "string"
+  },
+  "type": "array"
+}
```
- removedOutput schema / properties / ok / description
```
Removed value: -"The plugin exited cleanly"
```
- removedOutput schema / properties / revision / description
```
Removed value: -"Plan revision after it"
```
- removedOutput schema / properties / stderr / description
```
Removed value: -"What it complained"
```
- removedOutput schema / properties / stdout / description
```
Removed value: -"What it printed"
```
- removedOutput schema / properties / timed_out / description
```
Removed value: -"It ran out of time"
```
- addedOutput schema / properties / usage
```
Added value: +{
+  "type": "object"
+}
```
First observedv0.1.0Sep 24, 2026

TDQS

A4.1/5.0

Behavior4/5

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

Annotations already flag destructive/openWorld/not-readOnly, and the description adds real substance: resource limits declared in plugin.json, which limits are impossible to apply (not_applied), and the serialization rule against photo renders. It also restates the return shape, which is partly redundant given an output schema exists.

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?

Front-loads the verb and resource, then layers behavior; every sentence carries information. The dense parentheticals and the inline return-shape blob make it slightly heavy for its purpose.

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?

Covers the mutation's side effects, naming convention, and concurrency rule, which is what an agent needs for a destructive open-world tool. An output schema already exists, so the inline return-field list is redundant rather than necessary.

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

Parameters3/5

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

Schema coverage is 100% and both parameters are documented there, so baseline 3 applies. The description says 'by name' and 'args as JSON' but adds no argument syntax or format detail beyond the schema.

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), resource (plugin), and distinguishes it from the sibling that lists plugins ('The plugins tool lists them'). The parenthetical defines what a plugin is, so an agent can pick this over 'plugins' without opening a 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?

Names the sibling to use for discovery ('the plugins tool lists them') and gives a concurrency constraint ('runs alone, never beside a photo render'), which is clear usage context. It stops short of explicit when-not-to-use guidance beyond that one exclusion.

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