Mary

Export the complete workspace as a downloadable DOCX or XLSX file. A workspace (previously called an artifact or task) is a generated output such as a chronology or a financial/bank-statement analysis. Use artifact_id from search_workspaces. This always exports the full workspace — unlike the Mary web app's "Current view" export, no search, filters, sorting, or row selection are applied. A fresh server-side export is generated on every call. XLSX is the default; DOCX produces a Word document, the usual choice for chronologies and drafts. The result is a temporary, signed download URL for the generated DOCX/XLSX file — a binary document meant to reach the user as a download link.

export_workspace

Use when the user asks a factual question about the documents in a Mary matter — 'did X ever…', 'what do the records show about…', 'summarise the key issues'. This is Mary's Fact Explorer: it reads the matter's uploaded documents and answers in plain language, citing the facts and source documents behind each point. Specific questions get better answers — name the people, dates, and topics, and say what shape the answer should take (a table, a list in date order, chosen columns). It can also produce one-off custom chronology tables scoped by date range, document, or issue. The read_mary_guide topic 'fact-explorer' has fuller phrasing guidance and question patterns. The completed run returns a source-grounded answer with citations. It does not modify source documents or create a workspace. Fact Explorer is only available on matters created on or after 20 November 2025. Each invocation is a non-destructive write to the authenticated user's private Mary account: it adds an assistant turn to the conversation and starts asynchronous processing. Omitting conversation_id creates a new conversation; providing it continues that conversation. reference_document_ids, when provided, limits the source documents used. The initial response contains a run_id. assistant_wait_for_run returns the run's status and eventual result. A run may return an elicitation_request containing follow-up questions for the user. assistant_reply_to_elicitation submits the user's answers and continues the run; its elicitation_response.messageId must match the request's messageId.

ask_fact_explorer

Fetch one page of the document index for the search-results app UI. Backend tool for the widget's server-side quick search: document_id comes from the rendered payload, so no matter re-resolution is needed, and the structured content is the same envelope the stored ``get_document_index`` result uses (documents, total, documentId) — no task id is minted. Not addressed to the model — it is hidden behind ``ui.visibility: ["app"]``.

get_document_index_page

Mint a short-lived signed URL for one source document's PDF. Backend tool for the workspace widget's PDF viewer: document_id comes from the rendered payload, file_id from a citation or the documents list. The link expires after about 10 minutes — the widget re-calls this on a failed load rather than caching links. Not addressed to the model — it is hidden behind ``ui.visibility: ["app"]``.

get_file_preview

Read a matter's current processing status without starting or retrying it. Available to the model and progress card, including clients without MCP Apps. Returns documentId, name, statusKey, and a taskId for optional rendering with render_matter_progress. A failed status read does not mean processing failed. For follow-up checks while pending, processing, or updating, wait at least five seconds between calls; stop on completed, failed, or draft. Use this tool to replace an expired render task. Never call process_matter merely to refresh status or restore the UI.

get_matter_processing_status

Fetch one page of matching matters for the search-results app UI. Backend tool for the widget's server-side quick search: it returns the same payload envelope the stored ``search_matters`` result uses (matters, totalCount, page, searchName, maryUrl) directly in the structured content — no task id is minted. Not addressed to the model — it is hidden behind ``ui.visibility: ["app"]``.

get_matters_page

