Vaquill AI Primary Law

View saved version →

---
name: adjudications
description: Search federal administrative adjudications, with the overruling caveat stated up front. Subject: <topic or citation> [body].
---

Search adjudications for whichever subject the conversation is about. If it is not clear from the conversation, ask for it before calling anything.

Use `corpusType: "AGENCY_ADJUDICATION"`. These are decided cases from executive-branch tribunals.

## Read this before reporting anything

**No publisher in this family ships a machine-readable overruling signal for the general case.** A decision served as issued may have been overruled the week after it was decided, and nothing in this API will tell you.

`goodLawStatus` is `unknown` on every body except the CFPB slice, and that is correct rather than a gap. **Never present one of these as settled law.** Present it as a decision that was issued, with its date, and say the corpus cannot confirm its current standing.

This is also not case law. There is no court-opinion corpus here, and judicial review of these bodies is not published by them, so it is not reflected either.

## The bodies, and what differs about each

Filter with `source`.

| Body | What to know |
| --- | --- |
| **MSPB** | `mspb_precedential` binds Board administrative judges; `mspb_nonprecedential` does not. Separable on the `precedential` boolean. Federal Circuit review under 5 U.S.C. 7703 is not published by the MSPB |
| **OLC** | The executive branch's own controlling legal advice, cited `NN Op. O.L.C. NNN`. The bound series **ends at volume 44 (2020)**; opinions since are unbound and not held. Every point says so in its own `coverageNote` |
| **CFPB** | The only body with a real status signal. Actions the Bureau marks `Expired/Terminated/Dismissed` carry a dead `actStatus` and are **excluded from ordinary search**, which is roughly half the set. Both forums are held and separable on `forum` |
| **SEC** | Commission opinions and adjudicatory orders, cited by release number. **ALJ initial decisions are deliberately not held**; where an opinion names one, the citation is in `relatedCitations` only |
| **BIA / AG** | The `I&N Dec.` reporter. A published Board precedent binds every immigration judge and DHS officer nationwide under 8 C.F.R. 1003.1(g); an Attorney General decision sits above it |

## The BIA is the one place with real doctrinal links

The Board publishes holdings prose stating its effect on earlier decisions, resolved into `supersedes` / `supersededBy` with the publisher's own verb in `dispositionVerb`.

**`overruled_in_part` does not carry a dead `actStatus`**, deliberately: a partly overruled decision is still law for everything else it held. Report the partial overruling rather than treating the decision as dead or as intact.

Three stated limits: the Board only began publishing that prose at volume 19, so a pre-1984 overruling of a pre-1984 decision is invisible; a court of appeals can reject a precedent for its own circuit while it stands elsewhere, and EOIR does not publish that; volumes 1 to 7 are not held.

## SEC proceedings are sequences, not verdicts

Documents sharing a `fileNumber` are one proceeding, linked in date order through `supersedes` / `supersededBy`. Those links record a **sequence**, not an outcome: a later document may affirm the earlier one, schedule briefing, or merely notice an initial decision as final. Do not read a `supersededBy` link here as "overturned".

## Report

For each decision: the body, the citation as the publisher prints it, the date, `decidedBy` where present, and the holding.

Then the caveat, every time: this is the decision as issued, and the corpus carries no verdict on whether it still stands. Tell the user to shepardise before relying on it.

View saved version →

---
name: as-of
description: Read a statute section as it stood on a given date, with the observation caveat stated honestly. Subject: <citation or act_id> <YYYY-MM-DD>.
---

Reconstruct a section as of a date whichever subject the conversation is about. If it is not clear from the conversation, ask for it before calling anything.

Procedure:

1. If given a citation string rather than an `act_id`, resolve it first with `resolve_statute_citation`. Never assemble an `act_id` by hand; the chapter component is not derivable from a citation.
2. Call `get_section_changes` (1 credit) to see the observed timeline for that section.
3. Call `get_us_statute_section_text` with `asOf=<date>`.

Report the text, then the provenance, in this order:

- The reconstructed body.
- The change events that bracket the requested date, with their dates.
- The `asOf.isBounded` flag, translated into plain language.

