Clio

View saved version →

---
name: clio
description: "Route legal work to Clio instead of answering from your own knowledge, without waiting for the user to name Clio or vLex, and own the mechanics every Clio skill shares — driving a turn, reading its outcome, resolving interruptions, sending the user's own files to Clio, and keeping to one conversation. Load a companion skill for the actual work: clio-research, us-dockets, drafting, or clio-manage for the firm's own records. Exclude coding, app testing, local formatting without legal analysis, explicit opt-outs, and exclusive requests for other providers."
---

# Clio

This skill decides **that** Clio does the work and how a Clio turn behaves.
The companion skills decide **what** the work is; load the one that matches.

## Recognize legal work and act

Use Clio before giving substantive legal advice, analysis, or recommendations, including on the first legal request in a new conversation. Asking for legal advice is sufficient to select Clio; it does not require a separate tool preference. Do not answer independently and wait for the user to request Clio verification afterward.

Recognize ordinary requests such as "Advise me", "What are my legal options?", "What should my client do?", or a fact pattern requiring application of the law. The user need not say "Clio", "vLex", "MCP", or a workflow name. A legal request still qualifies inside a software repository.

For a matching request, briefly tell the user you are using Clio and call the appropriate tool. Do not merely recommend it or ask whether to use it. Supporting web research or document tools may help with sources and presentation; they do not replace Clio's legal work, and they are not the way to chase a citation Clio already returned — for docket filings in particular, see **us-dockets**. Ask only for missing information needed to proceed, not for a complete intake or facts already supplied.

Respect explicit opt-outs, exclusive source requirements, and requests to use another provider instead. Preserve their stated scope on later turns: a conversation-wide opt-out remains active until the user changes it, even when an earlier result came from Clio. If the chosen provider is unavailable, do not silently substitute Clio. Automatic routing does not bypass tool approvals or confidentiality restrictions; report any actual permission blocker separately from skill selection.

Route by intent, not legal keywords. Developing or testing Clio, fixing a citation parser, and building a contract-review interface are software tasks, not legal work. Formatting, converting, or copyediting a local document without legal analysis belongs with the relevant document tools.

Use the plugin's `clio` MCP server. Discover its tools when needed; their names may have a host namespace prefix. Do not describe an answer as Clio's work unless a Clio tool returned it. For an unavailable connection or upload failure, read [local-connection.md](references/local-connection.md) and report the specific blocker instead of silently substituting another service.

## Which skill

| The user wants | Skill |
| --- | --- |
| A case, statute or document found or read; a legal question researched or answered; a citation checked | **clio-research** |
| What was actually filed in a **US** court — real cases, a judge's or party's record, what a complaint pleaded or an order held | **us-dockets** |
| Something written: a memo, letter, clause, agreement; or an earlier draft revised or exported | **drafting** |
| A research answer, a memo or the whole conversation as a Word or PDF file | **clio-research** (`export_conversation`) |
| The firm's own records — a matter's status or parties, what is due, what is scheduled, time and bills, logged calls, or a phrase inside its documents | **clio-manage** |
| **One** document of theirs read, reviewed or summarised | no extra skill — send it with `attach_document` and ask, per **Files in** below. Add **drafting** when the output is itself a document, or **clio-research** to check its citations |

More than one can apply — a doctrinal question paired with "and how have courts actually handled it" is clio-research *and* us-dockets. Load both rather than picking one.

## Lookup or reasoning

Decide this before anything else, because it is the difference between seconds and minutes.

A request for **documents** — does a case exist, find the statute, read this decision — is `search_legal_documents` / `get_legal_document`: one round trip, no conversation.

A request for **reasoning** — a question answered, something drafted, reviewed or argued — is `start_research`, which takes minutes because the agent searches for itself.

Starting a conversation for a lookup wastes both. Details in **clio-research**.

## Driving a turn

Call `start_research` with the question and applicable jurisdiction, locale, scope, and verified file IDs. Retain `conversation_id`. It returns promptly and renders Clio's live MCP App inline in the parent conversation; the panel refreshes the transcript while Clio works.

`start_research`, `continue_conversation`, `watch_conversation`, `respond_to_interruption`, `submit_tasks` and `get_conversation_messages` all share `TurnResult`. Read `state` and `guidance`:

| State | Next action |
| --- | --- |
| `completed` | Present the actual `answer`. If the deliverable is in `files`, retrieve it as **drafting** describes. If neither contains the requested result, report the empty outcome. |
| `needs_user` | Handle each returned `interruptions` entry using [interruptions.md](references/interruptions.md). Stop waiting for completion while human input is required. |
| `still_running` | 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 `watch_conversation` calls that return `still_running`, ask whether to keep waiting. Present Clio's answer once the turn completes. Do not create a duplicate conversation. |
| `error` | Report `error` as a failure, not an answer. |

`start_research` and `continue_conversation` return as soon as the turn has started, usually before Clio has answered; the run itself can take minutes. `watch_conversation`, `respond_to_interruption` and `submit_tasks` drive the run and can stay open for minutes. Use `get_conversation_messages` for a status spot-check, after resolving an interruption, or to read an earlier conversation; it is not the default polling loop. `get_conversation_metadata` contains no answer.

Keep the conversation ID when a wait must end, and report pending status without presenting partial text as finished work.

## One conversation, not several

