courtlistener-mcp-server
Server Details
Search US court opinions, federal dockets, judges, citations, and oral arguments via CourtListener.
- Status
- Healthy
- Last Tested
- Transport
- Streamable HTTP
- URL
- Repository
- cyanheads/courtlistener-mcp-server
- GitHub Stars
- 1
Glama MCP Gateway
Connect through Glama MCP Gateway for full control over tool access and complete visibility into every call.
Full call logging
Every tool call is logged with complete inputs and outputs, so you can debug issues and audit what your agents are doing.
Tool access control
Enable or disable individual tools per connector, so you decide what your agents can and cannot do.
Managed credentials
Glama handles OAuth flows, token storage, and automatic rotation, so credentials never expire on your clients.
Usage analytics
See which tools your agents call, how often, and when, so you can understand usage patterns and catch anomalies.
Tool Definition Quality
Average 4.5/5 across 13 of 13 tools scored.
Each tool targets a distinct entity or operation (e.g., get vs search, opinions vs dockets vs judges), with no functional overlap. All 13 tools have clearly separate purposes.
All tools follow a consistent pattern: 'courtlistener_' plus a verb (get, lookup, search) followed by a noun. Verbs indicate operation type (fetch single item vs. search) and nouns clearly identify the entity.
13 tools is well-scoped for a legal research domain covering opinions, dockets, judges, citations, oral arguments, parties, and financial disclosures. Each tool earns its place without redundancy.
The server provides complete coverage for the intended use case: searching and retrieving key legal entities. It offers both lookup and search for citations, courts, opinions, dockets, judges, oral arguments, and financial disclosures with no obvious gaps.
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 (125 req/day) supports shallow traversal — following 1–2 hops of a single case is practical; deep multi-hop analysis burns through the daily budget quickly.
| 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. Each citation tool call costs one request against the rate limit — 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
| Name | Required | Description |
|---|---|---|
| notice | No | Recovery hint when no citations are found — echoes direction and filters, suggests alternatives. |
| results | Yes | Related opinions in the citation network. |
| direction | Yes | Direction of the citation relationship returned. |
| totalCount | Yes | Total citations in the requested direction. |
| next_cursor | Yes | Pagination cursor for the next page; null when no more results. |
| source_case_name | Yes | Case name for the source cluster. |
| source_cluster_id | Yes | The cluster ID this citation network is for. |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds significant behavioral context beyond annotations: rate limit details, page size behavior differences between directions, and practical traversal limitations. Annotations indicate readOnlyHint and openWorldHint, and the description complements them without contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a clear first sentence, but is slightly verbose. Every sentence adds value, but could be tightened without losing substance.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers all key aspects: direction semantics, rate limit impact, pagination behavior, parameter usage hints, and practical limitations. With an output schema present, return value documentation is handled elsewhere, so contextual completeness is high.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Despite 100% schema coverage, the description enriches parameter understanding: explains 'direction' choices with precedent relevance, reveals page_size quirks (minimum 20 for cited_by), and suggests usage for 'filed_after' parameter. It adds value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves a citation network for an opinion cluster, specifies two directions with their meanings, and positions it as the primary tool for tracing legal precedent chains, distinguishing it from sibling tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit usage context (tracing precedent chains) and practical guidance on rate limits (125 req/day) and traversal depth (1-2 hops practical). It implies not to use for deep multi-hop analysis but lacks explicit 'when not to use' or alternative suggestions.
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.
| 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
| Name | Required | Description |
|---|---|---|
| cause | Yes | Legal cause of action. |
| court | Yes | Court display name for major federal courts; the court identifier otherwise. |
| entries | Yes | Docket entries for this page (fixed at 20 per page; entries_page_size is not honored by upstream). |
| court_id | Yes | Court identifier — the stable value for filtering. |
| case_name | Yes | Short case name. |
| docket_id | Yes | Docket ID. |
| date_filed | Yes | Date the case was filed. |
| assigned_to | Yes | Assigned judge name; null if not recorded. |
| jury_demand | Yes | Jury demand status. |
| next_cursor | Yes | Next page number to pass as the `entries_page` argument (docket entries are page-paginated); null when this is the last page. |
| referred_to | Yes | Referred judge name; null if not recorded. |
| entries_page | Yes | Current entries page number (1-indexed). |
| docket_number | Yes | Docket number. |
| pacer_case_id | Yes | PACER case ID; null if not in RECAP. |
| total_entries | Yes | Total number of docket entries available — may exceed the returned entries list. |
| case_name_full | Yes | Full case name. |
| date_terminated | Yes | Date the case was terminated; null if active. |
| jurisdiction_type | Yes | Jurisdiction type. |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate read-only and idempotent behavior. Description adds valuable context about document availability (PACER vs RECAP) and pagination details, going beyond what annotations provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is two sentences with no wasted words. Parameter descriptions are concise yet informative, and the overall structure front-loads the core purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers all key aspects: metadata, entry list, document availability, pagination, and source of docket IDs. Output schema exists, so detailed return format isn't needed in description. Minor gap: could mention that pagination is 20 entries per page fixed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, but parameter descriptions add critical behavioral insights: entries_page explains proper pagination with next_cursor, and entries_page_size clarifies that the passed value is ignored, preventing misuse.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the tool fetches docket metadata and entries for a federal case by docket ID, with a specific verb and resource. It also explains how to obtain docket IDs from sibling tools, distinguishing this from other retrieval methods.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides clear context by stating the source of docket IDs (search results or opinion clusters), guiding when to use this tool. However, it does not explicitly exclude scenarios where a different tool might be preferred.
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).
| 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
| Name | Required | Description |
|---|---|---|
| kind | Yes | '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 | Yes | Filing year. |
| debts | No | Debts and liabilities. |
| gifts | No | Reported gifts. |
| counts | Yes | Count of line items in each disclosure category. |
| pdf_url | Yes | 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 | Yes | Person ID of the filer — pass to courtlistener_get_judge; null if absent. |
| positions | No | Outside positions. |
| agreements | No | Continuing agreements. |
| is_amended | Yes | True if this filing is an amendment. |
| page_count | Yes | Page count of the source filing; null if not recorded. |
| investments | No | Investment holdings. |
| report_type | Yes | Report type (Nomination, Initial, Annual, Final, or Unknown). |
| disclosure_id | Yes | 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 | Yes | True if line items were parsed from the PDF; category arrays are empty when false. |
| non_investment_incomes | No | Non-investment income sources. |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and idempotentHint, and the description adds valuable behavioral details: value decoding, overflow handling with outline vs full responses, and the re-call mechanism. No contradictions 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.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with the main purpose first, then parameter behavior, then edge-case handling. Every sentence adds value. Slightly longer than minimal but justified by the tool's complexity. Could be tightened slightly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
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, link to search), the description covers all essential aspects. The existence of an output schema means return values are documented separately. The description addresses the behavioral nuances that the schema and annotations cannot convey.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Both parameters are already documented in the schema (100% coverage). The description adds context: explains the purpose of categories (select specific categories, use for re-call) and clarifies that disclosure_id comes from the search tool. This goes beyond the baseline schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the tool fetches a single financial disclosure by ID with parsed line-item rows. Explicitly distinguishes from sibling courtlistener_search_financial_disclosures by noting the difference in output detail, making the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides clear guidance on when to use the tool, including obtaining disclosure IDs from the search tool. Describes how to use the categories parameter for partial retrieval and re-call logic. Could improve by explicitly stating when not to use, but the sibling distinction effectively serves that purpose.
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: appointment history across all courts, education, political affiliations, and ABA ratings. Obtain person IDs from courtlistener_search_judges results.
| 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
| Name | Required | Description |
|---|---|---|
| dob | Yes | Date of birth; null if not recorded. |
| dod | Yes | Date of death; null if living or not recorded. |
| name | Yes | Full name. |
| fjc_id | Yes | Federal Judicial Center ID for cross-referencing with FJC data; null if not available. |
| gender | Yes | Gender. |
| dob_city | Yes | City of birth; null if not recorded. |
| dob_state | Yes | State of birth; null if not recorded. |
| education | Yes | Educational history. |
| person_id | Yes | Person ID. |
| positions | Yes | All judicial positions held, across all courts. |
| aba_ratings | Yes | ABA qualification ratings, expanded to readable labels (e.g., "Well Qualified"). |
| political_affiliations | Yes | Political affiliation history. |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and idempotentHint, indicating a safe, idempotent read operation. The description adds behavioral context by detailing the types of biographical data included (appointment history, education, etc.), which is beyond what annotations provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two concise sentences with no wasted words. The first sentence states the purpose, and the second provides input guidance. It is front-loaded and efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of an output schema and annotations, the description adequately covers the tool's complexity. It lists key data points, states the prerequisite (search), and no obvious gaps remain for an agent to use it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema covers 100% of parameters with a clear description. The description adds value by explaining that person_id comes from search results and identifies a judge across courts, enriching the parameter's meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Fetch' and specifies the resource 'full biographical profile for a single judge' including appointment history, education, political affiliations, and ABA ratings. It clearly distinguishes from sibling tool courtlistener_search_judges by stating the input source.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context by stating that person IDs should be obtained from courtlistener_search_judges results, implying its use after search. While it doesn't explicitly list when not to use, the guidance is sufficient for typical scenarios.
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.
| 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
| Name | Required | Description |
|---|---|---|
| kind | Yes | '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 | Yes | Court display name. |
| judges | Yes | Judge names. |
| posture | Yes | Procedural posture (may be empty). |
| court_id | Yes | 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 | Yes | Syllabus text (may be empty). |
| case_name | Yes | Short case name. |
| citations | Yes | All known citation strings for this case. |
| docket_id | Yes | Associated docket ID. |
| cite_count | Yes | Total number of citations from other opinions. |
| cluster_id | Yes | Opinion cluster ID. |
| date_filed | Yes | Date the opinion was filed. |
| docket_number | Yes | Docket number. |
| case_name_full | Yes | Full case name with parties. |
| retrieval_notice | No | How to re-call the tool for specific opinion variants when the opinions overflow. |
| precedential_status | Yes | Publication/precedential status. |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and idempotentHint. Description adds behavioral detail: overflow handling with outline response and sections parameter. 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.
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with a clear first sentence, followed by explanation of cluster and overflow behavior. Slightly verbose but every sentence adds value; could be tightened slightly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 2 parameters and rich annotations, the description covers return content, overflow handling, and how to get IDs. Even with an output schema (not shown), it provides sufficient context for agent invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions for both parameters. Description adds value by explaining that cluster_id groups opinion variants and sections parameter retrieves specific variants from an outline, enhancing understanding beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states 'Fetch the full text and metadata for a single opinion cluster by cluster ID.' It distinguishes from sibling tools by specifying how to obtain cluster IDs (search, lookup, docket) and explains what a cluster groups.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides context on when to use the sections parameter (when response is an outline due to size) and how to re-call. Mentions sources for cluster IDs. Does not explicitly exclude alternatives but gives sufficient guidance.
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 overflows to a section outline; re-call with sections:["transcript"] to retrieve it in full. The argument date is not on this record — it comes from the search result or the linked docket.
| 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 in full, from a prior outline response (e.g. ["transcript"]). Omit for the full record, or an outline if it overflows the inline budget. |
Output Schema
| Name | Required | Description |
|---|---|---|
| kind | Yes | 'full' returns the record (or the selected sections); 'outline' lists retrievable sections when the transcript overflows the inline byte budget. |
| judges | No | Free-text judge names; often empty on this endpoint. |
| sections | No | Retrievable sections, largest first — pass names to `sections` on a re-call. |
| 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. |
| 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 specific sections when the record overflows. |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark the tool as read-only and idempotent. The description adds valuable behavioral details: what fields are returned, that long transcripts overflow and must be re-fetched with a sections parameter, and which information is absent (argument date). This goes beyond annotations and helps the agent understand the tool's limits and response behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three concise sentences. The first sentence front-loads the purpose and key return fields. The second sentence handles the edge case of transcript overflow. The third clarifies a missing data point. No redundant information—every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that the tool has an output schema (indicated but not shown) and the description explains return fields, transcript overflow handling, and missing date, it is complete for a detail retrieval tool. The description covers all necessary behavioral context without needing extra details.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions for both parameters. The tool description adds crucial context beyond the schema: explaining that 'id' is the audio_id from a search result and that 'sections' come from a prior outline response. This clarifies the origin and intended usage of parameters, significantly aiding correct invocation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it fetches the full detail record for a single oral argument by ID, using the verb 'fetch' and specifying the resource. It distinguishes from sibling tools by referencing the search tool for obtaining the ID and mentioning specific fields returned (case name, docket, etc.) that are not in other 'get' tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains when to use the tool (to get details of a single oral argument by ID) and provides guidance on handling transcript overflow by re-calling with sections. It also notes that the argument date is not on this record, directing users to the search result or linked docket. While it does not explicitly list alternatives, the context of sibling tools and the referenced search tool provide enough context.
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. Requires two upstream calls per page (parties + attorney batch); keep page_size low to stay within the free-tier rate limit (5 req/min, 125/day). Obtain docket IDs from courtlistener_search_dockets or courtlistener_get_docket.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Page number (1-indexed). Use with page_size to paginate large party lists. | |
| docket_id | Yes | Docket ID from a courtlistener_search_dockets or courtlistener_get_docket result's docket_id field. | |
| page_size | No | 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. |
Output Schema
| Name | Required | Description |
|---|---|---|
| page | Yes | Current page number. |
| parties | Yes | Parties on this page. |
| docket_id | Yes | Docket ID these parties belong to. |
| totalCount | Yes | Total parties on this docket across all pages. |
| next_cursor | Yes | Next page number to pass as the `page` argument (this list is page-paginated); null when this is the last page. |
| total_parties | Yes | 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). |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint and idempotentHint. Description adds behavioral traits: two upstream calls per page, rate limit constraints (free-tier: 5 req/min, 125/day). No contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is a single paragraph but efficient. Every sentence adds value. Could slightly benefit from bullet points but still clear.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Description covers all aspects: purpose, usage, rate limits, input source, and behavioral details. Output schema exists, so return values are not needed. Complete for this tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%. Description adds meaning beyond schema: mentions that docket_id comes from other tools, and page_size affects rate limit. Also explains that each call makes two upstream requests.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description uses specific verb 'Fetch' and resource 'parties and attorneys of record' for a RECAP federal docket. It distinguishes from siblings by mentioning that docket IDs come from courtlistener_search_dockets or courtlistener_get_docket.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Description states when to use (to get parties for a docket) and provides context about rate limits and upstream calls. It does not explicitly say when not to use, but the context is clear.
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 a formatted legal citation string (e.g., "410 U.S. 113", "93 S. Ct. 705") to a cluster ID and case metadata. Enables workflows that start from a known citation rather than a search query. Supports standard US reporter formats. Requires authentication — uses the CourtListener /citation-lookup/ endpoint.
| Name | Required | Description | Default |
|---|---|---|---|
| citation | Yes | Legal citation string to resolve (e.g., "410 U.S. 113", "347 U.S. 483", "93 S. Ct. 705"). Supports standard reporter formats. |
Output Schema
| Name | Required | Description |
|---|---|---|
| court | Yes | Court display name; null if not found. |
| notice | No | Recovery hint when the citation is not in the database — suggests alternative lookup strategies. |
| case_name | Yes | Case name; null if not found. |
| citations | Yes | All known citation strings for this case. |
| cluster_id | Yes | Opinion cluster ID — null if the citation is not in the CourtListener database. |
| date_filed | Yes | Date the opinion was filed; null if not found. |
| queriedCitation | Yes | The citation string that was looked up. |
| normalized_citation | Yes | Canonical citation form used by CourtListener; null if not resolved. |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and idempotentHint. The description adds that it uses the CourtListener /citation-lookup/ endpoint, requires authentication, and supports standard US reporter formats, providing useful context beyond the structured annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three concise sentences: first states purpose, second provides use case, third offers format and endpoint details. Every sentence adds value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (single parameter, no enums, output schema exists) and rich annotations, the description covers what the tool does, when to use it, authentication requirements, and input format. No gaps remain.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the description reinforces the single parameter with examples and format support, adding value by clarifying the expected input format (e.g., '410 U.S. 113').
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states the tool resolves a legal citation string to a cluster ID and case metadata, with a specific verb 'resolve' and resource 'formatted legal citation string'. It distinguishes from sibling search tools by emphasizing it works from a known citation, not a search query.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says 'Enables workflows that start from a known citation rather than a search query', guiding when to use it. It also mentions authentication and standard reporter formats, but does not explicitly list alternatives or when not to use.
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 and scraper status. Primarily used to discover court IDs for use in search and filter parameters across all other courtlistener tools. Returns court IDs, full names, citation strings, and scraper status.
| Name | Required | Description | Default |
|---|---|---|---|
| in_use | No | When true (default), only return courts currently scraped by CourtListener. Set to false to include historical or inactive courts. | |
| jurisdiction | No | 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. | |
| has_opinion_scraper | No | Filter to courts with active opinion scraping. Useful when planning search queries — courts without scrapers have sparse coverage. |
Output Schema
| Name | Required | Description |
|---|---|---|
| courts | Yes | Matching courts. |
| notice | No | Recovery hint when no courts match the applied filters. |
| totalCount | Yes | Total courts returned. |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=true and openWorldHint=true, so the description adds value by specifying return fields (court IDs, full names, citation strings, scraper status) and the filtering options. It does not mention pagination or rate limits, but for a listing tool, the additional context is helpful and consistent 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.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences: the first states the action and filtering, the second explains the primary use and return fields. Every word adds value with no redundancy. Information is front-loaded and efficiently structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple lookup tool with three optional parameters and a stated output of specific fields (court IDs, names, citation strings, scraper status), the description covers all necessary aspects. The existence of an output schema (as indicated by context signals) further reduces the burden, and the description provides enough context for effective use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema has 100% description coverage, so baseline is 3. The description summarizes filtering by 'jurisdiction type and scraper status' but does not add significant new meaning beyond the schema's own descriptions for each parameter. The schema already explains the in_use default and jurisdiction enum values.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool 'List courts with optional filtering by jurisdiction type and scraper status.' It identifies the specific verb (List) and resource (courts), and distinguishes it from siblings by noting it is used to discover court IDs for use across other CourtListener tools, which no other sibling tool does.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says 'Primarily used to discover court IDs for use in search and filter parameters across all other courtlistener tools,' providing clear context on when to use this tool. However, it does not explicitly state when not to use it or mention alternatives, but given the sibling tools are all specific lookups, the use case is well-defined.
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 with party name, attorney, court, and date filters. RECAP is a crowd-sourced mirror of PACER (the federal court filing system) — coverage varies by court and date. Returns docket metadata with up to 3 sample document entries per docket. Use courtlistener_lookup_courts to find court IDs.
| 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
| Name | Required | Description |
|---|---|---|
| notice | No | Recovery hint when results are empty — echoes filters and suggests how to broaden. |
| results | Yes | Matching docket records. |
| totalCount | Yes | Total matching dockets. |
| next_cursor | Yes | Pagination cursor for the next page; null when no more results. |
| coverage_note | Yes | Note about RECAP coverage limitations. |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate readOnlyHint and openWorldHint. The description adds context about RECAP being a crowd-sourced mirror of PACER with variable coverage, and that it returns up to 3 sample document entries per docket, which provides transparency beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise (three sentences), front-loaded with purpose, and each sentence adds essential information. No redundant or irrelevant details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (7 parameters, output schema exists), the description adequately covers data source caveats, return structure (metadata with sample documents), and provides a cross-reference to another tool. Minor: doesn't explicitly mention date filter parameters, but overall sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, but the description adds value beyond schema by noting that page_size enforces a minimum of 20 results, and that party_name is more precise than including names in q. This aides parameter understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool searches RECAP federal court dockets with specific filters (party name, attorney, court, date). It distinguishes itself from sibling tools like courtlistener_search_opinions by focusing on dockets.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly mentions using courtlistener_lookup_courts to find court IDs, which is helpful guidance. It also notes coverage varies by court and date, but does not specify 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_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. 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.
| Name | Required | Description | Default |
|---|---|---|---|
| year | No | 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. | |
| 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
| Name | Required | Description |
|---|---|---|
| notice | No | Recovery hint when no filings are found — echoes filters and suggests next steps. |
| results | Yes | 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 | Yes | Pagination cursor for the next page; null when no more results. |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and openWorldHint, so the description adds beyond that: it discloses that returns include per-filing metadata, category counts, itemized gifts, link to PDF, and that line-item investments are summarized as counts with full itemization in the PDF. 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.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single paragraph with clear, front-loaded sentences. Every sentence adds value: purpose, content, filter options, return details, and use case. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 4 parameters and an output schema, the description covers what is returned and the overall workflow (get judge ID first). It could briefly mention that results are paginated (cursor) but the schema covers cursor. Still, it is fairly complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, baseline 3. The description adds significant meaning by explaining judge_id's source (courtlistener_search_judges), year's purpose, and page_size behavior (minimum 20 regardless of value). This goes well beyond the schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Search' with a clear resource 'federal judicial financial disclosure filings' and details the content (investments, gifts, debts, outside positions, income). It distinguishes from sibling tools by focusing on financial disclosures for judicial ethics and recusal research, referencing the judge ID from a sibling tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains when to use this tool: for judicial-ethics and recusal research after identifying a judge's person ID via courtlistener_search_judges. It implies context (after ID) but does not explicitly state when not to use or name alternatives beyond the judge ID lookup.
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.
| 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
| Name | Required | Description |
|---|---|---|
| notice | No | Recovery hint when results are empty — echoes filters and suggests how to broaden. |
| results | Yes | Matching judge records. |
| totalCount | Yes | Total matching judge records. |
| next_cursor | Yes | Pagination cursor for the next page; null when no more results. |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true. Description adds context about return data (biographical, current position, appointment summary) but does not elaborate on pagination or other behavioral traits. With annotations covering safety, the description adds moderate value.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three concise sentences with no redundancy. Front-loaded with purpose and key search attributes, followed by return data and alternative tool reference.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Output schema exists, so return values are covered elsewhere. Description covers purpose, searchable fields, and suggests an alternative. For a search tool with 6 parameters, it is sufficiently complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema fully documents each parameter. The tool description does not add additional semantics beyond what is in the schema, meeting the baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the tool searches judge/person records with specific attributes (name, appointing president, court, etc.) and explicitly differentiates from sibling courtlistener_get_judge by noting that tool provides full appointment history and education records.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use this tool (search) and suggests courtlistener_get_judge for full history. Does not explicitly state when not to use, but context is clear enough.
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, and matched text snippets. 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. Rate limit: 5 req/min, 50/hr, 125/day on the free tier.
| 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
| Name | Required | Description |
|---|---|---|
| notice | No | Recovery hint when results are empty — echoes filters and suggests how to broaden. |
| results | Yes | Matching opinion cluster summaries. |
| totalCount | Yes | Total matching opinions in the corpus. |
| next_cursor | Yes | Pagination cursor for the next page; null when no more results. |
| effectiveQuery | Yes | Query terms sent to CourtListener. |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=true (safe read). Description adds critical behavioral details: rate limits (5/min, 50/hr, 125/day), minimum page size enforcement (always at least 20 results), and cost per request. 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.
Is the description appropriately sized, front-loaded, and free of redundancy?
Extremely concise (under 50 words), front-loaded with main purpose, no superfluous sentences. Every sentence adds useful information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 8 parameters, output schema present, and many sibling tools, the description covers all critical aspects: query syntax, filtering, pagination, ordering, rate limits, and cross-reference to another tool. Minor omission: no mention of error cases or empty results.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, but description adds significant value: explains field syntax and boolean operators, gives extra context for status values (e.g., 'Unpublished: not citable as precedent'), and clarifies page_size behavior beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states verb (search), resource (US court opinions), scope (9M+, full-text with field-level filtering), and output (opinion cluster summaries). Distinguishes from sibling tools like courtlistener_get_opinion or 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.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly advises using courtlistener_lookup_courts for court IDs and notes rate limits. Mentions omitting cursor for first page. Does not fully compare with all sibling tools, but provides actionable guidance.
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 download URLs, panel judge IDs, and transcript snippets where available. Download URLs are direct MP3 links. Panel judge IDs can be passed to courtlistener_get_judge for biographical context.
| 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
| Name | Required | Description |
|---|---|---|
| notice | No | Recovery hint when results are empty — echoes filters and suggests how to broaden. |
| results | Yes | Matching oral argument recordings. |
| totalCount | Yes | Total matching oral argument recordings. |
| next_cursor | Yes | Pagination cursor for the next page; null when no more results. |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate readOnlyHint: true, and the description adds behavioral details beyond annotations: download URLs are direct MP3 links, page_size is enforced at minimum 20 regardless of input, and panel judge IDs can be used for biographical context. 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.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences long, front-loaded with the main purpose, and each sentence adds value without wasted words. It is well-structured and easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 6 parameters, an output schema, and 12 sibling tools, the description covers the core functionality and adds behavioral notes (page_size enforcement, direct MP3 links). It mentions transcript snippets but does not detail the meaning of panel judge IDs beyond the chaining hint. Slightly more detail could be given about the response structure, but the output schema presumably provides that.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers all 6 parameters (100% coverage), so the description does not need to explain parameter basics, but it adds contextual value: it notes that download URLs are direct MP3 links and panel judge IDs can be passed to courtlistener_get_judge. This exceeds the baseline of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it searches appellate oral argument audio recordings and lists what is returned (metadata, download URLs, panel judge IDs, transcript snippets). It distinguishes from sibling tools like courtlistener_get_oral_argument which likely retrieves a single recording.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description says 'Search appellate oral argument audio recordings' and provides details about the output, including a chaining hint to courtlistener_get_judge. However, it does not explicitly state when to use this tool versus alternative search or retrieval tools, nor when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Claim this connector by publishing a /.well-known/glama.json file on your server's domain with the following structure:
{
"$schema": "https://glama.ai/mcp/schemas/connector.json",
"maintainers": [{ "email": "your-email@example.com" }]
}The email address must match the email associated with your Glama account. Once published, Glama will automatically detect and verify the file within a few minutes.
Control your server's listing on Glama, including description and metadata
Access analytics and receive server usage reports
Get monitoring and health status updates for your server
Feature your server to boost visibility and reach more users
For users:
Full audit trail – every tool call is logged with inputs and outputs for compliance and debugging
Granular tool control – enable or disable individual tools per connector to limit what your AI agents can do
Centralized credential management – store and rotate API keys and OAuth tokens in one place
Change alerts – get notified when a connector changes its schema, adds or removes tools, or updates tool definitions, so nothing breaks silently
For server owners:
Proven adoption – public usage metrics on your listing show real-world traction and build trust with prospective users
Tool-level analytics – see which tools are being used most, helping you prioritize development and documentation
Direct user feedback – users can report issues and suggest improvements through the listing, giving you a channel you would not have otherwise
The connector status is unhealthy when Glama is unable to successfully connect to the server. This can happen for several reasons:
The server is experiencing an outage
The URL of the server is wrong
Credentials required to access the server are missing or invalid
If you are the owner of this MCP connector and would like to make modifications to the listing, including providing test credentials for accessing the server, please contact support@glama.ai.
Discussions
No comments yet. Be the first to start the discussion!