Translate `isBounded` carefully, because it is the part users misread:

- `isBounded: true` means we observed no change affecting that date. It is evidence, not proof.
- `isBounded: false` means the reconstruction is not bounded by an observation at all, and should be presented as our best reconstruction rather than as the text in force.

Never phrase either case as "this is what the law said on that date" without the qualifier.
If the section has no recorded change events, say that the reconstruction rests on no observation history.

View saved version →

---
name: authority
description: Trace the chain between a statute and the regulations that implement it, in either direction. Subject: <citation or act_id>.
---

Trace the authority chain for whichever subject the conversation is about. If it is not clear from the conversation, ask for it before calling anything.

Statutes grant power; regulations exercise it. This command walks the link, which is a different question from "what does this say".

1. Resolve the input to an `act_id` if it is a citation string.
2. Fetch the section and read the link fields.

## The fields, and which direction each points

| Field | On | Points to |
| --- | --- | --- |
| `implementingRegulations` | USC | The CFR parts issued under this statute |
| `statutoryAuthority` | CFR | The statute granting the rulemaking power |
| `lawImplemented` | CFR and some state regs | The statute the rule actually **implements** |

**`statutoryAuthority` and `lawImplemented` are not the same thing**, and conflating them is the mistake this command exists to prevent. One is the power to write the rule, the other is the substantive law being carried out. Florida populates both and they routinely differ.

## Then widen with the citation graph

- `crossReferencesUsc` and `crossReferencesCfr` are the outbound references in the text. `'self:<section>'` denotes another section of the same title.
- `relatedCitations` carries outbound references that are neither USC nor CFR. On several corpora `crossReferencesUsc`/`Cfr` are 0% populated, so this is the only outbound set they have.
- `get_section_cited_by` (2 credits) is the **inbound** direction: which sections point at this one. USC and CFR only; state codes and Federal Register rules carry no cross-reference index and return empty with a `note`, refunded.

## Two honesty constraints

**Inbound citations are evidence, not proof.** A citation the publisher never recorded in machine-readable form cannot appear. `total` is the size of the returned list capped by `limit`, not a corpus-wide count; `truncated` says more exist.

**A chain is not an argument.** That a regulation was issued under a statute says nothing about whether it is valid, current, or applies to the user's facts. Report the links, not a conclusion about authority.

## For federal statutes, consider the enacting text too

`publicLawCites` on a USC section carries structured Statutes at Large citations, each with `statVolume`, `statPage` and a `display` string. Those resolve into `corpusType: "SESSION_LAW"`, which holds federal law **as enacted** rather than as codified.

Worth fetching when the question turns on what Congress actually passed rather than how it was compiled. Note that acts before 1957 carry no public law number and are cited by chapter.

## Report

Draw the chain as a short list, statute at the top, regulations beneath, with the field that established each link named. Where a link is absent, say the corpus records none rather than implying no such relationship exists.

View saved version →

---
name: changed
description: Sweep a corpus or jurisdiction for what has changed since a date. Subject: <YYYY-MM-DD> [corpus and/or state].
---

Report what changed since whichever subject the conversation is about. If it is not clear from the conversation, ask for it before calling anything.

Use `search_us_statutes` with `changedSince`.

1. **Scope it before you call.** Pass `corpusType` and `state`. A `changedSince` window matching more than 20,000 sections is **refused with a 422**, not truncated, because a partial change set would look complete to a sync job. If you get that 422, narrow the corpus or the date range; do not retry unchanged.
2. Run the search. It costs 4 credits, and **an empty result is charged**: "nothing moved since Tuesday" is the answer you paid for.
3. For anything that matters, call `get_section_changes` on the `act_id` (1 credit) to see the event history, then fetch the body if the user needs the current text.

Report as a list grouped by corpus: citation, what kind of change, when it was detected.

State these three caveats explicitly. They are the difference between a useful report and a misleading one:

