Godot AI

Overview Schema Source Related Servers Discussions Admin

Filesystem Manage

filesystem_manage

Read, write, search, move, rename, and remove Godot project files. Reimport assets, scan for class_name updates, and preserve UID references for safe refactoring.

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 the listed files via EditorFileSystem.update_file. 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, 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

TableJSON Schema

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

Output Schema

TableJSON 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

A5/5.0

Behavior5/5

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

With no annotations, the description carries full behavioral burden and meets it thoroughly: write_text performs a single-file update rather than a full scan, reimport reports skipped_non_imported without evidence of parsing, scan is single-flight, move/rename preserve UID sidecars but refuse certain references, all mutations are non-undoable, and partial errors must not be blindly retried. This goes far beyond the schema.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is long but justified by eight distinct operations, each with non-obvious semantics. It is well structured with op bullets, a separate mutation contract section, and a canonical call shape note; no filler or redundant restatement of the schema is present.

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?

Covers operation semantics, return fields for read_text/reimport/scan, error outcomes, mutation side effects, when scans are required, and the calling convention. Since an output schema exists, detailed return shapes need not be repeated; the description provides the contextual behavior an agent needs to call and interpret results correctly.

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

Parameters5/5

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

Schema coverage is 0% because params is an opaque additionalProperties object, so the description must document every op's parameters and does so explicitly: read_text(path), write_text(path, content=''), reimport(paths), search(name, type, path, offset, limit), move(path, new_path), rename(path, new_name), and remove(path, force, permanent). The canonical call shape is also stated.

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 resource scope ('Project filesystem access via the Godot editor's EditorFileSystem') and enumerates eight concrete operations with verbs like read_text, write_text, reimport, scan, search, move, rename, and remove. This clearly distinguishes the tool from script/resource/scene-focused siblings.

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?

Provides explicit when-to-use guidance: reimport is 'intended for imported assets', scan is recommended after adding class_name scripts, and script_patch/script_create are named as the alternative for receiving fresh script diagnostics. It also specifies operational constraints like 'direct call, not batch_execute' and 'call scan afterward' for directory mutations.

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