agentleFS

Create a document or folder

doc_create

Create something that is not there yet. Commits at once if your grant allows it and is refused if it does not; nothing is overwritten. If the top-level folder does not exist and you may create folders, it is created and you become its manager. The answer says what it created, names any new directory (a typo in folder_path makes one), lists what each [[Name]] link resolved to, and carries the node id and a console link. Frontmatter (type, tags, aliases) between --- lines at the top of content drives search; access comes from grants on the folders, never from frontmatter. Actions — document: a document in a folder (folder_path, name, content); refused when one is already there. A name ending .svg stores content as an image a document beside it links as alt . folder: a folder (folder_path); if your own access includes manager there, you can also share it with access_grant action=share. upload: files of any type, without typing their bytes (folder_path, entries: one {path, sha256, size} per file, delete, file). Each path answers unchanged, upload (a one-time url: curl -T ''), stored or refused; what arrived lands as one commit, a .docx is stored as markdown, and the same entries again send only what changed. delete: true removes what folder_path holds that entries leaves out. An entry may carry source_url (https) or data (a data: URI) instead.

Input Schema

Name	Required	Description
`file`	No	upload: a file ChatGPT attached, as it hands it to the tool; stored under its file_name
`name`	No	document: the document name, e.g. "Q3 summary.md". Cannot contain "/" — put folders in folder_path instead. END IT IN .md unless you mean otherwise: only .md and .mdx render in the console, and anything else opens as plain text with no way to switch. Nothing is appended for you.
`seat`	No	the seat token identity_write action=take_seat gave you; pass it on every call while you drive that agent
`action`	Yes	what to do; each action takes the arguments its line names
`delete`	No	upload: true to delete what folder_path holds that entries leaves out (rsync --delete); undoable
`content`	No	document: the whole document. Set metadata with YAML frontmatter at the top of `content`: `type` (one of: meeting-notes, playbook, spec, brand-asset, web-clip, contract, misc — anything else becomes misc), `title`, `summary`, and `tags` as a list. `tags` is the write-side spelling of what the listing tools call `label`. `status` takes `active` or `inactive` and is not a label: `inactive` retires a document — search and listings stop showing it, while whoever may write it still opens it by location or node, and removing the line brings it back. Omit it unless you mean to retire something. `aliases` (a list, or one name) are other names search how=titles finds the document by; a [[link]] still needs its file name or title. Any other key you write (`sources`, …) is kept as written and comes back on read; key order may change. A block that does not parse as YAML is refused, naming the line, and nothing is written: quote a value that contains ": " (summary: "a: b").
`entries`	No	upload: the files, one {path, sha256, size} each (at most 1000, 100 MB a file, 1 GB in all); a file unchanged since its last upload is not sent again
`acting_as`	No	an agent identity below you (its id, from identity_write action=spawn) to make this one call as, with that agent's narrower access; for a helper whose session signs in as its person
`folder_path`	No	document, upload: folder names, outermost first, e.g. ["handbook","policies"]; at least one, since documents go in a folder · folder: folder names, outermost first, e.g. ["product-docs"] or ["product-docs","specs"]
`idempotency_key`	No	Any unique string you choose for this write, e.g. a UUID. If you retry the call with the same key and the same arguments, the first answer is returned and nothing is done twice. Reusing a key for a different request is refused. Keys are kept 24 hours.

Output Schema

Name	Required	Description
`sync`	No	open until every upload URL has its bytes, then committed as one; at expires_at what arrived is committed
`text`	No	the answer as prose, for an action that answers in prose
`files`	No
`spans`	No	the blocks this write added or edited, in document order; absent when no commit was written
`action`	Yes	the action that answered
`commit`	No	the commit this call landed, when nothing was left to send
`stored`	No	what the document's head stores after this call, to check against what was sent (#1492)
`deleted`	No
`location`	No	the whole path from the workspace root this write resolved to; present on a successful write
`destination`	No
`remote_only`	No	files folder_path holds that entries leaves out, relative to it
`delete_refused`	No
`remote_only_more`	No

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedOct 31, 2026

addedOutput schema / properties / spans

Added value: +{
+  "description": "the blocks this write added or edited, in document order; absent when no commit was written",
+  "items": {
+    "additionalProperties": false,
+    "properties": {
+      "change": {
+        "description": "added: a new block; edited: an existing block given new text, same id",
+        "enum": [
+          "added",
+          "edited"
+        ],
+        "type": "string"
+      },
+      "id": {
+        "description": "the span id: what truth, comment and claim anchor to",
+        "type": "string"
+      },
+      "index": {
+        "description": "the block's position in the document's new head, 0-based",
+        "maximum": 9007199254740991,
+        "minimum": -9007199254740991,
+        "type": "integer"
+      }
+    },
+    "required": [
+      "id",
+      "index",
+      "change"
+    ],
+    "type": "object"
+  },
+  "type": "array"
+}

Changed2 schema fields changedOct 30, 2026

changedInput schema / $schema

Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"

changedOutput schema / $schema

Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"

