Tools that behave differently on some files

In one line: the tools that behave differently on particular files or particular books, and what to do about each difference.

What this solves

Most MCP tools treat every file the same way. The ones below do not. None of them errors — they just return something you were not expecting, and an unexpected success is far harder to notice than a clear failure.

read_file: two file types come back changed

.map relationship maps come back as raw JSON: node ids, pixel coordinates, group membership lists. Technically fine, practically unusable. Use view_relationship_map instead, which returns a picture plus a summary listing every character and every relationship — see Let an AI see a relationship map.

.geomap world maps come back with their three terrain grids replaced by a note. That is not truncation, it is deliberate: terrain is machine-encoded, there is nothing to read in it, and the operations that change it work in grid cells.

search_content: what it finds depends on the age of the book

On a 4.0 book, every file is searched, including the raw JSON of structured files. So a common word like name or title can come back as nothing but field names. Pass file_types: ["md"] when you want prose only.

On an older Script Studio book it works the other way: *.character, *.scene, *.storyline, *.note, *.location and the *.json files under .script_studio/ are excluded by default, because their raw JSON is noise in a full-text search. Pass include_structured: true to include them.

semantic_search: it only sees what is committed

Semantic search indexes the content of the book's latest commit. A paragraph the author typed in the app moments ago, not yet part of a commit, is not there.

A large book that has never been indexed hands the job to a background build, and that search comes back empty — "not built yet", not "nothing found". Search again shortly. Full details in Semantic search vs full-text search.

analyze_chapter: point it at prose, not at a structured file

Older Script Studio books are not supported at all. The call is refused outright, with a message pointing at the app's own analysis features.

On a 4.0 book, this one is on you. Nothing stops you setting file_path to a .script or a .beats file, and doing that is asking a reader to read you a JSON document. It will comply, and the report will be strange. Aim Beta Reader at .md manuscript files.

get_writing_stats: four types always count zero

.map, .beats, .timeline and .geomap have a word count of zero by contract — none of them is prose the author wrote. .script is the opposite: it counts the words inside its scenes, and it feeds the daily word count and the streak.

So tidying up a timeline for an author leaves no fake progress in their stats. Writing an episode does.

create_file: on the five structured extensions, your content is ignored

The server writes an empty skeleton, the filename becomes the document's name, and the reply says plainly that your content was replaced. Whatever you meant to put in it goes in through update_* batches — see Structured editing tools.

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 (FOLDER_NOT_EMPTY). If you really mean the whole subtree, send it again with recursive: true.

The guard exists because of a real accident: deleting only the folder row scatters every file under it to the root of the book, while the server answers 200.

get_chapter and read_file: use the second when you know the path

get_chapter accepts a bare filename (Chapter 01 - The Copyist Girl.md) or a partial path, and when it misses it lists the files that do exist. The cost is extra lookups.

Once the path is known, read_file does the same job more directly.

Related

• Docs: File operation tools
• Docs: Semantic search vs full-text search
• Docs: Let an AI see a relationship map
• Docs: What MCP can do, file type by file type
• Docs: AI Reader tools