Notes and comments tools

In one line: how an outside AI tool reads and writes your notes, and takes part in the comment loop — leaving one, resolving one, reopening one.

What this solves

The files are not the whole book. Two other layers sit beside them: the notes the author writes for themselves, and the comments an editor and an author pass back and forth.

Both matter a lot to an AI handed someone else's manuscript. The comments usually already contain what somebody said was wrong; skipping them and producing an independent list is how you end up arguing against a decision that was settled last week. And the notes are the author's thinking in progress — reading them is the difference between "this planted detail is never paid off" and "this planted detail is being held for book two on purpose".

Notes

list_notes(book_token)                              → every note on this book
create_note(book_token, title, content, note_type…) → leave one

What create_note takes:

Argument	Notes
title	Required. One short line.
content	Optional, up to 50,000 characters
note_type	book (the work as a whole) or chapter (anchored to one file). Defaults to book.
file_id	Required when note_type is chapter — the file's token. Get it from get_book_structure first.
color	One of gray / red / blue / green / yellow / purple

Notes live beside the manuscript, not in it. Writing one touches no prose and adds nothing to the word count.

There is no delete-note tool over MCP. Notes are not version-controlled, so unlike a file there is no history to recover one from. If the author wants a note gone, they remove it in the app.

Pairing a setup with its payoff happens in the app. A note record can pair the note where the locked drawer is first mentioned with the note where it is opened, but create_note does not expose those two fields. So when an AI reads twelve chapters and notices a detail that is planted and never paid off, what it can do is write a note saying so and leave the pairing to the author. That at least keeps the finding from disappearing when the conversation ends.

Comments

list_comments(book_token)                        → every thread, open and resolved
create_comment(book_token, content, file_token?) → leave one
resolve_comment(book_token, comment_token)       → mark a thread addressed
reopen_comment(book_token, comment_token)        → reopen one that should not have been closed

A book holds two kinds: plain comments, and suggestions that carry replacement text. What MCP creates is the first kind.

comment_token comes from list_comments and looks like bcmt_…. Pass file_token to hang the thread on one file; leave it out for the book as a whole.

Say what you did before you resolve. A thread that closes in silence tells the person who opened it nothing — they cannot tell whether you made the change or decided the note was wrong.

Resolving needs edit rights on the book. A read-only collaborator can read threads and add to them, but cannot close someone else's.

Three things MCP deliberately does not offer

Not available	Why
Deleting a note	Notes are not version-controlled, so a deletion has no history to restore from
Accepting or rejecting a suggestion	Accepting edits the manuscript, and that is the author's call
Editing or deleting someone else's comment	Those are their words

When to comment and when to just edit

One question settles it: is this a judgement, or something the author asked for?

One finding, two exits

Pacing sags, a motivation does not land, the scene has not earned its length Leave a comment

The author said "tighten this passage" Edit the file

When unsure, comment. A comment costs ten seconds to dismiss; an unwanted rewrite costs the author a diff of their own prose.

Related

• Docs: File operation tools
• Docs: Semantic search vs full-text search
• Docs: Guides and writing skills
• Docs: Comments and threads