Clio

List the collections (research databases) accessible to the current user. Use this to discover available collections before invoking start_research with a `collection_id` parameter. Each entry in `collections` has: - `collection_id`: opaque identifier — pass this as the `collection_id` argument to start_research. - `name`: human-readable name. - `description`: what the collection contains. - `collection_type`: "matter" | "knowledge" | "project". - `visibility`: "organization" | "private". - `files_count`: documents in the collection, when reported. - `created_at` / `archived_at`: timestamps; `archived_at` is set only when the collection has been archived. Arguments: - `page`: which page to fetch, starting at 1. - `per_page`: collections per page, 1 to 100, defaulting to 100. Leave it alone unless you have a reason to fetch fewer. - `collection_type`: optional filter. Omit to get matter and knowledge collections; project collections are returned only when requested explicitly. Prefer this over paging when the user has named a type. - `query`: optional search text, matched against collection names and descriptions (for a matter, its matter number and description). This returns ONE page. `has_more` is true when further pages exist. - If the user names a collection or matter, pass its name or number as `query`. Do not page through the full list to find it: a firm can have more matters than paging can reach. If the search matches more than one page, call again with page + 1. - If the user asked to see or browse their collections, show this page, tell them the `total`, and ask before fetching more. Never state a collection does not exist until a `query` search for it comes back empty. Never report `total` as the number you displayed.

list_collections

List the approvals that can be pre-granted when starting research. Each `approval_key` is a string accepted by `start_research(initial_approval_keys=[...])`; pre-granting one means Clio will not stop to ask before using that capability in the run. Pre-grant only what the user has actually asked to allow, and read the `label` back to them when you do. Passing the whole list to avoid interruptions removes the user's control over what Clio does on their behalf, which is the point of the approval gate. The set is user-specific — it depends on their organization's configuration and feature flags — so call this rather than reusing keys from elsewhere. An empty list means nothing can be pre-granted for this account.

list_approval_keys

Read one vLex document by its `vid`, one window of its text at a time. Use it on a `vid` from search_legal_documents when the user wants what a document actually says. `body_text` is empty when no format yielded text — report that rather than inferring content from the title or headnotes. A consolidated statute runs to megabytes, so the text arrives windowed: `body_total_chars` is the whole length and `body_has_more` says whether more follows. Read on with `body_offset=body_offset + len(body_text)`, and only when the answer actually needs the rest.

get_legal_document

Read the text of a document Clio drafted. Arguments: - `conversation_id` / `file_key`: as returned by list_output_documents. - `version`: omit for the latest version, which is what the user means unless they asked for an earlier draft. `available_versions` in the result lists what else can be read. - `max_chars`: how much of the body to return, default 50000 and capped at 200000. A drafted document can be far longer than a tool result may carry. - `start`: character offset to read from, for paging a long document. Paging: read `truncated`. While it is true there is more text, so call again with `start` advanced by the length of the `content` you were given; `total_chars` says how long the whole document is. Do not tell the user you read a document you only read the first page of. A Word document comes back as its extracted text, without formatting. Any other binary file comes back empty, with `guidance` saying what to do instead. Returns the document text plus the conversation's cited authorities. Those citations are conversation-scoped: report them as "authorities Clio used in this conversation", never as the source of a particular sentence. Never paraphrase this content as Clio's answer to the user's question — it is a document Clio wrote; quote or summarize it as such. Common errors: - 404: the conversation, file_key, or version does not exist for this user.

get_output_document

Read where a Clio conversation currently stands, without driving a turn. Use it when: - a turn returned `"still_running"` and you want one cheap look at where it got to — watch_conversation is the better answer when you mean to wait; - the user asks what happened in a conversation from earlier. Returns the same `TurnResult` as start_research, so read `state` the same way. `"still_running"` means Clio is genuinely still working. Pacing, if you do poll: wait about 5 seconds before the first re-check, then roughly double the wait each time up to about 30 seconds. If it is still running after a few minutes, tell the user it is taking longer than usual and offer to check again — do not spin silently. Prefer a driven turn where you can have one: watch_conversation and the turn-running tools stream progress and return on settlement, which is both faster and cheaper than this loop. Never invent or summarize an answer while `state` is `"still_running"`. Common errors: - 404: the conversation does not exist or does not belong to this user.

get_conversation_messages