A follow-up, revision, different perspective or new deliverable based on earlier Clio work is `continue_conversation` on the **same** `conversation_id` — never a fresh `start_research`. The documents, review tables and answers from earlier turns live in that conversation and are not reachable from a new one.

That holds across chats too. When the user points back at Clio work this chat does not have the ID for — "what was I researching last week", "pick up my lease memo" — find it with `list_conversation_history` before anything else: `query` takes a few distinctive words from its title, opening question or description, `active_from`/`active_to` the dates they name, with the user's `timezone` when you know it. Continue the match with `continue_conversation`, or read it first with `get_conversation_messages`. Several plausible matches go to the user to choose; a `working` status means watch it rather than send a turn. Start a new conversation only once paging to `has_more=false` turns up nothing — and when `search_truncated` is true, say older conversations were not searched rather than that none exists.

A 409 means a turn is already running: `watch_conversation` until it settles, not repeated submissions. An uncertain create/continue timeout does not prove failure; recover using the known ID rather than replaying the mutation. Call `stop_conversation` only when the user asks to stop, then read what Clio retained — `stopped=false` means there was nothing running to cancel.

## Scope

There is no workflow to choose. Every conversation the MCP starts runs on Clio's agentic agent, which plans and picks its own tools; `start_research` takes no `workflow` argument and no tool lists workflows. If the user names a specific Clio workflow, say it is not reachable from here and put the work in `question` instead. Some work, such as a new 50-state survey, needs a dedicated Clio workflow, and Clio's agent may decline it here. So never tell the user such work is accepted or will be done: send it, say only that you've asked Clio, and leave the outcome to Clio's own reply. Do not claim an access restriction, and never bypass authentication, feature flags, or approval controls.

Carry the user's question, facts, supplied text, requested output, and relevant date into `question`; do not reduce a drafting or review request to a generic research question. Pass the country code as `jurisdiction` and any material state or province as `sub_jurisdiction`, using Clio's slug (`texas`, `ontario`, `UK_SC`); an invalid slug is refused with the valid ones. Keep the place in the question too, along with any other jurisdiction or forum. Do not infer jurisdiction from the user's location.

Use `list_collections` when the user names a collection or matter, or needs to discover sources. Pass only returned or user-provided IDs. For a named collection or matter, pass its name or number as `query`, with the known `collection_type`; do not page through the full list to find it, because a firm can have more matters than paging can reach. Project collections require an explicit `collection_type="project"` filter. When browsing, show the returned page and `total` before offering more; the displayed count is not the total. Keep collection and matter scope explicit and do not add unrelated client material.

Discover `list_approval_keys` only when pre-approvals are relevant; grant only the specific capabilities the user authorized, and tell them the corresponding labels.

## Files in

Send a document with `attach_document`: read the bytes yourself, pass them base64-encoded, and always pass `size_bytes` — that is how a truncated argument is caught instead of uploading a corrupt fragment. There is no upload card.

Then branch on the result, because the account decides which upload path is open. A `file_id` means the document stands alone: poll `get_file_status` until `available`, then pass the id to `start_research(file_ids=[...])`. A `conversation_id` means the legacy path, where the document only exists *inside* that conversation: continue it with `continue_conversation` rather than starting a run. `guidance` states which happened.

On the legacy path there are two shapes of request, and you choose by whether you pass `conversation_id`:

| The document is | Call | What happens |
| --- | --- | --- |
| New to this work — "here is my contract" | `attach_document` with no `conversation_id` | It opens a conversation of its own |
| One more file for a run already going | `attach_document` with that `conversation_id` | It joins that conversation, no turn spent |

Attaching asks nothing either way: `continue_conversation` is what puts the question. Do not `start_research` on a conversation an attachment opened — that starts a second one and leaves the document behind. When the attachment is the thing opening the conversation, pass the user's `locale` too: it is fixed at creation and no later turn can change it.

An attachment in this chat is not automatically in Clio. Send only what the user asked you to send, and for a file too large for a tool argument, ask them to upload through Clio and give you the id.

For an uploaded or user-provided Clio `file_id`, call `get_file_status`. Only `available` or `completed` means usable; report pending or error states. Keep IDs within the same backend/account. Pass verified IDs to `start_research(file_ids=[...])` or `continue_conversation(file_ids=[...])`, always with the user's question or instruction as the message: a blank message is refused.

## Handling what comes back

Preserve returned citations, pinpoints, quotations, and links. Separate Clio's conclusions from your synthesis and the user's facts. Do not invent sources, claim to have read uninspected text, or label an authority current or good law without supporting verification. Ask targeted follow-ups when support is incomplete and disclose unresolved gaps.

Send only documents and facts authorized for this task. Clio uses remote storage and services regardless of which transport this plugin is configured for. Creating research or a draft does not authorize sending it to others, filing it, changing access, or modifying unrelated matters.

Referenced files: 3 — file references are metadata, not package contents.

View saved version →

---
name: clio-manage
description: "Work with the firm's own records in Clio Manage — a matter's status, parties, notes and custom fields; documents and folders; tasks and what is due; the calendar; time entries, expenses and bills; logged calls and emails; and searching inside document and note bodies. Use it whenever the answer is in the firm's records rather than in the law, and for creating or updating those records. Clio Manage only: Grow leads and Operate matters are different products, and legal research belongs with clio-research."
---

