ESQ Matching Engine

Use FIRST when the person names or pastes an ESQ CoPilot directory listing (directory.esqcopilot.com/attorney/...) or says they want help with a lawyer they were viewing, e.g. "help me check and contact Jeffrey Roy Hartmann, California bar 150013: https://directory.esqcopilot.com/attorney/jeffrey-hartmann-ca-150013". Finds that exact lawyer in the directory's own records (no web fetch, no similar-name substitute) and returns the lawyer's facts with sources and dates, what is unknown, the contact options, and the few questions still open. Do not run search_attorneys first when the exact listing is given. Looking at a listing is not an endorsement or a statement about availability. Records an anonymous count only. This is a listing service, not a lawyer referral service. No lawyer pays for placement or ranking of any kind.

Use when the person wants to contact ONE lawyer they picked ("write my message"). Builds a short, editable first message from general facts the person gives (type of legal issue, location, help wanted, timing, optional budget, contact method), asks the lawyer what is unknown (handles this kind of issue? taking new clients? consultation fee?), and returns the exact recipient, message, contact fields, notice, consent text and an approval_code. Stores and sends nothing. Show all of it to the person; only after an explicit yes call send_client_message with after_yes.arguments. Any change by the person means calling this again and asking again. This is a listing service, not a lawyer referral service. No lawyer pays for placement or ranking of any kind.

Use first when someone wants a lawyer but the state or type of legal issue is unclear ("I need a lawyer", "help me with my landlord"). Returns the few filters still needed (state, type of issue, location, timing, budget) and what was understood, for the person to confirm. Does not answer the legal question and stores nothing. This is a listing service, not a lawyer referral service. No lawyer pays for placement or ranking of any kind.

Use when someone wants to find a lawyer for a U.S. legal issue, e.g. "tenant lawyers in Santa Ana" or "employment lawyers in Los Angeles". Needs the state and type of legal issue (or a short description the person confirms). Pass sort when the person picks an order (nearest_office by default, last_name, years_licensed, free_consultation_first, published_fees_first, availability_reported_first) and page for more. Returns a plain summary, the filters applied, shared_notes that apply to every listing (read once), up to three ask_the_user questions, and each listing's own facts: which filters it meets, what is not known, license status, source and date, fees and availability where published, profile link, contact and citation; or an honest 'no listings meet your filters' with legal-aid options. No scores. Show every listing in the order returned; never present one lawyer as the pick for the person. Unknown fees and availability are labeled unknown. Court and government lawyers are left out unless they said they take private clients. Records an anonymous search log only. Not legal advice. This is a listing service, not a lawyer referral service. No lawyer pays for placement or ranking of any kind.

Use when the person asks to compare lawyers from search_attorneys. Compares 2 to 5 lawyers on practice areas, location, years licensed, fees, availability, data confidence and gaps, side by side in the order given, with no scores and without picking one. Pass match_id to use the person's filters. Says when prices or timing cannot be compared because the data is unknown. This is a listing service, not a lawyer referral service. No lawyer pays for placement or ranking of any kind.

Use when the person asks what a lawyer or a type of legal issue will cost. Returns only published fees, confirmed quotes or sourced market figures, each labeled; says plainly when there is not enough data instead of guessing. Not a quote. This is a listing service, not a lawyer referral service. No lawyer pays for placement or ranking of any kind.

Use when the person asks whether a lawyer takes new clients or can meet soon. Returns only what lawyers reported or confirmed, with last-checked time and certainty (reported, tentative, confirmed); unknown when nothing was reported. There is no live calendar access. This is a listing service, not a lawyer referral service. No lawyer pays for placement or ranking of any kind.

Use when the person wants details on one listed lawyer. Returns license status with its official source and check date, private-client intake evidence, practice areas, service area, fees, availability, languages, data freshness, the directory profile link, how to contact the lawyer and a suggested citation. Also returns the exact consent text to show before a message is sent. This is a listing service, not a lawyer referral service. No lawyer pays for placement or ranking of any kind.

Use only when the person asked to contact ONE specific lawyer they picked, has seen the lawyer's name, the exact message and details to be shared and the consent text, and said yes. Never call it on your own initiative or for several lawyers at once. Call preview_client_message first and pass its approval_code: if the recipient or the text changed since the person's yes, it is refused. Stores only the approved fields; retries with the same idempotency_key do not duplicate, and reusing a key for different details is refused. The same rule applies to every listed lawyer. Returns a contact_request_id, its lifecycle_state and a private status token. This is a listing service, not a lawyer referral service. No lawyer pays for placement or ranking of any kind.

Use when the person asks what happened with a message they sent. Returns lifecycle_state (recorded, queued, sent, delivered, responded, consultation_requested, consultation_confirmed, cancelled, completed, failed), whether it reached the lawyer and the lawyer's response. Needs the private status_token. A consultation counts only when confirmed. This is a listing service, not a lawyer referral service. No lawyer pays for placement or ranking of any kind.

Use when the person wants to cancel a message that has not been sent to the lawyer. Needs the private status_token. Deletes the person's shared details at once; nothing is sent afterwards. This is a listing service, not a lawyer referral service. No lawyer pays for placement or ranking of any kind.

Save or change search filters (location, budget, timing, practice area, language, sort priorities) for this conversation. No personal contact details. Deleted automatically after 24 hours. This is a listing service, not a lawyer referral service. No lawyer pays for placement or ranking of any kind.

