Godotwright

Overview Schema Source Related Servers Discussions Admin

Find what leaks per scene reload

godot_leaks

Cycles a Godot scene headless to detect object and orphan-node leaks, reporting per-cycle growth with classes, scripts, scenes, and the code that creates or removes them.

Instructions

Run a scene in Godot 4.7 headless in cycles (load, run cycle_frames frames, free; or keep: true to keep it running), snapshot the live objects after each cycle and report what grows per cycle after the warm-up: orphan nodes by class, script and scene with the parent they were removed from, the code that makes them and the remove_child() that dropped them; nodes left in the tree; objects that are not nodes, with the classes Godot still held at exit (--verbose) and the static or autoload containers that grow. input replays a timeline in every cycle. An error result when objects or orphan nodes grow more than the budget per cycle (default 0). Compares with the last run with the same mode, cycle_frames and input (.godot/godotwright/leaks/).

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "godot_leaks"
  }
}

Input Schema

Name	Required	Description
`keep`	No	keep the scene running instead of freeing it each cycle
`path`	No	project folder, or a file or folder inside it (relative to the server's folder; default: the current project)
`input`	No	timeline replayed each cycle: "10 press load; 40 press unload"
`scene`	No	the res:// scene to cycle (default: the main scene)
`cycles`	No	cycles (default 5)
`warmup`	No	first cycles not counted (default 1)
`cycle_frames`	No	frames per cycle (default 60)
`timeout_seconds`	No	timeout of the run (default 300)
`objects_per_cycle`	No	allowed object growth per cycle (default 0)
`orphans_per_cycle`	No	allowed orphan-node growth per cycle (default 0)

Schema Changelog

Changes observed during successful MCP inspections.

Addedv0.6.0Nov 5, 2026

TDQS

A3.8/5.0

Behavior4/5

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

Annotations only declare the safety profile (not read-only, not destructive, closed-world, not idempotent); the description goes further by disclosing the failure contract (error result when objects or orphan nodes exceed the per-cycle budget) and the persistence behavior (results compared against the last run with the same mode, cycle_frames and input under .godot/godotwright/leaks/). It also reveals that Godot is launched headless with --verbose to capture classes held at exit, which explains runtime cost and output provenance.

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 core operation is front-loaded, but the body is a single dense run-on sentence with nested parentheticals and semicolon-chained clauses about report contents. The information is valuable yet would scan far faster as two or three shorter sentences or a short bulleted breakdown of the report sections.

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 ten-parameter tool with no output schema, the description does the heavy lifting: it enumerates what the report contains, the conditions that produce an error, and the cross-run comparison state. Only the run-folder path semantics and timeout behavior are unaddressed, which the fully-described schema already covers.

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%, so the schema already documents all ten parameters and the baseline applies. The description adds modest meaning by tying `keep`, `input` (replayed every cycle), `warmup`, and the default-0 budgets into the leak-detection model, but `path`, `timeout_seconds` and the numeric bounds are left entirely to 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 and resource chain: run a scene headless in cycles, snapshot live objects, report what grows per cycle. The report contents (orphan nodes by class/script/scene, parent they were removed from, remove_child() call site, non-node objects, static/autoload containers) make it unmistakably a leak profiler rather than godot_perf or godot_check.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Implicit guidance is strong: it explains the load/run/free cycle, the `keep: true` variant, warm-up exclusion, and that growth over budget yields an error result, which tells an agent this is a regression gate after scene reloads. But it never names an alternative (godot_perf, godot_check) or states when not to use it, so routing between profiling siblings is left to inference.

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