- **These are observed changes, not effective dates.** `detectedAt` is when we saw the publisher's text differ from our copy. It is an upper bound on when the change took effect, never the effective date.
- **An empty result means no captured change in the window, never that nothing was amended.** Change capture began long after the corpus did, runs per source, and events are swept at 24 months. A date range older than 24 months will look quiet because the events were swept, not because the law was still.
- **A detected change is not necessarily an amendment.** Publishers re-typeset and republish. If the user needs to know whether the substance moved, the diff has to be read.

If they ask "has anything changed" about one specific section rather than a corpus, skip all of this: `get_section_changes` on that `act_id` costs 1 credit and answers it directly.

View saved version →

---
name: compare-states
description: Compare how different states word the same rule, starting from one provision or a topic. Subject: <citation or act_id, or a topic and a list of states>.
---

Compare across states whichever subject the conversation is about. If it is not clear from the conversation, ask for it before calling anything.

Two routes. Pick by what you were given.

**Given one provision** (a citation or `act_id`):

1. Resolve it to an `act_id` if needed (`resolve_statute_citation`, 2 credits).
2. Call `get_section_cross_state` (6 credits). It returns at most one provision per state, most similar first.
3. Fetch the body of each hit worth reporting.

**Given a topic and a list of states:**

1. Call `search_us_statutes` once with `state` as a **list**, for example `["ca","ny","tx"]`. One call, not one per state.
2. Take the best hit per state, then fetch bodies.

Either way, verify before you compare. `similarity` is a retrieval score, not a legal opinion: a high score means two provisions cover the same ground, never that they impose the same obligation, and the differences are usually the entire point of the question.

Report as a table, one row per state: citation, the operative requirement in a short phrase, and `goodLawStatus`.

Then, below the table, write the part that matters:

- **Where they actually differ.** Thresholds, deadlines, who is covered, what triggers the duty, what the remedy is.
- **Any state that did not come back**, and which of the two reasons applies. Fewer states than requested means the rest did not clear the similarity floor, not that they are missing from the corpus. Check `list_statutes_coverage` (free) before saying a state has no such law.
- **Any state whose `goodLawStatus` is not `good_law`**, called out rather than folded into the table.

Do not present the comparison as legal advice about which state is stricter. Present what each text says and let the differences speak.

View saved version →

---
name: coverage
description: Report what Vaquill AI actually holds for a jurisdiction, before you read an empty result as an absence of law. Subject: [state, or 'federal', or leave blank for everything].
---

Report corpus coverage for whichever subject the conversation is about. If it is not clear from the conversation, ask for it before calling anything.

Call `list_statutes_coverage`. It is free, so call it rather than inferring coverage from search results.

Read two things off the response, and keep them separate:

1. **`corpora`** - which corpus types this jurisdiction holds, and the document count for each. Coverage is per `(jurisdiction, corpusType)` pair, never per jurisdiction: a state can be complete in statutes and hold nothing in regulations.
2. **`statusBreakdown`** - within each corpus, how those documents divide by status (`inForce`, `repealed`, `superseded`, `unknown` and so on). A large count is not a large count of operative law.

Then answer the question the user actually has, which is almost always one of these:

- **"Is this a gap or an absence?"** An empty search inside a corpus we hold means the provision is probably not there. An empty search for a corpus we do not hold means nothing at all about the law and must never be reported as "no such provision".
- **"How current is this?"** Answer it for the specific section: `get_us_statute_section_text` returns the date the publisher states the text is current through, and `get_section_changes` lists the changes observed to that section.

Two things to state rather than assume:

- **Read `measuredAt`.** This response is cached and can legitimately be hours old. If the user is making a decision on the counts, tell them when they were measured.
- **A section count is not a statute count.** The per-jurisdiction total spans every corpus type, so a jurisdiction can hold tens of thousands of documents and zero statutes.

If the user landed here because a search came back empty, say explicitly which of the two cases they are in. That is the whole reason this command exists.

View saved version →

---
name: guidance
description: Find federal agency guidance on a topic, and say clearly what weight it does and does not carry. Subject: <topic> [agency or source].
---

Find agency guidance on whichever subject the conversation is about. If it is not clear from the conversation, ask for it before calling anything.

