Read-onlyClientsMCP tool
clients_list
Search for clients.
Search for clients. Returns IDs only by default for efficiency. Use fields parameter to include additional data. Response includes relatedIds.contactIds for chainable operations.
Note
When working with escrows, use relatedIds.clientIds directly with clients_bulk_update.
The contact_ids parameter is for finding clients by their linked contact - only needed for special cases.
Parameters#
| Parameter | Type | Required | Description |
|---|---|---|---|
query | string | No | Search term (searches name, email, phone) |
client_type | enum | No | Filter by client type · One of: buyer, seller, both |
status | enum | No | Filter by client status (active = working with, closed = deal completed, expired = agreement expired, cancelled = client cancelled) · One of: active, closed, expired, cancelled |
contact_ids | array of strings | No | Filter to clients linked to these contact IDs. CRITICAL for finding clients from escrow contacts - use escrow relatedIds.contactIds here. |
is_archived | boolean or string | No | Filter by archived state. Default: false (active clients only). Pass true to find ARCHIVED clients (e.g. for a restore workflow). Pass "any" to include both. |
fields | array of enum | No | Field groups to include. Empty/omitted = IDs only. Options: basic (id, type, status), contact (name, email, phone), financial (budget range), activity (dates), full (all fields). · Values: basic, contact, financial, activity, full |
limit | string | No | Max results. Use a number (e.g. "25") or "all". "all" and any value above 200 are capped at 200 server-side. |
Example prompts#
- "Show me all my active buyer clients with their contact info."
- "Search my clients for anyone named Garcia and pull their phone numbers."
Safety#
Read-only. This tool never changes your data — it only looks things up. Safe to run anytime.
Previous name#
This tool was previously published as search_clients. Call it by its current name — legacy names are kept here for reference and old links redirect, but they are not callable.