F
licenseNot graded
qualityA
maintenanceEnables LLM-friendly access to the CourtListener legal database and eCFR for searching legal opinions, court cases, judges, documents, and federal regulations.
12
-
courtlistener-mcp-server
Server Details
Search US court opinions, federal dockets, judges, citations, and oral arguments via CourtListener.
If you are the author of this connector, you can claim ownership with GitHub, an HTTP challenge, or a DNS record. Claimed connector authors can inspect health checks, view analytics, and manage their listing.
- Status
- Healthy
- Last Tested
- Transport
- Streamable HTTP
- URL
- Repository
- cyanheads/courtlistener-mcp-server
- GitHub Stars
- 2
- Server Listing
- @cyanheads/courtlistener-mcp-server
TDQS
A4.4/5.0
Scored across 14 tools
Disambiguation5/5
Each tool targets a distinct resource and action: citations, dockets, judges, opinions, oral arguments, parties, courts, and financial disclosures are all clearly separated between search/get/lookup operations. Even potentially similar tools (e.g., get_citations vs. lookup_citation) have clearly defined different purposes—network traversal vs. citation resolution—eliminating ambiguity.
Naming Consistency5/5
All tools follow the consistent pattern 'courtlistener_<action>_<noun>', with actions restricted to get, search, and lookup. Singular nouns are used for get/lookup, plural for search, and no style mixing or irregular verbs appear, making the naming scheme predictable and easy to navigate.
Tool Count5/5
With 14 tools, the server covers seven core legal research resources (dockets, opinions, judges, financial disclosures, oral arguments, courts, citations), each with a search and get operation, plus two lookup utilities. This is well-scoped for a comprehensive read-only API and every tool serves a distinct purpose without redundancy.
Completeness5/5
The tool surface provides full search-and-retrieve coverage for all major CourtListener data types: opinions, dockets, judges, financial disclosures, oral arguments, courts, and citations. There are no obvious dead ends—every search result can be followed by a corresponding get tool, and citation resolution integrates with opinion retrieval. The domain is fully addressed.
Available Tools
14 toolscourtlistener_get_citationsGet Citation NetworkARead-onlyInspect
Retrieve the citation network for an opinion cluster. Supports two directions: "cited_by" (opinions that cite this one — measures precedential influence) and "citing" (opinions this one cites — reveals the authority chain relied on). This is the primary tool for tracing legal precedent chains. Note: the free tier supports shallow traversal — following 1–2 hops of a single case is practical; deep multi-hop analysis burns through the daily budget quickly.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| court | No | Filter results to a specific court (e.g., "scotus", "ca9"). Applies to both directions. | |
| cursor | No | Pagination cursor from a previous response's next_cursor field. | |
| direction | No | "cited_by" (default): opinions that cite this one — measures precedential influence and downstream adoption. "citing": opinions this one cites — reveals the authority chain the court relied on. | cited_by |
| page_size | No | Number of results to request (default 20). For direction="cited_by", CourtListener enforces a minimum of 20 results per page regardless of the value passed — you will always receive at least 20 results. direction="citing" returns at most page_size (the cited-opinion list is sliced before querying) — fewer when the opinion cites fewer than page_size distinct opinions. Either direction costs three requests against the rate limit (a case with many opinion variants costs one more per extra variant page) — keep low for multi-hop traversal. | |
| cluster_id | Yes | Opinion cluster ID to retrieve citations for. Obtain from courtlistener_search_opinions or courtlistener_lookup_citation. | |
| filed_after | No | Limit to citations filed after this date (ISO 8601). For "cited_by", useful for "how has this precedent been applied recently?" |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
| error | No | Present when the call failed. Absent on success. |
| notice | No | Context when no citations are returned — either that this page had no match under the filters and more pages remain, or a recovery hint echoing direction and filters. |
| results | No | Related opinions in the citation network. |
| direction | No | Direction of the citation relationship returned. |
| totalCount | No | Total citations in the requested direction. For "cited_by" it counts matching clusters with the court and filed_after filters applied. For "citing" it counts the distinct opinions this case cites, before any filter — so it exceeds what the filters make reachable, and runs higher than the result rows, which are clusters (several cited opinions in one case collapse to one row). |
| next_cursor | No | Pagination cursor for the next page; null when no more results. |
| source_case_name | No | Case name for the source cluster. |
| source_cluster_id | No | The cluster ID this citation network is for. |
TDQS
A4.5/5.0
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, and the description does not contradict them. It adds valuable behavioral context: the free tier's shallow traversal limits and the daily budget burn for deep multi-hop analysis. It also notes per-page rate-limit cost in the page_size parameter. These are non-obvious details beyond the annotations, enhancing transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences plus a note, tightly packed with information. It front-loads the primary action, then clarifies directions and usage role, and ends with a practical caveat. No wasted words; every clause earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a complex tool with 6 parameters, an output schema, and read-only open-world semantics, the description covers everything crucial: purpose, directions, primary use case, budget constraints, and rate-limit behavior. The output schema handles return format, and the schema documents parameters. Nothing critical is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all parameters. The description adds some contextual meaning (e.g., the purpose of each direction) but does not go beyond the schema. Baseline 3 applies since the schema does the heavy lifting; the description adds marginal, not essential, value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource ('Retrieve the citation network for an opinion cluster') and clearly differentiates the two directions ('cited_by' vs 'citing') with their distinct meanings. It distinguishes itself from siblings like courtlistener_get_opinion by focusing on the network rather than the opinion text. Strong, specific purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description identifies this as 'the primary tool for tracing legal precedent chains,' providing clear use context. It also cautions about shallow vs deep traversal, which helps an agent decide scope. It does not explicitly list alternative tools or when-to-not-use conditions, but the context is sufficient for most decisions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
courtlistener_get_docketGet DocketARead-onlyIdempotentInspect
Fetch full docket metadata and entry list for a single federal case by docket ID. Returns all available docket entries with document availability status. Documents with is_available=true have a RECAP-stored copy; others require a PACER account. Obtain docket IDs from courtlistener_search_dockets or from opinion results.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| docket_id | Yes | Docket ID from a search result's docket_id field or from an opinion cluster result. | |
| entries_page | No | Page of docket entries to fetch (1-indexed). Docket entries are page-paginated at 20 per page; pass the next_cursor from a previous response here to page through large cases. | |
| entries_page_size | No | Requested docket entries per page. NOTE: CourtListener ignores this value — /docket-entries/ always returns a fixed 20-entry page regardless of what is passed. Use entries_page to reach entries beyond the first 20 (large cases can have hundreds). |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
| cause | No | Legal cause of action. |
| court | No | Court display name for major federal courts; the court identifier otherwise. |
| error | No | Present when the call failed. Absent on success. |
| entries | No | Docket entries for this page (fixed at 20 per page; entries_page_size is not honored by upstream). |
| court_id | No | Court identifier — the stable value for filtering. |
| case_name | No | Short case name. |
| docket_id | No | Docket ID. |
| date_filed | No | Date the case was filed. |
| assigned_to | No | Assigned judge name; null if not recorded. |
| jury_demand | No | Jury demand status. |
| next_cursor | No | Next page number to pass as the `entries_page` argument (docket entries are page-paginated); null when this is the last page. |
| referred_to | No | Referred judge name; null if not recorded. |
| entries_page | No | Current entries page number (1-indexed). |
| docket_number | No | Docket number. |
| pacer_case_id | No | PACER case ID; null if not in RECAP. |
| total_entries | No | Total number of docket entries available — may exceed the returned entries list. |
| case_name_full | No | Full case name. |
| date_terminated | No | Date the case was terminated; null if active. |
| jurisdiction_type | No | Jurisdiction type. |
TDQS
A4.2/5.0
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=true and idempotentHint=true, so the description correctly avoids repeating those. It adds value by detailing the return payload (docket entries with is_available status) and explaining what that status means (RECAP vs PACER). This is behavioral context beyond annotations, though it does not mention pagination behavior which the schema covers. Given the annotations cover safety, a 4 is appropriate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, each earning its place: purpose, return details, and source of docket IDs. No redundancy or filler. The content is tightly packed and front-loaded with the primary function, making it concise and efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has a rich output schema (as indicated by 'has output schema: true'), so the description need not detail the return structure. It does cover the essential behavioral notes (availability status, PACER requirement) and ID sourcing. A minor gap: the description claims 'Returns all available docket entries' but pagination is mentioned only in the schema; this is acceptable given the schema carries that detail, so not a significant completeness issue.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so per the rubric baseline is 3. The description adds a hint on how to obtain docket_id (from search or opinion results), but this is already implied in the schema description. It does not add syntax or format details beyond what the schema provides. Thus, no significant increment above baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action ('Fetch full docket metadata and entry list'), a specific resource ('a single federal case by docket ID'), and provides differentiation from siblings by referencing how to obtain the ID from search or opinion results. It clearly distinguishes from search tools like courtlistener_search_dockets.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly tells the agent where to obtain docket IDs (from courtlistener_search_dockets or opinion results), which implies this tool is used after an ID is known. It also clarifies that documents with is_available=false require a PACER account, guiding user expectations. It does not explicitly state 'use this when you have a docket ID' but the context is clear. No exclusions are mentioned, so not a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
courtlistener_get_financial_disclosureGet Financial DisclosureARead-onlyIdempotentInspect
Fetch a single judicial financial disclosure by ID with its parsed line-item rows — investments, debts, positions, reimbursements, non-investment and spouse income, agreements, and gifts. This is the itemized companion to courtlistener_search_financial_disclosures (which returns only category counts). Pass categories:[...] to select specific categories; omit for all. Coded value/income columns are decoded to readable dollar ranges. When the full itemization is too large to inline, the response lists each category as a retrievable section by byte size while keeping the filing metadata and counts — re-call with categories:[...] to pull specific categories in full. Obtain disclosure IDs from courtlistener_search_financial_disclosures (the disclosure_id field).
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| categories | No | Line-item categories to return in full: investments, debts, positions, reimbursements, non_investment_incomes, spouse_incomes, agreements, gifts. Omit for all categories (or an outline if they overflow the inline budget). Also the re-call selector — after an outline response, re-call with the category names it lists. | |
| disclosure_id | Yes | Financial disclosure ID — the disclosure_id field from a courtlistener_search_financial_disclosures result. |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
| kind | No | 'full' returns the requested category rows; 'outline' lists each category as a retrievable section (by byte size) when the itemization overflows the inline budget. Filing metadata and counts are present either way. |
| year | No | Filing year. |
| debts | No | Debts and liabilities. |
| error | No | Present when the call failed. Absent on success. |
| gifts | No | Reported gifts. |
| counts | No | Count of line items in each disclosure category. |
| pdf_url | No | URL to the source disclosure PDF; null if unavailable. |
| sections | No | Retrievable categories, largest first — pass names to `categories` on a re-call. |
| person_id | No | Person ID of the filer — pass to courtlistener_get_judge; null if absent. |
| positions | No | Outside positions. |
| agreements | No | Continuing agreements. |
| is_amended | No | True if this filing is an amendment. |
| page_count | No | Page count of the source filing; null if not recorded. |
| investments | No | Investment holdings. |
| report_type | No | Report type (Nomination, Initial, Annual, Final, or Unknown). |
| disclosure_id | No | Financial disclosure ID. |
| reimbursements | No | Reimbursements. |
| spouse_incomes | No | Spouse income sources. |
| retrieval_notice | No | How to re-call the tool for specific categories when the itemization overflows. |
| has_been_extracted | No | True if line items were parsed from the PDF; category arrays are empty when false. |
| non_investment_incomes | No | Non-investment income sources. |
TDQS
A4.5/5.0
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover readOnly and idempotent hints, but the description adds valuable behavior beyond those: coded value/income columns are decoded to readable dollar ranges, and the outline-vs-full response mechanism when too large. This goes beyond the minimal safety profile and explains output behavior, though it does not mention potential errors or rate limits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is moderately long but every sentence delivers value: purpose, sibling differentiation, category selection, decoding, overflow behavior, and ID sourcing. It is front-loaded with the main action and efficiently organized. Slightly verbose but not padded; the length is justified by the tool's complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (multiple categories, overflow handling, decoding), the description is quite complete. It explains the response structure when full and when outlined, and it covers how to retrieve missing sections. An output schema exists and covers return details, so the description does not need to duplicate that. Minor gaps like error handling or pagination are not critical for a read-only fetch tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description enhances both parameters: it explains that categories selects specific categories or acts as a re-call selector after an outline response, and it clarifies that disclosure_id comes from the search tool's field. These details go beyond the schema's brief descriptions, adding practical usage context.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description starts with a specific verb and resource: 'Fetch a single judicial financial disclosure by ID with its parsed line-item rows.' It enumerates the exact categories (investments, debts, positions, reimbursements, non-investment and spouse income, agreements, gifts). It explicitly differentiates from the sibling courtlistener_search_financial_disclosures by noting it returns only category counts, making the distinction unmistakable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides clear when-to-use guidance: 'This is the itemized companion to courtlistener_search_financial_disclosures (which returns only category counts).' It also instructs how to obtain IDs ('Obtain disclosure IDs from courtlistener_search_financial_disclosures') and how to handle oversized responses via re-calls with categories. This is explicit and actionable.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
courtlistener_get_judgeGet Judge ProfileARead-onlyIdempotentInspect
Fetch full biographical profile for a single judge: positions on record — judicial appointments across all courts plus non-judicial roles — education, political affiliations, and ABA ratings. The position list is paginated upstream and walked under a page bound; the response reports whether it was truncated. Obtain person IDs from courtlistener_search_judges results.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| person_id | Yes | Judge person ID from a search result's person_id field. Identifies a specific judge across all courts they have served on. |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
| dob | No | Date of birth as CourtListener stores it, always full ISO 8601 — but the month and day are placeholders unless dob_granularity is "day". Read dob_granularity before presenting this as an exact date. Null if not recorded. |
| dod | No | Date of death as CourtListener stores it, always full ISO 8601 — precision qualified by dod_granularity, as with dob. Null if living or not recorded. |
| name | No | Full name. |
| error | No | Present when the call failed. Absent on success. |
| fjc_id | No | Federal Judicial Center ID for cross-referencing with FJC data; null if not available. |
| gender | No | Gender. |
| notice | No | Present only when positions[] was truncated: what was withheld. |
| dob_city | No | City of birth; null if not recorded. |
| dob_state | No | State of birth; null if not recorded. |
| education | No | Educational history. |
| person_id | No | Person ID. |
| positions | No | Positions on record, across all courts — judicial appointments plus non-judicial roles (private practice, prosecutor, professor), which carry no court and describe themselves in job_title. CourtListener paginates this list and the walk is bounded, so read the truncated flag before treating it as a complete career. |
| truncated | No | True when the bounded /positions/ page walk stopped with pages outstanding — positions[] is then a prefix of the person's record, not the whole of it. False when the walk reached the end. |
| aba_ratings | No | ABA qualification ratings, expanded to readable labels (e.g., "Well Qualified"). |
| positionsShown | No | Number of position records returned. |
| dob_granularity | No | Precision actually recorded for dob: "year", "month", or "day". Null when CourtListener recorded no precision. An unrecognized upstream value passes through unchanged. |
| dod_granularity | No | Precision actually recorded for dod: "year", "month", or "day". Null when CourtListener recorded no precision. |
| political_affiliations | No | Political affiliation history. |
TDQS
A4.1/5.0
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and idempotentHint=true, so the safety profile is covered. The description adds valuable behavioral context beyond annotations: the position list is paginated upstream and walked under a page bound, and the response reports truncation. This gives the agent awareness of pagination and response completeness without contradicting any annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences, with the core purpose front-loaded. The pagination note and input-sourcing guidance are relevant and not wasteful. It could be slightly tighter (e.g., 'upstream' and 'walked' are somewhat jargon-heavy), but the structure is efficient and logical.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that an output schema exists, the description does not need to explain return values. It covers the tool's scope, pagination behavior, truncation reporting, and input source. For a read-only single-resource lookup that already has annotations and a full output schema, this is nearly complete; a small gap is the lack of any error-handling notes, but that is minor.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides a thorough description of person_id (source, meaning, and scope across courts), so schema coverage is 100%. The description's mention of obtaining IDs from search results reinforces the same information but adds little semantic value beyond the schema's explicit documentation. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Fetch full biographical profile for a single judge' and enumerates the specific content areas (positions, education, political affiliations, ABA ratings). This precise verb-resource pairing distinguishes it from siblings like get_opinion or get_docket, and it explicitly ties to the search tool for input.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context on how to obtain the required person_id ('Obtain person IDs from courtlistener_search_judges results') and mentions the pagination handling behavior. It implies the appropriate workflow (search first, then get), though it does not explicitly state when not to use this tool versus alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
courtlistener_get_opinionGet Court OpinionARead-onlyIdempotentInspect
Fetch the full text and metadata for a single opinion cluster by cluster ID. A cluster groups all opinions filed in a case — majority, concurrence, dissent, and per curiam. Returns the cluster metadata (case name, court, citations, dates) plus every opinion variant with HTML and plain text. When the combined opinion text is too large to inline, the response lists each variant as a retrievable section (opinion_) while keeping the cheap cluster metadata — re-call with sections:[...] to pull specific variants in full. Obtain cluster IDs from courtlistener_search_opinions, courtlistener_lookup_citation, or docket results.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| sections | No | Opinion variant identifiers to retrieve in full, from a prior outline response (e.g. ["opinion_12345"]). Omit to return all variants, or an outline if they overflow the inline byte budget. | |
| cluster_id | Yes | Opinion cluster ID — identifies a case decision and groups all opinion variants (majority, concurrence, dissent). Obtain from courtlistener_search_opinions, courtlistener_lookup_citation, or from docket results that link to opinions. |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
| kind | No | 'full' returns the opinion variants (all, or a selected subset); 'outline' lists each variant as a retrievable section (opinion_<id>) when the opinions overflow the inline byte budget. Cluster metadata is present either way. |
| court | No | Court display name. |
| error | No | Present when the call failed. Absent on success. |
| judges | No | Judge names. |
| posture | No | Procedural posture (may be empty). |
| court_id | No | Court identifier. |
| opinions | No | All opinion variants within this cluster. Present in full mode; omitted in outline mode — re-call with sections:["opinion_<id>"] to retrieve specific variants. |
| sections | No | Retrievable opinion variants, largest first — pass names to `sections` on a re-call. |
| syllabus | No | Syllabus text (may be empty). |
| case_name | No | Short case name. |
| citations | No | All known citation strings for this case. |
| docket_id | No | Associated docket ID. |
| cite_count | No | Total number of citations from other opinions. |
| cluster_id | No | Opinion cluster ID. |
| date_filed | No | Date the opinion was filed. |
| docket_number | No | Docket number. |
| case_name_full | No | Full case name with parties. |
| retrieval_notice | No | How to re-call the tool for specific opinion variants when the opinions overflow. |
| precedential_status | No | Publication/precedential status. |
TDQS
A4.9/5.0
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnlyHint and idempotentHint annotations, the description discloses key behavioral nuances: the outline response when inline budget is exceeded, the re-call with sections to fetch full variants, and the distinction between cluster metadata and opinion variants. No contradiction with annotations; the readOnlyHint aligns with 'Fetch'.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-organized paragraph that front-loads the core purpose, then explains the outline behavior and how to obtain IDs. Every sentence adds functional value, and the structure makes it easy to scan.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has an output schema, so return values are already covered. The description covers all necessary call patterns (full fetch vs. outlined vs. selective retrieval), parameter usage, and how to find the required ID. Nothing essential is missing for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so baseline is 3. The description adds value by explaining cluster_id's grouping semantics (majority, concurrence, dissent) and clarifying sections as variant identifiers from a prior outline response, with an example. This enriches understanding beyond the schema's own descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb (Fetch) and resource (full text and metadata for a single opinion cluster by cluster ID), and distinguishes it from sibling tools like courtlistener_search_opinions and courtlistener_lookup_citation. It explains what a cluster groups, making the tool's scope precise.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly instructs how to obtain cluster IDs via courtlistener_search_opinions, courtlistener_lookup_citation, or docket results. Also explains when to use the sections parameter (when the complete text is too large) and how to retrieve specific variants, covering both primary and secondary usage patterns.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
courtlistener_get_oral_argumentGet Oral ArgumentARead-onlyIdempotentInspect
Fetch the full detail record for a single oral argument audio recording by its ID (the audio_id from courtlistener_search_oral_arguments). Returns the case name, panel judge IDs, duration, MP3 download URL, linked docket, and the speech-to-text transcript when transcription has completed. A long transcript is withheld and listed as a retrievable section instead; re-call with sections:["transcript"] to pull it. Every other field is present either way. The argument date is not on this record — it comes from the search result or the linked docket.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Audio recording ID — the audio_id field from a courtlistener_search_oral_arguments result. | |
| sections | No | Section identifiers to retrieve, from a prior outline response — ["transcript"] is the only one that adds anything, since every other field is returned regardless. A selection that omits "transcript" therefore returns the record without it. Omit this argument entirely for the whole record, or the record minus an oversized transcript. |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
| kind | No | 'full' carries the transcript inline; 'outline' withholds it and lists it as a retrievable section because it overflows the inline byte budget. Every other field of the record is present either way. |
| error | No | Present when the call failed. Absent on success. |
| judges | No | Free-text judge names; often empty on this endpoint. |
| sections | No | Sections withheld from this response — only ever `transcript`; pass its name to `sections` on a re-call. Absent when nothing was withheld. |
| case_name | No | Case name. |
| docket_id | No | Associated docket ID; 0 if not linked. |
| panel_ids | No | Person IDs of panel judges — pass to courtlistener_get_judge. |
| transcript | No | Speech-to-text transcript; empty string if transcription has not completed. The only field an outline response withholds — re-call with sections:["transcript"] to retrieve it. |
| download_url | No | Direct MP3 download URL; null if not available. |
| case_name_full | No | Full case name with parties. |
| has_transcript | No | True if a speech-to-text transcript is available. |
| duration_seconds | No | Recording duration in seconds. |
| oral_argument_id | No | Audio recording ID. |
| retrieval_notice | No | How to re-call the tool for the transcript when it overflows the inline budget. |
TDQS
A4.4/5.0
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare read-only and idempotent, and the description builds on that by disclosing exactly what is returned (case name, judge IDs, duration, MP3 URL, docket, transcript) and the conditional behavior for long transcripts (withheld and retrievable via sections). It also explicitly notes a field that is NOT on this record (argument date), which prevents the agent from expecting it. This is rich behavioral context beyond the annotations, with no contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is longer than typical but every sentence contributes value: the purpose is front-loaded, then the returned fields are listed, then the sections behavior is explained, and finally the date absence is noted. It is structured and efficient, though the sections explanation could be slightly more compact. Still, it is not verbose or redundant; it earns its length.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (two parameters, one optional with subtle behavior) and the presence of an output schema (which defines the return shape), the description covers all necessary operational details: how to obtain the ID, how to handle oversized transcripts, and what fields are and are not present. The agent has everything needed to call the tool correctly, and the annotations cover safety.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema covers both parameters fully: 'id' is described as the audio_id from a search result, and 'sections' is described with its exact behavior (including that only 'transcript' adds anything and that omitting it returns the record without it). With 100% schema coverage, the description adds little beyond restating the same semantics. Baseline of 3 is appropriate; the description does not introduce any additional parameter meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description begins with a specific verb ('Fetch'), a clear resource ('full detail record for a single oral argument audio recording'), and the lookup mechanism (by its ID). It also distinguishes this from related tools by specifying the source of the ID (courtlistener_search_oral_arguments) and by listing the unique fields it returns (transcript, sections behavior). This makes the tool's role unambiguous relative to the sibling get/search tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use the tool: it requires an audio_id obtained from a prior search, and it explains that the argument date is not present here but must come from the search result or linked docket. It does not explicitly enumerate sibling alternatives or state 'do not use for X', but the context is sufficient for an agent to know this is the single-record fetcher for oral arguments and that sections can be used to pull oversized transcripts. Lacks an explicit when-not-to-use, hence 4 rather than 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
courtlistener_get_partiesGet PartiesARead-onlyIdempotentInspect
Fetch all parties and attorneys of record for a RECAP federal docket by docket ID. Returns each party's name, role (Plaintiff, Defendant, Petitioner, Respondent, etc.), and their attorneys with contact information, scoped to this docket. Costs two upstream requests per call (parties + attorney lookup) against a rate-limited free tier, and one more for each extra page of a large attorney roster. Obtain docket IDs from courtlistener_search_dockets or courtlistener_get_docket.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| cursor | No | Pagination cursor from a previous response's next_cursor field. Omit for the first page. This is an opaque token, not a page number — CourtListener cursor-paginates this endpoint, so a numeric value selects nothing and re-serves the first page. | |
| docket_id | Yes | Docket ID from a courtlistener_search_dockets or courtlistener_get_docket result's docket_id field. | |
| page_size | No | Requested number of parties per page (1–10). CourtListener paginates this endpoint at a fixed size and does not honor the requested value, so a page can come back larger than asked for. |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
| error | No | Present when the call failed. Absent on success. |
| parties | No | Parties on this page. |
| docket_id | No | Docket ID these parties belong to. |
| totalCount | No | Total parties on this docket across all pages — this endpoint reports its count as a URL rather than a number, so the total is only derivable when the first page is also the last, and is absent for any list spanning more than one page. |
| next_cursor | No | Opaque pagination cursor for the next page — pass it back as the `cursor` argument; null when this is the last page. |
| total_parties | No | Total parties on this docket across all pages; null when no total is derivable — CourtListener serves the count as a URL rather than a number here, so it is only known when the first page is also the last. |
TDQS
A4.4/5.0
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint=true and idempotentHint=true, and the description adds crucial behavioral context beyond that: it discloses the upstream request cost (two per call plus one per extra page) and the rate-limited free tier, which significantly affects invocation decisions. This is exactly the type of supplementary information that helps an agent plan calls. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences: the first states the purpose, the second covers costs and rate limits, the third points to sources. It is front-loaded with the core action and includes only high-value operational details. Slightly dense but efficient; could be tightened without losing substance, hence a 4.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has an output schema that defines return values, so the lack of return format in the description is acceptable. The description covers the input source, scope, cost, and rate limiting, and the schema covers pagination and parameter constraints. For a relatively straightforward fetch-with-pagination tool, nothing essential is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% parameter description coverage, so each parameter already has clear semantics (cursor is opaque, page_size is a request not honored, docket_id source). The description only reinforces the docket_id source and adds the cost implication of extra pages, which is not directly tied to parameter meaning. Since the schema carries the weight, a baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Fetch'), a resource ('parties and attorneys of record'), a scope (RECAP federal docket by docket ID), and the expected content (name, role, attorneys with contact info). It clearly distinguishes from sibling tools like courtlistener_get_docket by focusing solely on parties/attorneys. No ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly tells the agent where to obtain docket IDs ('Obtain docket IDs from courtlistener_search_dockets or courtlistener_get_docket'), which is a clear prerequisite. However, it does not directly contrast with alternatives (e.g., when to use this vs a search for parties), though the sibling names make the intent obvious. Usage context is strong but not fully explicit about alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
courtlistener_lookup_citationLookup Legal CitationARead-onlyIdempotentInspect
Resolve legal citations (e.g., "410 U.S. 113", "93 S. Ct. 705") to opinion cluster IDs and case metadata. Enables workflows that start from a known citation rather than a search query. CourtListener extracts every citation it finds in the submitted text, so passing a passage returns one entry per citation, each with its own resolution status — an unresolved or ambiguous citation is reported in the results, not raised as an error. Supports standard US reporter formats. Costs one request against CourtListener's per-citation quota, plus one ordinary request per distinct docket whose court is resolved — max_court_lookups bounds that second half (default 4, set 0 to skip court resolution entirely). CourtListener meters this endpoint by citations submitted rather than by call, so a long passage spends proportionally more of that quota. Requires authentication — uses the CourtListener /citation-lookup/ endpoint.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| citation | Yes | Text to extract citations from — normally a single citation (e.g., "410 U.S. 113", "347 U.S. 483", "93 S. Ct. 705"), but any passage works and every citation in it is resolved. Supports standard reporter formats. Up to 64000 characters, which is CourtListener's own ceiling; a longer passage is rejected here rather than spending a request to be refused upstream. | |
| max_court_lookups | No | How many distinct dockets this call may spend a request on to resolve cluster courts. The lookup itself is metered separately by CourtListener (per citation submitted), so this budget is drawn entirely from the ordinary per-request allowance — published free tier 5/min, 50/hour, 125/day, varying by token tier. 0 skips court resolution and costs nothing beyond the lookup; 20 is the ceiling. Clusters past the budget come back with court null and court_resolution "over_budget". |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
| error | No | Present when the call failed. Absent on success. |
| notice | No | Caveats on this result: a recovery hint when no citation in the input resolved to a case, and counts of the clusters whose court went unresolved — split by whether the per-call docket budget ran out or an attempted lookup returned nothing, since only the first is worth retrying with a larger budget. Absent when none applies. |
| matches | No | One entry per citation CourtListener extracted from the input, in the order they appear. |
| queriedCitation | No | The citation string that was looked up. |
TDQS
A4.7/5.0
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint and idempotentHint, but the description adds crucial behavioral details beyond these: it extracts every citation in the text, returns one entry per citation with individual resolution status, reports unresolved citations instead of raising errors, and explains the quota mechanics with 'over_budget' outcomes. This is substantial value and fully consistent with the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is detailed but every sentence contributes: purpose, extraction behavior, error handling, cost structure, and authentication are all covered without redundancy. It is front-loaded with the core purpose and then expands into operational details. Slightly long but appropriate for the tool's complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity—authentication, quota metering, multiple citation extraction, and over_budget behavior—and the presence of an output schema, the description covers all necessary operational aspects. An agent can correctly call this tool including handling edge cases like long passages and budget limits.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already documents both parameters well. The description goes further: for 'citation' it explains the extraction behavior and 64k character limit (rejected here to avoid wasted requests); for 'max_court_lookups' it specifies that the budget comes from the per-request allowance and how 'over_budget' is returned. This adds meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Resolve' with resource 'legal citations' to 'opinion cluster IDs and case metadata', and provides concrete examples. It clearly distinguishes from search and get operations by framing the use case: 'Enables workflows that start from a known citation rather than a search query.' This is unambiguous and differentiates from siblings like search_opinions or get_citations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly states the primary use case (starting from a known citation) and adds important operational context: authentication requirement, per-citation quota, and max_court_lookups budget. It implies this is for citation-driven workflows, but does not name alternative tools or explicitly state when not to use it. Still, the guidance is clear enough for an agent to decide.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
courtlistener_lookup_courtsLookup CourtsARead-onlyInspect
List courts with optional filtering by jurisdiction type, active/inactive status, and scraper coverage. Primarily used to discover court IDs for use in search and filter parameters across all other courtlistener tools. Defaults to the active bench — the courts CourtListener still scrapes; pass status:'inactive' for historical courts or status:'any' for every court. A bundled snapshot returns the complete list of matching court IDs without paging whenever the filtered set fits the response budget, which covers the default bench and every jurisdiction filter. Full court records — names, citation strings, scraper status — come live from CourtListener at a fixed 20 rows per page, so pull those only when a court ID alone is not enough.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Page number (1-indexed). CourtListener serves /courts/ at a fixed 20 rows per page and ignores any requested page size, so the number of pages is the enrichment totalCount divided by 20 — there is no way to pull a larger page. Pass the next_cursor from a previous response here to walk them one call at a time. | |
| status | No | Which bench to return. 'active' (default) returns only courts CourtListener currently scrapes; 'inactive' returns only the historical and defunct courts it no longer scrapes; 'any' returns both. The two filtered sets are disjoint, so 'any' is the only value that reaches the whole list — but reaching all of it means paging, one call per 20 courts, and the inactive bench is several times larger than the active one. Prefer the narrowest value that answers the question, and narrow with jurisdiction rather than paging the full list. | active |
| jurisdiction | No | Jurisdiction type — CourtListener's own court classification, one code per court: F=Federal Appellate, FD=Federal District, FB=Federal Bankruptcy, FBP=Federal Bankruptcy Panel, FS=Federal Special, S=State Supreme, SA=State Appellate, ST=State Trial, SS=State Special, SAG=State Attorney General, TRS=Tribal Supreme, TRA=Tribal Appellate, TRT=Tribal Trial, TRX=Tribal Special, TS=Territory Supreme, TA=Territory Appellate, TT=Territory Trial, TSP=Territory Special, MA=Military Appellate, MT=Military Trial, C=Committee, I=International. Omit to list all. SCOTUS and the numbered circuits are F; USITC and FISC are FS. Upstream's Testing code is not offered here: /courts/ excludes testing courts from every response, so a filter on it can only ever return nothing. Accepted but matching no court as of the 2026-07-30 snapshot: TSP, MT. Courts whose stored jurisdiction is not one of these codes (njcirctsussex, ohctapp1) are unreachable through this filter at any value — the value they store is not one the filter accepts. Pass those ids straight to the tool that needs them, or list with no jurisdiction filter. | |
| has_opinion_scraper | No | Filter to courts with active opinion scraping. Useful when planning search queries — courts without scrapers have sparse coverage. |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
| page | No | Current page number (1-indexed). |
| error | No | Present when the call failed. Absent on success. |
| courts | No | Matching courts on this page. |
| notice | No | Recovery hint when no courts match the applied filters. |
| totalCount | No | Total courts returned. |
| next_cursor | No | Next page number to pass as the `page` argument (this list is page-paginated at a fixed 20 rows/page); null when this is the last page — a non-null value means the courts shown are a partial view of the filtered set. |
| all_matching_court_ids | No | Every court id matching the same filters, from a snapshot of /courts/ bundled with this server (taken 2026-07-30) — the complete set, not just this page, and free of any request. Paging `courts` is only needed for the fields a court id alone does not carry (full_name, citation_string, scraper flags). Empty when more than 1000 courts match, since a prefix of the set would be indistinguishable from the whole of it — check all_matching_court_ids_complete before reading emptiness as "no courts match". A court added or retired upstream since the snapshot date appears in `courts` but may be missing here. |
| all_matching_court_ids_complete | No | True when all_matching_court_ids holds every matching court id. False when more than 1000 courts match: the list is withheld whole rather than truncated, and the notice gives the count and how to narrow. |
TDQS
A4.9/5.0
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already convey read-only and open-world, but the description adds critical behavioral details: the snapshot vs. live data distinction, the fixed 20-row paging, the exclusion of testing courts from every response, and the unreachable jurisdiction codes. It even notes that filtered sets are disjoint. This far exceeds the minimal annotation coverage.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is detailed but not wasteful; each sentence contributes operational insight (snapshot behavior, paging, exclusions). It is slightly long but front-loads the core purpose and groups related details logically. A minor trim could improve scanability, but it earns its length given the tool's complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the output schema exists and the tool has 4 parameters with two enums, the description covers all essential operational aspects: how to navigate paging, the snapshot vs. live trade-off, jurisdictional gaps, and upstream exclusions. Nothing an agent needs to call it correctly is omitted.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Although schema coverage is 100%, the description adds substantial meaning: clarifies the enum values for jurisdiction with real-world examples (SCOTUS and numbered circuits are F), explains page semantics (fixed 20 rows, next_cursor usage), and describes how the snapshot avoids paging for most filters. The description genuinely complements the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('List') and resource ('courts') with clear filtering dimensions (jurisdiction, status, scraper coverage). It explicitly positions the tool as the discovery mechanism for court IDs across sibling tools, distinguishing it from the search/get siblings. No ambiguity about what it does.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit guidance: defaults to active bench, how to get inactive/any, and the strategic advice 'Prefer the narrowest value that answers the question, and narrow with jurisdiction rather than paging the full list.' Also distinguishes when to rely on the snapshot vs. full records ('pull those only when a court ID alone is not enough'), effectively routing to alternative tools when needed.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
courtlistener_search_docketsSearch Federal Court DocketsARead-onlyInspect
Search RECAP federal court dockets. Query terms match case name, docket number, party, and attorney names; filters narrow by party name, court, and filing date. RECAP is a crowd-sourced mirror of PACER (the federal court filing system) — coverage varies by court and date. Returns docket metadata with the parties, attorneys, and firms of record, plus up to 3 sample document entries per docket. Use courtlistener_lookup_courts to find court IDs.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| q | Yes | Query terms matched against case name, docket number, party names, and attorney names. Example: "Apple Inc patent infringement". | |
| court | No | Filter to a specific federal court ID (e.g., "dnd", "cacd", "deb" for Delaware Bankruptcy). Use courtlistener_lookup_courts to find court IDs. | |
| cursor | No | Pagination cursor from a previous response's next_cursor field. | |
| page_size | No | Number of results to request (default 20). CourtListener search enforces a minimum of 20 results per page regardless of the value passed — you will always receive at least 20 results. | |
| party_name | No | Filter to dockets listing a specific party by name — applied in addition to (AND with) the q query. More precise than including party names in q when the party name is known. | |
| filed_after | No | Earliest case filing date (ISO 8601). | |
| filed_before | No | Latest case filing date (ISO 8601). |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
| error | No | Present when the call failed. Absent on success. |
| notice | No | Recovery hint when results are empty — echoes filters and suggests how to broaden. |
| results | No | Matching docket records. |
| totalCount | No | Total matching dockets. |
| next_cursor | No | Pagination cursor for the next page; null when no more results. |
| coverage_note | No | Note about RECAP coverage limitations. |
TDQS
A4.3/5.0
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so the agent knows this is a safe read operation. The description adds valuable behavioral context beyond that: it explains the data source (crowd-sourced mirror of PACER) and its implications (coverage varies by court and date), which warns the agent about potential gaps in results. It also states the return structure (docket metadata with parties, attorneys, firms, plus up to 3 sample documents), giving the agent a clear picture of output format. This goes beyond what annotations tell us and does not contradict them.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences, with no wasted words. The first sentence states the core purpose and scope, the second explains the data source and its variability, and the third describes the return content and points to a related tool. Every sentence carries essential information, and the structure front-loads the primary action. It is an exemplar of concise, well-organized documentation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a search tool with 7 parameters, an output schema, and annotations covering the safety profile, the description covers all critical context: what is searched, how queries and filters work, data source caveats (coverage varies), return content (parties, attorneys, firms, sample documents), and a pointer to find court IDs. The mention of pagination is implied by the cursor param and the output schema presumably handles it. Given the annotations already declare read-only, the description provides a complete picture for correct invocation and result interpretation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% — every parameter has its own description. The description adds extra meaning: it clarifies that q matches case name, docket number, party, and attorney names, which is more specific than the schema's generic 'Query terms matched against...'. It also provides a usage tip for party_name ('More precise than including party names in q when the party name is known'), which is practical guidance beyond the schema. These enhancements justify a score above the baseline 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states the specific verb 'Search' and resource 'RECAP federal court dockets', and enumerates what query terms match (case name, docket number, party, attorney names). This clearly distinguishes it from sibling search tools like courtlistener_search_opinions or courtlistener_search_oral_arguments, which target different record types. No ambiguity remains about what this tool does.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides context about RECAP being a crowd-sourced mirror with variable coverage, which informs interpretation of results. It also directs users to courtlistener_lookup_courts for court IDs. However, it does not explicitly state when to choose this tool over alternatives (e.g., search_opinions for opinions, or get_docket for a known docket ID). The usage guidance is implicit rather than explicit, and no exclusions are mentioned, so it is adequate but not thorough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
courtlistener_search_financial_disclosuresSearch Financial DisclosuresARead-onlyInspect
Search federal judicial financial disclosure filings — the annual reports judges file on investments, gifts, debts, outside positions, and income. Filter by judge (person ID from courtlistener_search_judges) and/or filing year; the year filter is applied to the fetched page only (CourtListener has no server-side year filter), so page through with cursor to reach a judge's filings for a year that fall on later pages. Returns per-filing metadata, category counts, itemized gifts, and a link to the source PDF. Line-item investments (often hundreds per filing, with coded values) are summarized as counts; the linked PDF carries the full itemization. Use this for judicial-ethics and recusal research after identifying a judge's person ID.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| year | No | Filing year to filter by (e.g., 2022). Applied client-side to the fetched page only — CourtListener rejects a server-side year param, so filings for this year on later pages are not included. When a page has no match for the year but more pages remain, next_cursor is returned; pass it as cursor to check the next page. Omit to return all years on the page. | |
| cursor | No | Pagination cursor from a previous response's next_cursor field. | |
| judge_id | No | Person ID of the judge whose disclosures to return — obtain from courtlistener_search_judges (the person_id field). Omit to browse across all filers. | |
| page_size | No | Number of filings to request (default 20). CourtListener enforces a minimum of 20 results per page regardless of the value passed — you will always receive at least 20 filings. |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
| error | No | Present when the call failed. Absent on success. |
| notice | No | Recovery hint when no filings are found — echoes filters and suggests next steps. |
| results | No | Matching financial disclosure filings. |
| totalCount | No | Total matching disclosure filings — present only when the API reports a numeric count (this endpoint returns it as a URL by default, so it is usually absent). |
| next_cursor | No | Pagination cursor for the next page; null when no more results. |
TDQS
A4.4/5.0
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations (readOnlyHint, openWorldHint), the description discloses genuine behavioral gotchas: the year filter is applied client-side only because CourtListener has no server-side year param, requiring cursor paging across pages; that line-item investments are deliberately summarized as counts with full itemization deferred to the linked PDF; and the return shape (metadata, category counts, itemized gifts, source PDF link). This is additive, accurate context that materially changes how an agent should drive the tool. No contradiction with the read-only annotation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with purpose, then moves through filtering, return format, the summarization limitation, and use case in logical order. It is longer than average, but every sentence carries load-bearing information (pagination caveat, investment-summary asymmetry, prerequisite person ID) rather than filler. The structure earns its length given the tool's complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with pagination pitfalls and an output asymmetry (investments summarized vs gifts itemized), the description is strikingly complete: it covers what it returns, how filtering behaves, the cursor-paging workflow, and the prerequisite of a judge person ID. An output schema exists, and the description complements rather than duplicates it. Nothing an agent needs to invoke this correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all four parameters in detail, including the client-side year-filter caveat and the page_size minimum of 20. The description reinforces the judge_id source (courtlistener_search_judges) and the year-filter behavior, but adds little net meaning beyond what the schema already carries — the schema does the heavy lifting here, so a baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The opening sentence states a specific verb and resource — "Search federal judicial financial disclosure filings" — with an enumeration of the content (investments, gifts, debts, outside positions, income) that makes its subject unmistakable. It distinguishes itself from the sibling courtlistener_get_financial_disclosure by being the search/filter variant, and adds a cross-reference to courtlistener_search_judges. Nothing about its purpose is left ambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives concrete usage direction: filter by judge (explicitly sourcing person ID from courtlistener_search_judges) and/or filing year, and states the intended context — "judicial-ethics and recusal research after identifying a judge's person ID." It also warns about the pagination consequence of the client-side year filter. It stops short of explicitly naming get_financial_disclosure as the single-filing alternative or stating when NOT to use it, so it lacks an explicit exclusion clause.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
courtlistener_search_judgesSearch JudgesARead-onlyInspect
Search judge/person records by name, appointing president, court, political affiliation, or demographic. Returns biographical data, current position, and appointment summary. Use courtlistener_get_judge for full appointment history and education records.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| q | Yes | Search query — judge name, court, city, or relevant keywords. | |
| court | No | Filter to judges who have held a position at this court (e.g., "scotus", "ca9"). Use court_id strings from courtlistener_lookup_courts. | |
| cursor | No | Pagination cursor from a previous response's next_cursor field. | |
| appointer | No | Filter by appointing president's last name (e.g., "Obama", "Trump", "Biden"). Matches against the appointer field in position records. | |
| page_size | No | Number of results to request (default 20). CourtListener search enforces a minimum of 20 results per page regardless of the value passed. | |
| political_affiliation | No | Filter by political affiliation: d=Democrat, r=Republican, i=Independent, l=Libertarian, g=Green Party, u=Unknown/unconfirmed. Based on party of the appointing president or election affiliation. |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
| error | No | Present when the call failed. Absent on success. |
| notice | No | Recovery hint when results are empty — echoes filters and suggests how to broaden. |
| results | No | Matching judge records. |
| totalCount | No | Total matching judge records. |
| next_cursor | No | Pagination cursor for the next page; null when no more results. |
TDQS
A4.5/5.0
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, covering the read-only nature and open-world expectation. The description adds value by specifying the output content (biographical data, current position, appointment summary) and implies that search results are summarized rather than exhaustive, which is useful behavioral context. It does not contradict the annotations, and given the annotation coverage, the added detail earns a 4.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two concise sentences with no filler. The first sentence front-loads the primary purpose and filter capabilities, the second states return content and the alternative tool. Every sentence earns its place, and the structure is optimally scannable for an agent.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has a rich output schema (indicated by 'Has output schema: true'), so return details are already structured. Annotations cover read-only and open-world behavior. The description covers the search scope, filter dimensions, return summary, and when to use the sibling tool. There is no missing information an agent needs to invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%: every parameter (q, court, cursor, appointer, page_size, political_affiliation) has a thorough description in the input schema, including enums and defaults. The tool description adds nothing about parameters beyond what the schema already documents, so the baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Search') and a clear resource ('judge/person records'), enumerating the filter dimensions (name, appointing president, court, political affiliation, demographic). It explicitly distinguishes from the sibling courtlistener_get_judge by noting that the latter provides 'full appointment history and education records,' so an agent can immediately tell which tool to use for which goal.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit usage context: it says what this tool returns ('biographical data, current position, and appointment summary') and explicitly points to an alternative ('Use courtlistener_get_judge for full appointment history and education records'). This tells the agent when to choose this search over the getter, providing both when-to-use and when-to-prefer-alternative guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
courtlistener_search_opinionsSearch Court OpinionsARead-onlyInspect
Full-text search across 9M+ written US court opinions with field-level filtering. Returns opinion cluster summaries with case metadata, citations, matched text snippets, and the individual opinion variants filed in each case. Supports CourtListener field syntax (caseName:"roe v wade", court_id:scotus, judge:"Alito") and boolean operators (AND, OR, NOT). Use courtlistener_lookup_courts to find court IDs. CourtListener publishes free-tier limits of 5 req/min, 50/hr, 125/day; actual limits vary by token tier.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| q | Yes | Full-text query. Supports field syntax (caseName:"roe v wade", court_id:scotus, judge:"Alito") and boolean operators (AND, OR, NOT). Use plain English for semantic-style queries or legal citations. | |
| court | No | Filter to a specific court by court ID (e.g., "scotus", "ca9", "nyed"). Use courtlistener_lookup_courts to find court IDs. | |
| cursor | No | Pagination cursor from a previous response's next_cursor field. Omit for the first page. | |
| status | No | Opinion publication status. "Published": precedential. "Unpublished": not citable as precedent in most jurisdictions. "Errata": corrections. "Separate": separate opinion filed outside main cluster. "In-chambers": single-justice order. "Relating-to": companion or related-case order. Omit to search all statuses. | |
| order_by | No | Result ordering. "score desc" (default) ranks by relevance. "citeCount desc" surfaces most-cited opinions first. | score desc |
| page_size | No | Number of results to request (default 20). CourtListener search enforces a minimum of 20 results per page regardless of the value passed — you will always receive at least 20 results. Each search costs one request against the rate limit. | |
| filed_after | No | Earliest filing date (ISO 8601, e.g., "2020-01-01"). Narrows search to opinions filed on or after this date. | |
| filed_before | No | Latest filing date (ISO 8601). Narrows search to opinions filed before or on this date. |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
| error | No | Present when the call failed. Absent on success. |
| notice | No | Recovery hint when results are empty — echoes filters and suggests how to broaden. |
| results | No | Matching opinion cluster summaries. |
| totalCount | No | Total matching opinions in the corpus. |
| next_cursor | No | Pagination cursor for the next page; null when no more results. |
| effectiveQuery | No | Query terms sent to CourtListener. |
TDQS
A4.5/5.0
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, so the description's additional disclosure of rate limits (5 req/min, 50/hr, 125/day), the page_size quirk (always returns at least 20 regardless of passed value), and the cost of one request per search adds meaningful behavioral context beyond the annotations. No contradiction is present.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences that front-load the core purpose, then the return contents, then field syntax and rate limits. Every sentence contributes essential information with no filler. It is compact yet highly informative.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With an output schema present, the description need not explain return values. It covers the tool's function, usage syntax, required cooperation with courtlistener_lookup_courts, and important operational constraints (rate limits, pagination behavior). An agent has everything it needs to invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description repeats some field syntax and court ID guidance already in the schema, but it does add the note about page_size always returning at least 20 results, which is valuable. However, this detail is also in the schema itself, so the description adds little beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Full-text search'), a precise resource ('9M+ written US court opinions'), and the scope of results ('opinion cluster summaries with case metadata, citations, matched text snippets, and the individual opinion variants'). It clearly distinguishes from sibling search tools (e.g., search_dockets, search_judges) by naming 'opinions' explicitly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives practical guidance: it directs users to courtlistener_lookup_courts for court IDs and documents rate limits. However, it does not explicitly state when to prefer this tool over alternatives (e.g., searching dockets vs. opinions), leaving that to the clear purpose. It covers how to use it but not when-not-to-use it relative to siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
courtlistener_search_oral_argumentsSearch Oral ArgumentsARead-onlyInspect
Search appellate oral argument audio recordings — the largest public collection of oral argument audio. Returns recording metadata with two direct MP3 links per result (download_url at the originating court, local_path for CourtListener's durable copy), panel judge IDs, and transcript snippets where available. Panel judge IDs can be passed to courtlistener_get_judge for biographical context.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| q | Yes | Query terms matched against case name and transcribed argument text (where available). | |
| court | No | Filter to a specific court (e.g., "scotus", "ca9"). | |
| cursor | No | Pagination cursor from a previous response's next_cursor field. | |
| page_size | No | Number of results to request (default 20). CourtListener search enforces a minimum of 20 results per page regardless of the value passed. | |
| argued_after | No | Earliest date the case was argued (ISO 8601) — filters by argument date, not publication date. | |
| argued_before | No | Latest date the case was argued (ISO 8601). |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
| error | No | Present when the call failed. Absent on success. |
| notice | No | Recovery hint when results are empty — echoes filters and suggests how to broaden. |
| results | No | Matching oral argument recordings. |
| totalCount | No | Total matching oral argument recordings. |
| next_cursor | No | Pagination cursor for the next page; null when no more results. |
TDQS
A3.8/5.0
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and openWorldHint, and the description does not contradict them. It adds meaningful behavioral details: the exact MP3 link fields (download_url, local_path), the panel judge IDs, and the caveat that transcript snippets are only 'where available.' It also explains the dual-link distinction (originating court vs durable CourtListener copy), giving the agent richer expectations than the annotations alone.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no waste: the first states purpose and scope, the second lists return fields and a chaining tip. The most critical information (search action, resource type) is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a search tool with an output schema and three annotations, the description covers return structure, output specifics, and a useful follow-up action. Missing pieces include explicit usage boundaries vs sibling search tools and any mention of pagination limits (though the schema param description covers the 20-per-page minimum). Given the output schema exists, this is sufficiently complete for an agent to invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description does not elaborate on any parameter specifics; it only describes the output and chaining. Since all six parameters are already well-documented in the schema (e.g., q, court, pagination, date filters), the description adds no extra semantic value beyond what is structured.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action and resource: 'Search appellate oral argument audio recordings' with a superlative ('largest public collection') and explicit return scope (MP3 links, judge IDs, transcripts). It clearly distinguishes this from sibling tools like courtlistener_get_oral_argument (retrieve specific) and other search tools (search_opinions, search_dockets) by the content type.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool compared to siblings. It does not mention search_opinions or search_dockets as alternatives, nor does it state conditions like 'use for audio recordings vs text opinions.' The only cross-tool hint is chaining judge IDs to courtlistener_get_judge, which is about post-processing output, not when to invoke this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
14 tool updates
- Changed
courtlistener_get_citations6 fields changed- changed
Input schema / $schemaPrevious value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema" - added
Input schema / additionalPropertiesAdded value: +false - changed
Output schema / $schemaPrevious value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema" - added
Output schema / anyOfAdded value: +[ + { + "not": { + "required": [ + "error" + ] + }, + "required": [ + "source_cluster_id", + "source_case_name", + "direction", + "results", + "next_cursor", + "totalCount" + ] + }, + { + "required": [ + "error" + ] + } +] - added
Output schema / properties / errorAdded value: +{ + "additionalProperties": {}, + "description": "Present when the call failed. Absent on success.", + "properties": { + "code": { + "description": "JSON-RPC error code for this failure.", + "maximum": 9007199254740991, + "minimum": -9007199254740991, + "type": "integer" + }, + "data": { + "additionalProperties": {}, + "properties": { + "reason": { + "description": "Machine-readable failure mode. Declared by this tool: `not_found`: Cluster ID does not exist in CourtListener. Both directions resolve the source cluster before searching, so a bad ID fails here rather than returning an empty network. `rate_limited`: 429 response from CourtListener. `invalid_date`: filed_after is not a valid ISO 8601 calendar date. Other values are possible when a failure originates below the handler.", + "examples": [ + "not_found", + "rate_limited", + "invalid_date" + ], + "type": "string" + }, + "recovery": { + "additionalProperties": {}, + "description": "Actionable next step for the caller.", + "properties": { + "hint": { + "type": "string" + } + }, + "required": [ + "hint" + ], + "type": "object" + }, + "retryable": { + "description": "Whether retrying may succeed.", + "type": "boolean" + } + }, + "type": "object" + }, + "message": { + "description": "Human-readable description of what went wrong.", + "type": "string" + } + }, + "required": [ + "code", + "message" + ], + "type": "object" +} - removed
Output schema / requiredRemoved value: -[ - "source_cluster_id", - "source_case_name", - "direction", - "results", - "next_cursor", - "totalCount" -]
- Changed
courtlistener_get_docket6 fields changed- changed
Input schema / $schemaPrevious value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema" - added
Input schema / additionalPropertiesAdded value: +false - changed
Output schema / $schemaPrevious value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema" - added
Output schema / anyOfAdded value: +[ + { + "not": { + "required": [ + "error" + ] + }, + "required": [ + "docket_id", + "case_name", + "case_name_full", + "court", + "court_id", + "date_filed", + "date_terminated", + "docket_number", + "pacer_case_id", + "assigned_to", + "referred_to", + "cause", + "jury_demand", + "jurisdiction_type", + "total_entries", + "entries_page", + "next_cursor", + "entries" + ] + }, + { + "required": [ + "error" + ] + } +] - added
Output schema / properties / errorAdded value: +{ + "additionalProperties": {}, + "description": "Present when the call failed. Absent on success.", + "properties": { + "code": { + "description": "JSON-RPC error code for this failure.", + "maximum": 9007199254740991, + "minimum": -9007199254740991, + "type": "integer" + }, + "data": { + "additionalProperties": {}, + "properties": { + "reason": { + "description": "Machine-readable failure mode. Declared by this tool: `not_found`: Docket ID does not exist in CourtListener. `rate_limited`: 429 response from CourtListener. Other values are possible when a failure originates below the handler.", + "examples": [ + "not_found", + "rate_limited" + ], + "type": "string" + }, + "recovery": { + "additionalProperties": {}, + "description": "Actionable next step for the caller.", + "properties": { + "hint": { + "type": "string" + } + }, + "required": [ + "hint" + ], + "type": "object" + }, + "retryable": { + "description": "Whether retrying may succeed.", + "type": "boolean" + } + }, + "type": "object" + }, + "message": { + "description": "Human-readable description of what went wrong.", + "type": "string" + } + }, + "required": [ + "code", + "message" + ], + "type": "object" +} - removed
Output schema / requiredRemoved value: -[ - "docket_id", - "case_name", - "case_name_full", - "court", - "court_id", - "date_filed", - "date_terminated", - "docket_number", - "pacer_case_id", - "assigned_to", - "referred_to", - "cause", - "jury_demand", - "jurisdiction_type", - "total_entries", - "entries_page", - "next_cursor", - "entries" -]
- Changed
courtlistener_get_financial_disclosure6 fields changed- changed
Input schema / $schemaPrevious value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema" - added
Input schema / additionalPropertiesAdded value: +false - changed
Output schema / $schemaPrevious value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema" - added
Output schema / anyOfAdded value: +[ + { + "not": { + "required": [ + "error" + ] + }, + "required": [ + "disclosure_id", + "person_id", + "year", + "report_type", + "page_count", + "has_been_extracted", + "is_amended", + "pdf_url", + "counts", + "kind" + ] + }, + { + "required": [ + "error" + ] + } +] - added
Output schema / properties / errorAdded value: +{ + "additionalProperties": {}, + "description": "Present when the call failed. Absent on success.", + "properties": { + "code": { + "description": "JSON-RPC error code for this failure.", + "maximum": 9007199254740991, + "minimum": -9007199254740991, + "type": "integer" + }, + "data": { + "additionalProperties": {}, + "properties": { + "reason": { + "description": "Machine-readable failure mode. Declared by this tool: `not_found`: Disclosure ID does not exist in CourtListener. `rate_limited`: 429 response from CourtListener. Other values are possible when a failure originates below the handler.", + "examples": [ + "not_found", + "rate_limited" + ], + "type": "string" + }, + "recovery": { + "additionalProperties": {}, + "description": "Actionable next step for the caller.", + "properties": { + "hint": { + "type": "string" + } + }, + "required": [ + "hint" + ], + "type": "object" + }, + "retryable": { + "description": "Whether retrying may succeed.", + "type": "boolean" + } + }, + "type": "object" + }, + "message": { + "description": "Human-readable description of what went wrong.", + "type": "string" + } + }, + "required": [ + "code", + "message" + ], + "type": "object" +} - removed
Output schema / requiredRemoved value: -[ - "disclosure_id", - "person_id", - "year", - "report_type", - "page_count", - "has_been_extracted", - "is_amended", - "pdf_url", - "counts", - "kind" -]
- Changed
courtlistener_get_judge6 fields changed- changed
Input schema / $schemaPrevious value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema" - added
Input schema / additionalPropertiesAdded value: +false - changed
Output schema / $schemaPrevious value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema" - added
Output schema / anyOfAdded value: +[ + { + "not": { + "required": [ + "error" + ] + }, + "required": [ + "person_id", + "name", + "gender", + "dob", + "dob_granularity", + "dob_city", + "dob_state", + "dod", + "dod_granularity", + "fjc_id", + "aba_ratings", + "political_affiliations", + "education", + "positions", + "positionsShown", + "truncated" + ] + }, + { + "required": [ + "error" + ] + } +] - added
Output schema / properties / errorAdded value: +{ + "additionalProperties": {}, + "description": "Present when the call failed. Absent on success.", + "properties": { + "code": { + "description": "JSON-RPC error code for this failure.", + "maximum": 9007199254740991, + "minimum": -9007199254740991, + "type": "integer" + }, + "data": { + "additionalProperties": {}, + "properties": { + "reason": { + "description": "Machine-readable failure mode. Declared by this tool: `not_found`: Person ID does not exist in CourtListener. `rate_limited`: 429 response from CourtListener. Other values are possible when a failure originates below the handler.", + "examples": [ + "not_found", + "rate_limited" + ], + "type": "string" + }, + "recovery": { + "additionalProperties": {}, + "description": "Actionable next step for the caller.", + "properties": { + "hint": { + "type": "string" + } + }, + "required": [ + "hint" + ], + "type": "object" + }, + "retryable": { + "description": "Whether retrying may succeed.", + "type": "boolean" + } + }, + "type": "object" + }, + "message": { + "description": "Human-readable description of what went wrong.", + "type": "string" + } + }, + "required": [ + "code", + "message" + ], + "type": "object" +} - removed
Output schema / requiredRemoved value: -[ - "person_id", - "name", - "gender", - "dob", - "dob_granularity", - "dob_city", - "dob_state", - "dod", - "dod_granularity", - "fjc_id", - "aba_ratings", - "political_affiliations", - "education", - "positions", - "positionsShown", - "truncated" -]
- Changed
courtlistener_get_opinion6 fields changed- changed
Input schema / $schemaPrevious value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema" - added
Input schema / additionalPropertiesAdded value: +false - changed
Output schema / $schemaPrevious value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema" - added
Output schema / anyOfAdded value: +[ + { + "not": { + "required": [ + "error" + ] + }, + "required": [ + "cluster_id", + "case_name", + "case_name_full", + "court", + "court_id", + "date_filed", + "docket_id", + "docket_number", + "judges", + "citations", + "cite_count", + "precedential_status", + "syllabus", + "posture", + "kind" + ] + }, + { + "required": [ + "error" + ] + } +] - added
Output schema / properties / errorAdded value: +{ + "additionalProperties": {}, + "description": "Present when the call failed. Absent on success.", + "properties": { + "code": { + "description": "JSON-RPC error code for this failure.", + "maximum": 9007199254740991, + "minimum": -9007199254740991, + "type": "integer" + }, + "data": { + "additionalProperties": {}, + "properties": { + "reason": { + "description": "Machine-readable failure mode. Declared by this tool: `not_found`: Cluster ID does not exist in CourtListener. `rate_limited`: 429 response from CourtListener. `unknown_section`: A requested sections name matches no opinion variant in this cluster. Other values are possible when a failure originates below the handler.", + "examples": [ + "not_found", + "rate_limited", + "unknown_section" + ], + "type": "string" + }, + "recovery": { + "additionalProperties": {}, + "description": "Actionable next step for the caller.", + "properties": { + "hint": { + "type": "string" + } + }, + "required": [ + "hint" + ], + "type": "object" + }, + "retryable": { + "description": "Whether retrying may succeed.", + "type": "boolean" + } + }, + "type": "object" + }, + "message": { + "description": "Human-readable description of what went wrong.", + "type": "string" + } + }, + "required": [ + "code", + "message" + ], + "type": "object" +} - removed
Output schema / requiredRemoved value: -[ - "cluster_id", - "case_name", - "case_name_full", - "court", - "court_id", - "date_filed", - "docket_id", - "docket_number", - "judges", - "citations", - "cite_count", - "precedential_status", - "syllabus", - "posture", - "kind" -]
- Changed
courtlistener_get_oral_argument6 fields changed- changed
Input schema / $schemaPrevious value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema" - added
Input schema / additionalPropertiesAdded value: +false - changed
Output schema / $schemaPrevious value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema" - added
Output schema / anyOfAdded value: +[ + { + "not": { + "required": [ + "error" + ] + }, + "required": [ + "kind" + ] + }, + { + "required": [ + "error" + ] + } +] - added
Output schema / properties / errorAdded value: +{ + "additionalProperties": {}, + "description": "Present when the call failed. Absent on success.", + "properties": { + "code": { + "description": "JSON-RPC error code for this failure.", + "maximum": 9007199254740991, + "minimum": -9007199254740991, + "type": "integer" + }, + "data": { + "additionalProperties": {}, + "properties": { + "reason": { + "description": "Machine-readable failure mode. Declared by this tool: `not_found`: Audio ID does not exist in CourtListener. `rate_limited`: 429 response from CourtListener. `unknown_section`: A requested sections name is not a field of the oral argument record. Other values are possible when a failure originates below the handler.", + "examples": [ + "not_found", + "rate_limited", + "unknown_section" + ], + "type": "string" + }, + "recovery": { + "additionalProperties": {}, + "description": "Actionable next step for the caller.", + "properties": { + "hint": { + "type": "string" + } + }, + "required": [ + "hint" + ], + "type": "object" + }, + "retryable": { + "description": "Whether retrying may succeed.", + "type": "boolean" + } + }, + "type": "object" + }, + "message": { + "description": "Human-readable description of what went wrong.", + "type": "string" + } + }, + "required": [ + "code", + "message" + ], + "type": "object" +} - removed
Output schema / requiredRemoved value: -[ - "kind" -]
- Changed
courtlistener_get_parties6 fields changed- changed
Input schema / $schemaPrevious value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema" - added
Input schema / additionalPropertiesAdded value: +false - changed
Output schema / $schemaPrevious value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema" - added
Output schema / anyOfAdded value: +[ + { + "not": { + "required": [ + "error" + ] + }, + "required": [ + "docket_id", + "total_parties", + "next_cursor", + "parties" + ] + }, + { + "required": [ + "error" + ] + } +] - added
Output schema / properties / errorAdded value: +{ + "additionalProperties": {}, + "description": "Present when the call failed. Absent on success.", + "properties": { + "code": { + "description": "JSON-RPC error code for this failure.", + "maximum": 9007199254740991, + "minimum": -9007199254740991, + "type": "integer" + }, + "data": { + "additionalProperties": {}, + "properties": { + "reason": { + "description": "Machine-readable failure mode. Declared by this tool: `not_found`: Docket ID does not exist in CourtListener or has no RECAP party data. `rate_limited`: 429 response from CourtListener. Each call to this tool makes at least two upstream requests. Other values are possible when a failure originates below the handler.", + "examples": [ + "not_found", + "rate_limited" + ], + "type": "string" + }, + "recovery": { + "additionalProperties": {}, + "description": "Actionable next step for the caller.", + "properties": { + "hint": { + "type": "string" + } + }, + "required": [ + "hint" + ], + "type": "object" + }, + "retryable": { + "description": "Whether retrying may succeed.", + "type": "boolean" + } + }, + "type": "object" + }, + "message": { + "description": "Human-readable description of what went wrong.", + "type": "string" + } + }, + "required": [ + "code", + "message" + ], + "type": "object" +} - removed
Output schema / requiredRemoved value: -[ - "docket_id", - "total_parties", - "next_cursor", - "parties" -]
- Changed
courtlistener_lookup_citation6 fields changed- changed
Input schema / $schemaPrevious value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema" - added
Input schema / additionalPropertiesAdded value: +false - changed
Output schema / $schemaPrevious value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema" - added
Output schema / anyOfAdded value: +[ + { + "not": { + "required": [ + "error" + ] + }, + "required": [ + "matches", + "queriedCitation" + ] + }, + { + "required": [ + "error" + ] + } +] - added
Output schema / properties / errorAdded value: +{ + "additionalProperties": {}, + "description": "Present when the call failed. Absent on success.", + "properties": { + "code": { + "description": "JSON-RPC error code for this failure.", + "maximum": 9007199254740991, + "minimum": -9007199254740991, + "type": "integer" + }, + "data": { + "additionalProperties": {}, + "properties": { + "reason": { + "description": "Machine-readable failure mode. Declared by this tool: `not_found`: CourtListener could not parse any citation out of the submitted text. A citation that parses but matches nothing is a result with status 404, not this error. `rate_limited`: 429 response from CourtListener. `empty_citation`: citation is empty or whitespace-only after trimming — no request is sent. `citation_too_long`: citation exceeds the 64000-character ceiling CourtListener accepts — no request is sent. Other values are possible when a failure originates below the handler.", + "examples": [ + "not_found", + "rate_limited", + "empty_citation", + "citation_too_long" + ], + "type": "string" + }, + "recovery": { + "additionalProperties": {}, + "description": "Actionable next step for the caller.", + "properties": { + "hint": { + "type": "string" + } + }, + "required": [ + "hint" + ], + "type": "object" + }, + "retryable": { + "description": "Whether retrying may succeed.", + "type": "boolean" + } + }, + "type": "object" + }, + "message": { + "description": "Human-readable description of what went wrong.", + "type": "string" + } + }, + "required": [ + "code", + "message" + ], + "type": "object" +} - removed
Output schema / requiredRemoved value: -[ - "matches", - "queriedCitation" -]
- Changed
courtlistener_lookup_courts6 fields changed- changed
Input schema / $schemaPrevious value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema" - added
Input schema / additionalPropertiesAdded value: +false - changed
Output schema / $schemaPrevious value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema" - added
Output schema / anyOfAdded value: +[ + { + "not": { + "required": [ + "error" + ] + }, + "required": [ + "page", + "next_cursor", + "courts", + "all_matching_court_ids", + "all_matching_court_ids_complete", + "totalCount" + ] + }, + { + "required": [ + "error" + ] + } +] - added
Output schema / properties / errorAdded value: +{ + "additionalProperties": {}, + "description": "Present when the call failed. Absent on success.", + "properties": { + "code": { + "description": "JSON-RPC error code for this failure.", + "maximum": 9007199254740991, + "minimum": -9007199254740991, + "type": "integer" + }, + "data": { + "additionalProperties": {}, + "properties": { + "reason": { + "description": "Machine-readable failure mode. Declared by this tool: `rate_limited`: 429 response from CourtListener. Other values are possible when a failure originates below the handler.", + "examples": [ + "rate_limited" + ], + "type": "string" + }, + "recovery": { + "additionalProperties": {}, + "description": "Actionable next step for the caller.", + "properties": { + "hint": { + "type": "string" + } + }, + "required": [ + "hint" + ], + "type": "object" + }, + "retryable": { + "description": "Whether retrying may succeed.", + "type": "boolean" + } + }, + "type": "object" + }, + "message": { + "description": "Human-readable description of what went wrong.", + "type": "string" + } + }, + "required": [ + "code", + "message" + ], + "type": "object" +} - removed
Output schema / requiredRemoved value: -[ - "page", - "next_cursor", - "courts", - "all_matching_court_ids", - "all_matching_court_ids_complete", - "totalCount" -]
- Changed
courtlistener_search_dockets6 fields changed- changed
Input schema / $schemaPrevious value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema" - added
Input schema / additionalPropertiesAdded value: +false - changed
Output schema / $schemaPrevious value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema" - added
Output schema / anyOfAdded value: +[ + { + "not": { + "required": [ + "error" + ] + }, + "required": [ + "results", + "next_cursor", + "coverage_note", + "totalCount" + ] + }, + { + "required": [ + "error" + ] + } +] - added
Output schema / properties / errorAdded value: +{ + "additionalProperties": {}, + "description": "Present when the call failed. Absent on success.", + "properties": { + "code": { + "description": "JSON-RPC error code for this failure.", + "maximum": 9007199254740991, + "minimum": -9007199254740991, + "type": "integer" + }, + "data": { + "additionalProperties": {}, + "properties": { + "reason": { + "description": "Machine-readable failure mode. Declared by this tool: `rate_limited`: 429 response from CourtListener. `empty_query`: q is empty or whitespace-only after trimming — no request is sent. `invalid_date`: filed_after or filed_before is not a valid ISO 8601 calendar date. Other values are possible when a failure originates below the handler.", + "examples": [ + "rate_limited", + "empty_query", + "invalid_date" + ], + "type": "string" + }, + "recovery": { + "additionalProperties": {}, + "description": "Actionable next step for the caller.", + "properties": { + "hint": { + "type": "string" + } + }, + "required": [ + "hint" + ], + "type": "object" + }, + "retryable": { + "description": "Whether retrying may succeed.", + "type": "boolean" + } + }, + "type": "object" + }, + "message": { + "description": "Human-readable description of what went wrong.", + "type": "string" + } + }, + "required": [ + "code", + "message" + ], + "type": "object" +} - removed
Output schema / requiredRemoved value: -[ - "results", - "next_cursor", - "coverage_note", - "totalCount" -]
- Changed
courtlistener_search_financial_disclosures6 fields changed- changed
Input schema / $schemaPrevious value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema" - added
Input schema / additionalPropertiesAdded value: +false - changed
Output schema / $schemaPrevious value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema" - added
Output schema / anyOfAdded value: +[ + { + "not": { + "required": [ + "error" + ] + }, + "required": [ + "results", + "next_cursor" + ] + }, + { + "required": [ + "error" + ] + } +] - added
Output schema / properties / errorAdded value: +{ + "additionalProperties": {}, + "description": "Present when the call failed. Absent on success.", + "properties": { + "code": { + "description": "JSON-RPC error code for this failure.", + "maximum": 9007199254740991, + "minimum": -9007199254740991, + "type": "integer" + }, + "data": { + "additionalProperties": {}, + "properties": { + "reason": { + "description": "Machine-readable failure mode. Declared by this tool: `rate_limited`: 429 response from CourtListener. Other values are possible when a failure originates below the handler.", + "examples": [ + "rate_limited" + ], + "type": "string" + }, + "recovery": { + "additionalProperties": {}, + "description": "Actionable next step for the caller.", + "properties": { + "hint": { + "type": "string" + } + }, + "required": [ + "hint" + ], + "type": "object" + }, + "retryable": { + "description": "Whether retrying may succeed.", + "type": "boolean" + } + }, + "type": "object" + }, + "message": { + "description": "Human-readable description of what went wrong.", + "type": "string" + } + }, + "required": [ + "code", + "message" + ], + "type": "object" +} - removed
Output schema / requiredRemoved value: -[ - "results", - "next_cursor" -]
- Changed
courtlistener_search_judges6 fields changed- changed
Input schema / $schemaPrevious value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema" - added
Input schema / additionalPropertiesAdded value: +false - changed
Output schema / $schemaPrevious value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema" - added
Output schema / anyOfAdded value: +[ + { + "not": { + "required": [ + "error" + ] + }, + "required": [ + "results", + "next_cursor", + "totalCount" + ] + }, + { + "required": [ + "error" + ] + } +] - added
Output schema / properties / errorAdded value: +{ + "additionalProperties": {}, + "description": "Present when the call failed. Absent on success.", + "properties": { + "code": { + "description": "JSON-RPC error code for this failure.", + "maximum": 9007199254740991, + "minimum": -9007199254740991, + "type": "integer" + }, + "data": { + "additionalProperties": {}, + "properties": { + "reason": { + "description": "Machine-readable failure mode. Declared by this tool: `rate_limited`: 429 response from CourtListener. `empty_query`: q is empty or whitespace-only after trimming — no request is sent. Other values are possible when a failure originates below the handler.", + "examples": [ + "rate_limited", + "empty_query" + ], + "type": "string" + }, + "recovery": { + "additionalProperties": {}, + "description": "Actionable next step for the caller.", + "properties": { + "hint": { + "type": "string" + } + }, + "required": [ + "hint" + ], + "type": "object" + }, + "retryable": { + "description": "Whether retrying may succeed.", + "type": "boolean" + } + }, + "type": "object" + }, + "message": { + "description": "Human-readable description of what went wrong.", + "type": "string" + } + }, + "required": [ + "code", + "message" + ], + "type": "object" +} - removed
Output schema / requiredRemoved value: -[ - "results", - "next_cursor", - "totalCount" -]
- Changed
courtlistener_search_opinions6 fields changed- changed
Input schema / $schemaPrevious value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema" - added
Input schema / additionalPropertiesAdded value: +false - changed
Output schema / $schemaPrevious value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema" - added
Output schema / anyOfAdded value: +[ + { + "not": { + "required": [ + "error" + ] + }, + "required": [ + "results", + "next_cursor", + "totalCount", + "effectiveQuery" + ] + }, + { + "required": [ + "error" + ] + } +] - added
Output schema / properties / errorAdded value: +{ + "additionalProperties": {}, + "description": "Present when the call failed. Absent on success.", + "properties": { + "code": { + "description": "JSON-RPC error code for this failure.", + "maximum": 9007199254740991, + "minimum": -9007199254740991, + "type": "integer" + }, + "data": { + "additionalProperties": {}, + "properties": { + "reason": { + "description": "Machine-readable failure mode. Declared by this tool: `rate_limited`: 429 response from CourtListener — minute, hour, or day throttle hit. `invalid_query`: Query uses invalid field syntax or unsupported operators. `empty_query`: q is empty or whitespace-only after trimming — no request is sent. `invalid_date`: filed_after or filed_before is not a valid ISO 8601 calendar date. Other values are possible when a failure originates below the handler.", + "examples": [ + "rate_limited", + "invalid_query", + "empty_query", + "invalid_date" + ], + "type": "string" + }, + "recovery": { + "additionalProperties": {}, + "description": "Actionable next step for the caller.", + "properties": { + "hint": { + "type": "string" + } + }, + "required": [ + "hint" + ], + "type": "object" + }, + "retryable": { + "description": "Whether retrying may succeed.", + "type": "boolean" + } + }, + "type": "object" + }, + "message": { + "description": "Human-readable description of what went wrong.", + "type": "string" + } + }, + "required": [ + "code", + "message" + ], + "type": "object" +} - removed
Output schema / requiredRemoved value: -[ - "results", - "next_cursor", - "totalCount", - "effectiveQuery" -]
- Changed
courtlistener_search_oral_arguments6 fields changed- changed
Input schema / $schemaPrevious value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema" - added
Input schema / additionalPropertiesAdded value: +false - changed
Output schema / $schemaPrevious value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema" - added
Output schema / anyOfAdded value: +[ + { + "not": { + "required": [ + "error" + ] + }, + "required": [ + "results", + "next_cursor", + "totalCount" + ] + }, + { + "required": [ + "error" + ] + } +] - added
Output schema / properties / errorAdded value: +{ + "additionalProperties": {}, + "description": "Present when the call failed. Absent on success.", + "properties": { + "code": { + "description": "JSON-RPC error code for this failure.", + "maximum": 9007199254740991, + "minimum": -9007199254740991, + "type": "integer" + }, + "data": { + "additionalProperties": {}, + "properties": { + "reason": { + "description": "Machine-readable failure mode. Declared by this tool: `rate_limited`: 429 response from CourtListener. `empty_query`: q is empty or whitespace-only after trimming — no request is sent. `invalid_date`: argued_after or argued_before is not a valid ISO 8601 calendar date. Other values are possible when a failure originates below the handler.", + "examples": [ + "rate_limited", + "empty_query", + "invalid_date" + ], + "type": "string" + }, + "recovery": { + "additionalProperties": {}, + "description": "Actionable next step for the caller.", + "properties": { + "hint": { + "type": "string" + } + }, + "required": [ + "hint" + ], + "type": "object" + }, + "retryable": { + "description": "Whether retrying may succeed.", + "type": "boolean" + } + }, + "type": "object" + }, + "message": { + "description": "Human-readable description of what went wrong.", + "type": "string" + } + }, + "required": [ + "code", + "message" + ], + "type": "object" +} - removed
Output schema / requiredRemoved value: -[ - "results", - "next_cursor", - "totalCount" -]
1 tool update
- Changed
courtlistener_lookup_courts2 fields changed- changed
Input schema / properties / jurisdiction / descriptionPrevious value: -"Jurisdiction type. F=Federal Appellate (circuit courts, SCOTUS), FD=Federal District, FB=Federal Bankruptcy, FBP=Federal Bankruptcy Panel, FS=Federal Special (USITC, FISC, etc.), C=Circuit (historical), I=International, T=Territory, ST=State Trial, SS=State Supreme, SAG=State Attorney General, SAL=State Legislature, SA=State Appellate, S=State (other), TT=Tribal/Territory. Omit to list all."New value: +"Jurisdiction type — CourtListener's own court classification, one code per court: F=Federal Appellate, FD=Federal District, FB=Federal Bankruptcy, FBP=Federal Bankruptcy Panel, FS=Federal Special, S=State Supreme, SA=State Appellate, ST=State Trial, SS=State Special, SAG=State Attorney General, TRS=Tribal Supreme, TRA=Tribal Appellate, TRT=Tribal Trial, TRX=Tribal Special, TS=Territory Supreme, TA=Territory Appellate, TT=Territory Trial, TSP=Territory Special, MA=Military Appellate, MT=Military Trial, C=Committee, I=International. Omit to list all. SCOTUS and the numbered circuits are F; USITC and FISC are FS. Upstream's Testing code is not offered here: /courts/ excludes testing courts from every response, so a filter on it can only ever return nothing. Accepted but matching no court as of the 2026-07-30 snapshot: TSP, MT. Courts whose stored jurisdiction is not one of these codes (njcirctsussex, ohctapp1) are unreachable through this filter at any value — the value they store is not one the filter accepts. Pass those ids straight to the tool that needs them, or list with no jurisdiction filter." - changed
Input schema / properties / jurisdiction / enumPrevious value: -[ - "F", - "FD", - "FB", - "FBP", - "FS", - "C", - "I", - "T", - "ST", - "SS", - "SAG", - "SAL", - "SA", - "S", - "TT" -]New value: +[ + "F", + "FD", + "FB", + "FBP", + "FS", + "S", + "SA", + "ST", + "SS", + "SAG", + "TRS", + "TRA", + "TRT", + "TRX", + "TS", + "TA", + "TT", + "TSP", + "MA", + "MT", + "C", + "I" +]
3 tool updates
- Changed
courtlistener_get_judge5 fields changed- added
Output schema / properties / noticeAdded value: +{ + "description": "Present only when positions[] was truncated: what was withheld.", + "type": "string" +} - changed
Output schema / properties / positions / descriptionPrevious value: -"Every position on record, across all courts — judicial appointments plus non-judicial roles (private practice, prosecutor, professor), which carry no court and describe themselves in job_title."New value: +"Positions on record, across all courts — judicial appointments plus non-judicial roles (private practice, prosecutor, professor), which carry no court and describe themselves in job_title. CourtListener paginates this list and the walk is bounded, so read the truncated flag before treating it as a complete career." - added
Output schema / properties / positionsShownAdded value: +{ + "description": "Number of position records returned.", + "type": "number" +} - added
Output schema / properties / truncatedAdded value: +{ + "description": "True when the bounded /positions/ page walk stopped with pages outstanding — positions[] is then a prefix of the person's record, not the whole of it. False when the walk reached the end.", + "type": "boolean" +} - changed
Output schema / requiredPrevious value: -[ - "person_id", - "name", - "gender", - "dob", - "dob_granularity", - "dob_city", - "dob_state", - "dod", - "dod_granularity", - "fjc_id", - "aba_ratings", - "political_affiliations", - "education", - "positions" -]New value: +[ + "person_id", + "name", + "gender", + "dob", + "dob_granularity", + "dob_city", + "dob_state", + "dod", + "dod_granularity", + "fjc_id", + "aba_ratings", + "political_affiliations", + "education", + "positions", + "positionsShown", + "truncated" +]
- Changed
courtlistener_lookup_citation5 fields changed- added
Input schema / properties / max_court_lookupsAdded value: +{ + "default": 4, + "description": "How many distinct dockets this call may spend a request on to resolve cluster courts. The lookup itself is metered separately by CourtListener (per citation submitted), so this budget is drawn entirely from the ordinary per-request allowance — published free tier 5/min, 50/hour, 125/day, varying by token tier. 0 skips court resolution and costs nothing beyond the lookup; 20 is the ceiling. Clusters past the budget come back with court null and court_resolution \"over_budget\".", + "maximum": 20, + "minimum": 0, + "type": "integer" +} - changed
Output schema / properties / matches / items / properties / clusters / items / properties / court / descriptionPrevious value: -"Court display name. The citation-lookup payload carries no court, so this is resolved from the cluster's docket — one extra request each, capped at 4 distinct dockets per call. Null when that lookup was skipped past the cap, failed, or the cluster has no docket_id; the response notice reports how many clusters were left unresolved. Pass docket_id to courtlistener_get_docket, or cluster_id to courtlistener_get_opinion, to resolve one."New value: +"Court display name. The citation-lookup payload carries no court, so this is resolved from the cluster's docket — one extra request each, capped by max_court_lookups (default 4 distinct dockets per call). Null when that lookup was skipped past the budget, failed, or the cluster has no docket_id; court_resolution says which. Pass docket_id to courtlistener_get_docket, or cluster_id to courtlistener_get_opinion, to resolve one." - added
Output schema / properties / matches / items / properties / clusters / items / properties / court_resolutionAdded value: +{ + "description": "Why court/court_id are or are not populated: \"resolved\" the docket lookup returned a court; \"no_docket\" the cluster carries no docket_id, so nothing can be resolved; \"lookup_failed\" a request was spent on the docket and it yielded no court; \"over_budget\" no request was spent because max_court_lookups ran out or the walk stopped on a rate limit — raise max_court_lookups or fetch that docket directly.", + "enum": [ + "resolved", + "no_docket", + "lookup_failed", + "over_budget" + ], + "type": "string" +} - changed
Output schema / properties / matches / items / properties / clusters / items / requiredPrevious value: -[ - "cluster_id", - "case_name", - "court", - "court_id", - "date_filed", - "docket_id", - "citations", - "cite_count", - "precedential_status", - "judges" -]New value: +[ + "cluster_id", + "case_name", + "court", + "court_id", + "court_resolution", + "date_filed", + "docket_id", + "citations", + "cite_count", + "precedential_status", + "judges" +] - changed
Output schema / properties / notice / descriptionPrevious value: -"Caveats on this result: a recovery hint when no citation in the input resolved to a case, and a count of clusters whose court the per-call docket cap left unresolved. Absent when neither applies."New value: +"Caveats on this result: a recovery hint when no citation in the input resolved to a case, and counts of the clusters whose court went unresolved — split by whether the per-call docket budget ran out or an attempted lookup returned nothing, since only the first is worth retrying with a larger budget. Absent when none applies."
- Changed
courtlistener_lookup_courts4 fields changed- added
Output schema / properties / all_matching_court_idsAdded value: +{ + "description": "Every court id matching the same filters, from a snapshot of /courts/ bundled with this server (taken 2026-07-30) — the complete set, not just this page, and free of any request. Paging `courts` is only needed for the fields a court id alone does not carry (full_name, citation_string, scraper flags). Empty when more than 1000 courts match, since a prefix of the set would be indistinguishable from the whole of it — check all_matching_court_ids_complete before reading emptiness as \"no courts match\". A court added or retired upstream since the snapshot date appears in `courts` but may be missing here.", + "items": { + "type": "string" + }, + "type": "array" +} - added
Output schema / properties / all_matching_court_ids_completeAdded value: +{ + "description": "True when all_matching_court_ids holds every matching court id. False when more than 1000 courts match: the list is withheld whole rather than truncated, and the notice gives the count and how to narrow.", + "type": "boolean" +} - changed
Output schema / properties / courts / descriptionPrevious value: -"Matching courts."New value: +"Matching courts on this page." - changed
Output schema / requiredPrevious value: -[ - "page", - "next_cursor", - "courts", - "totalCount" -]New value: +[ + "page", + "next_cursor", + "courts", + "all_matching_court_ids", + "all_matching_court_ids_complete", + "totalCount" +]
4 tool updates
- Changed
courtlistener_get_oral_argument6 fields changed- changed
Input schema / properties / sections / descriptionPrevious value: -"Section identifiers to retrieve in full, from a prior outline response (e.g. [\"transcript\"]). Omit for the full record, or an outline if it overflows the inline budget."New value: +"Section identifiers to retrieve, from a prior outline response — [\"transcript\"] is the only one that adds anything, since every other field is returned regardless. A selection that omits \"transcript\" therefore returns the record without it. Omit this argument entirely for the whole record, or the record minus an oversized transcript." - changed
Output schema / properties / kind / descriptionPrevious value: -"'full' returns the record (or the selected sections); 'outline' lists retrievable sections when the transcript overflows the inline byte budget."New value: +"'full' carries the transcript inline; 'outline' withholds it and lists it as a retrievable section because it overflows the inline byte budget. Every other field of the record is present either way." - changed
Output schema / properties / retrieval_notice / descriptionPrevious value: -"How to re-call the tool for specific sections when the record overflows."New value: +"How to re-call the tool for the transcript when it overflows the inline budget." - changed
Output schema / properties / sections / descriptionPrevious value: -"Retrievable sections, largest first — pass names to `sections` on a re-call."New value: +"Sections withheld from this response — only ever `transcript`; pass its name to `sections` on a re-call. Absent when nothing was withheld." - changed
Output schema / properties / sections / items / descriptionPrevious value: -"A retrievable section of the record and its serialized byte size."New value: +"A withheld section of the record and its serialized byte size." - changed
Output schema / properties / transcript / descriptionPrevious value: -"Speech-to-text transcript; empty string if transcription has not completed."New value: +"Speech-to-text transcript; empty string if transcription has not completed. The only field an outline response withholds — re-call with sections:[\"transcript\"] to retrieve it."
- Changed
courtlistener_get_parties7 fields changed- added
Input schema / properties / cursorAdded value: +{ + "description": "Pagination cursor from a previous response's next_cursor field. Omit for the first page. This is an opaque token, not a page number — CourtListener cursor-paginates this endpoint, so a numeric value selects nothing and re-serves the first page.", + "type": "string" +} - removed
Input schema / properties / pageRemoved value: -{ - "default": 1, - "description": "Page number (1-indexed). Use with page_size to paginate large party lists.", - "maximum": 9007199254740991, - "minimum": 1, - "type": "integer" -} - changed
Output schema / properties / next_cursor / descriptionPrevious value: -"Next page number to pass as the `page` argument (this list is page-paginated); null when this is the last page."New value: +"Opaque pagination cursor for the next page — pass it back as the `cursor` argument; null when this is the last page." - removed
Output schema / properties / pageRemoved value: -{ - "description": "Current page number.", - "type": "number" -} - changed
Output schema / properties / totalCount / descriptionPrevious value: -"Total parties on this docket across all pages — present only when the API reports a numeric count (this endpoint returns it as a URL by default, so it is absent for any list spanning more than one page)."New value: +"Total parties on this docket across all pages — this endpoint reports its count as a URL rather than a number, so the total is only derivable when the first page is also the last, and is absent for any list spanning more than one page." - changed
Output schema / properties / total_parties / descriptionPrevious value: -"Total parties on this docket across all pages; null when upstream reports no count (a multi-page list whose total is unknown until the last page)."New value: +"Total parties on this docket across all pages; null when no total is derivable — CourtListener serves the count as a URL rather than a number here, so it is only known when the first page is also the last." - changed
Output schema / requiredPrevious value: -[ - "docket_id", - "total_parties", - "page", - "next_cursor", - "parties" -]New value: +[ + "docket_id", + "total_parties", + "next_cursor", + "parties" +]
- Changed
courtlistener_lookup_citation10 fields changed- changed
Input schema / properties / citation / descriptionPrevious value: -"Legal citation string to resolve (e.g., \"410 U.S. 113\", \"347 U.S. 483\", \"93 S. Ct. 705\"). Supports standard reporter formats."New value: +"Text to extract citations from — normally a single citation (e.g., \"410 U.S. 113\", \"347 U.S. 483\", \"93 S. Ct. 705\"), but any passage works and every citation in it is resolved. Supports standard reporter formats. Up to 64000 characters, which is CourtListener's own ceiling; a longer passage is rejected here rather than spending a request to be refused upstream." - removed
Output schema / properties / case_nameRemoved value: -{ - "anyOf": [ - { - "type": "string" - }, - { - "type": "null" - } - ], - "description": "Case name; null if not found." -} - removed
Output schema / properties / citationsRemoved value: -{ - "description": "All known citation strings for this case.", - "items": { - "type": "string" - }, - "type": "array" -} - removed
Output schema / properties / cluster_idRemoved value: -{ - "anyOf": [ - { - "type": "number" - }, - { - "type": "null" - } - ], - "description": "Opinion cluster ID — null if the citation is not in the CourtListener database." -} - removed
Output schema / properties / courtRemoved value: -{ - "anyOf": [ - { - "type": "string" - }, - { - "type": "null" - } - ], - "description": "Court display name; null if not found." -} - removed
Output schema / properties / date_filedRemoved value: -{ - "anyOf": [ - { - "type": "string" - }, - { - "type": "null" - } - ], - "description": "Date the opinion was filed; null if not found." -} - added
Output schema / properties / matchesAdded value: +{ + "description": "One entry per citation CourtListener extracted from the input, in the order they appear.", + "items": { + "additionalProperties": false, + "description": "One citation found in the submitted text and everything it resolved to.", + "properties": { + "citation": { + "description": "The citation as CourtListener matched it in the submitted text.", + "type": "string" + }, + "clusters": { + "description": "Cases this citation resolved to — empty when status is not 200 or 300, and more than one when status is 300.", + "items": { + "additionalProperties": false, + "description": "An opinion cluster this citation resolved to.", + "properties": { + "case_name": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "description": "Case name; null if not recorded." + }, + "citations": { + "description": "All known citation strings for this case.", + "items": { + "type": "string" + }, + "type": "array" + }, + "cite_count": { + "anyOf": [ + { + "type": "number" + }, + { + "type": "null" + } + ], + "description": "Times other opinions cite this case — a rough authority weight. Null if not recorded." + }, + "cluster_id": { + "anyOf": [ + { + "type": "number" + }, + { + "type": "null" + } + ], + "description": "Opinion cluster ID — pass to courtlistener_get_opinion. Null when upstream sent no ID." + }, + "court": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "description": "Court display name. The citation-lookup payload carries no court, so this is resolved from the cluster's docket — one extra request each, capped at 4 distinct dockets per call. Null when that lookup was skipped past the cap, failed, or the cluster has no docket_id; the response notice reports how many clusters were left unresolved. Pass docket_id to courtlistener_get_docket, or cluster_id to courtlistener_get_opinion, to resolve one." + }, + "court_id": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "description": "Court identifier for the `court` filter on the search tools (e.g. \"scotus\"); null under the same conditions as `court`." + }, + "date_filed": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "description": "Date the opinion was filed; null if not recorded." + }, + "docket_id": { + "anyOf": [ + { + "type": "number" + }, + { + "type": "null" + } + ], + "description": "Linked docket — pass to courtlistener_get_docket. Null if not recorded." + }, + "judges": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "description": "Free-text judge names; null or empty if not recorded." + }, + "precedential_status": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "description": "Publication status (e.g. \"Published\", \"Unpublished\"); null if not recorded." + } + }, + "required": [ + "cluster_id", + "case_name", + "court", + "court_id", + "date_filed", + "docket_id", + "citations", + "cite_count", + "precedential_status", + "judges" + ], + "type": "object" + }, + "type": "array" + }, + "error_message": { + "description": "CourtListener's explanation when status is not 200; empty string otherwise.", + "type": "string" + }, + "normalized_citation": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "description": "Canonical citation form used by CourtListener; null if not resolved." + }, + "status": { + "description": "Resolution status for this citation alone: 200 one case, 300 several candidates, 400 unrecognized reporter, 404 no case found, 429 past the per-request citation cap. Not the status of the request, which succeeded.", + "type": "number" + }, + "status_label": { + "description": "status decoded to a label.", + "type": "string" + } + }, + "required": [ + "citation", + "normalized_citation", + "status", + "status_label", + "error_message", + "clusters" + ], + "type": "object" + }, + "type": "array" +} - removed
Output schema / properties / normalized_citationRemoved value: -{ - "anyOf": [ - { - "type": "string" - }, - { - "type": "null" - } - ], - "description": "Canonical citation form used by CourtListener; null if not resolved." -} - changed
Output schema / properties / notice / descriptionPrevious value: -"Recovery hint when the citation is not in the database — suggests alternative lookup strategies."New value: +"Caveats on this result: a recovery hint when no citation in the input resolved to a case, and a count of clusters whose court the per-call docket cap left unresolved. Absent when neither applies." - changed
Output schema / requiredPrevious value: -[ - "cluster_id", - "case_name", - "court", - "date_filed", - "citations", - "normalized_citation", - "queriedCitation" -]New value: +[ + "matches", + "queriedCitation" +]
- Changed
courtlistener_lookup_courts4 fields changed- removed
Input schema / properties / in_useRemoved value: -{ - "default": true, - "description": "When true (default), only return courts currently scraped by CourtListener. Set to false to include historical or inactive courts.", - "type": "boolean" -} - changed
Input schema / properties / page / descriptionPrevious value: -"Page number (1-indexed). CourtListener caps /courts/ at ~20 rows per page regardless of size, so the full list (~472 courts) spans ~24 pages — pass the next_cursor from a previous response here to page through them."New value: +"Page number (1-indexed). CourtListener serves /courts/ at a fixed 20 rows per page and ignores any requested page size, so the number of pages is the enrichment totalCount divided by 20 — there is no way to pull a larger page. Pass the next_cursor from a previous response here to walk them one call at a time." - added
Input schema / properties / statusAdded value: +{ + "default": "active", + "description": "Which bench to return. 'active' (default) returns only courts CourtListener currently scrapes; 'inactive' returns only the historical and defunct courts it no longer scrapes; 'any' returns both. The two filtered sets are disjoint, so 'any' is the only value that reaches the whole list — but reaching all of it means paging, one call per 20 courts, and the inactive bench is several times larger than the active one. Prefer the narrowest value that answers the question, and narrow with jurisdiction rather than paging the full list.", + "enum": [ + "active", + "inactive", + "any" + ], + "type": "string" +} - changed
Output schema / properties / next_cursor / descriptionPrevious value: -"Next page number to pass as the `page` argument (this list is page-paginated at ~20 rows/page); null when this is the last page."New value: +"Next page number to pass as the `page` argument (this list is page-paginated at a fixed 20 rows/page); null when this is the last page — a non-null value means the courts shown are a partial view of the filtered set."
2 tool updates
- Changed
courtlistener_get_judge21 fields changed- changed
Output schema / properties / dob / descriptionPrevious value: -"Date of birth; null if not recorded."New value: +"Date of birth as CourtListener stores it, always full ISO 8601 — but the month and day are placeholders unless dob_granularity is \"day\". Read dob_granularity before presenting this as an exact date. Null if not recorded." - added
Output schema / properties / dob_granularityAdded value: +{ + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "description": "Precision actually recorded for dob: \"year\", \"month\", or \"day\". Null when CourtListener recorded no precision. An unrecognized upstream value passes through unchanged." +} - changed
Output schema / properties / dod / descriptionPrevious value: -"Date of death; null if living or not recorded."New value: +"Date of death as CourtListener stores it, always full ISO 8601 — precision qualified by dod_granularity, as with dob. Null if living or not recorded." - added
Output schema / properties / dod_granularityAdded value: +{ + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "description": "Precision actually recorded for dod: \"year\", \"month\", or \"day\". Null when CourtListener recorded no precision." +} - changed
Output schema / properties / education / items / properties / degree / descriptionPrevious value: -"Degree level; null if not recorded."New value: +"Raw CourtListener degree-level code (e.g. \"ba\"); null if not recorded." - added
Output schema / properties / education / items / properties / degree_labelAdded value: +{ + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "description": "Degree level expanded to a readable label (e.g. \"Juris Doctor (J.D.)\"). An unmapped code passes through as the code itself; null if not recorded." +} - changed
Output schema / properties / education / items / requiredPrevious value: -[ - "school", - "degree", - "year" -]New value: +[ + "school", + "degree", + "degree_label", + "year" +] - changed
Output schema / properties / positions / descriptionPrevious value: -"All judicial positions held, across all courts."New value: +"Every position on record, across all courts — judicial appointments plus non-judicial roles (private practice, prosecutor, professor), which carry no court and describe themselves in job_title." - changed
Output schema / properties / positions / items / descriptionPrevious value: -"Judicial position record."New value: +"Position record — judicial or otherwise." - changed
Output schema / properties / positions / items / properties / date_start / descriptionPrevious value: -"Date position started; null if not recorded."New value: +"Date the position started as CourtListener stores it, always full ISO 8601 — the month and day are placeholders unless date_start_granularity is \"day\". Null if not recorded." - added
Output schema / properties / positions / items / properties / date_start_granularityAdded value: +{ + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "description": "Precision actually recorded for date_start: \"year\", \"month\", or \"day\". Null when CourtListener recorded no precision." +} - changed
Output schema / properties / positions / items / properties / date_termination / descriptionPrevious value: -"Date position ended; null if current."New value: +"Date the position ended as CourtListener stores it, always full ISO 8601 — precision qualified by date_termination_granularity. Null if current." - added
Output schema / properties / positions / items / properties / date_termination_granularityAdded value: +{ + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "description": "Precision actually recorded for date_termination: \"year\", \"month\", or \"day\". Null when CourtListener recorded no precision." +} - added
Output schema / properties / positions / items / properties / job_titleAdded value: +{ + "description": "Free-text title for a role with no position_type code (e.g. \"Assistant district attorney\"); empty on judicial rows.", + "type": "string" +} - added
Output schema / properties / positions / items / properties / organization_nameAdded value: +{ + "description": "Employer for a non-judicial role; empty on judicial rows, which use court.", + "type": "string" +} - changed
Output schema / properties / positions / items / properties / position_type / descriptionPrevious value: -"Position title (e.g., \"District Judge\", \"Circuit Judge\", \"Justice\")."New value: +"Raw CourtListener position-type code (e.g. \"jud\", \"c-jud\") — the value the /positions/ position_type filter takes. Empty for non-judicial roles, which describe themselves in job_title." - added
Output schema / properties / positions / items / properties / position_type_labelAdded value: +{ + "description": "Position type expanded to a readable label (e.g. \"Judge\", \"Chief Judge\"). An unmapped code passes through as the code itself; empty for non-judicial roles.", + "type": "string" +} - changed
Output schema / properties / positions / items / properties / termination_reason / descriptionPrevious value: -"Reason for termination; null if still serving."New value: +"Raw CourtListener termination-reason code (e.g. \"other_pos\"); null if still serving." - added
Output schema / properties / positions / items / properties / termination_reason_labelAdded value: +{ + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "description": "Termination reason expanded to a readable label (e.g. \"Appointed to Other Judgeship\"). An unmapped code passes through as the code itself; null if still serving." +} - changed
Output schema / properties / positions / items / requiredPrevious value: -[ - "court", - "court_id", - "position_type", - "appointer", - "nomination_process", - "date_nominated", - "date_confirmation", - "date_start", - "date_termination", - "termination_reason" -]New value: +[ + "court", + "court_id", + "position_type", + "position_type_label", + "job_title", + "organization_name", + "appointer", + "nomination_process", + "date_nominated", + "date_confirmation", + "date_start", + "date_start_granularity", + "date_termination", + "date_termination_granularity", + "termination_reason", + "termination_reason_label" +] - changed
Output schema / requiredPrevious value: -[ - "person_id", - "name", - "gender", - "dob", - "dob_city", - "dob_state", - "dod", - "fjc_id", - "aba_ratings", - "political_affiliations", - "education", - "positions" -]New value: +[ + "person_id", + "name", + "gender", + "dob", + "dob_granularity", + "dob_city", + "dob_state", + "dod", + "dod_granularity", + "fjc_id", + "aba_ratings", + "political_affiliations", + "education", + "positions" +]
- Changed
courtlistener_get_opinion3 fields changed- changed
Output schema / properties / opinions / items / properties / type / descriptionPrevious value: -"Opinion type: \"lead-opinion\", \"concurrence\", \"dissent\", \"combined-opinion\", etc."New value: +"Raw CourtListener opinion-type code (e.g. \"030concurrence\"); the numeric prefix is a sort key, not part of the type. Empty when upstream recorded none." - added
Output schema / properties / opinions / items / properties / type_labelAdded value: +{ + "description": "Opinion type expanded to the label courtlistener_search_opinions serves for the same variant: \"lead-opinion\", \"concurrence-opinion\", \"dissent\", \"combined-opinion\", etc. An unmapped code passes through as the code itself.", + "type": "string" +} - changed
Output schema / properties / opinions / items / requiredPrevious value: -[ - "id", - "type", - "author_id", - "per_curiam", - "html_text", - "plain_text", - "cites", - "download_url" -]New value: +[ + "id", + "type", + "type_label", + "author_id", + "per_curiam", + "html_text", + "plain_text", + "cites", + "download_url" +]
1 tool update
- Changed
courtlistener_get_citations3 fields changed- changed
Input schema / properties / page_size / descriptionPrevious value: -"Number of results to request (default 20). For direction=\"cited_by\", CourtListener enforces a minimum of 20 results per page regardless of the value passed — you will always receive at least 20 results. direction=\"citing\" returns at most page_size (the cited-opinion list is sliced before querying) — fewer when the opinion cites fewer than page_size distinct opinions. Each citation tool call costs one request against the rate limit — keep low for multi-hop traversal."New value: +"Number of results to request (default 20). For direction=\"cited_by\", CourtListener enforces a minimum of 20 results per page regardless of the value passed — you will always receive at least 20 results. direction=\"citing\" returns at most page_size (the cited-opinion list is sliced before querying) — fewer when the opinion cites fewer than page_size distinct opinions. Either direction costs three requests against the rate limit (a case with many opinion variants costs one more per extra variant page) — keep low for multi-hop traversal." - changed
Output schema / properties / notice / descriptionPrevious value: -"Recovery hint when no citations are found — echoes direction and filters, suggests alternatives."New value: +"Context when no citations are returned — either that this page had no match under the filters and more pages remain, or a recovery hint echoing direction and filters." - changed
Output schema / properties / totalCount / descriptionPrevious value: -"Total citations in the requested direction."New value: +"Total citations in the requested direction. For \"cited_by\" it counts matching clusters with the court and filed_after filters applied. For \"citing\" it counts the distinct opinions this case cites, before any filter — so it exceeds what the filters make reachable, and runs higher than the result rows, which are clusters (several cited opinions in one case collapse to one row)."
1 tool update
- Changed
courtlistener_get_parties9 fields changed- changed
Input schema / properties / page_size / descriptionPrevious value: -"Number of parties per page (1–10). Each call makes two upstream requests (parties + attorney batch) — keep low to stay within the free-tier rate limit."New value: +"Requested number of parties per page (1–10). CourtListener paginates this endpoint at a fixed size and does not honor the requested value, so a page can come back larger than asked for." - added
Output schema / properties / parties / items / properties / attorneys / items / properties / date_actionAdded value: +{ + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "description": "Date the attorney–party relationship ended; null while the attorney is still of record." +} - added
Output schema / properties / parties / items / properties / attorneys / items / properties / roleAdded value: +{ + "description": "role_code decoded to a label (e.g., \"Lead attorney\"). Codes 5–9 (\"Self-terminated\" through \"Disbarred\") mean the attorney is no longer of record. The stringified code when upstream sends a value outside the documented enum, \"Unrecorded\" when it sends none.", + "type": "string" +} - added
Output schema / properties / parties / items / properties / attorneys / items / properties / role_code / anyOfAdded value: +[ + { + "type": "number" + }, + { + "type": "null" + } +] - changed
Output schema / properties / parties / items / properties / attorneys / items / properties / role_code / descriptionPrevious value: -"Numeric attorney role code from the party–attorney relationship (e.g., 1 = Lead attorney)."New value: +"Numeric attorney role code from the party–attorney relationship (1 = Attorney to be noticed, 2 = Lead attorney, 3 = Attorney in sealed group, 4 = Pro hac vice, 5 = Self-terminated, 6 = Terminated, 7 = Suspended, 8 = Inactive, 9 = Disbarred, 10 = Unknown); null when upstream recorded no code." - removed
Output schema / properties / parties / items / properties / attorneys / items / properties / role_code / typeRemoved value: -"number" - changed
Output schema / properties / parties / items / properties / attorneys / items / requiredPrevious value: -[ - "attorney_id", - "name", - "contact_raw", - "role_code" -]New value: +[ + "attorney_id", + "name", + "contact_raw", + "role_code", + "role", + "date_action" +] - changed
Output schema / properties / totalCount / descriptionPrevious value: -"Total parties on this docket across all pages."New value: +"Total parties on this docket across all pages — present only when the API reports a numeric count (this endpoint returns it as a URL by default, so it is absent for any list spanning more than one page)." - changed
Output schema / requiredPrevious value: -[ - "docket_id", - "total_parties", - "page", - "next_cursor", - "parties", - "totalCount" -]New value: +[ + "docket_id", + "total_parties", + "page", + "next_cursor", + "parties" +]
5 tool updates
- Changed
courtlistener_get_citations1 field changed- changed
Output schema / properties / results / items / properties / snippet / descriptionPrevious value: -"Text excerpt showing context around the citation (where available)."New value: +"Matched text excerpt from the related opinion, taken from the first opinion variant in the cluster that carries one; empty string when none does. It is a relevance preview for the cluster, not necessarily text surrounding the citation itself."
- Changed
courtlistener_search_dockets15 fields changed- added
Output schema / properties / results / items / properties / attorneysAdded value: +{ + "description": "Attorney names of record on this docket; empty when none are recorded.", + "items": { + "type": "string" + }, + "type": "array" +} - added
Output schema / properties / results / items / properties / case_name_fullAdded value: +{ + "description": "Full case name with all parties; empty string when not recorded.", + "type": "string" +} - removed
Output schema / properties / results / items / properties / document_countRemoved value: -{ - "description": "Number of documents available in RECAP.", - "type": "number" -} - added
Output schema / properties / results / items / properties / firmsAdded value: +{ + "description": "Law firm names of record on this docket; empty when none are recorded.", + "items": { + "type": "string" + }, + "type": "array" +} - added
Output schema / properties / results / items / properties / jurisdiction_typeAdded value: +{ + "description": "Basis of federal jurisdiction (e.g. \"Federal Question\"); empty string when not recorded.", + "type": "string" +} - added
Output schema / properties / results / items / properties / referred_toAdded value: +{ + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "description": "Referred magistrate judge name; null if not recorded." +} - changed
Output schema / properties / results / items / properties / sample_documents / descriptionPrevious value: -"Up to 3 sample filings from this docket."New value: +"Up to 3 sample filings matched on this docket — a search excerpt, not the docket's full filing list. Call courtlistener_get_docket for every entry." - changed
Output schema / properties / results / items / properties / sample_documents / items / properties / date_filed / descriptionPrevious value: -"Date the document was filed."New value: +"Date the parent docket entry was filed; empty string when not recorded." - added
Output schema / properties / results / items / properties / sample_documents / items / properties / document_typeAdded value: +{ + "description": "Document classification (e.g. \"PACER Document\", \"RECAP Document\"); empty string when not recorded.", + "type": "string" +} - added
Output schema / properties / results / items / properties / sample_documents / items / properties / entry_numberAdded value: +{ + "anyOf": [ + { + "type": "number" + }, + { + "type": "null" + } + ], + "description": "Docket entry number this document belongs to; null if unnumbered." +} - added
Output schema / properties / results / items / properties / sample_documents / items / properties / filepath_localAdded value: +{ + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "description": "Fully-qualified RECAP storage URL (https://storage.courtlistener.com/...) for the document; null when no copy is stored." +} - added
Output schema / properties / results / items / properties / sample_documents / items / properties / page_countAdded value: +{ + "anyOf": [ + { + "type": "number" + }, + { + "type": "null" + } + ], + "description": "Page count; null if not recorded." +} - changed
Output schema / properties / results / items / properties / sample_documents / items / requiredPrevious value: -[ - "id", - "description", - "date_filed", - "document_number", - "is_available" -]New value: +[ + "id", + "description", + "date_filed", + "document_number", + "entry_number", + "document_type", + "page_count", + "filepath_local", + "is_available" +] - added
Output schema / properties / results / items / properties / suit_natureAdded value: +{ + "description": "Nature-of-suit label, usually prefixed with its PACER code (e.g. \"830 Patent\"); empty string when not recorded.", + "type": "string" +} - changed
Output schema / properties / results / items / requiredPrevious value: -[ - "docket_id", - "case_name", - "court", - "court_id", - "date_filed", - "date_terminated", - "docket_number", - "pacer_case_id", - "assigned_to", - "cause", - "jury_demand", - "parties", - "document_count", - "sample_documents" -]New value: +[ + "docket_id", + "case_name", + "case_name_full", + "court", + "court_id", + "date_filed", + "date_terminated", + "docket_number", + "pacer_case_id", + "assigned_to", + "referred_to", + "cause", + "jury_demand", + "suit_nature", + "jurisdiction_type", + "parties", + "attorneys", + "firms", + "sample_documents" +]
- Changed
courtlistener_search_judges4 fields changed- changed
Output schema / properties / results / items / properties / aba_rating / descriptionPrevious value: -"ABA qualification ratings."New value: +"ABA qualification labels (e.g. \"Well Qualified\", \"Qualified\"), one per rating on record — not the rating codes." - changed
Output schema / properties / results / items / properties / current_position / anyOfPrevious value: -[ - { - "additionalProperties": false, - "properties": { - "appointer": { - "anyOf": [ - { - "type": "string" - }, - { - "type": "null" - } - ], - "description": "Appointing president; null if elected or not recorded." - }, - "court": { - "anyOf": [ - { - "type": "string" - }, - { - "type": "null" - } - ], - "description": "Court where currently serving; null if not applicable." - }, - "court_id": { - "anyOf": [ - { - "type": "string" - }, - { - "type": "null" - } - ], - "description": "Court identifier." - }, - "date_start": { - "anyOf": [ - { - "type": "string" - }, - { - "type": "null" - } - ], - "description": "Date position started." - }, - "position_type": { - "anyOf": [ - { - "type": "string" - }, - { - "type": "null" - } - ], - "description": "Position title (e.g., \"District Judge\")." - } - }, - "required": [ - "court", - "court_id", - "position_type", - "appointer", - "date_start" - ], - "type": "object" - }, - { - "type": "null" - } -]New value: +[ + { + "additionalProperties": false, + "properties": { + "appointer": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "description": "Name of the appointing president (e.g. \"Obama, Barack Hussein, II\"); null if elected or not recorded." + }, + "court": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "description": "Court full name; null for non-judicial positions." + }, + "court_id": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "description": "Court identifier for use in filter parameters; null for non-judicial positions." + }, + "date_start": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "description": "Date the position started; null if not recorded." + }, + "date_termination": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "description": "Date the position ended; null while the judge still holds it." + }, + "job_title": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "description": "Free-text title for non-judicial roles (e.g. \"Assistant district attorney\"); null for judicial positions." + }, + "organization_name": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "description": "Employer for non-judicial roles; null for judicial positions." + }, + "position_type": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "description": "Judicial position title (e.g. \"Judge\", \"Chief Judge\"); null for non-judicial positions — see job_title." + }, + "selection_method": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "description": "How the judge reached the position (e.g. \"Appointment (President)\", \"Election (Partisan)\"); null if not recorded." + }, + "termination_reason": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "description": "Why the position ended (e.g. \"Appointed to Other Judgeship\", \"Retirement\"); null while still serving." + } + }, + "required": [ + "court", + "court_id", + "position_type", + "job_title", + "organization_name", + "appointer", + "selection_method", + "date_start", + "date_termination", + "termination_reason" + ], + "type": "object" + }, + { + "type": "null" + } +] - changed
Output schema / properties / results / items / properties / current_position / descriptionPrevious value: -"Current or most recent position; null if not available."New value: +"The position with no termination date, or — when several or none qualify — the one with the latest start date. Null when the record carries no positions. courtlistener_get_judge returns the full appointment history." - changed
Output schema / properties / results / items / properties / political_affiliation / descriptionPrevious value: -"Political affiliation codes."New value: +"Party labels (e.g. \"Democratic\", \"Republican\"), one per recorded affiliation — not the single-letter codes the political_affiliation input filter takes."
- Changed
courtlistener_search_opinions3 fields changed- added
Output schema / properties / results / items / properties / opinionsAdded value: +{ + "description": "Opinion variants filed in this case (majority, concurrence, dissent, per curiam). Empty when upstream returned none.", + "items": { + "additionalProperties": false, + "description": "One opinion variant within the cluster.", + "properties": { + "author_id": { + "anyOf": [ + { + "type": "number" + }, + { + "type": "null" + } + ], + "description": "Person ID of the authoring judge — pass to courtlistener_get_judge; null when unattributed." + }, + "cites": { + "description": "Opinion IDs this variant cites. These are opinion-level IDs, not cluster IDs — courtlistener_get_opinion and courtlistener_get_citations both take a cluster_id, so do not pass these values to them directly.", + "items": { + "type": "number" + }, + "type": "array" + }, + "download_url": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "description": "URL of the originating court's copy; null when none was recorded. Often plain HTTP and prone to rot — prefer local_path." + }, + "id": { + "description": "Opinion ID for this variant — identifies one opinion within the cluster (the cluster itself is cluster_id).", + "type": "number" + }, + "local_path": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "description": "CourtListener-hosted copy of the source document (https://storage.courtlistener.com/...); null if not stored." + }, + "per_curiam": { + "description": "True when the opinion was issued per curiam (by the court).", + "type": "boolean" + }, + "type": { + "description": "Variant type as an expanded label (e.g. \"combined-opinion\", \"lead-opinion\", \"dissent\").", + "type": "string" + } + }, + "required": [ + "id", + "type", + "author_id", + "per_curiam", + "download_url", + "local_path", + "cites" + ], + "type": "object" + }, + "type": "array" +} - changed
Output schema / properties / results / items / properties / snippet / descriptionPrevious value: -"Matched text excerpt from the opinion."New value: +"Matched text excerpt, taken from the first entry in opinions[] that carries one; empty string when no variant has an excerpt. CourtListener does not mark which variant the search matched, so treat this as a relevance preview for the cluster, not as an excerpt attributable to a specific opinion — read opinions[] to attribute it." - changed
Output schema / properties / results / items / requiredPrevious value: -[ - "cluster_id", - "case_name", - "case_name_full", - "court", - "court_id", - "date_filed", - "docket_number", - "docket_id", - "citations", - "cite_count", - "judges", - "status", - "snippet" -]New value: +[ + "cluster_id", + "case_name", + "case_name_full", + "court", + "court_id", + "date_filed", + "docket_number", + "docket_id", + "citations", + "cite_count", + "judges", + "status", + "snippet", + "opinions" +]
- Changed
courtlistener_search_oral_arguments2 fields changed- changed
Output schema / properties / results / items / properties / download_url / descriptionPrevious value: -"Direct MP3 download URL; null if not available."New value: +"MP3 URL at the originating court; null if not recorded. Often plain HTTP and prone to rot as courts reorganize — prefer local_path, CourtListener's durable copy." - changed
Output schema / properties / results / items / properties / local_path / descriptionPrevious value: -"Local storage path on CourtListener servers; null if not available."New value: +"CourtListener-hosted copy of the recording (https://storage.courtlistener.com/...); null if not stored."
2 tool updates
- Changed
courtlistener_lookup_courts4 fields changed- added
Input schema / properties / pageAdded value: +{ + "default": 1, + "description": "Page number (1-indexed). CourtListener caps /courts/ at ~20 rows per page regardless of size, so the full list (~472 courts) spans ~24 pages — pass the next_cursor from a previous response here to page through them.", + "maximum": 9007199254740991, + "minimum": 1, + "type": "integer" +} - added
Output schema / properties / next_cursorAdded value: +{ + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "description": "Next page number to pass as the `page` argument (this list is page-paginated at ~20 rows/page); null when this is the last page." +} - added
Output schema / properties / pageAdded value: +{ + "description": "Current page number (1-indexed).", + "type": "number" +} - changed
Output schema / requiredPrevious value: -[ - "courts", - "totalCount" -]New value: +[ + "page", + "next_cursor", + "courts", + "totalCount" +]
- Changed
courtlistener_search_financial_disclosures1 field changed- changed
Input schema / properties / year / descriptionPrevious value: -"Filing year to filter by (e.g., 2022). Filters the fetched filings — pair with judge_id for complete per-judge results. Omit to return all available years."New value: +"Filing year to filter by (e.g., 2022). Applied client-side to the fetched page only — CourtListener rejects a server-side year param, so filings for this year on later pages are not included. When a page has no match for the year but more pages remain, next_cursor is returned; pass it as cursor to check the next page. Omit to return all years on the page."
5 tool updates
- Changed
courtlistener_lookup_citation1 field changed- removed
Input schema / properties / citation / minLengthRemoved value: -1
- Changed
courtlistener_search_dockets1 field changed- removed
Input schema / properties / q / minLengthRemoved value: -1
- Changed
courtlistener_search_judges1 field changed- removed
Input schema / properties / q / minLengthRemoved value: -1
- Changed
courtlistener_search_opinions1 field changed- removed
Input schema / properties / q / minLengthRemoved value: -1
- Changed
courtlistener_search_oral_arguments1 field changed- removed
Input schema / properties / q / minLengthRemoved value: -1
1 tool update
- Added
courtlistener_get_financial_disclosure
3 tool updates
- Changed
courtlistener_get_citations2 fields changed- changed
Input schema / properties / page_size / defaultPrevious value: -10New value: +20 - changed
Input schema / properties / page_size / descriptionPrevious value: -"Number of results (1–20). Each citation tool call costs one request against the rate limit — keep page_size low for multi-hop traversal."New value: +"Number of results to request (default 20). For direction=\"cited_by\", CourtListener enforces a minimum of 20 results per page regardless of the value passed — you will always receive at least 20 results. direction=\"citing\" returns at most page_size (the cited-opinion list is sliced before querying) — fewer when the opinion cites fewer than page_size distinct opinions. Each citation tool call costs one request against the rate limit — keep low for multi-hop traversal."
- Changed
courtlistener_get_docket6 fields changed- added
Input schema / properties / entries_pageAdded value: +{ + "default": 1, + "description": "Page of docket entries to fetch (1-indexed). Docket entries are page-paginated at 20 per page; pass the next_cursor from a previous response here to page through large cases.", + "maximum": 9007199254740991, + "minimum": 1, + "type": "integer" +} - changed
Input schema / properties / entries_page_size / descriptionPrevious value: -"Number of docket entries to return (1–50). Large cases can have hundreds of entries."New value: +"Requested docket entries per page. NOTE: CourtListener ignores this value — /docket-entries/ always returns a fixed 20-entry page regardless of what is passed. Use entries_page to reach entries beyond the first 20 (large cases can have hundreds)." - changed
Output schema / properties / entries / descriptionPrevious value: -"Docket entries up to entries_page_size."New value: +"Docket entries for this page (fixed at 20 per page; entries_page_size is not honored by upstream)." - added
Output schema / properties / entries_pageAdded value: +{ + "description": "Current entries page number (1-indexed).", + "type": "number" +} - added
Output schema / properties / next_cursorAdded value: +{ + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "description": "Next page number to pass as the `entries_page` argument (docket entries are page-paginated); null when this is the last page." +} - changed
Output schema / requiredPrevious value: -[ - "docket_id", - "case_name", - "case_name_full", - "court", - "court_id", - "date_filed", - "date_terminated", - "docket_number", - "pacer_case_id", - "assigned_to", - "referred_to", - "cause", - "jury_demand", - "jurisdiction_type", - "total_entries", - "entries" -]New value: +[ + "docket_id", + "case_name", + "case_name_full", + "court", + "court_id", + "date_filed", + "date_terminated", + "docket_number", + "pacer_case_id", + "assigned_to", + "referred_to", + "cause", + "jury_demand", + "jurisdiction_type", + "total_entries", + "entries_page", + "next_cursor", + "entries" +]
- Changed
courtlistener_search_financial_disclosures1 field changed- changed
Input schema / properties / page_size / descriptionPrevious value: -"Number of filings to return (1–20)."New value: +"Number of filings to request (default 20). CourtListener enforces a minimum of 20 results per page regardless of the value passed — you will always receive at least 20 filings."
2 tool updates
- Changed
courtlistener_get_opinion6 fields changed- added
Input schema / properties / sectionsAdded value: +{ + "description": "Opinion variant identifiers to retrieve in full, from a prior outline response (e.g. [\"opinion_12345\"]). Omit to return all variants, or an outline if they overflow the inline byte budget.", + "items": { + "type": "string" + }, + "type": "array" +} - added
Output schema / properties / kindAdded value: +{ + "description": "'full' returns the opinion variants (all, or a selected subset); 'outline' lists each variant as a retrievable section (opinion_<id>) when the opinions overflow the inline byte budget. Cluster metadata is present either way.", + "enum": [ + "full", + "outline" + ], + "type": "string" +} - changed
Output schema / properties / opinions / descriptionPrevious value: -"All opinion variants within this cluster."New value: +"All opinion variants within this cluster. Present in full mode; omitted in outline mode — re-call with sections:[\"opinion_<id>\"] to retrieve specific variants." - added
Output schema / properties / retrieval_noticeAdded value: +{ + "description": "How to re-call the tool for specific opinion variants when the opinions overflow.", + "type": "string" +} - added
Output schema / properties / sectionsAdded value: +{ + "description": "Retrievable opinion variants, largest first — pass names to `sections` on a re-call.", + "items": { + "additionalProperties": false, + "description": "A retrievable opinion variant (opinion_<id>) and its serialized byte size.", + "properties": { + "bytes": { + "description": "Serialized byte size of the section", + "maximum": 9007199254740991, + "minimum": 0, + "type": "integer" + }, + "name": { + "description": "Section identifier — pass in `sections` to retrieve it", + "type": "string" + } + }, + "required": [ + "name", + "bytes" + ], + "type": "object" + }, + "type": "array" +} - changed
Output schema / requiredPrevious value: -[ - "cluster_id", - "case_name", - "case_name_full", - "court", - "court_id", - "date_filed", - "docket_id", - "docket_number", - "judges", - "citations", - "cite_count", - "precedential_status", - "syllabus", - "posture", - "opinions" -]New value: +[ + "cluster_id", + "case_name", + "case_name_full", + "court", + "court_id", + "date_filed", + "docket_id", + "docket_number", + "judges", + "citations", + "cite_count", + "precedential_status", + "syllabus", + "posture", + "kind" +]
- Changed
courtlistener_get_oral_argument5 fields changed- added
Input schema / properties / sectionsAdded value: +{ + "description": "Section identifiers to retrieve in full, from a prior outline response (e.g. [\"transcript\"]). Omit for the full record, or an outline if it overflows the inline budget.", + "items": { + "type": "string" + }, + "type": "array" +} - added
Output schema / properties / kindAdded value: +{ + "description": "'full' returns the record (or the selected sections); 'outline' lists retrievable sections when the transcript overflows the inline byte budget.", + "enum": [ + "full", + "outline" + ], + "type": "string" +} - added
Output schema / properties / retrieval_noticeAdded value: +{ + "description": "How to re-call the tool for specific sections when the record overflows.", + "type": "string" +} - added
Output schema / properties / sectionsAdded value: +{ + "description": "Retrievable sections, largest first — pass names to `sections` on a re-call.", + "items": { + "additionalProperties": false, + "description": "A retrievable section of the record and its serialized byte size.", + "properties": { + "bytes": { + "description": "Serialized byte size of the section", + "maximum": 9007199254740991, + "minimum": 0, + "type": "integer" + }, + "name": { + "description": "Section identifier — pass in `sections` to retrieve it", + "type": "string" + } + }, + "required": [ + "name", + "bytes" + ], + "type": "object" + }, + "type": "array" +} - changed
Output schema / requiredPrevious value: -[ - "oral_argument_id", - "case_name", - "case_name_full", - "docket_id", - "duration_seconds", - "download_url", - "judges", - "panel_ids", - "has_transcript", - "transcript" -]New value: +[ + "kind" +]
2 tool updates
- Changed
courtlistener_get_judge2 fields changed- changed
Output schema / properties / positions / items / properties / appointer / descriptionPrevious value: -"Appointing president name; null if elected or not recorded."New value: +"Position URI of the appointing authority (e.g., \".../positions/123/\"), not resolved to a name; null if elected or not recorded." - changed
Output schema / properties / positions / items / properties / nomination_process / descriptionPrevious value: -"Nomination process; null if not recorded."New value: +"Selection method, expanded to a readable label (e.g., \"Appointment (President)\"); null if not recorded."
- Changed
courtlistener_get_opinion1 field changed- changed
Output schema / properties / opinions / items / properties / html_text / descriptionPrevious value: -"Full opinion text as HTML; may be empty if only a download URL is available."New value: +"Full opinion text as HTML, drawn from the best available variant (citation-linked when present); empty only when no HTML text is stored — use download_url then."
2 tool updates
- Changed
courtlistener_get_docket3 fields changed- changed
Output schema / properties / entries / items / properties / documents / items / properties / document_number / anyOfPrevious value: -[ - { - "type": "number" - }, - { - "type": "null" - } -]New value: +[ + { + "type": "string" + }, + { + "type": "null" + } +] - changed
Output schema / properties / entries / items / properties / documents / items / properties / document_number / descriptionPrevious value: -"PACER document number; null if not assigned."New value: +"PACER document number as a string (e.g. \"1\"); attachments can be non-integer like \"70-1\". Null if not assigned." - changed
Output schema / properties / entries / items / properties / documents / items / properties / filepath_local / descriptionPrevious value: -"RECAP storage URL for available documents; null if not available."New value: +"Fully-qualified RECAP storage URL (https://storage.courtlistener.com/...) for the document; null if not available."
- Changed
courtlistener_get_parties4 fields changed- changed
Output schema / properties / next_cursor / descriptionPrevious value: -"Opaque cursor for the next page; null when this is the last page."New value: +"Next page number to pass as the `page` argument (this list is page-paginated); null when this is the last page." - added
Output schema / properties / total_parties / anyOfAdded value: +[ + { + "type": "number" + }, + { + "type": "null" + } +] - changed
Output schema / properties / total_parties / descriptionPrevious value: -"Total number of parties on this docket across all pages."New value: +"Total parties on this docket across all pages; null when upstream reports no count (a multi-page list whose total is unknown until the last page)." - removed
Output schema / properties / total_parties / typeRemoved value: -"number"
1 tool update
- Changed
courtlistener_get_parties2 fields changed- added
Output schema / properties / totalCountAdded value: +{ + "description": "Total parties on this docket across all pages.", + "type": "number" +} - changed
Output schema / requiredPrevious value: -[ - "docket_id", - "total_parties", - "page", - "next_cursor", - "parties" -]New value: +[ + "docket_id", + "total_parties", + "page", + "next_cursor", + "parties", + "totalCount" +]
1 tool update
- Added
courtlistener_get_parties
Related MCP Connectors
Search US federal and state court records through CourtListener and the RECAP archive
MCP for CourtListener: US federal and state opinions, dockets, judges, plus eCFR regulations.
Search U.S. case law, fetch opinions, and ask matter-aware legal questions over your documents.
CourtListener MCP — Free Law Project's CourtListener API (free, no auth required for basic access)
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables legal research across 3,352 U.S. courts using the CourtListener API, providing access to case search, precedent analysis, judge patterns, citation validation, and federal PACER dockets through natural language queries.22 npm3MIT
- AlicenseNot gradedqualityCmaintenanceEnables AI agents to query and access legal data from the Free Law Project's CourtListener API, including court opinions, judges, and dockets, with basic access requiring no authentication.11 npmMIT
- AlicenseAqualityAmaintenanceMCP server for free U.S. case-law and court-docket search via CourtListener, providing tools for opinion search, docket lookup, citation verification, and more.104 npm1MIT
Try in Browser
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd
Glama MCP Gateway
Add one secure layer between your agents and this server.