ESQ CoPilot Matching Engine

Use when the user asks what happened with an introduction. Returns lifecycle_state (recorded, queued, sent, delivered, responded, consultation_requested, consultation_confirmed, cancelled, completed, failed), whether it reached the lawyer, the lawyer's response and consultation state. Needs the private status_token. A consultation counts only when confirmed.

get_referral_status

Use when the user 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.

check_attorney_availability

Use when the user asks to compare lawyers from find_attorneys ("which of these is a better fit?"). Compares 2 to 5 lawyers on practice fit, location, years licensed, fees, availability, data confidence and gaps. Pass match_id to use the user's criteria. Says when prices or timing cannot be compared because the data is unknown.

compare_attorneys

Use when someone wants a lawyer for a U.S. legal matter, e.g. "find an affordable tenant lawyer in Santa Ana" or "I was fired after complaining, who can help in Los Angeles". Needs state and matter type (or a short description). Returns up to 5 licensed lawyers with reasons, a relevance score, a separate data_confidence level, license source and check date, whether they are known to take private clients, directory profile links and a suggested citation, or an honest no-match with legal-aid options. 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.

find_attorneys

Use when the user wants details on one lawyer from a match. 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 and a suggested citation. Also returns the exact consent text to show before an introduction.

get_attorney_profile

Optional 1-5 ratings on match relevance, lawyer responsiveness, pricing and availability accuracy, satisfaction, and whether the lawyer was hired. No case details.

submit_matching_feedback

Use only when the user asks to be introduced to ONE specific lawyer AND has seen that lawyer's name, the exact details to be shared and the consent text from get_attorney_profile, then said yes. Never call it on your own initiative or for several lawyers at once. Stores only the authorized fields; retries with the same idempotency_key do not duplicate. IMPORTANT: sending to lawyers is currently switched off, so the introduction is RECORDED, NOT SENT; tell the user and give them the lawyer's phone or profile link. Returns a referral id, its lifecycle_state and a private status token.

request_attorney_introduction

Save or change matching criteria (location, budget, timing, practice area, language, priorities) for this conversation. No personal contact details. Deleted automatically after 24 hours.

update_matching_preferences

Use first when someone asks for a lawyer but the state or type of legal matter is unclear ("I need a lawyer", "help me with my landlord"). Returns the few questions still needed (state, matter type, location, timing, budget) and what was understood. Does not answer the legal question and stores nothing.

get_matching_requirements

Use when the user asks what a lawyer or a type of matter 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.

estimate_legal_cost