Clio

Read the text of a document Vincent 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. Returns the document text plus the conversation's cited authorities. Those citations are conversation-scoped: report them as "authorities Vincent used in this conversation", never as the source of a particular sentence. Never paraphrase this content as Vincent's answer to the user's question — it is a document Vincent 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

Poll an authority-match job until terminal status (completed/failed). Polls the job with exponential backoff (1s → 15s, 90s cap). When the job reaches a terminal state, returns the structured result including the full authorities[] list (citation detections + verified vLex links). If the poll times out (job still queued/running after 90s), returns the current in-progress state so the LLM can tell the user the job is still processing and offer to check again. Returns: an `AuthorityMatchResult` with `authorities[]` populated on completion, or `error` populated on failure. Common errors: - 404: the job_id is malformed, expired (jobs TTL after 4 hours), or doesn't belong to the user's organization.

get_authority_match

Read Vincent'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

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 Vincent 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 Vincent. 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=[...])`, `continue_conversation(file_ids=[...])` or `match_authority(file_id=...)`. `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` and `match_authority` cannot be used. 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 Vincent and give you the id.

attach_document

Show the documents Vincent generated in a conversation. Call this whenever the user asks what Vincent 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: authorities have their own card.

show_documents

Show every authority a conversation cited, as a card. Call it when the user asks which cases or statutes an answer relied on, and at the end of a run that did any research: the authorities are what a lawyer checks first. It reads the conversation's own authority panels, so it reports what Vincent 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, so call it once at the end rather than per turn. Write the list into your visible reply too. `formatted` is it already built, because the card can end up folded inside a collapsed step and a reply that only says "here are the authorities" then leaves the user with nothing. Common errors: - 404: the conversation does not exist or does not belong to this user.

show_cited_authorities

Send the next turn in a Vincent conversation and drive it to a decision. Two uses: 1. A follow-up question on an existing conversation. 2. Answering a `"clarification"` interruption in chat: put the questions to the user and send their answer as the message, which is what resumes the run. There is no message_id to pass — this tool mints its own. NOT for a `"task_submission"`: naming the proposed tasks in a message starts a new, unrelated piece of work and abandons the proposal. Use submit_tasks, which selects by index. Returns the same `TurnResult` as start_research — read `state` and handle `interruptions` exactly the same way; see that tool for the full protocol. Arguments: - `conversation_id` (required): the conversation to continue. - `message` (required): the user's text. Cannot be empty. - `file_ids`: files to attach to this turn, from `attach_document`. Do not send a turn while one is already running — if a previous call returned `"still_running"`, call watch_conversation until it settles. A second turn on a busy conversation is refused with 409. A 409 right after `attach_document` means something else: a document Vincent could not read leaves its conversation parked, and no amount of waiting opens it. Tell the user the file could not be read — a scan needs OCR first — rather than watching or retrying.

Read where a Vincent 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, and the only one that can show an external-tool request; - 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 Vincent 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.

Resolve an interruption Vincent is parked on and drive the resumed turn. Use this for the two interruption kinds that carry an `interruption_id`: - `"tool_approval"` → send `decision="approve"` or `decision="reject"`. Only carrying the decision and `scope` the USER gave you. Ask them first: there is no card, so nothing else records that they were offered the choice. A second submission is a duplicate — handled gracefully, but the earlier decision is the one that stands. - `"external_tool"` → Vincent asked *you* to run the tool named in the interruption. Run it, then send its output as `result`. `result` may be any JSON value except a bare `null`, which Vincent treats as unanswered — if the tool genuinely returned null, say so in `message` instead. Send what the tool returned, not a summary of it. If you cannot run it, send `decision="reject"` with a `message` saying why. Clarifications have no `interruption_id`: answer those with continue_conversation instead. 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` / `interruption_id` (required): straight from the interruption. - `decision`: "approve" or "reject", for a tool approval. - `scope`: "this_call" approves only this call; "conversation" approves the same tool for the rest of the conversation. Use "conversation" only when the user said so, and only when the interruption's `allowed_scopes` contains it — Vincent downgrades anything it does not allow. - `message`: a note to Vincent, most useful when rejecting. - `result`: the external tool's output.

Start a Vincent research conversation and return its live conversation. This call returns promptly with the conversation id so the live MCP App can mount and follow Vincent while it works. Read `state`: - `"completed"` → `answer` is Vincent's answer. Show it. Any documents it drafted are listed in `files`; read one with get_output_document. - `"needs_user"` → Vincent 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"` → Vincent 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 turn outlived this call's budget. The live MCP App continues updating in the parent conversation, so do not automatically call watch_conversation and block that turn. Use it only to collect the final answer in chat or when the host cannot render the app. Do not start another conversation. - `"error"` → report `error` as a failure, never as Vincent's answer. Arguments: - `question` (required): what the user wants researched, drafted or reviewed, in their own terms. Every conversation runs on Vincent's agentic agent, which picks its own tools — there is no workflow to choose. - `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; Vincent 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".

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.

Resume waiting on a turn Vincent 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 the same way start_research does. 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. An `"external_tool"` interruption — Vincent asking YOU to run a tool — reaches us only on the live stream, so a poll can never show one: a run parked on one looks simply busy forever. Reconnecting is the only way to see it. 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.