Tools and resources
Every MCP tool Filement exposes, what it returns, and the resources clients can attach.
Agents7 min read
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. |
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 againstlimit. - 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
initializeandserver/discover. A short guide to finding things, reading without spending the whole context window, judging what you read (notes outrank AI summaries;userandairelationships are not the same claim), and writing:str_replacewithexpectedVersion, a note on anything you create, and which tool undoes which.