Changed1 schema field changedOct 29, 2026

changedInput schema / properties / content / description

Previous value: -"document: the whole document. Set metadata with YAML frontmatter at the top of `content`: `type` (one of: meeting-notes, playbook, spec, brand-asset, web-clip, contract, misc — anything else becomes misc), `title`, `summary`, and `tags` as a list. `tags` is the write-side spelling of what the listing tools call `label`. `status` takes `active` or `inactive` and is not a label: `inactive` retires a document — it stays in the folder and stays openable in the console, but agents stop retrieving it. Omit it unless you mean to retire something. `aliases` (a list, or one name) are other names search how=titles finds the document by; a [[link]] still needs its file name or title. Any other key you write (`sources`, …) is kept as written and comes back on read; key order may change. A block that does not parse as YAML is refused, naming the line, and nothing is written: quote a value that contains \": \" (summary: \"a: b\")."New value: +"document: the whole document. Set metadata with YAML frontmatter at the top of `content`: `type` (one of: meeting-notes, playbook, spec, brand-asset, web-clip, contract, misc — anything else becomes misc), `title`, `summary`, and `tags` as a list. `tags` is the write-side spelling of what the listing tools call `label`. `status` takes `active` or `inactive` and is not a label: `inactive` retires a document — search and listings stop showing it, while whoever may write it still opens it by location or node, and removing the line brings it back. Omit it unless you mean to retire something. `aliases` (a list, or one name) are other names search how=titles finds the document by; a [[link]] still needs its file name or title. Any other key you write (`sources`, …) is kept as written and comes back on read; key order may change. A block that does not parse as YAML is refused, naming the line, and nothing is written: quote a value that contains \": \" (summary: \"a: b\")."

Changed1 schema field changedOct 28, 2026

addedOutput schema / properties / location

Added value: +{
+  "description": "the whole path from the workspace root this write resolved to; present on a successful write",
+  "type": "string"
+}

Changed3 schema fields changedOct 24, 2026

addedInput schema / properties / seat

Added value: +{
+  "description": "the seat token identity_write action=take_seat gave you; pass it on every call while you drive that agent",
+  "maxLength": 64,
+  "type": "string"
+}

removedOutput schema / properties / commit / anyOf

Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]

addedOutput schema / properties / commit / type
```
Added value: +[
+  "string",
+  "null"
+]
```

Changed14 schema fields changedOct 16, 2026

addedInput schema / properties / acting_as

Added value: +{
+  "description": "an agent identity below you (its id, from identity_write action=spawn) to make this one call as, with that agent's narrower access; for a helper whose session signs in as its person",
+  "type": "string"
+}

changedInput schema / properties / action / enum

Previous value: -[
-  "document",
-  "folder"
-]New value: +[
+  "document",
+  "folder",
+  "upload"
+]

addedInput schema / properties / delete

Added value: +{
+  "description": "upload: true to delete what folder_path holds that entries leaves out (rsync --delete); undoable",
+  "type": "boolean"
+}

addedInput schema / properties / entries

Added value: +{
+  "description": "upload: the files, one {path, sha256, size} each (at most 1000, 100 MB a file, 1 GB in all); a file unchanged since its last upload is not sent again",
+  "items": {
+    "properties": {
+      "data": {
+        "description": "the bytes inline as a data: URI, for a file under 256 KB",
+        "type": "string"
+      },
+      "mimeType": {
+        "description": "its media type, e.g. image/png; guessed from the extension when absent",
+        "type": "string"
+      },
+      "path": {
+        "description": "where the file goes, relative to folder_path, e.g. figure.svg or img/photo.png",
+        "type": "string"
+      },
+      "sha256": {
+        "description": "the file's SHA-256 as 64 hex characters (sha256sum / shasum -a 256); needed unless data or source_url brings the bytes",
+        "type": "string"
+      },
+      "size": {
+        "description": "the file's length in bytes; needed with sha256",
+        "maximum": 9007199254740991,
+        "minimum": 0,
+        "type": "integer"
+      },
+      "source_url": {
+        "description": "an https URL the server fetches the bytes from instead",
+        "type": "string"
+      }
+    },
+    "required": [
+      "path"
+    ],
+    "type": "object"
+  },
+  "type": "array"
+}

addedInput schema / properties / file

Added value: +{
+  "description": "upload: a file ChatGPT attached, as it hands it to the tool; stored under its file_name",
+  "properties": {
+    "download_url": {
+      "type": "string"
+    },
+    "file_id": {
+      "type": "string"
+    },
+    "file_name": {
+      "type": "string"
+    },
+    "mime_type": {
+      "type": "string"
+    }
+  },
+  "required": [
+    "download_url"
+  ],
+  "type": "object"
+}

changedInput schema / properties / folder_path / description

Previous value: -"document: folder names, outermost first, e.g. [\"handbook\",\"policies\"]; at least one, since documents go in a folder · folder: folder names, outermost first, e.g. [\"product-docs\"] or [\"product-docs\",\"specs\"]"New value: +"document, upload: folder names, outermost first, e.g. [\"handbook\",\"policies\"]; at least one, since documents go in a folder · folder: folder names, outermost first, e.g. [\"product-docs\"] or [\"product-docs\",\"specs\"]"

