expand_hierarchy
ChatGPTShow the codified-law hierarchy ONE LEVEL below the given path: the Division at path plus its direct children's display_names and paths. USE THIS when you need to see what's directly INSIDE a title, chapter, part, subchapter, etc. — the "what's the next level of the table of contents under here?" view. Reads the database-backed display_children field, so it works for every law type in every jurisdiction (does not depend on the search index being populated). Returns ONLY hierarchy info — display_name, path, direct children. No section text. Once you've drilled to the section you want, pass its path to get_division_by_path to retrieve the text (or resolve_citation if you have a parseable citation). TO DRILL DEEPER: re-call this tool with one of the child paths as the new path; this tool does NOT recurse into grandchildren in a single call. An empty children list means the node is a true leaf.
fetch
ChatGPTRetrieve the full text of one OpenLaws document by the id returned by a search result.
get_division_by_path
ChatGPTRetrieve a Division's full TEXT by its ltree path (not a citation). Companion to expand_hierarchy: that tool navigates the structure and hands you a path; this one pulls the section text AT that path. Returns the SAME envelope shape as resolve_citation — a division metadata block plus content. USE THIS as the reliable way to get section text when a citation won't parse: some jurisdictions use a citation structure the parser can't read (e.g. Nebraska's agency/title/chapter/section form), so resolve_citation returns a parse failure even though the section exists and is reachable by path. The recovery: find the section's path (from a search_codified_law result or by drilling with expand_hierarchy), then call this tool with that path. The text comes back through OpenLaws, so it is a grounded retrieval — do NOT substitute text from a web page.
list_jurisdictions
ChatGPTList every U.S. jurisdiction for which OpenLaws has law data. Returns states, federal (FED), federal bankruptcy (FED-BANKR), military (MIL), tribal, plus D.C. and territories. Returns each jurisdiction's key (e.g. 'CA', 'FED'), name, Bluebook abbreviation, and the laws available in it. OpenLaws covers codified law only — statutes, regulations, and constitutions. Case law and court opinions are NOT in the corpus and are not retrievable by these tools. Call this first when you don't know a jurisdiction's key or want to discover what law types are available before calling resolve_citation or search_codified_law.
resolve_citation
ChatGPTLook up a specific section of statute, regulation, or constitution by its Bluebook legal citation within a given U.S. jurisdiction. Use strict Bluebook form with period abbreviations (e.g. 'Cal. Civ. Code § 1798.100'). Long Divisions paginate into pincite chunks; page with chunk_offset.
search
ChatGPTSearch OpenLaws US codified law — statutes, regulations, and constitutional provisions. ALWAYS include the jurisdiction in the query: a US state name or 'federal' (e.g. 'California meal break requirements', 'federal overtime rules'). Returns a ranked list of sections; pass a result's id to fetch to read its full text.
search_codified_law
ChatGPTFull-text (BM25) search for codified law (statutes, regulations, constitutional provisions) matching keywords within a jurisdiction. This is the unified search tool for the v0 Surveyor surface. Scope is controlled by the optional law_key and within_division_path params: - No `law_key`: searches across ALL law types in the jurisdiction (statutes, regulations, constitutions). Returns a single ranked list. Best for natural-language questions when you don't know which law type holds the answer. - `law_key` set: scopes to one specific law (e.g. CA-STAT, TX-RR, FED-CFR). The RELIABLE way to sidestep BM25 ranking biases that can cause one law type to crowd out another in jurisdiction-wide search. Required when you want to drill into a within_division_path. - `within_division_path` set: scopes the search to a subtree of the law (e.g. title_15.division_1.chapter_1). Requires law_key. Useful for iterative drill-down. Pass a list to search across multiple sibling subtrees in one call (OR semantics, comma-joined under the hood). - `with_federal=true`: also include federal laws in the search alongside the named state jurisdiction. - `query_type` set: switches the matching mode. Defaults to the API's default (whitespace-split, every word must appear). Set to "phrase" as a tokenization-gap workaround when the default mode returns thin results on apostrophe- or punctuation-containing queries — see TOKENIZATION FALLBACK below. Results are returned as LEAN SUMMARIES — path, identifier, display_name, display_ancestors (context; may be empty), lifecycle flags, and dates. display_ancestors is a list of display-name strings (root-most first), e.g. ["Title 28: Transportation", "Chapter 23: Highway Beautification", "Article 1"] — NOT a list of dicts. To get the full text of a winning result, pass its path to get_division_by_path (with the result's jurisdiction_key and law_key) — path is always present and needs no citation formatting, so this is the reliable retrieve step. Alternatively, if you have a clean citation, build a strict Bluebook form from identifier (plus display_ancestors when present), e.g. Tex. Lab. Code § 406.033, and call resolve_citation. Either way the workflow is: search, skim results, retrieve primary source, quote. COMMON law_keys (discover the full list via list_jurisdictions): - State statutes: CA-STAT, NY-STAT, TX-STAT, FL-STAT, ... - State regulations: CA-RR, NY-RR, TX-RR, FL-RR, ... - State constitutions: CA-CONST, NY-CONST, ... - Federal statutes: FED-USC, US-USC - Federal regulations: FED-CFR, US-CFR IMPORTANT — BM25 scoring can favor regulations over statutes for natural-language queries. Regulations have longer, more keyword-dense operational text, so they often outrank shorter statutory provisions even when the statute is the better answer. If the results look homogeneous (e.g., all from one law_type like CA-RR) but you suspect the right answer is a statute (or vice versa), do one of: 1. Re-call this tool with law_key set to the expected law_type (e.g. CA-STAT for California statutes) to scope the search and bypass the ranking bias. Reliable move. 2. Rephrase the query with vocabulary closer to the target law type's lexicon. Statutes tend to use short, declarative language ("shall notify", "is guilty of", "harbors conceals aids", "felony") rather than operational language ("duty to report", "mandatory reporting requirements"). If your first query reads like a regulation's prose, try rewriting it to sound more like a statute. 3. If neither surfaces the expected answer, honestly consider that the relevant provision may not be in the corpus OR the query vocabulary may be too far from the text. "No responsive statute found" is a valid answer; confidently returning adjacent regulations as if they answered a statute question is the failure mode to avoid. TOKENIZATION FALLBACK: by default this search splits the query on whitespace and requires every word to appear (the API's default mode, which is the "and" tokenizer). If you…
search_codified_law_balanced
ChatGPTBalanced search that guarantees EVERY law type in a jurisdiction gets its own result slots. Unlike search_codified_law (which merges all law types into a single BM25-ranked list where regulations can crowd out statutes), this tool runs a separate search per law type and returns the top results from each. USE THIS when you want to discover relevant provisions across statutes AND regulations AND constitutions for a natural-language question. The results are grouped by law type so you can see the best matches in each category independently. WHEN TO USE: - For broad exploratory questions like "data breach disclosure requirements" or "duty to report a felony" where the answer could live in statutes, regulations, or both. - When you've tried search_codified_law and the results were homogeneous (all regulations, no statutes) — this tool guarantees statute slots. - When you want a comparative view: "what does the statute say vs. what do the regulations say?" WHEN NOT TO USE: - When you already know the specific law type — use search_codified_law (with law_key set) directly. - When you have a citation — use resolve_citation. - When you need more than 3 results per type — use search_codified_law (with law_key set) with a higher limit on each type separately. Results are grouped by law type with the type name as a header. Within each group, results are ranked by BM25 relevance. Each result is a lean summary — same shape as search_codified_law, including display_ancestors as a list of display-name strings (root-most first). If a law type returns zero results for the query, it appears with an empty list so the LLM knows that category was checked. Per-group failure shapes (when a per-type query errors out): the group carries error with the first 200 chars of the error string, or note with "No matching divisions for this law type" when the category was checked but had no usable hits. Read these the same way as empty results — the category was checked, just no usable hits. Top-level failure shape: if the jurisdiction has no laws at all, the tool returns {"error": "No laws found for jurisdiction '<jurisdiction>'"} instead of a list of groups. If with_federal is true, every law in the FED jurisdiction (typically FED-USC, FED-CFR, and any other federal laws OpenLaws publishes) is searched alongside the state's own law types. This adds one additional group per federal law to the results. The flag is a no-op when jurisdiction is already FED or US. query_type is forwarded to every per-law-type search; use "phrase" as the tokenization-gap workaround when the default mode produces thin or zero results on apostrophe-containing queries (same discipline as search_codified_law). Defaults to the API default.
survey_jurisdictions
ChatGPTRun a balanced search across multiple jurisdictions in parallel and return a per-jurisdiction row with the grouped results. USE THIS when the question is comparative or multi-state — "what does each of these states require?" or "where do CA/TX/NY differ on X?" This is the headline tool for compliance-style multi-state surveys. WHEN TO USE: - Multi-state compliance questions (e.g., "workers' comp coverage requirements across CA, TX, NY, FL, DE") - "What does each state's statutes and regulations say about X?" - Side-by-side comparisons across jurisdictions WHEN NOT TO USE: - Single-jurisdiction queries — call search_codified_law_balanced directly (this tool reduces to that with extra envelope cost when jurisdictions has only one entry). - When you have a citation — use resolve_citation. - When you need only one law type per state and you know which — call search_codified_law (with law_key set) per state instead. Response shape: a cap_status envelope wrapping the rows. { "cap_status": "within_cap" | "trimmed_rpt" | "trimmed_states" | "summary_only", "requested_rpt": <int>, "returned_rpt": <int>, "trimmed_states": [<jurisdiction keys, in trim order>], "rows": [...], "summary": <null when not summary_only, else per-state hits>, "state_offset": <int>, "next_state_offset": <int | null>, "total_states": <int> } Paging over states. A survey returns at most one page of states per call. When the request covers more states than fit in one page, next_state_offset is the index to pass back as state_offset to fetch the next page; it is null on the last page. total_states is the full count requested. This is how a large survey (e.g., all 50 states) is answered: call once, then keep calling with the returned next_state_offset until it comes back null, merging the rows. Each page carries full results — paging is the size control, so the trim ladder below rarely fires within a page and summary_only should not occur in normal use. The tool self-regulates response size to keep the assembled output under Claude's documented 25K-token per-tool-result cap. The trim ladder: - within_cap: requested rpt fits the budget. Full rows returned. - trimmed_rpt: rpt reduced globally; returned_rpt carries the level that fit. Agent should narrate "returned N results per type, asked for M". - trimmed_states: rpt=1 still didn't fit, so the heaviest rows had their results emptied and groups marked truncated: true. trimmed_states lists the jurisdiction keys whose results were dropped; pull them via direct citation lookup or a smaller follow-up survey. - summary_only: full rows didn't fit. rows is empty; summary carries per-state hit_count and top_path per law-type so the agent can drill in selectively via resolve_citation. Each row has a status enum: - "ok": all per-law-type groups succeeded. - "partial_error": at least one group errored AND at least one succeeded (e.g., rate-limit failure on one law type while others succeeded). success_count and error_count describe the partial state. Agent can detect partial losses at row level rather than scanning every group. - "error": every group errored, or the per-state call raised an unrecoverable exception. error carries a generic failure message; the underlying exception is reported to our error tracker for triage, not returned to the caller. - "no_laws": the jurisdiction key is not in the API directory. groups is []; note carries the API's error message. Rows are returned in the same order as the input jurisdictions list. Per-state execution is concurrent but bounded by an internal semaphore. There is no ceiling on the size of the jurisdictions list: only one page of states is fetched per call, so parallelism cost is bounded by the page size regardless of how many states the caller passes. If with_federal is true, every per-state row's groups will additionally include FED law groups (FED-USC, FED-CFR, etc.) — same per-row behavior as search_codified_law_balanced. To get a single FED block instead of FED-per-state duplication, add "FED" or "US" directl…
