clio-search

name	clio-search
description	Pick the right Clio Manage tool when the user asks to find, list, filter, or look up matters, contacts, time entries, tasks, calendar events, notes, documents, or bills. Use when the user says "find", "search", "list", "show me", "look up", "what matters", "who is", "show open tasks", "any bills for", "did we log time on", or similar discovery phrasing against Clio data.

Searching Clio

Map the user's request to the smallest correct tool call. Lists in Clio support filtering — use the filters instead of fetching everything and filtering client-side. Pagination defaults are sane (25/page, 200 max) but list results can be huge; warn the user before pulling unbounded data. List tools return total_records and truncated — check truncated to detect capped results.

The decision table

User intent	First tool	Key filters
Find a matter	clio_list_matters	client_id, status, practice_area_id, updated_since, query
Look up one matter by ID	clio_get_matter	id, fields
Find people or companies	clio_search_contacts	query (free-text)
Filter contacts by type	clio_list_matter_contacts (if scoped to a matter) or clio_get_contact	—
Time entries on a matter	clio_list_activities	matter_id, user_id, type=TimeEntry, start_date, end_date
Expenses on a matter	clio_list_activities	matter_id, type=ExpenseEntry
Tasks across firm	clio_list_tasks	assignee_id, status, priority, due_at_from, due_at_to
Tasks on a matter	clio_list_tasks	matter_id
Notes on a matter	clio_list_notes	matter_id
Calendar	clio_list_calendar_entries	calendar_id, from, to, user_id
Bills	clio_list_bills	client_id, matter_id, state (draft, pending_approval, awaiting_payment, paid, void), due_since, due_before
Billing summary for a matter	clio_get_billing_summary	matter_id
Documents	clio_list_documents	matter_id, contact_id, parent_id
Document folders	clio_list_folders	parent_id, matter_id
Users in the firm	clio_list_users	enabled, subscription_type
Practice areas	clio_list_practice_areas	—

Field selection (cheap optimization)

Every Clio v4 list tool accepts a fields parameter. Use it. The default response is sparse (only id and etag) and the agent will then re-fetch each result — wasteful. Pass fields explicitly:

fields = "id,display_number,description,status,client{id,name},practice_area{id,name},open_date,close_date"

Tell the user roughly how many records you're asking for. If a list might return thousands, page deliberately — limit=200&page=1 then page=2, not an unbounded loop.

Search quirks to know

• query on clio_list_matters is full-text across description and display number. Use it for natural-language matches; combine with client_id when you know the client.
• updated_since takes an ISO-8601 timestamp. Use it for delta syncs.
• matter_id filter is singular. Clio rejects arrays here — if the user wants entries across multiple matters, loop or call clio_api_request.
• status on matters is case-sensitive Title Case: Open, Pending, Closed. Don't lowercase them.
• description on activities is write-only on the create endpoints; to read, look at the note field on GET.

When the user gives a name, not an ID

The flow is: search → confirm → act. Don't guess.

1. clio_search_contacts(query="Jane Smith")  → list of candidates
2. If 1 match: use that ID
3. If multiple: ask the user which one
4. If 0: offer to create the contact (clio_create_person_contact)

The same pattern applies to matters: clio_list_matters with a query or client_id first; never assume a matter ID from a casual reference.

When to escape to clio_api_request

Only when:

• A filter combination isn't covered by the typed tools (rare)
• A response field isn't exposed by the typed tools
• The user asks for something on an endpoint not yet wrapped (e.g., /credit_memos.json, /trust_requests.json)

clio_api_request is a documented escape hatch. Use it sparingly; the typed tools have built-in validation, audit, and an optional etag concurrency guard on updates (pass the etag from a prior get; a 412 means re-fetch and retry).

Showing results

Default to a small, readable table for ≤ 20 rows. For larger sets, summarize counts and let the user drill in:

Found 47 open matters for Acme Corp. Top 5 by last-updated:

• 2024-0042 — "Acme v. Smith" — updated 2 days ago
• 2024-0039 — ...

Don't paste raw JSON unless the user asks.