# Tools and resources > Every MCP tool Filement exposes, what it returns, and the resources clients can attach. Tool names carry no `filement_` prefix. Clients already namespace tools by server (Claude Code shows `mcp__filement__search`), and a shorter name costs fewer tokens on every turn. ## Read | Tool | What it does | | -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `workspace_overview` | The bound workspace, your role, whether this connection can write, every project, and recently changed documents. Call it first. | | `search` | Meaning and literal words at once, then one hop along the relationships people drew: a result carries the `connections` somebody stated about it, and a connected document that matched nothing itself is appended with `matchedBy: "connected"`. `mode`: `auto`, `semantic`, `keyword`. Optional `alternates` (up to two more wordings, searched together), `projectId` or `folderId` (any depth), `limit`, `includeSuperseded`. See [Current versions in search](#current-versions-in-search). | | `read_document` | Path, version, notes, AI summary, lock state, and text (a Word file's text is markdown, with its headings and tables). An uploaded Office file also carries `fromFile`: its author and when it was created and last saved, from inside the file. Read part of it with `find` (where a phrase occurs, no body returned; a phrase that is not there returns the text with `findMiss`), `section` (one heading, or a trail like `Plan › Pricing` to pick the one under another; with `find`, searches only under it), or `offset` / `maxChars` (default 20 000, max 100 000). A long document also returns its `headings`. | | `read_documents` | `read_document` for up to 8 documents in one call, sharing one `maxChars` budget (default and max 60 000). `section` and `find` apply to each. | | `list_documents` | Documents by what they are, newest first, with a `total` (`"N+"` when there are more than were scanned) and a `cursor`: `kind` (as the pipeline classified it), `mentions` (a name it contains), `since` / `until`, `nameContains`, `projectId`, `folderId`. For list and count questions; `search` only ranks a sample. | | `document_summaries` | Notes and AI summaries for up to 25 documents, without their text. For triage before reading in full. | | `list_folder` | Direct children of a project root or folder, with ids, notes, sizes, and lock state, 200 at a time: pass `nextCursor` back as `cursor` for the rest. A document with no note carries `suggestedNote`, an unaccepted draft. Pass a good one to `set_note`. | | `project_tree` | The project (or a subtree) as an indented text outline. `maxDepth` defaults to 4. | | `get_relationships` | Direct edges of a document or folder, split into `userAsserted` and `aiSuggested`. | | `related_context` | Follows relationships 1–3 hops out and returns every reachable item with its notes and summary, plus the edges. | | `recent_documents` | Most recently changed documents, optionally within one project. | | `document_history` | Version list, or the text of one `version`, paged. | | `resolve_path` | Turns a path a person would say (`Roadmap / Q3 / Spec`) into ids. A segment that misses returns the candidates at that level rather than failing. | ## Threads, versions and names Filement works out which documents are versions of one another (a **family**, with one current version) and which documents are one piece of work told over time (a **thread**, with a summary, what was decided and what is still open). These tools read that directly, so a question like "where does the pricing work stand" does not have to be pieced together from search results. | Tool | What it does | | ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `current_state` | Where a piece of work stands. Pass `nodeId`, or `topic` to find it by meaning. Returns its thread(s): `summary`, `decided`, `open`, the `current` documents, and the `timeline` with each document's date, role and whether it is an earlier version or a copy. | | `what_changed` | Documents changed since `since` (an ISO date or date-time), newest first, at most 25, each with who changed it, its summary and thread; plus the threads with activity since then. Optional `projectId` or `folderId` (everything under the folder). | | `open_questions` | What is still undecided, deduplicated: the `open` items of recently active threads and the open questions their current documents raise, each with where it comes from. Optional `threadId`, `projectId` or `folderId`. | | `entity` | Every document that names a person, organisation, system or identifier. An exact, case-insensitive match on the name, then by prefix. Not a search by meaning. Newest and current versions first, each with its thread, with a `total` and a `cursor`. | | `list_threads` | The pieces of work in the workspace, a project or a folder, most recently active first, each with its summary, `decided`, `open` and current documents. Optional `projectId`, `folderId`, `cursor`. | | `get_thread` | One thread whole: its summary, `decided`, `open`, and every document in time order with its date, role, version and a one-line summary. | | `document_versions` | A document's family, newest first: which one `isCurrent`, and `howSure`: a person said so, the files show it, or a model's reading. Not the edit history of one document; that is `document_history`. | A thread whose documents you cannot all open comes back without its summary, decisions and open questions, since those were written from every document in it. A current version you cannot open is never named. ### Current versions in search When a search result is an older version or a copy of a document, it carries `supersededBy` with the current one. Nothing is hidden, but older versions are demoted: - With the current version also in the results, the older one keeps its row and loses its excerpt (`demoted: true`). - Without it, the current version is appended as a result with `matchedBy: "newer_version"` and its summary. These rows do not count against `limit`. - Five copies of one file share one document's allowance of passages, so they cannot crowd out everything else. Pass `includeSuperseded: true` for a question about history ("what did the first draft say"): every excerpt is kept, and results are still labelled. ## Write These tools are hidden from `tools/list` for read-only connections and for workspace viewers, so they take up no context there. Everything they change is listed in the workspace's **Activity**, grouped into one session per connection (a session ends after half an hour without a change), under the name the connection was given. People can undo the whole session or any change in it. | Tool | What it does | | ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `create_document` | Creates a markdown document. A name clash gets a numbered suffix. | | `edit_document` | `mode`: `str_replace` (preferred; `oldText` must match exactly once unless `replaceAll`), `append`, `prepend`, `append_to_section` / `replace_section` (what is under the heading named in `section`), or `replace` (whole text; requires `expectedVersion`). Pass `expectedVersion` to catch conflicts. | | `create_folder` | Creates a folder at a project root or inside `parentNodeId`, with an optional note. | | `create_project` | Creates a top-level project. | | `set_note` | Sets or clears (`""`) the note on a document or folder. | | `rename_item` | Renames a document or folder. | | `move_item` | Moves into `targetNodeId`, or to a project root by omitting it: its own, or with `targetProjectId`, another project's (everything inside moves along). | | `link_items` | Creates a directional relationship with a type, a reason, and a confidence from 0 to 1. Stored as AI-suggested and listed in Activity, where people can undo it. Refused on a pair a person already connected. | | `unlink_items` | Withdraws one relationship by `relationshipId`. An AI-suggested link is dismissed, so it is not suggested again; a link a person drew needs `force: true`. | | `trash_item` | Moves to Trash, recoverable for 30 days. Nothing here deletes permanently. | | `restore_item` | Puts an item back from Trash. The undo for `trash_item`. | | `restore_version` | Puts a document's text back to an earlier version. The restore is itself a new version, so nothing is lost. | Every tool declares MCP annotations (`readOnlyHint`, `destructiveHint`, `idempotentHint`, `openWorldHint`) so clients can decide which calls need approval. Tools return JSON text. They deliberately declare no `outputSchema`: with one, the gateway also sends `structuredContent`, and every result would go over the wire twice. ## Prompts Prompts are workflows rather than calls: a client shows them as slash commands (`/mcp__filement__research` in Claude Code, the prompt picker in Claude Desktop), and picking one sends the agent a sequence to follow with the tools above. | Prompt | Arguments | What it does | | ----------------- | --------------- | -------------------------------------------------------------------------------------------------- | | `orient` | none | Surveys the workspace: projects, shape, what is in flight. Reads nothing in full, changes nothing. | | `research` | `topic` | Search, triage, read, follow relationships, and report with citations by path. | | `check_current` | `subject` | Whether a document is still the one that counts: its note, its versions, its thread, its edges. | | `capture` | `what`, `where` | Files new material in the right place, with a note and links back to what it came from. | | `review_document` | `subject` | Reads a document with everything around it and says what is stale, contradicted or missing. | | `map_connections` | `subject` | Proposes the relationships an item should have, for approval before anything is written. | `subject` takes a path, a name or a `nodeId`. The prompt resolves it first. ## Resources and instructions - **`filement://document/{documentId}`**: a resource template. Reading it returns the document as markdown, headed by its path, version, note, and AI summary. - **`resources/list`**: your 50 most recently changed documents, so clients with an attach or @-mention picker can pull one into context. - **Server instructions**: sent in `initialize` and `server/discover`. A short guide to finding things, reading without spending the whole context window, judging what you read (notes outrank AI summaries; `user` and `ai` relationships are not the same claim), and writing: `str_replace` with `expectedVersion`, a note on anything you create, and which tool undoes which.