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.4/5 across 10 of 10 tools scored.
Each tool has a clearly distinct purpose: search tools for different entities (opinions, dockets, judges, oral arguments), retrieval tools for specific entities, citation resolution, and court listing. No overlap or ambiguity.
All tools follow a consistent verb_noun pattern with the courtlistener_ prefix, using snake_case throughout (e.g., search_opinions, get_docket, lookup_citation). No deviations or mixed conventions.
10 tools is well-scoped for a legal research server covering search, retrieval, citation analysis, and metadata lookup. Each tool earns its place without redundancy or excessive count.
The tool surface covers the main domain operations: search and retrieve opinions, dockets, judges, oral arguments, resolve citations, and list courts. Minor gaps exist, such as absence of batch retrieval or citation search, but core workflows are supported.
Available Tools
10 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 (1–20). Each citation tool call costs one request against the rate limit — keep page_size 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 |
|---|---|---|
| results | Yes | Related opinions in the citation network. |
| direction | Yes | Direction of the citation relationship returned. |
| next_cursor | Yes | Pagination cursor for the next page; null when no more results. |
| total_count | Yes | Total citations in the requested direction. |
| 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?
Annotations already declare readOnlyHint=true and openWorldHint=true. The description adds context about rate limit consumption (each call costs one request) and implicit pagination via cursor. It does not contradict 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: two sentences plus a critical note. It is front-loaded with the core purpose, and every sentence adds value.
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 6 parameters (1 required), output schema exists, and the description covers direction meanings, rate limit implications, and practical usage. 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 description coverage is 100%, and the tool description adds value beyond schema by explaining direction semantics in detail and advising to keep page_size low for multi-hop traversal due to rate limits.
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 retrieves the citation network for an opinion cluster and explains the two directions ('cited_by', 'citing') with their meanings. This distinguishes it from sibling tools like courtlistener_get_opinion or search 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?
Explicitly identifies it as the primary tool for tracing legal precedent chains and provides practical usage guidance about rate limits and traversal depth ('following 1–2 hops of a single case is practical; deep multi-hop analysis burns through the daily budget quickly').
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_size | No | Number of docket entries to return (1–50). Large cases can have hundreds of entries. |
Output Schema
| Name | Required | Description |
|---|---|---|
| cause | Yes | Legal cause of action. |
| court | Yes | Court display name. |
| entries | Yes | Docket entries up to entries_page_size. |
| court_id | Yes | Court identifier. |
| 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. |
| referred_to | Yes | Referred judge name; null if not recorded. |
| 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. Description adds context about document availability status and RECAP/PACER distinction, enhancing 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?
Three sentences, each serving a distinct purpose: core action, return details, and ID sourcing. No redundant information; front-loaded with essential info.
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 output schema present, description need not detail return format. Covers purpose, usage, and a key behavioral trait. Complete for this tool's complexity.
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 both parameters fully (100% coverage). Description adds no extra semantic detail beyond what schema provides, so baseline score of 3 is appropriate.
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 full docket metadata and entry list for a single federal case by docket ID', specifying action (fetch), resource (docket), and scope (full metadata/entries). Differentiates from siblings like search tools by mentioning where to obtain docket IDs.
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 says when to use (by docket ID) and provides hints for document availability (is_available flag) and ID source (search/opinion results). Lacks explicit 'when not to use' but sibling list implies alternatives.
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 rating codes (e.g., "wq"=well qualified, "q"=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 indicate read-only and idempotent behavior. The description adds value by enumerating the returned data (appointment history, education, etc.), providing useful behavioral context beyond 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.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise, with two sentences that front-load the purpose and provide clear usage guidance. 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 (one parameter, no nested objects, output schema present), the description fully covers what the tool does, what data it returns, and how to supply the input, leaving no significant gaps.
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 parameter semantics are already well-covered. The description adds minor context that person_id comes from search results, but it does not significantly improve understanding 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 fetches a full biographical profile for a single judge, listing specific data (appointment history, education, political affiliations, ABA ratings). It distinguishes from sibling search tool by specifying the input source, making 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?
It explains when to use the tool (to get a judge profile) and how to obtain the required person ID from search results. Although it doesn't explicitly state when not to use it, the context implies it's for single judge details, not searching, which is adequate guidance.
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 all opinion variants with HTML and plain text. Obtain cluster IDs from courtlistener_search_opinions, courtlistener_lookup_citation, or docket results.
| Name | Required | Description | Default |
|---|---|---|---|
| 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 |
|---|---|---|
| court | Yes | Court display name. |
| judges | Yes | Judge names. |
| posture | Yes | Procedural posture (may be empty). |
| court_id | Yes | Court identifier. |
| opinions | Yes | All opinion variants within this cluster. |
| 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. |
| precedential_status | Yes | Publication/precedential status. |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=true and idempotentHint=true, but the description adds behavioral context: 'Returns all opinion variants with HTML and plain text.' There is no contradiction with annotations. The description fully discloses the output scope without repeating annotation data.
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?
Two sentences, no filler. Key information is front-loaded: the action, resource, and identifier. Every sentence serves a 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?
With an output schema present, the description need not detail return values. It explains what is returned (full text, metadata, all variants, HTML/plain text) and the concept of a cluster. For a simple single-parameter tool, this is 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 has 100% coverage with a good description for the single parameter. The tool description adds value by explaining the concept of a cluster and advising where to obtain the ID, going beyond the schema's description. Given high schema coverage, the baseline is 3, and the added context justifies a 4.
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 verb ('Fetch'), resource ('full text and metadata for a single opinion cluster'), and identifies the key identifier ('cluster ID'). It distinguishes from sibling tools by explicitly naming the tools used to obtain cluster IDs (courtlistener_search_opinions, courtlistener_lookup_citation, docket results).
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 tells the agent how to obtain the required cluster ID by referencing sibling tools. It implies when to use this tool (when you need full text and metadata for a specific cluster). However, it does not explicitly state when not to use it or mention alternatives for similar tasks (e.g., getting citations or docket info). The guidance is clear but could be more comprehensive.
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. |
| 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. |
| 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 provide readOnlyHint and idempotentHint; description adds endpoint usage and supported formats. Does not contradict annotations. Could add error handling or rate limit info but not required.
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?
Two sentences, no filler. Front-loaded with the core action. Every sentence adds value.
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 one parameter, rich annotations, and output schema present, the description covers all necessary context: purpose, usage, authentication, endpoint, and format support.
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 provides 100% coverage with description. Description adds examples and mentions 'standard reporter formats', adding context 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 the verb 'resolve' and the resource 'legal citation string', with specific output (cluster ID and metadata). Distinguishes from sibling tools like courtlistener_search_opinions by emphasizing start from known citation.
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 says when to use: 'workflows that start from a known citation' vs. alternatives like search queries. Also mentions authentication requirement upfront.
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. |
| total_count | Yes | Total courts returned. |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare read-only and open-world. Description adds return fields but doesn't contradict annotations. No extra behavioral traits disclosed beyond what schema/annotations imply.
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?
Two concise sentences, front-loaded with action and purpose, no wasted words. Efficiently communicates key 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?
Given full schema coverage, output schema existence (implied), and annotations, the description is sufficient for a simple lookup tool. No missing critical information.
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 has 100% coverage with descriptions for all three parameters. Description briefly restates filtering options but adds no new meaning 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 'List courts' with optional filtering, and explicitly says it's used to discover court IDs for other tools, distinguishing it from sibling tools that perform different operations.
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 mentions primary usage for discovering court IDs for use in search/filter parameters across other tools, and hints at when to use optional filters. No direct alternatives, but 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_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 |
|---|---|---|
| results | Yes | Matching docket records. |
| next_cursor | Yes | Pagination cursor for the next page; null when no more results. |
| total_count | Yes | Total matching dockets. |
| 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 already declare readOnlyHint and openWorldHint. The description adds that RECAP is crowd-sourced with variable coverage, and mentions returning up to 3 sample documents per docket, which is behavioral context 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 two sentences, front-loading the purpose and adding necessary context about RECAP and sample documents. No unnecessary 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 the complexity and existing output schema, the description covers purpose, data source limitations, sample behavior, and a pointer to a related tool. It omits pagination details but schema covers cursor. 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% with detailed parameter descriptions. The tool description summarizes filtering capabilities but does not add significant new meaning beyond the schema. Baseline 3 is appropriate.
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 RECAP federal court dockets with filters for party, attorney, court, and dates, and explains RECAP's nature. It is distinct from sibling tools that search opinions, judges, etc.
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 guidance on using courtlistener_lookup_courts for court IDs, implying prerequisite. It does not explicitly mention when not to use or compare to alternatives, but the purpose is clear enough given sibling tool names.
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 |
|---|---|---|
| results | Yes | Matching judge records. |
| next_cursor | Yes | Pagination cursor for the next page; null when no more results. |
| total_count | Yes | Total matching judge records. |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, so the description is not required to repeat those. The description adds context about return data but does not disclose behavioral traits beyond what annotations provide. 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.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with two information-dense sentences and a clear alternative recommendation. It front-loads the action and key features without any unnecessary 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 the tool has 6 parameters with full schema coverage, an output schema exists, and the description provides return data summary and an alternative tool, the description is contextually complete for an AI agent to use 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?
Since the input schema has 100% description coverage for all 6 parameters, the description does not need to add parameter-level detail. It adds overarching context by listing filter types and outputs, but does not enhance individual parameter meaning 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 searches judge/person records with multiple filter options and specifies the return data (biographical, current position, appointment summary). It explicitly distinguishes from the sibling tool courtlistener_get_judge, which provides full history, 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?
The description provides clear guidance by directing users to courtlistener_get_judge for full details, implying this tool is for search and summary. However, it does not explicitly state when not to use this tool or compare with other search siblings like courtlistener_search_opinions, which slightly reduces completeness.
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 |
|---|---|---|
| results | Yes | Matching opinion cluster summaries. |
| next_cursor | Yes | Pagination cursor for the next page; null when no more results. |
| total_count | Yes | Total matching opinions in the corpus. |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already signal read-only and open-world. Description adds concrete behavioral details: full-text search, field syntax, boolean operators, and return of summaries with snippets. Rate limit info is also provided, 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?
Concise single paragraph, front-loaded with purpose, each sentence adds distinct value (scope, field syntax, rate limits, alternative tool reference). No unnecessary 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?
For a search tool with 8 parameters, the description covers purpose, filtering syntax, boolean operators, pagination, ordering, rate limits, and links to an auxiliary tool for court IDs. Output schema exists, so return values need not be detailed.
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 value beyond schema: e.g., explains that page_size always returns at least 20 results regardless of passed value, and describes order_by options with relevance to citations.
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 full-text search across 9M+ US court opinions with field-level filtering, snippet returns, and mentions specific field syntax and boolean operators, distinguishing from sibling tools that focus on citations, dockets, judges, or oral arguments.
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?
Advises using courtlistener_lookup_courts for court IDs and mentions rate limits. However, it does not explicitly state when to avoid this tool in favor of siblings, e.g., for docket search.
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 |
|---|---|---|
| results | Yes | Matching oral argument recordings. |
| next_cursor | Yes | Pagination cursor for the next page; null when no more results. |
| total_count | Yes | Total matching oral argument recordings. |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate read-only and open-world behavior; description adds that download URLs are direct MP3 links and transcript snippets are available only where available, clarifying data variability.
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?
Four focused sentences: one for purpose, one for outputs, two for additional details (download format and related tool usage). No redundant or filler content.
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 search scope, output format, pagination nuance, date filter semantics, and cross-tool usage; output schema documents return values, so description is sufficient for safe and 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?
All parameters have schema descriptions (100% coverage); description adds clarity for `q` (matched against case name and transcribed text), `page_size` (enforces minimum 20), and `argued_after/before` (filters by argument date), going beyond schema basics.
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 searches appellate oral argument audio recordings, specifies key outputs (metadata, download URLs, panel judge IDs, transcript snippets), and distinguishes itself from sibling tools like courtlistener_search_opinions by focusing on audio content.
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 guidance on using outputs (direct MP3 links, passing judge IDs to another tool) but does not explicitly contrast with sibling search tools or state when not to use this tool.
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!