Skip to main content
Glama

Filesystem Manage

filesystem_manage

Manages project files via Godot's EditorFileSystem: read and write text files, inspect and patch import options, force reimports, scan for class_name registration, search, move, rename, and remove assets.

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. • import_get(path) Read an already-imported asset's importer, options, Variant types, writable_options, revision and native import_valid status. Validation uses stored config types, not a full importer enum/range schema. • import_set(path, options, reimport=True, expected_revision="") Patch existing scalar import options for one asset. Unknown keys, importer switching and _subresources edits are unsupported. Pass the revision from import_get to reject stale edits. Busy scans/imports refuse before writing. Staged replacement preserves recovery paths on failure; file edits are non-undoable. Returns settings_committed, import_attempted, import_pending, import_valid, import_succeeded and revision. Native import failure after commit returns these outcomes in error data. Native validity alone can be stale; import_succeeded also requires no captured errors. import_diagnostics describes editor errors during the synchronous import, not guaranteed per-asset attribution. reimport=False saves settings only. Native import can exceed the 120-second command budget: inspect current status before retrying. • 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. Failed native validity goes under failed_imports; valid paths with captured editor errors go under unconfirmed_imports. Responses include per-path import_status and bounded import_diagnostics. • 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.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "op": "<op>"
    },
    "name": "filesystem_manage"
  }
}

Input Schema

NameRequiredDescriptionDefault
opYes
paramsNo
session_idNo

Output Schema

NameRequiredDescriptionDefault

No arguments

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv4.4.1
    • changedInput schema / properties / op / enum
      Previous value: -[
      -  "move",
      -  "read_text",
      -  "reimport",
      -  "remove",
      -  "rename",
      -  "scan",
      -  "search",
      -  "write_text"
      -]New value: +[
      +  "import_get",
      +  "import_set",
      +  "move",
      +  "read_text",
      +  "reimport",
      +  "remove",
      +  "rename",
      +  "scan",
      +  "search",
      +  "write_text"
      +]
  2. Changed1 schema field changedv4.2.1
    • 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"
      +]
  3. First observedv2.9.1

TDQS

A4.6/5.0
Behavior5/5

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

With no annotations supplied, the description carries the full behavioral burden and does so thoroughly: mutations are non-undoable, write_text performs a single-file update, import_set preserves recovery paths and rejects stale revisions, busy scans refuse writes, reimport distinguishes skipped_non_imported from reimported, and partial/rolled_back outcomes are explicitly called out.

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?

The description is long but well structured with operation bullets and a clear canonical call shape at the end. Some redundancy exists, such as repeated non-undoable warnings and dense import_set detail, but the length is largely justified by the ten-operation surface.

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?

For a multiplexed ten-operation tool with no annotations and effectively no schema property descriptions, the definition supplies operation semantics, failure modes, return field names, sequencing rules, and alternatives to sibling tools. An agent has enough information to select and invoke the correct operation without opening the output schema or guessing at behavior.

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 description coverage is 0%, but the description compensates by documenting signatures and defaults for every operation, including search(name, type, path, offset, limit), import_set(options, reimport, expected_revision), and remove(force, permanent). The main gap is session_id, which is mentioned only as remaining top-level and never explained semantically.

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 states a specific domain (project filesystem access via EditorFileSystem) and enumerates each operation with concrete verbs and resources: read_text, write_text, import_get, import_set, reimport, scan, search, move, rename, remove. It also distinguishes behavior from siblings such as script_create/script_patch for script diagnostics and batch_execute for mutations.

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?

It gives explicit routing guidance for several operations, including using script_patch/script_create instead of reimport for scripts, scan after adding class_name scripts, and direct calls rather than batch_execute for move/rename/remove. Gaps remain for read_text, write_text, and search, where no alternative or when-not-to-use guidance is provided.

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