OpenRegs: Regulatory Research

Show 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.

expand_hierarchy

Retrieve the full text of one OpenLaws document by the id returned by a `search` result.

fetch

Retrieve 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.

get_division_by_path

List 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.

list_jurisdictions

Look 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.

resolve_citation

Search 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

Full-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 your query contains apostrophes, possessives, or punctuation (`workers' compensation`, `employer's notice`) and the default search returns thin or zero results, that's often a tokenization mismatch, NOT a corpus gap. Some OpenLaws law titles use curly apostrophes (`workers'`) that don't match the straight-apostrophe form (`workers`) under the default tokenizer. Before concluding the topic isn't covered, retry with `query_type="phrase"` — the phrase tokenizer handles apostrophe/punctuation boundaries differently and frequently surfaces results the default mode misses. Three `query_type` values are supported: - `"and"` (same as default, None): every word must appear. - `"or"`: any word may match. Useful for synonym-spread queries; behavior may overlap with `"and"` depending on Vespa's scoring on the specific query. - `"phrase"`: words are matched as an exact phrase AND the phrase tokenizer is more permissive on apostrophes/punctuation. The primary use is the tokenization workaround above. HONEST-GAP BEHAVIOR: if this tool returns zero results AND you have strong reason to believe the corpus should contain something relevant, rephrase the query (see BM25 guidance), try `query_type="phrase"` (see TOKENIZATION FALLBACK), or scope to a more likely law type. If broad, scoped, AND phrase searches all come back empty, honestly report "no responsive provision found in the indexed corpus" rather than falling back on tangentially related results. Defaults to the top 10 results; can request up to 50.

search_codified_law

Balanced 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.

search_codified_law_balanced

Run 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" directly to `jurisdictions` and leave `with_federal` false.

survey_jurisdictions