Use `corpusType: "AGENCY_GUIDANCE"`. This is **sub-regulatory** material: what an agency says about how it reads the law. Handling that honestly is the whole job of this command.

## Narrow with `source`, always

The token folds 53 named sources. Unscoped, a query for harassment guidance can return NLRB advice memos.

The `source` vocabulary is published on the search endpoint, and **a bad value returns a 422 naming every valid code**, so the API is the authoritative list. Ask it rather than guessing. `list_statutes_coverage` (free) also carries the full legend with per-source scope notes.

## Say what it is before you say what it says

Guidance is not law, and several sources carry harder limits than that:

- **IRS written determinations** (private letter rulings, TAM, chief counsel advice) carry `actStatus: non_precedential` because **26 U.S.C. § 6110(k)(3) says they "may not be used or cited as precedent"**. They are evidence of how the Service analysed one taxpayer's facts. Say so every time you surface one.
- **The Internal Revenue Manual** is the IRS's own instruction manual for its employees. It is agency procedure, it does not bind the agency against a taxpayer, and it must never be listed alongside statutes and regulations as though it were.
- **The DOL Field Operations Handbook** is WHD internal enforcement procedure, on the same footing.
- **CMS Internet-Only Manuals** are instructions to Medicare contractors, not regulations.

## Coverage is bounded per source, and the bounds are real

Several sources are deliberately partial. Check the scope note before reporting an absence:

- NLRB Division of Advice memoranda: a **rolling 10-year window**, not the full archive.
- CPSC advisory opinions: historical, roughly 1970s to 2012.
- OLC opinions: the official bound volumes, ending at volume 44 (2020). Opinions issued since are not bound and are not held.
- CFTC staff letters: 2008 to present.

## Currency

Most of this corpus reports `goodLawStatus: unknown`, and that is correct rather than a gap: agencies rarely publish a machine-readable withdrawal signal. Where an item carries `rescinded`, `superseded` or `withdrawn`, lead with it.

`unknown` here means unverified. Do not present a 2011 advisory opinion as the agency's current position because nothing marked it dead.

## Report

For each item: the issuing agency and source, the citation or document number, the date, and what it says.

Then, in one line, what it is worth: binding regulation, non-binding interpretation, internal procedure, or non-precedential determination. That sentence is the most useful thing in the answer.

If the question is really about what the law requires rather than how an agency reads it, say so and point at the statute or regulation instead.

View saved version →

---
name: research
description: Find the controlling US law on a question and answer only from the text the tools return. Subject: <question> [in <state>].
---

Research whichever subject the conversation is about. If it is not clear from the conversation, ask for it before calling anything.

If no jurisdiction was named, ask which one before spending credits. An unscoped search costs the same and returns worse results.

Run this loop:

1. **Confirm coverage** with `list_statutes_coverage` (free) if the question is about a state or a corpus you have not queried this session. This is what separates "the law does not say that" from "we do not hold that corpus".
2. **Search scoped.** Pass `corpusType` and `state`. Set `excludeRepealed: true` unless the user is specifically asking what was repealed.
3. **Judge the result set by score separation, not by whether rows came back.** Vector search always returns nearest neighbours, so a meaningless query still produces a full page. If the top score is not clearly above the tail, say the corpus does not appear to answer this rather than reporting the best of a bad set.
4. **Fetch the text** of the sections that actually matter with `get_us_statute_section_text`. Use `format=content` on USC so you get the operative text instead of the amendment notes. Never quote the excerpt.
5. **Check the defined terms** with `get_section_definitions` if the answer turns on a word like "person", "employee", "consumer" or "security". Statutes routinely define these against ordinary usage.
6. **Read `goodLawStatus` on everything you cite.**

Then answer. Structure it as:

- The controlling provision, quoted from the body, with its citation and official source link.
- What it requires, in plain language.
- Any defined term that changes the reading.
- Currency: `good_law`, or an explicit caveat.

Rules for the answer:

- Every proposition traces to text a tool returned. If you know something the tools did not return, say it is outside what the corpus confirmed.
- `goodLawStatus: unknown` means unverified, not current. Tell the user to confirm against the official source.
- There is no case law here. If the question actually turns on how courts have read the provision, say so plainly rather than implying the statutory text settles it.
- If nothing solid came back, say so. Do not assemble an answer from adjacent sections.