addedOutput schema / properties / commit

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "description": "the commit this call landed, when nothing was left to send"
+}

addedOutput schema / properties / delete_refused
```
Added value: +{
+  "type": "string"
+}
```

addedOutput schema / properties / deleted

Added value: +{
+  "items": {
+    "type": "string"
+  },
+  "type": "array"
+}

addedOutput schema / properties / destination
```
Added value: +{
+  "type": "string"
+}
```

addedOutput schema / properties / files

Added value: +{
+  "items": {
+    "additionalProperties": false,
+    "properties": {
+      "answer": {
+        "enum": [
+          "unchanged",
+          "upload",
+          "received",
+          "stored",
+          "refused"
+        ],
+        "type": "string"
+      },
+      "expires_at": {
+        "type": "string"
+      },
+      "link": {
+        "description": "the markdown a document beside it links it with",
+        "type": "string"
+      },
+      "location": {
+        "description": "where it is stored; a .docx becomes .md",
+        "type": "string"
+      },
+      "max_size": {
+        "type": "number"
+      },
+      "method": {
+        "type": "string"
+      },
+      "path": {
+        "type": "string"
+      },
+      "reason": {
+        "description": "refused: why",
+        "type": "string"
+      },
+      "sha256": {
+        "type": "string"
+      },
+      "url": {
+        "description": "upload: PUT the file's bytes here, e.g. curl -T <file> '<url>'",
+        "type": "string"
+      }
+    },
+    "required": [
+      "path",
+      "answer"
+    ],
+    "type": "object"
+  },
+  "type": "array"
+}

addedOutput schema / properties / remote_only

Added value: +{
+  "description": "files folder_path holds that entries leaves out, relative to it",
+  "items": {
+    "type": "string"
+  },
+  "type": "array"
+}

addedOutput schema / properties / remote_only_more

Added value: +{
+  "maximum": 9007199254740991,
+  "minimum": -9007199254740991,
+  "type": "integer"
+}

addedOutput schema / properties / sync

Added value: +{
+  "anyOf": [
+    {
+      "additionalProperties": false,
+      "properties": {
+        "expires_at": {
+          "type": "string"
+        },
+        "id": {
+          "type": "string"
+        }
+      },
+      "required": [
+        "id",
+        "expires_at"
+      ],
+      "type": "object"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "description": "open until every upload URL has its bytes, then committed as one; at expires_at what arrived is committed"
+}

Changed1 schema field changedOct 12, 2026

addedOutput schema / properties / stored

Added value: +{
+  "additionalProperties": false,
+  "description": "what the document's head stores after this call, to check against what was sent (#1492)",
+  "properties": {
+    "bytes": {
+      "description": "the stored body's length in UTF-8 bytes; frontmatter is kept beside the body, not in it",
+      "maximum": 9007199254740991,
+      "minimum": -9007199254740991,
+      "type": "integer"
+    },
+    "previousBytes": {
+      "anyOf": [
+        {
+          "maximum": 9007199254740991,
+          "minimum": -9007199254740991,
+          "type": "integer"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "the length of the body this replaced; null when nothing was there"
+    },
+    "sha256": {
+      "description": "the stored body's sha256, hex",
+      "type": "string"
+    }
+  },
+  "required": [
+    "bytes",
+    "sha256",
+    "previousBytes"
+  ],
+  "type": "object"
+}

AddedOct 6, 2026

TDQS

B3.3/5.0

Behavior1/5

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

The description is behaviorally rich, but it contradicts the annotations: destructiveHint=false is declared while the upload action documents delete=true as removing files under folder_path. That is a non-additive, destructive operation, so the annotation and description are inconsistent.

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 description is front-loaded but very dense and rambling, relying on long semicolon- and dash-separated clauses rather than clear sections. Much of the content is useful for a complex 10-parameter tool, but its structure could be much tighter.

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?

Given the tool's complexity, the description covers the key operational details: permissions, refusal behavior, frontmatter, upload semantics, delete behavior, and response contents. With an output schema present, the additional return-value explanation is helpful rather than required.

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 description coverage is 100%, so the schema already carries the detailed parameter semantics. The description adds useful cross-parameter behavior such as .svg image handling and folder_path creating directories, but the baseline 3 is appropriate because the schema does most of the work.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states the create verb and names the supported resources: document, folder, and upload. It does not explicitly name sibling tools such as doc_update, but it does clarify that existing items are not overwritten and that document creation is refused when something already exists.

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 clear action-specific usage context: when document creation is refused, how folder creation behaves, and what upload/delete do. It does not explicitly point to doc_update as the alternative for existing documents, but the create-only scope is reasonably clear.

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

All agentleFS tools Inspect

Try in Browser

Context All Your Agents Can ShareAgents share what they learn, hand off work, and hold it when you switch models. Start with 5 GB free.fulcradynamics.comAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources

Need Help?