File operation tools

In one line: the reference for the file tools that act on a path — read, edit in place, overwrite, create, delete, append, search.

What this solves

This is the group that actually touches the draft. What they share: every one of them takes a path, and every write produces a commit. There is no save step, and the author sees your commits beside their own in version history.

Tool	What it does	Arguments
read_file	Read one file	book_token, path
edit_file	Find a passage and replace it	path, old_string, new_string, replace_all?, commit_message?
write_file	Replace the whole file	path, content, commit_message?
create_file	Create a new file	path, content?, content_type?, commit_message?
delete_file	Delete a file or folder	path, recursive?, commit_message?
append_to_file	Add to the end of a file	path, content, commit_message?
search_content	Full-text search	query, file_types?, limit?, include_structured?

Seeing a relationship map is a different tool — see Let an AI see a relationship map.

For revisions, reach for edit_file

It is the most-used of the group, and the only write that fails loudly instead of overwriting when the author is editing the same file.

The match and the replacement happen server-side inside a lock, so the count it reports is what actually landed rather than a local guess. When the text is missing, or appears more than once so the target is ambiguous, the call fails and tells you what to do next — act on that instead of resending the same arguments.

replace_all defaults to false, replacing only the first match. Pass an empty new_string to delete the passage.

write_file replaces everything

Right for a genuine full rewrite. It also takes whatever the author typed a minute ago with it, so prefer edit_file whenever edit_file can do the job.

create_file: content_type decides whether the words count

Writing a chapter? Pass content_type: "manuscript". Without it, a new file inherits its containing folder, and at the root it defaults to reference — those words do not reach the author's word count, streak or manuscript export. The values are manuscript, reference, character, location and storyline.

Folders in the path that do not exist yet are created for you, so there is no separate mkdir step. See Manuscript vs reference.

delete_file: a non-empty folder has to be said out loud

Deleting a folder that still has things in it is refused by default, and the message tells you how many are inside. Pass recursive: true when you really mean the whole subtree.

The guard exists because of a real accident: remove only the folder row and its contents lose their parent, so the app shows the whole subtree at the top level of the book. The author sees their files scattered, and the server answered success.

A delete is also a commit, so the file is still in version history and can be restored from there — see Restore a version or a single file.

search_content: these arguments, and no scope

search_content({
  "book_token": "bk_...",
  "query": "word furnace",
  "file_types": ["md"],
  "limit": 20
})

file_types takes extensions with or without the dot (["md", ".txt"]).

On a 4.0 book, file_types matters more than it looks. The raw JSON of structured files is searched too, so a common word like name or title can come back as a page of field names. Say file_types: ["md"] when you want prose. Older Script Studio books work the other way: there, structured files are excluded by default and include_structured: true brings them back. See Tools that behave differently on some files.

What this group cannot touch

• Prose (.md / .markdown / .txt) — the whole group works.
• The five structured types (.map / .beats / .timeline / .script / .geomap) — write_file, edit_file and append_to_file are refused, and the refusal names the update_* tool to use instead. Two exceptions to remember: create_file does work, but the content you send is ignored (the server writes an empty skeleton), and delete_file works too (deletion does not check the type policy, only the plan). Writing and deleting both belong to the subscription plans.
• .character / .location / .json / .yaml — not writable at all, and there is no field-level route either.

To change a structured file, go through Structured editing tools. The authoritative list is always the table get_capabilities returns.

commit_message is worth filling in

Leave it out and one is generated, but that generated line is what the author reads in version history later. "Tightened the harbour scene's opening" beats "Update file".

Related

• Docs: Structured editing tools
• Docs: Let an AI see a relationship map
• Docs: What MCP can do, file type by file type
• Docs: Permission denied on write
• Docs: Auto-version rules