Clio MCP by usefulapi

List contacts

clio_list_contacts

Read-onlyIdempotent

Search and list contacts — clients, prospective clients, companies, opposing parties and co-counsel. query wildcard-matches name, email, phone, address and more; custom_field_id + custom_field_value filter by one of the firm's custom fields. Clio: GET /contacts.json.

Input Schema

Name	Required	Description
`type`	No	Only people or only companies.
`limit`	No	Records per page, 1-200 (default 50).
`order`	No	Sort order. Default id(asc).
`query`	No	Wildcard search across name, title, email, phone, address, web site and custom fields.
`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).
`initial`	No	Only contacts whose last name or company name starts with this letter (A-Z).
`email_only`	No	Only contacts that have an email address.
`page_token`	No	next_page.page_token from the previous page. Omit for the first page.
`client_only`	No	Only contacts who are clients.
`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.
`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.

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 declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile carries itself. The description adds the wildcard-match scope and the custom-field filtering behavior, but says nothing about result volume, pagination expectations, or the 10,000-record cap beyond what the schema states.

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

Conciseness5/5

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

Three tight sentences: the resource scope first, then the two non-obvious filtering mechanisms, then the underlying endpoint. Nothing is repeated from the schema or annotations.

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 14 optional parameters and no output schema, the description covers the resource scope and the two search mechanisms well enough to invoke correctly. It leaves the shape of a returned contact record unaddressed, which is a minor gap given there is no output schema to fall back on.

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

Parameters3/5

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

Schema coverage is 100%, so the schema already documents all 14 parameters in detail. The description reframes `query` and the custom_field_id/custom_field_value pairing in prose, but adds no syntax or format detail beyond the schema, so baseline 3 applies.

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 and resource ('Search and list contacts') and enumerates the record categories covered (clients, prospective clients, companies, opposing parties, co-counsel). The list-vs-get distinction against clio_get_contact is inferable but never stated explicitly, so sibling routing is left to the agent.

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?

The description explains two mechanisms (wildcard `query` and the custom-field pair) but never says when to prefer this tool over clio_get_contact or how to page through large result sets. Usage is implied by the parameter mechanics rather than stated as guidance.

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 contacts

Input Schema

Schema Changelog

TDQS

Glama MCP Gateway

Resources