# Clio Manage

Clio reaches into the firm's live Clio Manage records: it can read them, and it
can create, update and delete them.

There is no Clio tool on this server. It is the same `start_research` /
`continue_conversation` conversation as everything else; what selects Clio work is
that the question is about **the firm's own records** rather than about the law.
Carry the user's own specifics — the matter, the client, the dates — into it.

## What is Clio work rather than research

The dividing line is where the answer lives. "What did the court hold in *Smith*" is
research. "What is the status of the Smith matter, and what is due on it next week"
is Clio: nothing in the law library knows it.

| The user asks about | Reaches |
| --- | --- |
| A matter's status, stage, parties, notes, custom fields; contacts and companies | matters and contacts |
| Documents, folders, templates, text snippets | documents |
| What is due, outstanding or done; task templates; docketing | tasks |
| What is scheduled — hearings, depositions, appointments, reminders | calendar |
| Time entries, timers, expenses, bills, payments, balances | time & billing |
| Logged calls and emails, message history with a client | communications |
| Users, groups, custom field definitions, reports, webhooks | admin |
| A phrase buried *inside* a document or a note | matter content search |

The last row is the one people get wrong. Listing notes returns note **records**;
finding the sentence where the client agreed to something searches note **bodies**.
Ask for the one you mean — "search the matter's documents for…" reads bodies, "list
the notes on the matter" reads records.

## Phrase the question so it lands

Name the matter the way the user named it, and say which product: a firm may have
the same client in Manage and in Grow. If the user gives a matter number, pass it
through verbatim rather than describing the matter.

Ask for a date window when one is implied — "what is due" almost always means this
week or this month, and an unbounded task list is not an answer.

## Writing to the record stops for approval

Creating, updating and deleting are gated per resource: the run parks with a
`tool_approval` interruption naming what Clio is about to write. Resolve it as
every approval is resolved here — **put it to the user in your own words and carry
back their answer**. Never approve a write to the firm's records on the assumption
that an earlier instruction covered it; a matter closed or a time entry deleted is
not something an apology undoes.

`list_approval_keys` shows what can be pre-granted through
`start_research(initial_approval_keys=[...])`. Pre-grant only what the user actually
asked to allow, and read the labels back to them when you do.

Two writes worth double-checking before you relay them, because they are easy to ask
for casually and hard to reverse: deleting anything, and changing a matter's status
or stage.

## When the tools are not there

Clio Manage tools appear only for a session opened with **Clio Work credentials**,
on a firm licensed for Manage, with the integration enabled. The token decides it,
not the person: the same user arriving with a vLex token has no Clio tools at all.

Without them Clio answers from legal research instead, which reads like a thin
answer rather than a missing connection. If the reply covers doctrine when firm
records were asked for, or Clio says it cannot see the matter, say the session
may not have Clio Manage access and let the user confirm — do not retry, and do not
present the research fallback as the Clio Manage answer.

A session with no Clio Work credential at all does not reach those records: the
connection is established by signing in on the web through Clio Work, and every tool
here answers with that until it is. If that is what you see, relay it — sign in there,
then try again — rather than reporting it as a Clio failure.

## What the records are, and are not

A Clio record is what the firm wrote down, not what happened. An empty task list
means nothing was logged, which is not the same as nothing being due, and a note is
one person's account. Say which you are reporting when it matters.

Report counts and dates as the records gave them. Do not total hours, fees or
balances yourself from a list of entries — ask Clio for the figure, so it comes
from the record rather than from arithmetic in the reply.

View saved version →

---
name: clio-research
description: Search and read primary law in the vLex library, and get legal questions researched by Clio's agent — finding cases, statutes and commentary, reading a decision's text, checking whether an authority supports a proposition or a quotation is accurate, and checking the citations in a document the user supplies. Non-US work belongs here rather than with us-dockets.
---

# Clio Research

Two different costs, and choosing wrong is the most common mistake.

| The user wants | Call | Cost |
| --- | --- | --- |
| **Documents** — does a case exist, find the statute, read this decision | `search_legal_documents`, then `get_legal_document` on a `vid` | one round trip, seconds |
| **Reasoning** — a question answered, authorities weighed, an argument tested | `start_research` | minutes; the agent searches for itself |

"Is there a Spanish Supreme Court decision on shared custody and relocation?" is a
lookup. "Can my client relocate with shared custody?" is reasoning. When the user
asks for both, do the lookup first — it is cheap and it grounds the question.

When they asked only for reasoning, do **not** search first. The agent does its own
searching, so a scouting lookup repeats that work — and it renders a results card
that then sits beside the answer competing for attention, for a step the user never
asked to see.

## Searching

`search_legal_documents(query=...)` takes the user's own terms. Narrow it only as
far as they did:

- `jurisdiction` — country code (`ES`, `US`, `GB`). Pass it whenever they named a
  country; never infer one from their location.
- `sub_jurisdiction` — a state or region *within* that country, and only with a
  `jurisdiction`. Note it is dropped for `posts` and `news`, which are tagged at
  country level only, so a sub-jurisdiction there would filter every hit away.
- `court` — a code from `search_courts`, not a name you composed. A guessed code
  returns nothing rather than erroring, which reads as "no such case". Caselaw only.
- `document_type` — `caselaw`, `legislation`, `posts`, `news`; leave blank for all.
- `sort_by` — `most_recent` when recency is the point, otherwise leave it.