Read Clio's formatted conversation in its native message order. This is the data source for the live MCP App. Unlike ``get_conversation_messages``, it does not project, filter, or reverse the formatted conversation payload. ``status`` rides alongside it because the raw ``conversationStatus`` cannot be read as one: it is absent unless the org holds the status-indicator flag, and when present it is stored, so a ``working`` outlives the run that set it. Either way the panel would say "working" forever.

get_live_conversation

Read back the document review table a conversation built. Use it to check what a review actually produced: which documents became rows, which questions became columns, and what each cell says. Building a table reports success as prose, so this is the only way to confirm the rows are the ones expected — a collection search that matched two documents of nineteen still reads as a table that was built. Cells fill in after the rows appear, so an empty cell means that question is still being answered for that document, not that the answer is empty. Read again rather than reporting a blank as a finding. Raises when the conversation has no table, which is itself the answer: the build did not happen.

read_review_table

Start a Clio research conversation and return its live conversation. This call returns promptly with the conversation id so the live MCP App can mount and follow Clio while it works. Clio decides whether to do the work, so until a turn completes never tell the user it has started, is under way or will be done; say only that you've asked Clio. Read `state`: - `"completed"` → `answer` is Clio's answer. Show it. Any documents it drafted are listed in `files`; read one with get_output_document. - `"needs_user"` → Clio is parked. For each entry in `interruptions`, act on its `kind`: - `"tool_approval"` → tell the user what is being approved, using the interruption's `tool_name`, `tool_summary`, `arguments_preview` and `allowed_scopes`, and get their answer. Then respond_to_interruption with the decision and scope THEY chose. Do not decide for them. - `"clarification"` → put the `questions` to the user, then continue_conversation with their answers in prose. - `"external_tool"` → you are being asked to run the tool. Do it, then return the output with respond_to_interruption(result=...). - `"task_submission"` → Clio has proposed follow-up work. Put the proposal to the user, then submit_tasks with the indices they chose. Never continue_conversation: that starts unrelated work and abandons the proposal. Whichever path resolves it, the run picks up from there. - `"still_running"` → the usual result: the run has started and Clio has not answered yet. Tell the user only, in their language: "I've asked Clio. I'll share its answer here when it's ready." Do not describe, summarise or promise what it will produce, or say it agreed to the request. Then call watch_conversation, and again while it returns `"still_running"`; resolve any interruptions with the user first, and after three such calls ask whether to keep waiting. Present Clio's answer once the turn completes. Do not start another conversation. - `"error"` → report `error` as a failure, never as Clio's answer. Arguments: - `question` (required): what the user wants researched, drafted or reviewed, in their own terms. Every conversation runs on Clio's agentic agent, which picks its own tools — there is no workflow to choose. Clio may decline work that needs a dedicated workflow, such as a new 50-state survey, so never tell the user it will be done; say only that you've asked Clio. - `collection_id`: scope the research to one collection; see list_collections. - `jurisdiction`: the governing jurisdiction as a country code ("US", "GB", "CA", ...). Pass it whenever the user names one; Clio otherwise researches unscoped or asks. - `matter_id`: associate the conversation with a matter. - `file_ids`: files to attach, from `attach_document`. Confirm each is `available` with get_file_status first. - `initial_approval_keys`: approvals to pre-grant so the run does not stop for them; discover the valid keys with list_approval_keys. Pre-grant only what the user actually asked to be allowed — never a blanket list to save turns. - `unattended`: set True only when no human is watching, e.g. a scheduled job. - `locale`: response language, default "en".

start_research

Search vLex for legal documents and get the hits back directly. Use this for a lookup: finding a case or statute, checking what exists on a point, gathering candidates to read. It answers in one round trip. Prefer it over start_research whenever the user wants *documents* rather than analysis — starting a conversation for a lookup costs minutes of agent work. Use start_research instead when the user wants Clio to reason: a legal question answered, a document drafted or reviewed, an argument tested. Those need the agent, and it does its own searching. `total_count` is how many matched, not how many came back: say so rather than implying the results are exhaustive. Each hit's `vid` reads the full text via get_legal_document. Report `snippet` and `summary` as extracts, never as the document's holding — and never present a hit as good law on this evidence. Write the hits into your visible reply, each with its link. A host may also render them as a card, but that card can end up folded inside a collapsed step, so a reply that only says "I found some cases" leaves the user with nothing. `formatted` is the hits already built into a numbered, linked list: use it directly when the user wanted a list, and as the source of the links when your answer is prose.

