When to use:
- User wants the docket sheet (every filing in the case)
- Before downloading documents (to see what's available)

Notes:
- Parties and attorneys are NOT available from the docket endpoints; for
  them, use docketbird_ask_litigation_graph.
- The upstream /documents endpoint has no pagination: the entire docket is
  always fetched, and page/page_size only shape this response. Very large
  dockets can hit DocketBird's own ~29s gateway timeout (a 504).
- For a case's metadata alone (no docket fetch), use docketbird_get_case.

Args:
    case_id: DocketBird case ID (e.g., 'txnd-3:2007-cv-01697')
             Format: {court_id}-{district}:{year}-{type}-{number}
    page: Page number for documents (starts at 1, default 1)
    page_size: Number of documents per page (default 20, max 50)

This matches docket-entry METADATA only (the title and description shown on
the docket sheet), not the text inside the filings. To search the full text
of filing bodies — across all courts or within one case — use
docketbird_fulltext_search instead.

When to use:
- User wants filings TITLED a certain way in a known case
  (e.g. docket entries labeled "motion to dismiss")
- Narrowing down a docket sheet before download

Note: the upstream /documents endpoint has no pagination, so the entire
docket is always fetched and matched in memory; very large dockets can hit
DocketBird's own ~29s gateway timeout (a 504).

Args:
    case_id: DocketBird case ID
    search_term: Term to match against docket-entry titles/descriptions
    page: Page number (starts at 1, default 1)
    page_size: Results per page (default 20, max 50)

This searches what the filings actually say, not what they are titled. To
match docket-entry titles within one case, use docketbird_search_documents.

When to use:
- Scanning recent filings for a company, industry, or legal topic
  (e.g. new suits naming a target company — set sort='recency')
- Finding every filing whose text mentions a term, phrase, or citation
- Practice research inside your firm's own cases (set my_cases_only=True)

Scope boundary: with my_cases_only=False (default) this is cross-corpus
RESEARCH over public court records. With my_cases_only=True it is limited
to cases associated with your firm's account (resolved from your API key).

Query syntax:
- space / and: all terms must appear.  or: either term.
- -term: exclude (the word 'not' is NOT supported).
- term* or term!: word endings (end of word only).
- /n, /s, /p: terms within n words / same sentence / same paragraph.
- "...": exact phrase. Email addresses and legal symbols (§, ¶) work.

Pagination contract (upstream cursors, bounded requests):
- next_cursor is the ONLY end-of-results signal. A page may hold fewer
  than `size` documents — even zero — while more remain, because
  restricted documents are removed after matching. Keep following the
  cursor until it is null. The 'found' count may include documents that
  will never be returned. Result window is the first 10,000 matches —
  narrow with court_id/case_id/dates if you need the deep tail.

Args:
    query: Full-text query (max 500 chars), e.g. '"summary judgment" and forfeit* -insurance'
    court_id: Comma-separated court restriction; each entry may be a slug
              ('nysd'), an abbreviation ('S.D.N.Y.'), or a full court name.
    case_id: Restrict to a single case by DocketBird case ID.
    filed_after: Only documents filed on/after this date (YYYY-MM-DD).
    filed_before: Only documents filed on/before this date (YYYY-MM-DD).
    my_cases_only: True = only your firm's cases (practice scope);
                   False = the whole corpus (research/marketing scope).
    sort: 'relevance' (default) or 'recency' (most recently filed first).
    size: Results per page (default 25, max 50).
    cursor: Pagination cursor from a previous response's next-page note.

This is your firm's tracked caseload only. To search all cases across all
courts, use docketbird_search_cases.

When to use:
- User wants to see their own/their firm's tracked cases
- Finding case IDs for calendar, follow, or autocalendar operations

Args:
    scope: 'company' for all company cases, 'user' for personal cases
    page: Page number (starts at 1, default 1)
    page_size: Results per page (default 20, max 50)

A lightweight, research-scope lookup: works for any case in DocketBird's
index (not just your account's cases) and does NOT fetch the docket, so it
can't hit the large-docket timeout. Use docketbird_get_case_details for the
full docket sheet, and docketbird_ask_litigation_graph for parties/attorneys.

When to use:
- Resolving a case ID (e.g. from docketbird_search_cases) to its metadata
- Jumping straight to the initiating complaint
- Checking PACER case ID / client code without pulling the docket

Args:
    case_id: DocketBird case ID (e.g., 'txwd-1:2022-cv-00398')

Research scope: this covers every court and every case DocketBird knows
about — not just cases on your account (that's docketbird_list_cases).

Matching: case-number-shaped queries (e.g. '2:2017-bk-00112' or
'17-bk-112') match on filing year, case type, and terminating digits;
anything else matches against case names.

Date filters match in tiers: cases with an exact filing date match at day
precision; cases with only a known filing year match at year granularity;
cases with no known date are included unless exclude_unknown_dates=True.

When to use:
- Finding a case's DocketBird ID from a name or number
- Checking whether a company has been sued (pair with
  docketbird_ask_litigation_graph for who represented whom)

Args:
    query: Case name (e.g. 'Immedia Semiconductor') or case number
           (e.g. '4:2022-cv-04775'). Max 500 chars.
    court_id: Comma-separated court restriction; each entry may be a slug
              ('nysd'), an abbreviation ('S.D.N.Y.'), or a full court name.
    filed_after: Only cases filed on/after this date (YYYY-MM-DD, inclusive).
    filed_before: Only cases filed on/before this date (YYYY-MM-DD, inclusive).
    exclude_unknown_dates: Drop cases whose filing date and year are both
                           unknown from date-filtered results (default False).
    size: Results per page (default 25, max 50).
    cursor: Pagination cursor from a previous response's next-page note.

Research scope — the full court set, independent of your account.

Behavior:
- No arguments: the curated set (~300 rows: all federal courts plus named
  state courts), followed by the case-type reference for the case ID format.
- search: free-text lookup by court name ('Southern District of New York'),
  abbreviation ('S.D.N.Y.'), or court_id ('nysd'); returns up to 25 ranked
  matches from the FULL set of enabled courts, including several thousand
  unlisted state courts. The fastest way to resolve a court to its court_id.
- court_system: browse every court inside one system (identifier from
  docketbird_list_court_systems), including unlisted ones.

Args:
    search: Free-text court lookup (name, abbreviation, or court_id).
    court_system: Court-system identifier to browse (e.g. 'uc-tx-distct').
    court_type: Optional filter: 'federal' or 'state'.

Returns the federal system plus each state court system, with a
human-readable name and how many covered courts each holds. Use a
court_system_id with docketbird_list_courts(court_system=...) to browse the
courts inside a system, including unlisted courts that don't appear in the
default listing. Changes rarely; safe to cache.

When to use:
- Discovering what state-court coverage exists
- Getting the identifier to browse one system's courts

Returns the document content to **you** (the client) as an embedded resource
so you can read or save it — this works over the remote HTTP connection. In
local stdio mode, passing ``save_path`` instead writes the file to that folder
on your own machine (the server runs locally there).

When to use:
- User wants to retrieve a specific filing
- After searching for documents
- Downloading individual documents

Args:
    document_id: DocketBird document ID
    save_path: Local folder to save into. Only honored in local stdio mode,
               where the server shares your filesystem. Ignored over a remote
               HTTP connection (the file would land on the server, not your
               machine), where the content is returned to you directly.

Returns:
    - Remote, or local with no save_path: a list of content blocks — a text
      summary plus an embedded resource holding the document bytes (base64),
      capped at MAX_INLINE_SIZE. If the document exceeds that cap, returns a
      text message with its direct download URL instead of inlining it.
    - Local stdio with save_path: a text confirmation of the saved file path.
    - On error / unavailable / restricted: a plain text message.

A case can hold many large PDFs, so over a remote HTTP connection this returns
a list of per-document **direct download links** (pre-signed, short-lived)
rather than inlining every file — fetch the ones you need, or call
``docketbird_download_document`` for a single document's content. In local
stdio mode, passing ``save_path`` instead streams every file to that folder on
your own machine.

When to use:
- User wants the complete case file archive
- Bulk document retrieval
- Surveying which filings are available to download

Args:
    case_id: DocketBird case ID
    save_path: Local folder to save into. Only honored in local stdio mode,
               where the server shares your filesystem. Over a remote HTTP
               connection it is ignored and download links are returned instead.

Returns:
    str: Markdown. Remote (or local with no save_path) lists each available
    document's title, ID, and direct download URL, plus counts of
    restricted/unavailable filings. Local stdio with save_path reports how
    many files were saved to disk and any that were skipped or failed.

Lightweight lookup for a single filing: title, filing date, restricted
status, and (when retrieved) a direct PDF download link. Use
docketbird_download_document for the file content itself, or
docketbird_get_document_text for the extracted text.

When to use:
- Checking whether a filing is available/restricted before downloading
- Getting a direct PDF link to hand to the user
- Resolving a document ID from search results to its metadata

Args:
    document_id: DocketBird document ID (e.g., 'txwd-1:2022-cv-00398-00177')

Returns what the document says (for summarizing, quoting, comparing) rather
than its metadata or PDF — those come from docketbird_get_document /
docketbird_download_document.

Availability varies: some documents aren't downloaded yet, some are scans
with no text layer, some docket entries are text-only stubs with no
document. When no text is available this returns a clear message — the PDF
may still be retrievable via docketbird_get_document.

When to use:
- Reading, summarizing, or quoting a filing's contents
- Pulling the complaint's text after docketbird_get_case points to it

Args:
    document_id: DocketBird document ID (e.g., 'txwd-1:2022-cv-00398-00177')
    offset: Character offset into the text to start from (for paging
            through long documents; default 0).
    max_chars: Maximum characters to return (default 50000, max 200000).

Practice scope: this reads YOUR company's autocalendars (requires a full
DocketBird account with autocalendars created; see
docketbird_create_autocalendar).

Two scopes, one tool:
- With case_id: every calendar entry for that case.
- Without case_id: entries across ALL cases your company has active
  autocalendars for, within the next `days` days — "what deadlines does my
  firm have coming up?"

The company-wide scope is served from a pre-computed rollup; if it has
never been built, the API starts building it and this tool says to retry
in a minute or two.

Args:
    case_id: DocketBird case ID (e.g., 'txnd-3:2007-cv-01697').
             Omit for the company-wide scope.
    days: Company-wide scope only: how many days ahead to include,
          starting today (default 7, clamped to 1-90 upstream).
          Ignored when case_id is given.

When to use:
- User wants to track/monitor a case for new documents
- Setting up ongoing monitoring of a docket

Followed federal cases are checked about twice weekly; state cases about
once weekly. New filings trigger DocketBird's new-documents notifications.

Args:
    case_id: DocketBird case ID (e.g., 'txnd-3:2007-cv-01697')

Practice scope: acts on YOUR DocketBird account. Creation is queued — the
case's docket sheet is updated first, then the autocalendar is built.
Court (PACER) fees may apply for the docket update.

When to use:
- Adding a case's deadlines to the firm's calendar
- After following a case you need to track dates for

Args:
    case_id: DocketBird case ID (e.g., 'txnd-3:2007-cv-01697')

This is the ONLY source of party/attorney/firm/judge relationships — the
docket endpoints do not return them. Examples: "What attorneys appeared
for Google in the Northern District of California?", "Every case where
Firm A appeared opposite Firm B", "What judges has Quinn Emanuel appeared
before?".

COVERAGE CEILING — read before trusting absence: the graph covers federal
civil cases active in DocketBird's data flows since July 2025 (roughly 30%
of federal civil cases). No criminal, bankruptcy, or state-court matters.
Zero records means "not in the graph," NEVER "no such cases exist" — do
not present an empty result as a finding that something doesn't exist.

Behavior:
- Slow: responses can take 10-25 seconds (an AI model interprets the
  question, then queries the graph).
- Result shape varies with the question; entity IDs accompany names.
- At most 200 records per response; 'truncated' means more matches exist —
  narrow the question to see the rest.
- Attorney email addresses are never included. This tool reports exactly
  what the API returned — it never invents contact details.

Args:
    question: The natural-language question (max 1000 characters).