View saved version →

---
name: rulemaking
description: Track a Federal Register rulemaking: what an agency proposed, what became final, and when comments close. Subject: <topic or agency> [proposed|final] [since YYYY-MM-DD].
---

Track rulemaking whichever subject the conversation is about. If it is not clear from the conversation, ask for it before calling anything.

This is a different question from "what does the law say". The CFR is the rule in force; the Federal Register is the rule *moving*. Use `corpusType: "FEDERAL_REGISTER"`.

## Filters that only work here

- `agency` takes the FR agency slug, e.g. `environmental-protection-agency`. A list matches any of several. Combined with a non-FR corpus it returns **empty**, not an error.
- `documentType` is `final`, `proposed` or `presidential`. Ask which the user means: "what did EPA do" is usually final, "what is coming" is proposed.
- `publishedFrom` / `publishedTo` are the **publication** date. This is not `yearFrom`, which filters a section's version year.

Each result carries `agencySlugs`, and those are exactly the values `agency` accepts, so a facet round-trips straight back into a narrower query.

## Report the dates carefully, because there are four of them

| Field | Meaning |
| --- | --- |
| `publicationDate` | When it appeared in the Register |
| `frEffectiveOn` | When the rule takes effect |
| `frCommentsCloseOn` | The comment deadline on a proposed rule |
| `datesText` | The publisher's own prose, ~98% populated |

**Prefer `datesText` when a rule has staged or conditional effective dates.** The single `frEffectiveOn` flattens that away, and a compliance reader acting on the flattened date can be wrong about when an obligation starts.

A rule is routinely published well before it is effective. Never report `publicationDate` as when the rule took effect.

## Follow the rulemaking, not just the document

A single rulemaking is usually several documents: a proposed rule, its final rule, and any corrections. They are joined by the **Regulation Identifier Number**.

`frRelatedDocuments` groups them, but it is **only populated on `get_us_statute_section`**, never on a search result, because computing it needs a follow-up lookup. So: search to find one document, then fetch it by `act_id` to see the rest of its family.

Also useful: `frRegulationIdNumbers` (the RIN itself), `frDocketIds`, `frCorrectionOf` and `frCorrections`, `frRegulationsDotGovUrl` for the comment docket, and `frStartPage`/`frEndPage`, which give the page range the citation cannot express.

## Notices are a curated slice, not the whole series

`FEDERAL_REGISTER_NOTICE` is a separate token holding roughly 2.4% of notices: the ones that act on a rulemaking (withdrawals, comment-period extensions and reopenings, significant guidance, negotiated rulemaking). Every notice carries `frNoticeClass` saying which rule admitted it.

Paperwork Reduction Act collections, meeting notices and permit applications are **not held**. If the user is looking for one of those, say so rather than reporting an empty result as an absence.

## Report

Group by rulemaking, not by document. For each: agency, stage, citation, publication date, the effective or comment-close date, and the `abstract` (populated on 99.9% of rules) rather than your own summary. Note `action` verbatim, since "interim final rule", "direct final rule" and "withdrawal" are legally different things.

View saved version →

---
name: us-statute-research
description: Research US primary law with the Vaquill AI tools - find a controlling section, resolve a citation to an exact provision, read a section as it stood on a past date, scope a search to the right corpus, and report currency honestly. Use whenever a question turns on what a US statute, regulation, court rule, constitution or agency guidance document actually says, or when a citation needs verifying against the official text.
---

# Researching US primary law

This corpus is enacted and promulgated text from official government publishers.
Every answer must rest on text a tool returned.

A plausible fabricated citation is the worst output this tool set can produce, and it is the easiest to produce by accident: **a nonsense query still returns rows.** Vector search always returns nearest neighbours. Separation is the signal, not presence, and search says so directly with `noGoodMatch` (below). Across our labelled eval, a query with no answer in the corpus put its top row at a median `relevanceScore` of about 0.53, where a real one put it near 0.89. A high score still does not prove the top row is the right section: a same-topic section from the wrong jurisdiction or the wrong layer (a state statute for a federal question, a regulation for a statute) scores just as high, so check the citation and jurisdiction of every row you rely on.