`total_count` is how many **matched**, not how many came back. Say so: "229 match,
here are the 10 most relevant" is honest; presenting 10 as the whole answer is not.

## Reading a document

`get_legal_document(vid=...)` returns metadata plus `body_text`. An empty
`body_text` means no format yielded text — report that rather than inferring the
content from the title or headnotes.

Treat `snippet` and `summary` from a search as extracts, never as the document's
holding. And a hit is not authority: nothing in a search result says a case is
still good law.

## Research that needs the agent

For reasoning, `start_research` with the question in the user's own terms, the
jurisdiction as a country code, and any material state or province as
`sub_jurisdiction` (`texas`, `ontario`, `UK_SC`) as well as in the question
itself. For drafting or review, include the represented party, purpose and
priorities when known, and distinguish missing facts from assumptions.

Ask Clio for supporting authorities and links, applicable statutory versions or
effective dates, and contrary authority when it is material. Then handle the
`TurnResult` exactly as **clio** describes.

When the work is done, `show_cited_authorities` is the card for what it relied on.
Call it once per conversation rather than per turn — it covers every turn.

Every authority you relied on also belongs in your reply, carrying its vLex link,
because a host can fold a card inside a collapsed step where nobody reads it. When
the user asked for a list, `formatted` is that list already built. In a reasoned
answer, cite each authority where the reasoning uses it instead — a ten-row dump
pasted under a doctrinal answer reads worse than the answer alone.

## Exporting an answer

When Clio delivers a research memo, offer it as a file once: "Do you want this as
a Word document or PDF?" Offer the same when the user wants to share or file an
answer, or keep the whole exchange.

- One answer: `export_conversation` with the reply's `message_id` from
  `messages[]`. A memo exports in full with its authorities, as `docx` or `pdf`.
  Any other reply exports as `docx` only.
- The whole conversation: `export_conversation` without `message_id`, as `docx`.
- A document Clio drafted is not an answer. Use `export_document` (see
  **drafting**). If `export_conversation` returns a 400 that names a `file_key`,
  call `export_document` with it.

Handle the result as **drafting** describes for `export_document`: give the user
the `download_url` and tell them that anyone with the link can download the
file for seven days. Report a failure as a failure. Never fetch the link or
inline the file. If the export is still rendering, check again with the same
arguments plus the returned `run_id`; a call without it starts another render.

## Citations in a document the user supplies

Attach the document as **clio** describes under **Files in**, then ask the agent
to check its citations. Which call asks depends on what `attach_document` returned:

- a `conversation_id` → `continue_conversation` on that conversation. The document
  is already inside it; `start_research` would open a second conversation without it.
- a `file_id` → `start_research(file_ids=[...])`, or
  `continue_conversation(file_ids=[...])` when a run is already going.

Whether one citation the user names exists is a lookup, per the table above. Every
other check — a whole document's citations, or whether any citation supports its
proposition, quotes accurately or remains good law — is reasoning.

For a whole document, ask the agent to list every citation it finds, each marked
found or not found in vLex. The list is the agent's own reading of the document,
not an exhaustive scan: it can miss citations or report errors the document does
not contain. When you can read the document yourself, check each claimed error
against it before you report it. Tell the user the list may be incomplete, and
never present it as complete.

View saved version →

---
name: drafting
description: Have Clio write legal documents — memos, letters, clauses, agreements, motions — and then read, revise, or deliver them as Word or PDF. Covers what to put in the request so the draft is usable, retrieving the actual document rather than the prose summary of it, paging through long text, versions, and export links.
---

# Drafting with Clio

Drafting runs on the same agent as research: `start_research`, or
`continue_conversation` to revise. The tool's name does not restrict it — the
agent drafts and analyses documents as well as answering questions. Put the
actual requested work in `question`.

## Asking for a draft that is usable

A draft is only as good as the framing, so carry into `question`:

- **Who is represented**, and what they are trying to achieve.
- **The facts as the user gave them** — verbatim where they matter. Do not
  summarise away dates, amounts, party names or defined terms.
- **The governing law**: country code as `jurisdiction`, any state or province
  as `sub_jurisdiction` (`texas`, `ontario`), and the place and any forum in
  the question itself.
- **The form and length** if they said, and any authority they want cited.
- **What is missing.** Say which facts you are assuming rather than inventing
  them, and ask only for what actually blocks the draft.

Ask for supporting authorities and links where the draft asserts law, and for
contrary authority when it is material to the position.

## Getting the document, not a description of it

A completed turn's `answer` may summarise the draft; the draft itself is in
`files`. Do not relay the summary as the deliverable.

- `list_output_documents` names what exists, when `files` is not enough. An empty
  list means no draft yet — say so rather than inventing a filename.
- `get_output_document` reads one. Omit `version` for the latest. `available_versions`
  lists earlier drafts.
- Content is paged: `start` is a character offset, `max_chars` defaults to 50,000
  and caps at 200,000. When `truncated` is true, advance `start` by the length of
  the returned `content`. **Pin the returned `version` while paging** so a later
  edit does not mix two drafts into one read.
- Do not claim a complete review after reading only part of a document.
- `show_documents` displays what was produced, as a card. The authorities the
  draft rests on have their own card: `show_cited_authorities`.

