"What am I in court for today?" — an attorney's HEARING CALENDAR, by bar number OR by name.
REQUIRES `bar`, OR BOTH `last` AND `first`. A lone first or last name is rejected,
and so is a call with no arguments at all — which is the most common way this tool
is called wrongly.
Returns every scheduled hearing in the date range: date and time, case number,
caption, hearing type, judge and courtroom. Defaults to TODAY in North Carolina (NC)
when no dates are given, so `get_attorney_hearing_calendar(bar="21262")` is
exactly "what's on my calendar today".
THIS IS THE TOOL FOR "TODAY", "TOMORROW", "THIS WEEK" AND "MY CALENDAR".
`search_cases_by_attorney` is a different question: it lists the cases an attorney
is of record on and its `file_date_*` filters bound WHEN A CASE WAS FILED. A case
filed in 2023 has hearings today, so filtering that tool's file date to today
returns cases OPENED today — almost always nothing. Never substitute it for this.
PREFER THE BAR NUMBER whenever the user can supply it: it resolves to exactly one
attorney, and a name may not — see `attributable` below for what that costs.
READ `attributable` BEFORE ATTRIBUTING THE CALENDAR TO ANYONE. True means these
hearings belong to exactly one attorney; false means they do not and must not be
described as one person's day. On a BAR search it is always true and
`attorney_name` is null — the hearing search returns no name, so that null means
"not reported", not "ambiguous".
A NAME SEARCH MAY NOT BE ATTRIBUTABLE. The hearing grid has no attorney column,
so if a name matches several attorneys their hearings come back MERGED with no
way to tell whose is whose. To catch this the tool cross-checks the name against
the case index and reports `matched_attorneys`:
- exactly one match -> `attorney_name` is set; treat the calendar as that person's
- more than one -> the calendar spans them all and CANNOT be split. Say so and
ask for a State Bar number. Do not present it as one
lawyer's day.
- none -> no cases exist under that name, so an empty calendar may
mean the name is wrong rather than the day being clear.
The cross-check is evidence, not proof — a single match still warrants preferring
the bar number when the answer decides whether someone travels to a courthouse.
SLOW ON A CACHE MISS — 30-120 seconds, because it drives a real browser through
two CAPTCHAs. Tell the user you're pulling their calendar and let it run. This is
the opposite of `search_cases_by_attorney`, which is fast and needs no warning.
Repeat calls for the same search and range are served from a 6-hour cache and
return instantly; `cached: true` with `fetched_at` tells you which you got. If the
answer is being used to decide whether to appear somewhere, quote `fetched_at`.
AN EMPTY CALENDAR IS A REAL ANSWER, BUT ONLY WHEN THE LOOKUP SUCCEEDED. If the
call returns an `error`, the calendar could NOT be checked — say that, and never
turn it into "you have nothing scheduled". Those differ by someone missing court.
Covers all 100 counties at once; there is no county filter on this search.
Public record. Read-only. NC only. Informational, not legal advice.