Get one workspace of a matter: its details and its rows, in one call. A workspace (previously called an artifact or task) is a generated output such as a chronology, a financial/bank-statement analysis, or a draft document. Use artifact_id from search_workspaces. This tool returns the workspace summary, source-document usage, and review-flag counts TOGETHER WITH the first page of matching rows — no separate details or search call is needed. Depending on the user's rollout, the result carries either a text digest or structured workspace details, items, hasMore, and nextCursor with no text block. In the structured variant, items contain the full data, citations, annotations, and review. For a draft, the text variant carries Markdown with [n] citation markers and numbered sources; the structured variant preserves the original Markdown and citation tags in items[].data.body. Mary web-app links come ready-made: the workspace url ("Open in Mary:" in text), each row's url ("link:"), and each citation's url (listed with a draft's numbered sources). Prefer them over building links by hand. IMPORTANT: this tool does not display anything by itself. It returns a task_id. When an interactive view would help the user inspect the result, call render_workspace with that task_id. Skip rendering when this call is only supporting internal research, reasoning, or another intermediate tool call. Table workspaces retain the interactive rows view and details tabs; draft workspaces render as a read-only Markdown page with clickable citations and no details tab. Every argument beyond the ids is optional — call with none of them to see the workspace and browse the first page of rows, discovering the column keys (each row's `data` is keyed by column key). Each row also includes itemId; pass it as item_id to get_audit_trail. Then narrow: - search: free-text, case-insensitive match over the row's text columns (e.g. event / description); not dates, numbers, filenames, citations. - filters: a list of {field_key, op, value} rules (see ArtifactFilter), combined with join_operator ("and" by default; "or" to widen). - sort_by / sort_order: order by a column key, ascending or descending. - limit / cursor: page size (max 100) and nextCursor of a prior call. On the first page, omitted limit defaults to 10 for text or 25 for structured results; continuation calls preserve the previous limit. You can paginate to retrieve the complete set of matching items: start without a cursor, then repeatedly call get_workspace with cursor set to the returned nextCursor and the same document_id and artifact_id. The cursor restores search, filters, join_operator, sorting, and limit automatically; you may override limit. To change the query, start again without cursor. Cursors expire after about an hour. Legacy raw cursors require repeating all query arguments. For structured results, continue until hasMore is false; for text results, follow the next-page cursor whenever one is provided. Use limit=100 to fetch up to 100 items per call. Omit search and filters to retrieve all workspace items, and collect the items from every page rather than treating the first page as the complete workspace. Field keys: - Data columns use their own key (from an unfiltered call's row `data`), e.g. a chronology commonly uses "date" and "event". Always use the exact key returned for this workspace; do not infer a key from its label or from another workspace. - "citation.file_id" filters by cited source file; the value is a file id (or list) from this tool's documents used list. - "annotation.type" filters by review flag; the value is a flag type (or list) from this tool's annotations, e.g. "gap". - "review_status" filters by review state; values are "verified", "needs_review", and "unverified" (rows never reviewed). Use the "in" op. Citation and annotation fields support the "eq" and "in" ops. Examples (showing the args you pass): - Free text: search="wire transfer" - One value: filters=[{"field_key": "event_type", "op": "eq", "value": "payment"}] - Any of several values: filters=[{"field_key": "event_type", "op": "in", "value": ["payment", "invoice"]}] - Substring match: filters=[{"field_key": "description", "op": "contains", "value": "Ltd"}] - Date / number range: filters=[{"field_key": "date", "op": "range", "value": {"gte": "2026-01-01", "lte": "2026-03-31"}}] - Rows citing a specific source file: filters=[{"field_key": "citation.file_id", "op": "in", "value": ["doc-005", "doc-012"]}] - Rows carrying a specific review flag: filters=[{"field_key": "annotation.type", "op": "eq", "value": "contradiction"}] - Rows not yet verified by a reviewer: filters=[{"field_key": "review_status", "op": "in", "value": ["needs_review", "unverified"]}] - Widen with OR, then sort and page: filters=[...], join_operator="or", sort_by="date", sort_order="asc", limit=50 # then pass cursor=<nextCursor>

get_workspace

Fetch one page of workspace rows for the workspace app UI. Backend tool for the widget's progressive loading: document_id comes from the rendered payload, so no matter re-resolution is needed. Not addressed to the model — it is hidden behind ``ui.visibility: ["app"]``.

get_workspace_rows

Read the built-in guide to working with Mary through these tools. Call it without a topic for the table of contents, then with a topic slug for that page. Consult it when unsure how to phrase a generation query, what a Mary term means, how relevance/review works, or how to build links into the Mary web app (topic "linking"). Content is served by this server itself: reading it consumes no Mary credits and touches no matter data.

read_mary_guide

Get the contextual summary of a matter by document ID. The matter summary is the standing description of the case in Mary — its Overview, Key Issues, People & parties, Entities, and Additional Notes sections. Mary scores every extracted fact against it (the relevance ratings), so it reflects the team's current case theory. Use it to orient on what a matter is about before deeper work such as searching the workspace, drafting, or asking Fact Explorer. It can only be edited in the Mary web app. Returns the summary plus its revision number. A null summary means none has been written yet; legacy matters may return the summary as a single block of text instead of sections.

get_matter_summary

Create a new draft matter and prepare tus resources for its local files. Only for files this client can read locally. Documents in iManage go through create_matter_from_imanage. These tools cannot reach NetDocuments, Smokeball, or any other document management system: do not call this tool for them. Send the user to https://us.marytechnology.com/matters to choose New Matter and add the files from that system at the Sources step, or, for an existing matter, to https://us.marytechnology.com/matters/fms/{documentId}/sources. read_mary_guide topic matter-upload has the details. matter contains name, areaOfLawId, and optional subAreaOfLawId and firmMatterId. Law IDs must be actual Mary IDs; look them up with get_areas_of_law and do not invent them. Each file declares clientFileId, name, sizeBytes, declaredType (MIME type or null), and optional relativePath. Client IDs must be unique within this batch. Inspect local files to obtain their real sizes. Calls Mary once to create the matter and batch, then once to prepare upload resources. Returns IDs, file mappings, a temporary upload credential, and per-file uploadStatus, uploadUrl and uploadError. PATCH bytes directly to each ready uploadUrl; no creation POST or base64 metadata is needed. Every upload request must send the User-Agent mary-upload-client/1.0 (curl: -A 'mary-upload-client/1.0'); read_mary_guide topic matter-upload has the full procedure and a ready-made curl command. Do not pass file contents, base64 file data, or absolute local paths to this tool. Mary validates the actual bytes after transfer. Every call creates a new matter; existing matters are not supported. There is no request ID or automatic deduplication. Do not automatically retry an uncertain result. Preparation can partially or entirely fail after the matter exists; retain returned IDs, mappings and ready URLs, and inspect each uploadError. An outcome_unknown resource may already exist. This step does not complete uploads or start processing. After transfers complete, check get_matter_upload_status with the documentId, then call process_matter. Format selection and fact-generation toggles are not supported.

prepare_matter

Start processing an existing draft matter after its files have been uploaded. Use the documentId returned by prepare_matter, or the exact matter id from search_matters, not a matter name or firm matter ID. Finish transferring every prepared file first (read_mary_guide topic matter-upload covers the upload procedure). Mary checks upload validation, usable files, processing limits, available credits, and the user's matter permissions. Processing consumes credits and may be refused while files are validating. Success means processing has started, not that results are ready. Returns documentId, statusKey, and a taskId. In MCP Apps clients, optionally call render_matter_progress with that taskId to display the progress card. Otherwise, check status with get_matter_processing_status. A null taskId means the render result could not be saved; the confirmed status still holds. This tool does not upload files or accept summary, format, or fact-generation options. If Mary reports files are still validating, wait before trying again. Resolve credit or processing-limit refusals in Mary. After a timeout, server error, or unconfirmed response, check status before another attempt; do not automatically repeat the call.

process_matter

Search, filter, sort, and page the rows inside one workspace of a matter. A workspace (previously called an artifact or task) is a generated output such as a chronology or a financial/bank-statement analysis; this tool queries the rows inside one and returns just the matching page. Backed by the Mary artifact query API (POST /api/mcp/matters/{matterId}/tasks/{artifactId}/query). Use get_workspace instead when you also want the workspace's details (summary, source documents, review flags) alongside the rows. IMPORTANT: this tool displays nothing by itself. It returns the data plus a task_id. When an interactive rows table would help the user inspect the result, call render_workspace with that task_id. Skip rendering when this call is only supporting internal research, reasoning, pagination, or another intermediate tool call. Use artifact_id from search_workspaces. Every argument beyond the ids is optional — call with none of them to browse the first page and discover the column keys (each row's `data` is keyed by column key). Each row also includes itemId; pass it as item_id to get_audit_trail. Its "link:" opens the row in Mary on the same query and page; offer it rather than building a link by hand. Then narrow: - search: free-text, case-insensitive match over the row's text columns (e.g. event / description); not dates, numbers, filenames, or citations. - filters: a list of {field_key, op, value} rules (see ArtifactFilter), combined with join_operator ("and" by default; "or" to widen). - sort_by / sort_order: order by a column key, ascending or descending. - limit / cursor: page size (max 100) and the `nextCursor` of a prior page. The first page defaults to 25 items. To continue, send the cursor and the same document_id and artifact_id; the cursor restores search, filters, join_operator, sorting, and limit automatically. You may override limit. To change the query, start again without cursor. Cursors expire after about an hour. Legacy raw cursors require repeating all query arguments. Field keys: - Data columns use their own key (from an unfiltered query's `data`), e.g. a chronology commonly uses "date" and "event". Always use the exact key returned for this workspace; do not infer a key from its label or from another workspace. - "citation.file_id" filters by cited source file; the value is a file id (or list) from get_workspace (workspace.documents.used[].id). - "annotation.type" filters by review flag; the value is a flag type (or list) from get_workspace (workspace.annotations[].type), e.g. "gap". - "review_status" filters by review state; values are "verified", "needs_review", and "unverified" (rows never reviewed). Use the "in" op. Citation and annotation fields support the "eq" and "in" ops. Examples (showing the args you pass): - Free text: search="wire transfer" - One value: filters=[{"field_key": "event_type", "op": "eq", "value": "payment"}] - Any of several values: filters=[{"field_key": "event_type", "op": "in", "value": ["payment", "invoice"]}] - Substring match: filters=[{"field_key": "description", "op": "contains", "value": "Ltd"}] - Date / number range: filters=[{"field_key": "date", "op": "range", "value": {"gte": "2026-01-01", "lte": "2026-03-31"}}] - Rows citing a specific source file: filters=[{"field_key": "citation.file_id", "op": "in", "value": ["doc-005", "doc-012"]}] - Rows carrying a specific review flag: filters=[{"field_key": "annotation.type", "op": "eq", "value": "contradiction"}] - Rows not yet verified by a reviewer: filters=[{"field_key": "review_status", "op": "in", "value": ["needs_review", "unverified"]}] - Widen with OR, then sort and page: filters=[...], join_operator="or", sort_by="date", sort_order="asc", limit=50 # then pass cursor=<nextCursor> for page 2

