Clio MCP by usefulapi

List matters

clio_list_matters

Read-onlyIdempotent

Search and list matters (the firm's cases) with their client, practice area, responsible attorney and status. query wildcard-matches matter number or description and the client's name; custom_field_id + custom_field_value filter by one of the firm's custom fields (e.g. a court case number). Clio: GET /matters.json.

Input Schema

Name	Required	Description
`limit`	No	Records per page, 1-200 (default 50).
`order`	No	Sort order. Default id(asc), the only order that allows unlimited cursor paging.
`query`	No	Wildcard search on display number, number, description, or the client's name.
`fields`	No	Override the returned fields: a comma-separated list, nested resources in braces one level deep, e.g. id,name,matter{id,display_number}. Omit for a sensible default.
`offset`	No	next_page.offset from the previous page (used when a custom order is set; capped at 10,000 records).
`status`	No	open, closed or pending — or several comma-separated, e.g. open,pending.
`billable`	No	Only billable (true) or non-billable (false) matters.
`client_id`	No	Only this client's (contact id) matters.
`page_token`	No	next_page.page_token from the previous page. Omit for the first page.
`updated_since`	No	Only records updated after this ISO-8601 timestamp, e.g. 2026-09-01T00:00:00Z.
`custom_field_id`	No	Only records whose custom field with this id (from clio_list_custom_fields) matches custom_field_value.
`practice_area_id`	No	Only matters in this practice area.
`custom_field_value`	No	The value to match. Checkbox: true or false; picklist: the option id; contact or matter field: the record id; date: YYYY-MM-DD. Text, checkbox, picklist, contact and matter fields always match exactly.
`custom_field_operator`	No	Required for currency, date, time and numeric fields (= for an exact match); leave it out for every other field type.
`originating_attorney_id`	No	Only matters with this originating attorney (user id).
`responsible_attorney_id`	No	Only matters with this responsible attorney (user id).

Schema Changelog

Changes observed during successful MCP inspections.

Changed3 schema fields changedOct 23, 2026

addedInput schema / properties / custom_field_id

Added value: +{
+  "description": "Only records whose custom field with this id (from clio_list_custom_fields) matches custom_field_value.",
+  "exclusiveMinimum": 0,
+  "maximum": 9007199254740991,
+  "type": "integer"
+}

addedInput schema / properties / custom_field_operator

Added value: +{
+  "description": "Required for currency, date, time and numeric fields (= for an exact match); leave it out for every other field type.",
+  "enum": [
+    "=",
+    "<",
+    ">",
+    "<=",
+    ">="
+  ],
+  "type": "string"
+}

addedInput schema / properties / custom_field_value

Added value: +{
+  "description": "The value to match. Checkbox: true or false; picklist: the option id; contact or matter field: the record id; date: YYYY-MM-DD. Text, checkbox, picklist, contact and matter fields always match exactly.",
+  "maxLength": 500,
+  "minLength": 1,
+  "type": "string"
+}

First observedOct 23, 2026

TDQS

A3.6/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, openWorld), so the bar is lower. The description adds the underlying endpoint (GET /matters.json) and the wildcard nature of `query`, but says nothing about paging behavior (page_token vs offset, the 10,000-record offset cap) or result size, which are real behavioral considerations for a 16-parameter list tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three dense sentences, front-loaded with purpose before narrowing to the two non-obvious filter mechanisms. The trailing "Clio: GET /matters.json" is marginally useful for mapping to vendor docs but is the only element that is not strictly load-bearing.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With 0 required parameters and full schema documentation, the description covers purpose, the two search modes, and the shape of records returned, which is enough to call the tool correctly. It leaves paging strategy (cursor default vs offset with custom orders) entirely to the schema, which is acceptable given the schema documents it thoroughly and there is no output schema to explain.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so baseline would be 3. The description earns the extra point by tying the pair together operationally — `custom_field_id` + `custom_field_value` filter one custom field, with a concrete motivating example (a court case number) — which is genuinely useful framing the schema lists but does not synthesize.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource ("Search and list matters") and parenthetically defines the domain term for non-legal users ("the firm's cases"), plus names the enrichments returned (client, practice area, responsible attorney, status). It is clearly distinguishable from clio_get_matter and clio_create_matter by the search/list verb, though it never names a sibling explicitly.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is implied by the verb (browse/search rather than fetch one record) and the custom-field example hints at a use case, but there is no explicit "use this when… / use clio_get_matter instead when…" routing and no stated prerequisites. An agent must infer the boundary from the sibling naming convention alone.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

All Clio MCP by usefulapi tools Inspect

Try in Browser

Pay for results, not tokens.Fund a bounty. Let AI agents compete and collaborate to solve your problems.agentbounties.appAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

List matters

Input Schema

Schema Changelog

TDQS

Glama MCP Gateway

Resources