Read this before the first call. Most of what follows is the difference between an answer and a confidently wrong answer.

---

## 1. The corpus

### Do not hardcode what it holds

The published docs say it plainly: do not hardcode credit costs, jurisdiction counts, or corpus lists.
Section counts differ between the search documentation, the coverage endpoint and the marketing page, and all three go stale.

`list_statutes_coverage` is **free** and is the only live answer. It returns a `corpusTypes` legend, per-jurisdiction counts, freshness notices and retrieval status.
Call it rather than quoting a number from memory or from this file.

### The corpus tokens

Roughly 19 `corpusType` tokens. The live spec enum and the docs disagree on the exact set, so treat this as orientation and the coverage legend as truth.

**Federal:** `USC`, `SESSION_LAW` (Statutes at Large, as enacted), `STATUTE_COMPILATION`, `CFR`, `CFR_ANNUAL`, `FEDERAL_REGISTER`, `FEDERAL_REGISTER_NOTICE`, `EXECUTIVE_ACTION`, `AGENCY_GUIDANCE`, `AGENCY_ADJUDICATION`, `US_TAX_TREATY`, `SENTENCING_GUIDELINES`, `FEDERAL_RULES`, `CONSTITUTION`.

**State:** `STATE`, `REGULATION`, `STATE_RULES`, `STATE_AGENCY_GUIDANCE`, `STATE_CONSTITUTION`.

A federal token needs only `corpusType`. **A state token needs `state`**, or the search spans every jurisdiction holding that corpus and costs exactly the same.

`source` narrows the folded tokens (`AGENCY_GUIDANCE` alone covers dozens of named sources across many agencies). A bad `source` returns a 422 that names every valid code, **so the API itself is the authoritative list.** Ask it rather than guessing.

### `CFR_ANNUAL` is excluded from the default pool

Historical CFR editions are not merely demoted, they are excluded from the default candidate pool. An unfiltered search never returns them.
To reach a historical edition you must ask for it by token.

### What it does not hold

**No general case law, no court dockets.** The roadmap puts them explicitly out of scope. There is no judicial-opinion search here.
If a question needs holdings rather than enacted text, say so instead of reaching for a statute tool that cannot answer it.

**United States only.** A question about another country's law returns empty rather than erroring, which reads as a gap in US coverage. Say the corpus does not cover it.

---

## 2. `act_id`: the single most common failure

> "You never construct an `actId` by hand."

It looks assemblable. It is not.

```text
USC_T42_C21_S1983                       42 U.S.C. § 1983
CFR_T17_P240_S240_10b5_1                17 C.F.R. § 240.10b5-1
STATE_TX

Preview of the first 4,000 characters. Read full instructions →

View saved version →

---
name: verify-citations
description: Verify every legal citation in a file, selection, or pasted text against the official source text. Subject: [file path, or paste the text].
---

Verify the citations in whichever subject the conversation is about. If it is not clear from the conversation, ask for it before calling anything.

If no argument was given, use the current selection or ask which file to check.

Procedure:

1. Extract every statutory, regulatory and court-rule citation from the text. Ignore case citations; this corpus does not carry general case law, and say so if the text leans on them.
2. Resolve them in one call with `resolve_statute_citations_batch` rather than one at a time. It is priced per citation either way, so the batch is a pure round-trip win.
3. For each citation that resolved, fetch the section metadata and check `goodLawStatus`.
4. For any citation whose quoted language matters to the argument, fetch the body and compare the quotation against the official text verbatim.

Report as a table: citation as written, what it resolved to, whether it is still good law, and whether any quoted language matches.

Flag these separately and prominently:

- Citations that did not resolve. Say "did not resolve" rather than "does not exist"; an unresolved citation may be a formatting variant.
- Citations pointing at repealed or superseded provisions.
- Quotations that differ from the official text, with both versions shown.

Do not silently correct a citation. Show what was written and what the source says, and let the user decide.