query_workspace

Display a saved matter processing result as a live progress card. Pass only the taskId from process_matter or get_matter_processing_status. Call when the client supports MCP Apps and a visible progress card helps the user. Otherwise use the data tools' text and status responses. The widget reads current status until completion or failure; rendering never starts or retries processing. Results are user-scoped and kept for about an hour. For an expired result, call get_matter_processing_status to obtain a fresh taskId. Never repeat process_matter to restore the UI.

render_matter_progress

Display a previously fetched browse result as an interactive view. Pass the task_id returned by search_matters, search_workspaces, get_document_index, get_audit_trail, or get_sources; the view matches the tool that produced it — a matter or workspace table mirroring the Mary web app's list pages (quick search, sortable columns, status pills, per-row deep links), the document-index table (date, title, description, type, source file, and relevance, like Mary's Document index page, where clicking a source file opens its PDF side-by-side), the sources table (file name, pages, upload date, and status, like Mary's Sources tab), or the entry-history audit timeline — with a fullscreen control for viewing everything. Call this when the interactive view would help the user inspect the result. Do not call it when the data is only supporting internal research, reasoning, pagination, ID resolution, or another intermediate tool call. Results are kept for about an hour.

render_search_results

Display a previously fetched task result as an interactive app view. Pass the task_id returned by get_workspace or query_workspace; the view matches the tool that produced it. A get_workspace task renders either the established rows table with its original details tab or, for a draft workspace, a read-only Markdown document with clickable citation PDFs and no details tab. A query_workspace task always renders the rows table scoped to the query. Call this renderer when the interactive view would help the user inspect the result. Do not call it when the data is only supporting internal research, reasoning, pagination, or another intermediate tool call. Results are kept for about an hour.

render_workspace

Search your matters by name. Returns matching matter names and metadata. A matter is Mary's case file: it holds the documents uploaded for a case and everything generated from them (chronologies, analyses, drafts). Each matter includes its name, id, firm matter ID, contributors, creation date, and status. Leave name empty to list your most recent matters. Results are paged: when totalCount exceeds the matters returned, call again with page=2, 3, … and the same name. Pass the selected matter's id as document_id to the other Mary tools (search_workspaces, create_chronology, ask_fact_explorer, …). If multiple matters plausibly match, clarify which one the user means before using its id. A firm matter ID is not a document_id. Depending on the user's rollout, results are returned as a text digest or a structured matters array with no text block. Both formats include taskId, searchName, page, and totalCount. In the structured format, read matters[].id to select the document_id for subsequent calls. This tool displays nothing by itself; it returns the data plus a task_id. When an interactive list would help the user inspect the result, call render_search_results with that task_id. Skip rendering when the search is only supporting internal research, pagination, ID resolution, or another intermediate tool call.

search_matters

List the workspaces for a matter (chronologies, analyses, drafts). A workspace — sometimes referred to as a task or artifact — is a generated output inside the matter: a chronology (timeline of dated, cited events), a bank-statement/financial analysis (transaction table), or a draft document. Returns each workspace's name, id, type, creator, creation date, and status. Use the returned artifact_id with get_workspace to load any single workspace and its rows. Depending on the user's rollout, results are returned as a text digest or a structured tasks array with no text block. Both formats include taskId and documentId. In the structured format, read tasks[].id to select the artifact_id for get_workspace. This is the workspace list, not the items inside each workspace. This tool displays nothing by itself; it returns the data plus a task_id. When an interactive list would help the user inspect the result, call render_search_results with that task_id. Skip rendering when this call is only supporting internal research, ID resolution, or another intermediate tool call.

search_workspaces

Mark one workspace row verified, or send it back to needs-review. Backend tool for the workspace widget's reviewed/undo control: document_id and artifact_id come from the rendered payload, item_id from the row. Not addressed to the model — it is hidden behind ``ui.visibility: ["app"]``.

set_workspace_item_review

List the source documents uploaded to a matter, by document ID. Sources are the files the matter is built from — every chronology entry, fact, and analysis cites back to them. Each source includes its file name, page count, upload date, processing status, and whether it was a manual entry (a source the user recorded without a file, e.g. a phone call). Use it to answer "what files have we uploaded?" for a matter; for what Mary detected *inside* those files, use get_document_index instead. Results are paged: when total exceeds the sources returned, call again with page=2, 3, … and the same document_id. This tool displays nothing by itself; it returns the source list plus a task_id. When an interactive, searchable table would help the user inspect the result, call render_search_results with that task_id. Skip rendering when this call is only supporting internal research, reasoning, or another intermediate tool call. The rendered view matches the Mary web app's Sources tab.

get_sources

Polls a Mary assistant run until it is terminal or a bounded timeout expires. It takes the run_id returned by ask_fact_explorer, create_chronology, analyze_bank_statements, or draft_document. Completed responses include the answer, artifact ids, generated outputs, and any elicitation request; a run still in progress is returned as running and polled again on the next call — generation runs commonly take several minutes, so repeated calls are normal. When the result carries an elicitation_request, the attached Mary card walks the user through the questions, submits their answers, and tracks the continued run to completion itself, recording the outcome in the model context when the user finishes.

assistant_wait_for_run