courtlistener-mcp-server

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description adds significant context beyond annotations: it explains the two directional behaviors, warns about free tier limits (125 req/day), and advises on shallow vs. deep traversal. This compensates for the lack of idempotency hint (which is fine for a read operation).

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, well-structured paragraph that front-loads the core purpose and quickly covers usage tips. 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 that an output schema exists (which likely documents return fields), the description adequately covers the input semantics and rate-limit context. It could mention pagination cursor usage, but the schema already describes 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 coverage is 100%, so baseline is 3. The description adds value by explaining the meaning of direction values, giving use cases for filed_after, and warning about page_size's cost. This goes beyond the schema's labels.

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 the citation network for an opinion cluster, specifying two directions ('cited_by' and 'citing'). It distinguishes itself from sibling tools like courtlistener_lookup_citation, which is likely for finding a specific citation rather than traversing networks.

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 identifies this as the primary tool for tracing legal precedent chains and provides practical guidance on rate limits and traversal depth. However, it does not explicitly state when to use alternatives like courtlistener_search_opinions for broader searches or courtlistener_lookup_citation for direct lookups.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already indicate readOnlyHint=true and idempotentHint=true. The description adds value by explaining document availability status and PACER requirements, which are behavioral traits 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 very concise, with three sentences that front-load the primary purpose and include essential details without any fluff.

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 (2 parameters, output schema exists), the description covers what the tool returns, how to get the docket ID, and data availability implications. It feels 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 already documents both parameters. The description mainly reinforces that docket_id comes from search results, adding minimal extra semantics.

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 action ('Fetch full docket metadata and entry list') and the specific resource ('single federal case by docket ID'), which distinguishes it from sibling tools that handle citations, judges, opinions, 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 context on when to use the tool (to get docket details by ID) and how to obtain docket IDs from other tools. It does not explicitly state when not to use it or list alternatives, but the guidance is clear enough.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already indicate read-only and idempotent operations. The description adds concrete details about the biographical content returned, enhancing transparency without contradicting 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?

Two concise sentences front-load the core action and content, then provide necessary context for obtaining the ID. 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 the complex biographical data, the description covers the key elements. The presence of an output schema means return values are documented elsewhere, so no further details are needed.

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, so the description adds minimal value beyond restating the parameter's origin. It correctly explains how to obtain the person_id, but the schema already describes it well.

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 content (appointment history, education, etc.) and links to the sibling search tool for obtaining person IDs, effectively distinguishing it from other 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 instructs to obtain person IDs from courtlistener_search_judges, providing clear context for when to use this tool. Does not mention when not to use, but the connection to search is sufficient.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Beyond readOnlyHint and idempotentHint annotations, description details return fields (case name, panel judge IDs, duration, MP3 URL, linked docket, transcript when completed) and notes missing argument date.

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, front-loaded with primary action, no filler. Every sentence adds essential context.

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 single-parameter input and output schema existence, description lists return fields and clarifies data source, making it fully sufficient 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% so baseline 3. Description adds context by specifying parameter is audio_id from search results, enhancing schema's numeric range description.

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?

Explicitly states it fetches full detail record for a single oral argument by ID. Distinguishes from sibling search tool by specifying input source (audio_id from search results) and outputs.

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 tells agent to use audio_id from courtlistener_search_oral_arguments, and clarifies what is not included (argument date) and where to find it (search result or linked docket).

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint and idempotentHint, so the agent knows it is safe. The description adds critical context: two upstream calls per page and rate limit exposure. However, it does not mention error handling or response format beyond the brief listing.

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, front-loaded with the main purpose, followed by rate limit warning and source hint. No redundant or filler content. 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 the existence of an output schema, the description adequately explains return fields (name, role, attorneys, contact info) and the operational constraint (two upstream calls). It could briefly mention pagination behavior, but the parameter descriptions cover 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?

The input schema already describes all three parameters with 100% coverage. The description reinforces the page_size rate limit advice and the source of docket_id, but adds modest new semantic 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 explicitly states the action ('Fetch all parties and attorneys'), the resource ('RECAP federal docket by docket ID'), and the output structure. It also differentiates from sibling tools by noting 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?

The description provides clear guidance on obtaining docket IDs and recommends keeping page_size low to respect rate limits. While it does not explicitly exclude alternative tools for related tasks, the context of siblings implies specific use case. It could be improved by stating 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.

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.

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.

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.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint and openWorldHint. The description adds important behavioral context: line-item investments are summarized as counts and the full itemization is only in the linked PDF. This clarifies what the response contains and what it omits.

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 (3 sentences) and front-loaded with the main purpose. Each sentence provides necessary detail without redundancy. It efficiently conveys the tool's function, filtering options, return data, and use case.

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 4 optional parameters and existing output schema, the description sufficiently covers the tool's operation, return format, and limitations (summarized investments). It could mention pagination via cursor, but that is clear from the schema. Overall, it provides adequate context for an AI agent to decide when and how to use 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%, so baseline is 3. The description adds value by explicitly linking judge_id to courtlistener_search_judges and summarizing how the parameters (year, judge_id) are used together. It also mentions the default page_size, though that is in 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 federal judicial financial disclosure filings and lists the types of data included (investments, gifts, debts, etc.). It distinguishes itself from siblings by focusing specifically on financial disclosures and references the related tool courtlistener_search_judges for obtaining judge 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?

The description explicitly recommends using this tool for judicial-ethics and recusal research after identifying a judge's person ID. It mentions the prerequisite of using courtlistener_search_judges, but does not explicitly state when to avoid this tool or list alternatives.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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.

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.

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.