Godot AI

Overview Schema Source Related Servers Discussions Admin

Filesystem Manage

filesystem_manage

Read, write, search, move, rename, remove, and reimport Godot project files, and run filesystem scans to register new class_name scripts after creation.

Instructions

Project filesystem access via the Godot editor's EditorFileSystem.

Ops: • read_text(path) Read a text file at a res:// path. Returns content, size, line_count. • write_text(path, content="") Create or overwrite a text file. Updates the editor filesystem entry for that one file (single-file update, not a full scan). Newly-created files include data.cleanup.rm for transient smoke tests; overwrite omits the field. • reimport(paths) Force-reimport imported assets via EditorFileSystem.reimport_files. paths is a list of res:// paths. Intended for imported assets such as textures, models, and audio. Paths that are not imported resources (.gd scripts, .tscn, hand-written .tres, or an asset the editor has not imported yet) report under skipped_non_imported rather than reimported: their filesystem entry is refreshed with update_file, but no import runs, so a success there is not evidence that a script parsed or that diagnostics were produced. Use script_patch/script_create to save a script and receive fresh diagnostics, or scan for an asset awaiting its first import. Returns reimported, skipped_non_imported, not_found and their counts. • scan() Force a full EditorFileSystem.scan() and wait for it to settle. This is the headless equivalent of the editor regaining window focus: write_text/script_create register single files but do NOT rebuild the global class_name table, so a freshly-created class_name MyThing extends Resource is invisible to resource_manage/type references until a scan runs. Call this once after adding class_name scripts when the editor isn't focused. Single-flight (awaits any in-progress scan rather than stacking another). Returns scan_completed and global_classes_registered_delta. • search(name="", type="", path="", offset=0, limit=100) Find files by name, resource type, or path substring. At least one filter must be set. Paginated. • move(path, new_path), rename(path, new_name) Move a resource group with .uid/.import sidecars and preserve proven UID references. Destination parent must exist. Literal-path owners, project settings, open scene tabs, links and incomplete discovery are refused before mutation; dependency rewriting is unsupported. • remove(path, force=False, permanent=False) Default: OS trash. Known references block unless force=True; force never overrides incomplete discovery or protected paths. Permanent deletion supports files only. Directory deletion uses trash.

move/rename/remove contract: Mutations require a direct call, not batch_execute. Directory results set scan_required: call scan afterward. All mutations are non-undoable. Errors report outcome unchanged/rolled_back/partial and actual affected paths. Never blindly retry a partial result.

Canonical call shape: {"op": "<verb>", "params": {...}}. Flat op parameters are accepted as a compatibility alias when the client transmits them; op and session_id remain top-level.

Input Schema

Name	Required	Description	Default
`op`	Yes
`params`	No
`session_id`	No

Output Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedv4.2.1Sep 22, 2026

changedInput schema / properties / op / enum

Previous value: -[
-  "read_text",
-  "reimport",
-  "scan",
-  "search",
-  "write_text"
-]New value: +[
+  "move",
+  "read_text",
+  "reimport",
+  "remove",
+  "rename",
+  "scan",
+  "search",
+  "write_text"
+]

First observedv2.9.1Jul 11, 2026

TDQS

A4.8/5.0

Behavior5/5

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

No annotations exist, so the description carries the full burden and does so: mutations are 'non-undoable', remove defaults to OS trash with force/permanent semantics, protected paths and incomplete discovery are refused before mutation, scan is single-flight, and errors report outcome unchanged/rolled_back/partial with a 'never blindly retry' warning. This is exactly the operational context an agent needs before a destructive call.

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-loaded with the one-line purpose, then bulleted per-op blocks, which is the right structure for an eight-op dispatcher. It is long but nearly every sentence earns its place; the reimport caveat about 'success there is not evidence that a script parsed' runs slightly long for the point it makes.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return shapes need not be covered, yet the description still names key return fields (reimported/skipped_non_imported/not_found, scan_completed, global_classes_registered_delta) where they carry behavioral meaning. For a complex multi-op tool with an opaque params object, nothing essential about invocation is missing apart from session_id.

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

Parameters4/5

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

Schema coverage is 0% and the nested params object is opaque, yet the description documents nearly every op parameter — path, content, paths, force, permanent, new_path, new_name, name/type/path/offset/limit defaults. The gap is session_id, which appears in the call-shape note but is never explained, and search's offset/limit semantics stay at 'Paginated'.

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?

Opens with a specific verb+resource ('Project filesystem access via the Godot editor's EditorFileSystem') and enumerates all eight operations with concrete signatures, so an agent can tell exactly which capability lives here versus resource_manage or script_patch. Sibling differentiation is explicit in the reimport and scan sections.

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

Usage Guidelines5/5

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

Gives when-to-use routing in multiple places: reimport vs script_patch/script_create for diagnostics, scan 'once after adding class_name scripts', and the constraint that move/rename/remove 'require a direct call, not batch_execute'. Exclusions are stated too — reimport lists path kinds that are skipped rather than imported.

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