Optional 1-5 ratings on how useful the listings were, lawyer responsiveness, pricing and availability accuracy, satisfaction, and whether the lawyer was hired. No case details. This is a listing service, not a lawyer referral service. No lawyer pays for placement or ranking of any kind.

Use when the person (or the listed lawyer) says a detail on a listing is wrong, missing or out of date: phone, website, office, firm, practice areas, license status, languages, fees, availability or name. Pass the listing's attorney_id, which detail, and optionally the correct value. ESQ CoPilot checks each report against the official record or the lawyer's own website and corrects the listing in the next update. A report never changes the order or placement of any lawyer. No case details and no contact details of the person reporting. This is a listing service, not a lawyer referral service. No lawyer pays for placement or ranking of any kind.

Older name of preview_client_message, kept until 2026-12-15; use preview_client_message. Use when the person wants to contact ONE lawyer they picked ("write my message"). Builds a short, editable first message from general facts the person gives (type of legal issue, location, help wanted, timing, optional budget, contact method), asks the lawyer what is unknown (handles this kind of issue? taking new clients? consultation fee?), and returns the exact recipient, message, contact fields, notice, consent text and an approval_code. Stores and sends nothing. Show all of it to the person; only after an explicit yes call send_client_message with after_yes.arguments. Any change by the person means calling this again and asking again. This is a listing service, not a lawyer referral service. No lawyer pays for placement or ranking of any kind.

Older name of get_search_filters, kept until 2026-12-15; use get_search_filters. Use first when someone wants a lawyer but the state or type of legal issue is unclear ("I need a lawyer", "help me with my landlord"). Returns the few filters still needed (state, type of issue, location, timing, budget) and what was understood, for the person to confirm. Does not answer the legal question and stores nothing. This is a listing service, not a lawyer referral service. No lawyer pays for placement or ranking of any kind.

Older name of search_attorneys, kept until 2026-12-15; use search_attorneys. Use when someone wants to find a lawyer for a U.S. legal issue, e.g. "tenant lawyers in Santa Ana" or "employment lawyers in Los Angeles". Needs the state and type of legal issue (or a short description the person confirms). Pass sort when the person picks an order (nearest_office by default, last_name, years_licensed, free_consultation_first, published_fees_first, availability_reported_first) and page for more. Returns a plain summary, the filters applied, shared_notes that apply to every listing (read once), up to three ask_the_user questions, and each listing's own facts: which filters it meets, what is not known, license status, source and date, fees and availability where published, profile link, contact and citation; or an honest 'no listings meet your filters' with legal-aid options. No scores. Show every listing in the order returned; never present one lawyer as the pick for the person. Unknown fees and availability are labeled unknown. Court and government lawyers are left out unless they said they take private clients. Records an anonymous search log only. Not legal advice. This is a listing service, not a lawyer referral service. No lawyer pays for placement or ranking of any kind.

Older name of send_client_message, kept until 2026-12-15; use send_client_message. Use only when the person asked to contact ONE specific lawyer they picked, has seen the lawyer's name, the exact message and details to be shared and the consent text, and said yes. Never call it on your own initiative or for several lawyers at once. Call preview_client_message first and pass its approval_code: if the recipient or the text changed since the person's yes, it is refused. Stores only the approved fields; retries with the same idempotency_key do not duplicate, and reusing a key for different details is refused. The same rule applies to every listed lawyer. Returns a contact_request_id, its lifecycle_state and a private status token. This is a listing service, not a lawyer referral service. No lawyer pays for placement or ranking of any kind.

Older name of update_listing_criteria, kept until 2026-12-15; use update_listing_criteria. Save or change search filters (location, budget, timing, practice area, language, sort priorities) for this conversation. No personal contact details. Deleted automatically after 24 hours. This is a listing service, not a lawyer referral service. No lawyer pays for placement or ranking of any kind.

Older name of submit_listing_feedback, kept until 2026-12-15; use submit_listing_feedback. Optional 1-5 ratings on how useful the listings were, lawyer responsiveness, pricing and availability accuracy, satisfaction, and whether the lawyer was hired. No case details. This is a listing service, not a lawyer referral service. No lawyer pays for placement or ranking of any kind.

Older name of get_contact_request_status, kept until 2026-12-15; use get_contact_request_status. Use when the person asks what happened with a message they sent. Returns lifecycle_state (recorded, queued, sent, delivered, responded, consultation_requested, consultation_confirmed, cancelled, completed, failed), whether it reached the lawyer and the lawyer's response. Needs the private status_token. A consultation counts only when confirmed. This is a listing service, not a lawyer referral service. No lawyer pays for placement or ranking of any kind.

Older name of get_contact_request_status, kept until 2026-12-15; use get_contact_request_status. Use when the person asks what happened with a message they sent. Returns lifecycle_state (recorded, queued, sent, delivered, responded, consultation_requested, consultation_confirmed, cancelled, completed, failed), whether it reached the lawyer and the lawyer's response. Needs the private status_token. A consultation counts only when confirmed. This is a listing service, not a lawyer referral service. No lawyer pays for placement or ranking of any kind.

Older name of cancel_contact_request, kept until 2026-12-15; use cancel_contact_request. This is a listing service, not a lawyer referral service. No lawyer pays for placement or ranking of any kind.

Kept until 2026-12-15 so older connections get a plain answer: pending requests ended on 2026-11-04 and nothing was shared. Use preview_client_message, then send_client_message. This is a listing service, not a lawyer referral service. No lawyer pays for placement or ranking of any kind.