# MCP tool reference > All 22 tools the MCP endpoint exposes, with their parameters, their defaults and what refuses a call. Source: https://baalda.com/docs/mcp-tools Site: Baalda, https://baalda.com Every connection sees the same catalog. What a call may actually touch is decided by the per-folder access of the person the token belongs to, so two tokens in the same vault can get different answers from the same tool. ## Conventions - `vaultId` (string): Comes from `list_vaults`. Most tools that work across a vault need it. - `docId` (string): A note's stable id, from `list_notes` or `search_notes`. It survives renames and moves. - `relPath` (string): A vault-relative path, such as `Ideas/draft.md`. Folders in it must already exist. - `revision` (string): Returned by `read_note`. Pass it as `expectedRevision` on a write to refuse rather than merge if the note changed. - `Annotations`: Each tool is marked read-only, write or destructive, so a client can decide what to confirm before calling. - `Unknown properties`: Refused. Every input schema is closed. > Access tools are owner and admin only. Everything else answers within the caller's own permissions. ## Discovery ### list_vaults Lists the top-level note collections you can reach, each with a `vaultId`. Start here. Takes no parameters. ### list_folders Lists every folder in a vault, with its path and parent. - `vaultId` (string, required): From `list_vaults`. ### list_notes Lists the notes you can access in a vault, optionally within one folder. Each row carries the note's `docId`, title, path and your permission on it. - `vaultId` (string, required): From `list_vaults`. - `folderId` (string): Restrict the listing to one folder. ### search_notes Semantic and keyword search across everything you can access: notes, and the text extracted from files such as docx, xlsx, pdf, csv and code. Each hit carries a `kind` of `note` or `file`, so you know whether to follow it with `read_note` or `read_attachment_text`. - `vaultId` (string, required): From `list_vaults`. - `query` (string, required): What to search for. - `k` (number): Maximum results. Default 10, capped at 50. - `includeFiles` (boolean): Search the text of files as well as notes. Default true. ## Reading ### read_note Reads a note's full Markdown by `docId`, and returns its current `revision` alongside the content. - `docId` (string, required): From `list_notes` or `search_notes`. ### list_attachments Lists the files, as opposed to notes, that you can access: spreadsheets, documents, PDFs, images and other attachments. Each row's `hasText` says whether `read_attachment_text` has anything for it. - `vaultId` (string, required): From `list_vaults`. - `folder` (string): A vault-relative folder to list within, such as `Team/Reports`. - `limit` (number): Maximum files. Default 50, capped at 200. ### read_attachment_text Reads the extracted plain text of a file, not the file itself. A file that has not been indexed yet returns empty text rather than an error. - `vaultId` (string, required): From `list_vaults`. - `relPath` (string): The file's vault-relative path, such as `Team/q3.xlsx`. Use this or `blobId`. - `blobId` (string): The file's blob id, from `list_attachments` or a file search hit. - `maxChars` (number): Maximum characters. Default 20,000, capped at 200,000. The reply's `truncated` says whether there was more. ## Writing notes ### create_note Creates a new Markdown note. Every folder in `relPath` must already exist, so create folders first if you are building a tree. - `vaultId` (string, required): From `list_vaults`. - `relPath` (string, required): Vault-relative path ending in `.md`, such as `Ideas/draft.md`. - `title` (string): Display title. Defaults to the file name. - `folderId` (string): Usually omitted. If given it must be the folder whose path is `relPath`'s directory. - `content` (string): Initial Markdown content. ### update_note Replaces a note's entire content. Prefer `edit_note` when you are changing part of a note, so you are not resending text you did not touch. - `docId` (string, required): The note to replace. - `content` (string, required): The new full Markdown content. - `expectedRevision` (string): The `revision` from `read_note`. If the note no longer matches, the write is refused as a conflict: read again and retry. ### append_note Appends text to the end of a note. - `docId` (string, required): The note to append to. - `text` (string, required): Markdown to append. - `expectedRevision` (string): Refuses the append if the note changed since you read it. - `idempotencyKey` (string): A caller-chosen key, such as a UUID. A repeat with the same key returns the first result instead of appending twice. Use it whenever a call may be retried. ### edit_note Makes targeted edits without resending the body: replace exact text, insert before or after an anchor, or delete exact text. Edits apply in order, each matched against the text as the previous edit left it. - `docId` (string, required): The note to edit. - `edits` (array, required): One or more edits, applied in order. - `edits[].type` (replace · insert_before · insert_after · delete, required): What to do at the anchor. - `edits[].find` (string): Exact text to replace or delete. Matched exactly first, then ignoring differences in whitespace, quotes, dashes and Unicode form. - `edits[].replace` (string): Replacement text, for `replace`. - `edits[].anchor` (string): Exact text to insert next to, for the insert types. - `edits[].text` (string): Text to insert, for the insert types. - `edits[].all` (boolean): For `replace` and `delete`: apply to every occurrence instead of requiring exactly one. - `expectedRevision` (string): Also refuse the whole call if the note changed since you read it. > An anchor that is missing, or that matches more than once without `all`, refuses the entire call and writes nothing. A partial edit is never left behind. ### delete_note Deletes a note. The delete is soft: its edit history is preserved and the server's Trash can restore it. - `docId` (string, required): The note to delete. ## Folders and files ### create_folder - `vaultId` (string, required): From `list_vaults`. - `name` (string, required): Folder name. - `path` (string, required): Vault-relative folder path, such as `Ideas/Drafts`. - `parentId` (string): Parent folder id, when you have it. ### delete_folder - `folderId` (string, required): From `list_folders`. - `recursive` (boolean): Delete the contents too: notes are soft-deleted and subfolders removed. Default false, which refuses a folder that is not empty. ### move_note Renames, moves or retitles a note. It keeps its `docId` and its full history, so links and edits survive. - `docId` (string, required): The note to move. - `relPath` (string): New vault-relative path ending in `.md`. Its directory must be an existing folder, which becomes the note's folder. - `title` (string): New display title. - `folderId` (string | null): Re-parent the note while keeping its file name. `null` means the vault root. Omit to leave it where it is. ### move_folder Renames or moves a folder. Its notes and subfolders move with it: every descendant path is rewritten in place and every id preserved, so backlinks and history survive. - `folderId` (string, required): The folder to move. - `path` (string): New vault-relative folder path. - `name` (string): New name. Defaults to the last segment of `path`. - `parentId` (string | null): New parent folder id, or `null` for the vault root. ### move_file Renames or moves a file that is not a note, keeping its id. - `fileId` (string, required): The id `list_attachments` reports. - `path` (string, required): New vault-relative path, such as `Archive/report.pdf`. Its directory must be an existing folder. ### delete_file Deletes a file such as a PDF, image, Office document or CSV, for everyone. Teammates' stale copies are set aside rather than re-uploaded. - `fileId` (string, required): The id `list_attachments` reports. ## Access These four are owner and admin only, and they write the same rows the Members and access page writes. ### get_access_default Reads what future members will see when they join, which is the New members row: `open` for Can edit, `readonly` for Can view, `private` for No access. Takes no parameters. ### set_access_default Sets that default. Existing members are unchanged. - `mode` (private · readonly · open, required): The level future members get for content that already exists. ### list_resource_access Lists every member's effective access to one folder or file, after each person's own vault level, the team's access and any locks. - `resourceType` (folder · file, required): What kind of thing `resourceId` names. - `resourceId` (string, required): A folder id, or a file or note `docId`. ### manage_access Replaces access on one or more folders and files, or on the whole vault. An `org` audience clears the custom per-person overrides in the selected subtrees, while a `users` audience changes only those people. A `users` audience on the vault resource writes that person's absolute vault level. - `resources` (array, required): 1 to 1000 targets, each `{ resourceType, resourceId }`, where `resourceType` is `folder`, `file` or `vault`. For `vault`, the id is the organization id. - `audience` (object, required): `{ type: "org" }` for everyone, or `{ type: "users", userIds: [...] }` for named people. - `mode` (private · readonly · open, required): No access, Can view or Can edit. ## Refusals and conflicts | What happened | What you get back | |---|---| | The note changed since you read it | A conflict refusal. Read it again and retry with the new `revision` | | An `edit_note` anchor is missing or ambiguous | The whole call is refused and nothing is written | | The caller cannot see the target | The same answer as if it did not exist, rather than a hint that it does | | The caller may read but not write | A permission refusal on the write, with reads still working | | An access tool called by a plain member | Refused: those four are owner and admin only | | A token that has been revoked | 401, with a header pointing an OAuth-capable client at the authorization server | > Tool annotations let a client separate a read from a destructive write before calling, which is what makes an approval prompt meaningful. `delete_note`, `delete_folder`, `delete_file`, `update_note` and the two access writes are marked destructive.