search_legal_documents

Attach a document to Clio. Read the result: there are two outcomes. Read the bytes yourself and pass them base64-encoded. Which upload path is open depends on the account, so **branch on what comes back** rather than assuming: - `file_id` set → the document stands alone. Pass it to `start_research(file_ids=[...])` or `continue_conversation(file_ids=[...])`. `status` is `pending`, because ingest runs on after the upload; confirm with get_file_status that it reads `available` first, or the run gets a record with no text behind it. - `conversation_id` set → the account is on the legacy path, where a document can only arrive *inside* a conversation. There is no `file_id`. Continue THAT conversation with `continue_conversation`; do not start a new one, or the document is not in it. On that legacy path the request itself takes one of two shapes, and you choose which by whether you pass `conversation_id`: leave it blank and the document opens a conversation of its own, which is where a fresh "here is my contract" goes; pass the id of a run already going and the document joins that one, with no turn spent. Either way the next call is `continue_conversation` — that is what asks the question, since attaching alone runs nothing. Always pass `size_bytes`. Bytes ride inside this call, and a host that truncates a long tool argument does it silently — that is how an earlier version of this tool uploaded a 306-byte fragment of a 220 KB PDF to S3 as a working file. The size you declare is checked against what arrived, so a truncated argument fails here instead of corrupting a document. Send only what the user asked you to send, and for a file too large to survive a tool argument, ask them to upload through Clio and give you the id.

attach_document

Show the documents Clio generated in a conversation. Call this whenever the user asks what Clio produced or wants a document, rather than retyping the list into chat. The card lets the user pick a document and download it as DOCX or PDF. For which cases or statutes an answer relied on, call show_cited_authorities instead.

show_documents

List the authorities a conversation cited, as text. Call it only when the user asks which cases or statutes an answer relied on. It reads the conversation's own authority panels, so it reports what Clio actually cited rather than what you remember it citing — never assemble this list yourself. One call covers the whole conversation, however many turns it took. `formatted` is the list as markdown, ready to put in your reply. Common errors: - 404: the conversation does not exist or does not belong to this user.

show_cited_authorities

Resume waiting on a turn Clio is already running, without sending anything. This is what to call after a turn returned `"still_running"`, in place of polling: it re-attaches to the live run and returns when the turn actually gets somewhere, streaming progress while it waits. Nothing is posted, so it cannot start a second turn or double-charge the user, and it is safe on a busy conversation. Prefer it to repeated get_conversation_messages calls. Returns the same `TurnResult` as start_research, `interruptions` included, so read `state` and resolve them exactly the same way. `"still_running"` again means the run outlived this call's budget too — call this once more. Use get_conversation_messages instead when you only want a cheap glance at where a conversation stands and do not intend to wait. Common errors: - 404: the conversation does not exist or does not belong to this user.

watch_conversation

Cancel the turn Vincent is currently running in a conversation. Call this only when the user asks to stop, cancel, or abandon a run — never because a turn is taking a while. The conversation survives; a stopped run just ends where it got to, and the user can send another turn afterwards. `stopped` is False when there was nothing running. That is a benign outcome, not an error: say the run had already finished rather than reporting a failure. Read get_conversation_messages afterwards to see what Vincent kept. Common errors: - 404: the conversation does not exist or does not belong to this user.

Submit the proposed tasks the user picked, and drive the run that follows. This is how a `"task_submission"` interruption is resolved. Vincent proposes follow-up work as a list of tasks; the user chooses which of it to run, and this call sends that choice back and returns the resulting turn. Selection is by INDEX: a proposed task has no id until it is submitted, so pass the `index` values from the interruption's `tasks`. Never answer a task proposal with continue_conversation. That posts a new question instead, which starts a fresh piece of work and abandons the proposal — the tasks the user chose are then never run. There is no card for this: list the proposed work, ask which of it they want, and submit their answer here. Returns the same `TurnResult` as start_research — read `state` and handle any further `interruptions` the same way; see that tool for the full protocol. Arguments: - `conversation_id` (required): the conversation holding the proposal. - `message_id` (required): the interruption's `message_id`, which is the proposal message's own id. Submitting replaces that message in place. - `selected_task_indices` (required): the `index` of every task to run. Must name at least one; tasks left out are recorded as not selected.