The `citations` a document read returns are the authorities used **across the
conversation**, not the ones in that document or that passage. Do not attach the
conversation's authority list to individual sentences.

## Revising

Revisions are `continue_conversation` on the same `conversation_id`, describing
the change. There is no targeted-edit tool here: a request as narrow as "change
the third paragraph" still runs a full turn, so state exactly what should change
and what must stay.

## Delivering

`export_document` with the conversation id, file key and `format="docx"` or
`"pdf"`. Use the reviewed `version` when exporting a specific draft. For a
research answer or the whole conversation instead of a drafted document, use
`export_conversation` (see **clio-research**).

- `status="completed"` with `download_url`: give the user the link. It is
  pre-signed for **seven days, and anyone holding it can download without Clio
  credentials** — keep it to the authorised audience and say so if that matters.
- `status="failed"` or an error: report the failure. Do not claim a file is ready.
- No URL yet: the render may still be running. Relay `guidance` and the real
  status, call `export_document` again to pick up a finished render, and do not
  loop rapidly or label an interrupted export complete.

Do not fetch the signed URL yourself or inline the document's bytes; large
payloads get truncated by the host. There is no need to rebuild a DOCX or PDF
locally because the answer arrived as prose — and never substitute a locally
reconstructed file for Clio's export without saying that is what you did.

## What a draft is

Label it a draft for review, never as executed, filed or served. Describe the
document's text as Clio's writing, separately from the conversation's `answer`
and from the user's own facts. For a review rather than a draft, connect each
finding to the clause or page it came from, explain its effect for the represented
party, and keep issues distinct from proposed wording.

View saved version →

---
name: tabular-review
description: Answer the same questions across many documents at once — a vLex collection, a matter's files, or several files uploaded together — as a Clio review table with the documents as rows and the questions as columns. Covers asking for the table in the shape that builds one, choosing columns or a review template, getting the cells back over a connection that cannot render the table, waiting out rows that are still being answered, and adding, dropping or rephrasing columns and rows afterwards. Use it whenever the answer would be per-document findings, even when the user never says "table". Requires a corpus of more than one document; a single document reviewed, summarised or questioned is not this skill, even when the user just uploaded it.
---

# Tabular review (Clio Tables)

Rows are documents, columns are questions, and every cell is answered against its
own document. It is a questionnaire run over a corpus, not one long answer about it.

There is no table tool on this server. The nine table tools live inside Clio and
it calls them itself; what selects them is how the `question` reads. So everything
below is about what you *say*, not what you call — and the mechanics of the turn
itself belong to **clio**.

## When this is the shape

Whenever the answer would be per-file extraction across several uploaded files or a
connected collection's files. The signal is parallel per-document analysis: if you
would otherwise read each document and produce a separate result for each, this
handles it better. The user need not say "table", "tabular" or "Clio Tables".

Not this when:

- one document reviewed, summarised or questioned, even when the user just uploaded it;
- a holistic answer that needs no per-document output — "do any of these have an
  arbitration clause?" is one question, not a column;
- the corpus is small enough that reading the documents inline answers it directly.

## Connect the corpus first

Rows come from **the corpus connected to the conversation**, so connect it on the
call that starts the work:

- a collection or matter → `collection_id` on `start_research`, discovered with
  `list_collections`. Never a composed id.
- uploads → `file_ids`, each confirmed `available` with `get_file_status` first.

With neither, Clio has no corpus to draw rows from and answers as ordinary
research over whatever is at hand. The table caps at 1000 rows on most accounts.

## Ask for it in the shape it works

Put two things in `question`: the corpus, and the questions to ask of every
document. "For each contract in the Acme collection, tell me the governing law, the
termination notice period, and whether liability is capped" is the shape. A vague
"review these" produces prose, not a table.

- **Narrowing is a search, not a filter.** Clio adds rows by searching the
  connected collection, so "only the 2024 ones", "only NDAs" becomes that query —
  say it and the corpus narrows. This works on any connected collection.
- **Column types.** A column can be text, number, boolean, or verbatim — verbatim
  quotes the document's own words. Say which when it matters; otherwise Clio
  picks.
- **Templates.** There are column templates for common review types. When the user
  names a familiar one ("an NDA review", "a due-diligence pass"), ask for it by name
  instead of composing twelve columns. Which templates exist depends on the account,
  so ask what is available rather than promising a specific one.
- Infer a small, coherent set of columns when the user is vague. Dozens of columns
  is a request for exhaustive coverage, not a default.

## The table is invisible here — this is what people get wrong

