godot-omni

Overview Schema Source Related Servers Discussions Admin

filesystem_manage

Manage Godot project files: read/write text, reimport assets, list, move, delete, scan, search, and download assets via the editor's filesystem.

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. • list(path="res://", recursive=False, max_depth=1) Browse the project's res:// tree (files, sizes, UIDs, and directories). • delete(path) Delete a file or directory from the project along with its .uid and .import sidecars. • move(from_path, to_path) Move or rename a file in the project, keeping sidecars consistent. • 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. • download_asset(url, path, extract=False, reimport=True) Download an asset or zip archive from the internet directly into the Godot project (res:// path). If extract=True or archive is zip, extracts into target directory. Automatically triggers editor reimport and scan. Returns: {url, path, size_bytes, is_archive, extracted_files, reimport_result} • search_assets(query="", category="all", limit=20) Search curated free/CC0 game assets (tilesets, audio, textures, UI, 3D models). Categories: "all", "tileset", "audio", "texture", "ui". Returns matching assets with direct download URLs ready for download_asset.

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 changedv5.0.9Sep 19, 2026

changedInput schema / properties / op / enum

Previous value: -[
-  "read_text",
-  "reimport",
-  "scan",
-  "search",
-  "write_text"
-]New value: +[
+  "asset_search",
+  "delete",
+  "download_asset",
+  "download_file",
+  "list",
+  "move",
+  "read_text",
+  "reimport",
+  "scan",
+  "search",
+  "search_assets",
+  "write_text"
+]

First observedv4.1.0Sep 17, 2026

TDQS

A4.6/5.0

Behavior5/5

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

With no annotations, the description fully carries behavioral disclosure and does so thoroughly: write_text is a single-file update, scan is single-flight and waits to settle, delete removes .uid/.import sidecars, move keeps sidecars consistent, and download_asset automatically triggers reimport and scan. It also reveals the class_name-table limitation and the data.cleanup.rm smoke-test detail.

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 highly structured: a one-line scope, bulleted operations, and a closing canonical call shape. Each caveat earns its place, especially the nuanced reimport and scan warnings, so the length is justified rather than padded.

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 the documented operations, the description is remarkably complete: it covers return values, side effects, aliases, sync behavior, and canonical call format. It is not fully complete because the input schema allows asset_search and download_file as valid ops, yet those are neither described nor identified as aliases, so an agent cannot confidently invoke them.

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?

Since schema_description_coverage is 0%, the description compensates well by giving operation signatures, defaults, and types (e.g., list(path='res://', recursive=False, max_depth=1), search(name, type, path, offset, limit)). It loses a point because two schema enum values, asset_search and download_file, have no documented parameters or behavior, leaving an agent to guess at their call shapes.

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?

The description opens with a specific scope: 'Project filesystem access via the Godot editor's EditorFileSystem.' It then enumerates concrete operations (read_text, write_text, reimport, list, delete, move, scan, search, download_asset, search_assets), each with a verb and target, making the tool clearly distinct from sibling resource/script/project managers.

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?

The description gives strong per-operation usage guidance, such as explicitly recommending script_patch/script_create for scripts and scan for assets awaiting first import, and explaining when reimport is not evidence of success. However, it does not provide tool-level when-to-use guidance versus sibling tools, and the schema exposes asset_search/download_file ops that the description never explains or disambiguates.

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