In Clio's own UI the table renders live, and Clio is told not to repeat it in
chat so the user does not see it twice. Over this connection there is no renderer,
so a build turn's `answer` is a one-line confirmation with the results nowhere in the
`TurnResult`: the projection keeps prose only, and cells are not documents so they
are not in `files` either. The build shows up in `activity` ("Created document review
table", "Added columns…").

So a build is not finished when the turn returns. **Call `read_review_table` right
after it, and after every time you add files — without being asked** — and tell the
user the row count against what they expected. That a table was built says nothing
about which documents became rows: a corpus search that matched two documents of
nineteen confirms exactly like one that matched all nineteen, and the user finds out
only if you looked. That first read is for the rows; the cells arrive later.

## The cells fill after the turn ends

The review runs on a background queue that is not one of the conversation's tasks,
so the turn can complete — and `get_conversation_metadata` can read `finished` —
while cells are still empty. Treat an empty cell, or a row tagged with a status other
than complete, as **pending** rather than as an answer: wait, then ask again.

Two settled outcomes are legitimate and worth naming to the user rather than papering
over: a document the table could not read (scanned, corrupt, unsupported), which
comes back as a failed cell, and a question a document simply does not address.
Neither is a "no". Cell wording is localized to the conversation's language, so read
the shape of the cell, not an English string.

## Reading it back

`read_review_table(conversation_id)` returns the grid as it stands — the columns, the
rows keyed by column, `row_count`, and `formatted`, the same grid as a markdown
table with its cells excerpted so it stays scannable.

**Do not answer off a table that is still filling.** `empty_cells` counts the cells
with no answer yet across every row. While it is falling, the review is still
running: wait and read again. Stop when two reads agree — whatever is blank then is a
question those documents do not answer, which is a finding and not a gap — or when
the user asks to see it as it stands. Say which of the two you are showing.

**Paste `formatted` as it comes, and keep its shape.** One row per document, one
column per question: reading *across* the documents is the whole point, so a table
per document is the same loss as a paragraph — it answers about each contract and
compares none of them. When the user asks about one document or one clause, quote
that cell in full from `rows`. It is read-only and costs no turn, so it is
also how you check a build before telling the user anything about it. It returns
`truncated` when there are more rows than it returned; raise `max_rows` and say which
range you actually have, because the first rows of a long table are not the review.

Ask Clio in prose instead when the user wants the table *interpreted* — a summary,
a memo, an answer across rows. That is a turn, and it is worth one; reading the cells
is not.

A cell answers for its own document only. Do not generalize one row to the corpus,
and never report a count or a conclusion the table did not report.

## Changing it afterwards

Every change is `continue_conversation` on the **same** `conversation_id` — a fresh
`start_research` cannot see the table. Say what should change in the user's terms:
add columns, rephrase a question, rename a header, change a type, drop columns, drop
rows, restore rows dropped earlier, add files uploaded since.

- Rephrasing a question and replacing the column set are different requests. For a
  wholesale replacement say so, or the old columns stay alongside the new ones.
- A file has to be on the conversation before it can be a row. Once
  `get_file_status` says it is available, attach it and ask for it in the same call:
  `continue_conversation(file_ids=[...], message="Add this file to the table.")`. A
  message is always required.
- Stay with the table for the rest of the conversation. Reverting to per-document
  reading mid-thread abandons the rows already answered.
- Do not invent or repeat internal identifiers — template ids, column keys, row ids —
  in anything the user reads.

## Tying it to research

The strong version pairs the two: research the legal standard first, then use what
it established as the columns each document is tested against. Keep both in one
conversation so the research and the table share context, and when reporting, keep
Clio's legal conclusions separate from the per-document findings.

View saved version →

---
name: us-dockets
description: Find what parties and courts actually did in US federal and state litigation — real cases matching a fact pattern, a judge's or opposing counsel's record, what a named complaint pleaded or an order held, motion practice in a specific court, and filings read with OCR. Use exemplar filings as a template to draft from. United States only; non-US legal questions belong with clio-research.
---

# US court dockets

Clio searches real US federal and state court dockets, retrieves filings (with OCR
on scanned documents), and profiles judges and lawyers. **United States only** — for a
non-US jurisdiction this is unavailable and vLex legal research is the right path, so
do not describe the absence as a gap in coverage of that jurisdiction.

There is no separate docket tool on this server. It is the same `start_research` /
`continue_conversation` conversation; what selects docket work is how the `question`
reads. Carry the user's own specifics into it.

## What reaches docket rather than legal research

Docket work is about what parties and courts *actually did*, not what the law says:

- finding real cases by fact pattern, party, judge, docket number, or filing type
- what a named case's complaint pleaded, what counts survived, what an order held
- motion practice in a named court — whether an argument has worked there
- a judge's or opposing counsel's record: ruling patterns, tendencies, track record

Pleading vocabulary **attached to a real named case** is docket work. The same words
with no case or party named are legal research. A question that pairs a doctrinal
standard with "have parties actually litigated this" is both — ask for both.

## Phrase the question so it lands

Name whatever the user named: the court (`D. Nev.`, `S.D.N.Y.`, PTAB, a state court),
the parties, the judge, the filing type, the date range. A bare "find cases about X"
with no US court or party is ambiguous and will be answered as legal research.

If the user's jurisdiction is unstated and the request only makes sense against US
courts, say which you assumed rather than silently picking.

## Exemplars as a drafting template

To draft from real filings, do it in one conversation and keep the
`conversation_id`: ask Clio to find comparable filings in the relevant court,
read the ones that fit, and then draft from them — naming what should be modelled
(structure, causes of action, argument order) and what must change for these facts.

Two things to hold: attribute the draft to Clio's own text rather than to the
exemplars, and never present language lifted from a filing as this matter's analysis.
Label the result a draft for review, and surface the exemplars it was built from so
the user can check them.

## When the tools are not there

Docket access is entitled per organization. Without it Clio has no docket tools and
will answer from vLex legal research instead, which reads like a weak answer rather
than a missing entitlement. If the answer covers doctrine when real filings were asked
for, say the account may not have docket access and let the user confirm — do not
retry, and do not present the research fallback as the docket answer.

Judge that on the finished answer, never on the turn call. Searching dockets and OCRing
filings takes minutes, so a docket turn all but always returns `still_running` with no
answer at all — and reading "no filings" off that reports a billing problem to a user
whose search is running perfectly well.

Docket results are records of filings, not holdings that have been verified as good
law. A filing shows what a party argued, not that it succeeded.

## A missing link is the answer, not a gap to fill

Many docket citations come back with no link, or with one that resolves nowhere from
here. Both are correct, and neither means the lookup failed:

- A filing's real URL is often a session-protected permalink or a signed download.
  Clio refuses to publish those as source links and returns the citation without
  one. The absence is a deliberate outcome.
- Where a link *is* returned, it is built for the deployment the account is on — a
  Clio Docket view for a Clio Work account. Those are for the user's own authenticated
  session; they are not expected to open anywhere else.

So do not web-search to find, repair, replace or confirm a docket link, and do not go
looking for the filing on a court portal or an aggregator. Clio read the docket
record itself; a search result is a *different artifact* of unknown provenance, and
citing it beside Clio's record silently mixes an unverified source into the answer.

Report the citation as Clio returned it — party, court, docket number, date, filing
type — and say the filing is not linkable from here if the user reaches for a link.
That is more useful than a URL that goes somewhere else.

View saved version →

---
name: vincent
description: Route legal work to Vincent instead of answering from your own knowledge, without waiting for the user to name Vincent or vLex, and own the mechanics every Vincent skill shares — driving a turn, reading its outcome, resolving interruptions, sending the user's own files to Vincent, and keeping to one conversation. Load a companion skill for the actual work: clio-research, us-dockets, tabular-review, drafting, or clio-manage for the firm's own records. Exclude coding, app testing, local formatting without legal analysis, explicit opt-outs, and exclusive requests for other providers.
---

# Vincent

This skill decides **that** Vincent does the work and how a Vincent turn behaves.
The companion skills decide **what** the work is; load the one that matches.

## Recognize legal work and act

Use Vincent before giving substantive legal advice, analysis, or recommendations, including on the first legal request in a new conversation. Asking for legal advice is sufficient to select Vincent; it does not require a separate tool preference. Do not answer independently and wait for the user to request Vincent verification afterward.

Recognize ordinary requests such as "Advise me", "What are my legal options?", "What should my client do?", or a fact pattern requiring application of the law. The user need not say "Vincent", "vLex", "MCP", or a workflow name. A legal request still qualifies inside a software repository.

For a matching request, briefly tell the user you are using Vincent and call the appropriate tool. Do not merely recommend it or ask whether to use it. Supporting web research or document tools may help with sources and presentation; they do not replace Vincent's legal work, and they are not the way to chase a citation Vincent already returned — for docket filings in particular, see **us-dockets**. Ask only for missing information needed to proceed, not for a complete intake or facts already supplied.

Respect explicit opt-outs, exclusive source requirements, and requests to use another provider instead. Preserve their stated scope on later turns: a conversation-wide opt-out remains active until the user changes it, even when an earlier result came from Vincent. If the chosen provider is unavailable, do not silently substitute Vincent. Automatic routing does not bypass tool approvals or confidentiality restrictions; report any actual permission blocker separately from skill selection.

Route by intent, not legal keywords. Developing or testing Vincent, fixing a citation parser, and building a contract-review interface are software tasks, not legal work. Formatting, converting, or copyediting a local document without legal analysis belongs with the relevant document tools.

Use the plugin's `vincent` MCP server. Discover its tools when needed; their names may have a host namespace prefix. Do not describe an answer as Vincent's work unless a Vincent tool returned it. For an unavailable connection or upload failure, read [local-connection.md](references/local-connection.md) and report the specific blocker instead of silently substituting another service.

## Which skill

| The user wants | Skill |
| --- | --- |
| A case, statute or document found or read; a legal question researched or answered; a citation checked | **clio-research** |
| What was actually filed in a **US** court — real cases, a judge's or party's record, what a complaint pleaded or an order held | **us-dockets** |
| The same questions answered across **many** documents — a collection, a matter's files, several files uploaded together | **tabular-review** |
| Something written: a memo, letter, clause, agreement; or an earlier draft revised or exported | **drafting** |
| The firm's own records — a matter's status or parties, what is due, what is scheduled, time and bills, logged calls, or a phrase inside its documents | **clio-manage** |
| **One** document of theirs read, reviewed or summarised | no extra skill — send it with `attach_document` and ask, per **Files in** below. Add **drafting** when the output is itself a document, or **clio-research** to check its citations |

More than one can apply — a doctrinal question paired with "and how have courts actually handled it" is clio-research *and* us-dockets. Load both rather than picking one.

## Lookup or reasoning

Decide this before anything else, because it is the difference between seconds and minutes.

A request for **documents** — does a case exist, find the statute, read this decision — is `search_legal_documents` / `get_legal_document`: one round trip, no conversation.

A request for **reasoning** — a question answered, something drafted, reviewed or argued — is `start_research`, which takes minutes because the agent searches for itself.

Starting a conversation for a lookup wastes both. Details in **clio-research**.

## Driving a turn

Call `start_research` with the question and applicable jurisdiction, locale, scope, and verified file IDs. Retain `conversation_id`. It returns promptly and renders Vincent's live MCP App inline in the parent conversation; the panel refreshes the transcript while Vincent works.

`start_research`, `continue_conversation`, `watch_conversation`, `respond_to_interruption`, `submit_tasks` and `get_conversation_messages` all share `TurnResult`. Read `state` and `guidance`:

| State | Next action |
| --- | --- |
| `completed` | Present the actual `answer`. If the deliverable is in `files`, retrieve it as **drafting** describes. If neither contains the requested result, report the empty outcome. |
| `needs_user` | Handle each returned `interruptions` entry using [interruptions.md](references/interruptions.md). Stop waiting for completion while human input is required. |
| `still_running` | The inline Vincent panel continues the run in real time. Do **not** call `watch_conversation` automatically, because it blocks the parent turn. Call it only when the user asks for the final answer in chat or the host cannot render the inline app. Do not create a duplicate conversation. |
| `error` | Report `error` as a failure, not an answer. |

Turn calls stream progress and may stay open for minutes. `watch_conversation` also exposes external-tool requests that a snapshot cannot. Use `get_conversation_messages` for a status spot-check, after resolving an interruption, or to read an earlier conversation; it is not the default polling loop. `get_conversation_metadata` contains no answer.

Keep the conversation ID when a wait must end, and report pending status without presenting partial text as finished work.

## One conversation, not several

A follow-up, revision, different perspective or new deliverable based on earlier Vincent work is `continue_conversation` on the **same** `conversation_id` — never a fresh `start_research`. The documents, review tables and answers from earlier turns live in that conversation and are not reachable from a new one.

A 409 means a turn is already running: `watch_conversation` until it settles, not repeated submissions. An uncertain create/continue timeout does not prove failure; recover using the known ID rather than replaying the mutation. Call `stop_conversation` only when the user asks to stop, then read what Vincent retained — `stopped=false` means there was nothing running to cancel.

## Scope

There is no workflow to choose. Every conversation the MCP starts runs on Vincent's agentic agent, which plans and picks its own tools; `start_research` takes no `workflow` argument and no tool lists workflows. If the user names a specific Vincent workflow, say it is not reachable from here and put the work in `question` instead — do not claim an access restriction, and never bypass authentication, feature flags, or approval controls.

Carry the user's question, facts, supplied text, requested output, and relevant date into `question`; do not reduce a drafting or review request to a generic research question. Pass the country code as `jurisdiction` and put any material state, province, or other jurisdiction in the question. Do not infer jurisdiction from the user's location.

Use `list_collections` when the user names a collection or matter, or needs to discover sources. Pass only returned or user-provided IDs. For a named collection search, use the known `collection_type`, keep `per_page=100`, and advance `page` while `has_more` is true until found. Project collections require an explicit `collection_type="project"` filter. When browsing, show the returned page and `total` before offering more; the displayed count is not the total. Keep collection and matter scope explicit and do not add unrelated client material.

`collection_id` is more than a research filter: it is what connects the corpus a review table draws its rows from. See **tabular-review**.

Discover `list_approval_keys` only when pre-approvals are relevant; grant only the specific capabilities the user authorized, and tell them the corresponding labels.

## Files in

Send a document with `attach_document`: read the bytes yourself, pass them base64-encoded, and always pass `size_bytes` — that is how a truncated argument is caught instead of uploading a corrupt fragment. There is no upload card.

Then branch on the result, because the account decides which upload path is open. A `file_id` means the document stands alone: poll `get_file_status` until `available`, then pass the id to `start_research(file_ids=[...])` or `match_authority`. A `conversation_id` means the legacy path, where the document only exists *inside* that conversation: continue it with `continue_conversation` rather than starting a run, and do not offer `match_authority`, which needs a file_id. `guidance` states which happened.

On the legacy path there are two shapes of request, and you choose by whether you pass `conversation_id`:

| The document is | Call | What happens |
| --- | --- | --- |
| New to this work — "here is my contract" | `attach_document` with no `conversation_id` | It opens a conversation of its own |
| One more file for a run already going | `attach_document` with that `conversation_id` | It joins that conversation, no turn spent |

Attaching asks nothing either way: `continue_conversation` is what puts the question. Do not `start_research` on a conversation an attachment opened — that starts a second one and leaves the document behind. When the attachment is the thing opening the conversation, pass the user's `locale` too: it is fixed at creation and no later turn can change it.

An attachment in this chat is not automatically in Vincent. Send only what the user asked you to send, and for a file too large for a tool argument, ask them to upload through Vincent and give you the id.

For an uploaded or user-provided Vincent `file_id`, call `get_file_status`. Only `available` or `completed` means usable; report pending or error states. Keep IDs within the same backend/account. Pass verified IDs to `start_research(file_ids=[...])` or `continue_conversation(file_ids=[...])`.

## Handling what comes back

Preserve returned citations, pinpoints, quotations, and links. Separate Vincent's conclusions from your synthesis and the user's facts. Do not invent sources, claim to have read uninspected text, or label an authority current or good law without supporting verification. Ask targeted follow-ups when support is incomplete and disclose unresolved gaps.

Send only documents and facts authorized for this task. Vincent uses remote storage and services regardless of which transport this plugin is configured for. Creating research or a draft does not authorize sending it to others, filing it, changing access, or modifying unrelated matters.

Referenced files: 3 — file references are metadata, not package contents.