courtlistener-mcp-server

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

The description goes beyond the readOnlyHint annotation by explaining the two directions' precedential meaning and adding a critical operational warning about rate limits and daily budget. This provides behavioral context not present in the annotations, though some details like pagination are left to the schema.

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 the purpose, then directions, then usage guidance and a budget note. Every sentence earns its place with no filler or repetition.

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 multiple parameters and an output schema, the description covers purpose, directions, usage context, and rate-limit implications. The existence of an output schema means return-value details are already handled, so the description is sufficiently complete for guiding an agent.

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 input schema already documents all parameters with detailed semantics (e.g., direction enum, page_size behavior, cluster_id origin). The description does not add parameter-level detail, so the baseline of 3 applies.

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 opens with 'Retrieve the citation network for an opinion cluster' — a specific verb+resource that clearly distinguishes it from sibling tools like courtlistener_get_opinion. It further clarifies the two directions ('cited_by' and 'citing') and their legal significance, making the tool's 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 explicitly identifies this as 'the primary tool for tracing legal precedent chains,' giving clear usage context. It also cautions about free-tier depth limitations ('deep multi-hop analysis burns through the daily budget quickly'), which helps set expectations. It does not explicitly name alternatives or state when not to use the tool, but 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 already declare readOnlyHint and idempotentHint, so the safety profile is known. The description adds valuable behavioral details about the is_available field and the RECAP vs. PACER distinction, which goes beyond the annotations. It also implies pagination through 'all available' but the schema clarifies the actual paging 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 sentences, with the action front-loaded in the first sentence. Every sentence contributes key information: what it returns, the availability caveat, and how to obtain IDs. No filler or 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?

The output schema exists, and the description conveys the core data shape and the RECAP/PACER context. While the main text doesn't discuss pagination explicitly, the parameter schema covers it thoroughly. Given the tool's complexity, the description is adequately complete and actionable.

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% with detailed per-parameter explanations, including the fixed 20-entry page size behavior. The description adds context that docket_id comes from search results or opinions, which is not in the schema. This pairing makes parameter semantics very clear.

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 full docket metadata and entry list for a single federal case by docket ID, using a specific verb-resource structure. It distinguishes itself from search tooling by explicitly noting docket IDs come from courtlistener_search_dockets or opinion results, avoiding confusion with 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 gives clear context that this tool is for fetching by an existing docket ID, and tells the user where to obtain those IDs. It doesn't explicitly state when-not-to-use or list alternatives like get_parties, but the instruction to get IDs from search implies it is not a search tool. This is sufficient for most use cases.

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, but the description adds meaningful behavioral context: decoded value/income columns into readable dollar ranges, overflow handling where large responses become outlined sections with byte sizes, and the need to re-call for full categories. This is beyond what annotations provide and no contradictions exist.

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 compact yet information-dense, front-loaded with the core purpose, then covering category selection, decoding, overflow behavior, and ID sourcing. Every sentence earns its place without redundancy or filler.

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 parameter count, schema richness, and output schema presence, the description fully covers the usage workflow, including how to obtain IDs, optional category filtering, and handling large responses. It leaves no significant gaps for the agent to invoke the tool 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?

Schema coverage is 100% with descriptions for both parameters, so baseline is 3. The description adds extra value by explaining the 'omit for all' behavior for categories, framing categories as the re-call selector, and concretely mapping disclosure_id to the search result field. This goes beyond the schema but is not dramatically richer.

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 starts with a specific verb ('Fetch a single judicial financial disclosure by ID') and enumerates the parsed line-item rows (investments, debts, positions, etc.). It explicitly distinguishes itself from courtlistener_search_financial_disclosures as the itemized companion, so it is clearly differentiated from siblings.

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 provides direct usage guidance: obtain disclosure IDs from courtlistener_search_financial_disclosures, pass categories to select specific categories or omit for all, and re-call with categories after an outline response for full itemization. This tells the agent when and how to use the 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 indicate read-only and idempotent behavior. The description adds useful context about pagination of the position list and truncation reporting, which is not captured in annotations. This helps the agent interpret response characteristics without contradicting any annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise and front-loaded with the core purpose, followed by relevant behavioral details and a clear source for the parameter. Every sentence contributes meaningful information without waste.

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 availability of an output schema and annotations, the description adequately covers the tool's scope, including pagination behavior and truncation reporting, and directs the user to the appropriate search tool for obtaining IDs. It is complete for a read-only fetch operation.

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 already provides a clear description of person_id, including its source and meaning. The tool description's mention of obtaining IDs from search results is redundant with the schema. No additional parameter semantics are added beyond what the schema already provides.

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 types (positions, education, affiliations, ABA ratings). It distinguishes itself from sibling search tools by emphasizing 'single judge' and 'full biographical profile'.

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 instructs users to obtain person IDs from courtlistener_search_judges results, providing a clear workflow. It does not mention explicit exclusions or alternatives, but the context is sufficient for an agent to understand when 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?

The description discloses the overflow/outline behavior, the meaning of sections, and the return structure. It goes well beyond the readOnlyHint/idempotentHint annotations by explaining what happens when the response is too large and how to retrieve specific variants, which is non-obvious 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?

Although several sentences long, every sentence contributes unique information. The main purpose is front-loaded, followed by the cluster explanation, return format, overflow handling, and ID sourcing. No redundant or filler language.

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 two-parameter read-only tool with an output schema, the description covers all necessary context: what data is returned, how to handle large responses, and where to find the input ID. It is self-sufficient and leaves no major 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 coverage is 100%, so the baseline is 3. The description adds meaningful context for both parameters: cluster_id is tied to the cluster concept and section identifiers are explained as coming from a prior outline response. This enhances the schema's 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 opens with a specific verb and resource: 'Fetch the full text and metadata for a single opinion cluster by cluster ID.' It clarifies the cluster concept and distinguishes this from sibling tools by explaining why you'd use it (obtaining a specific cluster) and how to get cluster IDs via 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?

It explicitly names the alternatives for obtaining cluster IDs (courtlistener_search_opinions, courtlistener_lookup_citation, docket results) and provides clear guidance on when to use sections for oversized responses. This directly tells the agent how to integrate with sibling tools.

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 the readOnly/idempotent annotations, the description discloses the record's field composition, the conditional withholding of long transcripts, and the exact re-call behavior with sections:['transcript']. It also notes the absence of argument date, a useful behavioral caveat. This goes well beyond the annotation hints.

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 sentences, each carrying distinct information: primary purpose, key return fields, transcript special case, and date caveat. No redundancy or filler.

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 get-by-id tool with an output schema and annotations, the description covers the main use case, return fields, special transcript behavior, and the date limitation. It leaves no obvious gap for an agent to misuse the 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?

The schema already provides full descriptions for both parameters (100% coverage). The description adds crucial semantic linkage: id is defined as the audio_id from the search tool, and sections is explained in terms of transcript retrieval and the distinction between omitting vs including. This enriches parameter understanding beyond the schema alone.

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 opens with 'Fetch the full detail record for a single oral argument audio recording by its ID' — a specific verb+resource. It clarifies the ID source from courtlistener_search_oral_arguments, distinguishing it from other get_* tools. This is a clear, specific purpose statement.

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 states the ID comes from courtlistener_search_oral_arguments, implying the natural workflow of searching first. It also warns that the argument date is not on this record and must come from the search result or the linked docket, providing explicit guidance on where to find that data. No direct comparison to alternatives, but the reference to the search counterpart and the distinction from other get tools provide adequate context.

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 the readOnlyHint and idempotentHint annotations, the description discloses important behavioral traits: 'Costs two upstream requests per call (parties + attorney lookup) against a rate-limited free tier, and one more for each extra page' and notes that 'CourtListener paginates this endpoint at a fixed size and does not honor the requested value.' This adds significant value for the agent's decision-making.

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 sentences, each earning its place: purpose, cost/behavior, and source of docket IDs. It is front-loaded with the primary function and includes no filler or repetition. The form is compact yet information-dense.

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 pagination complexity, rate-limit implications, and the presence of a rich output schema, the description covers all necessary context: scope, input source, cost, pagination quirks, and page-size behavior. The output schema handles return-value details, and the description fills behavioral gaps completely.

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 covers 100% of parameters with descriptions. The tool description adds extra context beyond schema, e.g., explaining that page_size is not honored ('does not honor the requested value') and that cursor is an opaque token, not a page number. This enriches parameter understanding beyond the schema's 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?

The description clearly states the tool's function: 'Fetch all parties and attorneys of record for a RECAP federal docket by docket ID.' It specifies the resource (parties/attorneys), scope (docket), and output (names, roles, attorneys with contact info), distinguishing it from sibling tools like get_docket (docket metadata) and get_opinion (opinion 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?

It provides explicit guidance on obtaining docket IDs: 'Obtain docket IDs from courtlistener_search_dockets or courtlistener_get_docket.' It also warns about rate-limiting costs and pagination behavior. However, it does not explicitly state when to choose this tool over alternatives, though the purpose is clear enough that no exclusions are needed.

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 the readOnly/idempotent annotations, the description discloses rich behavioral detail: it extracts every citation from a passage and returns a result per citation, unresolved citations are reported not errors, quota mechanics (per-citation plus per-docket requests, max_court_lookups budget), and authentication requirement. This greatly exceeds annotation coverage.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is longer than two sentences but every sentence adds a distinct piece of information: purpose, use-case, extraction behavior, error handling, formats, quota, authentication. It is front-loaded with the core purpose, and while dense, it is well-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 tool with this complexity (citation extraction, quota nuances, optional court resolution), the description covers all critical operational aspects: what it returns (cluster IDs and metadata), how errors are surfaced (reported not raised), limits (max_court_lookups, char limit), and auth. The output schema exists, so return values need no further elaboration.

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 meaningful semantic context: citation length limit (64000 chars) and behavior for passed passages, plus max_court_lookups budget semantics and default/ceiling. This enriches 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 opens with a specific verb+resource: 'Resolve legal citations... to opinion cluster IDs and case metadata.' This clearly distinguishes it from sibling search and get tools. The examples of citation formats further anchor the purpose.

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 explicitly states the workflow context: 'Enables workflows that start from a known citation rather than a search query,' which contrasts with search tools. It does not name alternatives directly, but the 'rather than a search query' phrasing implies the distinction. No explicit when-not-to-use, but the use case is clear.

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/openWorldHint, the description discloses the snapshot-vs-live paging behavior, 20-row fixed page size, default active bench, and unreachable/testing court edge cases. This is extensive behavioral context that annotations alone don't 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?

Every sentence is information-dense and earns its place: purpose, default behavior, snapshot/paging distinction, and caveats. Despite its length, it is tightly structured and front-loaded with the most important 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?

For a read-only lookup with four optional params and an output schema, the description covers defaults, filtering options, paging behavior, data freshness, and edge cases (testing codes, unreachable courts). It is complete enough for an agent to select and invoke 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?

Schema description coverage is 100% and each parameter already carries detailed enum meanings and defaults. The description adds strategic guidance (e.g., prefer narrow values) but does not materially extend parameter-level semantics beyond the schema, so the baseline of 3 applies.

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 opens with a specific verb and resource: 'List courts' with optional filters, and immediately states its primary purpose: discovering court IDs for search/filter parameters across all other courtlistener tools. This clearly distinguishes it from sibling get/search tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives clear when-to-use context ('Primarily used to discover court IDs') and practical filter guidance (prefer narrowest status, narrow by jurisdiction rather than paging). It stops short of explicitly naming alternative tools or stating when not to use the tool itself, so not a 5.

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

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

No annotations are contradicted. It adds value by revealing that RECAP is a 'crowd-sourced mirror of PACER — coverage varies by court and date' and that results are metadata plus 'up to 3 sample document entries per docket,' which go beyond the readOnlyHint and openWorldHint 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?

Four sentences, front-loaded with the core operation, and each sentence contributes: scope, query/filter behavior, data-source caveat, return contents, and a cross-tool pointer. No filler or repetition.

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 a full output schema, 100% schema coverage, and readOnlyHint/openWorldHint annotations, the description covers the data source caveat, return shape ('parties, attorneys, firms of record, plus up to 3 sample documents'), and a court-ID lookup pointer. It does not discuss pagination behavior, but the schema's cursor and page_size descriptions handle 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 the baseline is 3. The description summarizes that 'Query terms match case name, docket number, party, and attorney names; filters narrow by party name, court, and filing date,' but the schema already describes each parameter with examples and caveats; the description adds no syntax details 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 opens with 'Search RECAP federal court dockets' — a specific verb+resource — and details what query terms match, what filters exist, and what is returned. This clearly distinguishes it from sibling tools like courtlistener_get_docket or search_opinions.

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 states 'Use courtlistener_lookup_courts to find court IDs,' giving explicit cross-tool guidance for a prerequisite. It also describes the scope ('Search RECAP federal court dockets') and query semantics, making the intended use clear. However, it doesn't explicitly contrast with alternatives like get_docket for known dockets.

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 declare readOnlyHint and openWorldHint, but the description adds substantial behavioral detail: the year filter is client-side only and may require cursor pagination; CourtListener enforces a minimum of 20 results per page; line-item investments are summarized as counts with the full itemization in the PDF. This goes far beyond the annotations and sets accurate expectations.

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 moderately long but every sentence provides necessary operational detail (pagination caveat, year filter behavior, return summary). It is front-loaded with the purpose and then covers limitations. It earns its length, though it could be slightly tightened without losing 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 the tool's complexity (server-side filtering limitations, pagination, summarization of investments) and the presence of an output schema, the description covers return contents, pagination behavior, year filter caveat, and the source of judge_id. It leaves no major gaps for an agent selecting and invoking 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 description coverage is 100%, so the baseline is 3. The description supplements the schema by explaining that the year filter is applied only to the fetched page (requiring cursor pagination) and that judge_id comes from courtlistener_search_judges. It also clarifies page_size minimum. This adds practical meaning beyond the schema's property 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 opens with a specific verb and resource: 'Search federal judicial financial disclosure filings' and lists what the filings contain (investments, gifts, debts, outside positions, income). This clearly distinguishes it from sibling tools like courtlistener_get_financial_disclosure (which likely retrieves a single disclosure) and courtlistener_search_judges (which finds judges).

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 states when to use it: 'Use this for judicial-ethics and recusal research after identifying a judge's person ID.' It also directs the user to courtlistener_search_judges for obtaining the person ID. It does not explicitly name alternatives (e.g., get_financial_disclosure for a single filing), but the context makes the search purpose clear.

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, so the agent knows this is a safe read operation. The description adds that it returns biographical data, current position, and appointment summary, but this is largely redundant with the output schema. No additional behavioral context (e.g., pagination behavior, rate limits) is provided beyond what annotations and schema already convey.

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 clear, front-loaded sentences. The first sentence states the action and scope; the second identifies the complementary tool. No wasted words, perfectly sized.

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 rich input schema, output schema, and annotations, the description is sufficient. It explains what the tool returns and points to get_judge for deeper detail, which is exactly what an agent needs. It does not explicitly mention pagination, but the schema covers cursor and page_size, so the description need not repeat 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 description coverage is 100%, with each parameter fully described. The description lists some filter dimensions (name, appointer, court, political affiliation) but does not add meaning beyond the schema. Baseline 3 applies because the schema carries the full parameter 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 tool searches judge/person records with specific filter criteria (name, appointing president, court, political affiliation, demographic). It explicitly distinguishes itself from the sibling courtlistener_get_judge by noting that tool is for full history, making the purpose unmistakable.

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 a clear alternative: 'Use courtlistener_get_judge for full appointment history and education records.' This tells the agent when to choose this search tool versus the more detailed retrieval tool. It does not enumerate all sibling exclusions, but that is unnecessary given the obvious resource differences.

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, and the description adds valuable behavioral details: exact rate limits (5 req/min, 50/hr, 125/day), the page_size minimum behavior, and the note that each search costs one request. These go beyond the schema and annotations, providing operational expectations.

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 four sentences, front-loaded with the core purpose, then covering filtering, return format, syntax, cross-tool reference, and rate limits. No word is wasted; every sentence contributes essential 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 the tool's complexity (8 parameters, output schema present), the description provides a complete picture: scope, return format, query syntax, rate limits, and a pointer to a related tool for court IDs. The output schema covers return details, so further explanation is unnecessary.

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 already provides 100% coverage for all 8 parameters, so the baseline is 3. The description adds extra context by explaining the field syntax and boolean operators in the query parameter (even though partially duplicated in schema) and explicitly linking page_size to rate limit usage. This adds marginal 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's function with a specific verb ('search') and resource ('9M+ written US court opinions'), and differentiates it from sibling tools like courtlistener_search_dockets and courtlistener_lookup_courts. It also outlines what is returned (cluster summaries, metadata, snippets, variants), making the tool's role 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 gives clear context for when to use the tool (full-text search of opinions) and explicitly instructs to use courtlistener_lookup_courts for court IDs. However, it does not explicitly state when to prefer this over alternatives like courtlistener_get_opinion or courtlistener_lookup_citation, so it misses the 'when-not-to-use' dimension.

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, so the safety profile is covered. The description adds context about the return payload (two MP3 links, panel judge IDs, transcript snippets) and mentions 'durable copy,' which hints at data reliability. It does not disclose any additional behavioral traits like rate limits or pagination specifics beyond what the schema already covers, so this is adequate but not exceptional.

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-loaded with the primary purpose, and then details the key output features. Every sentence contributes meaningful information, and there is 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?

Given the tool's complexity (6 parameters, output schema present), the description is sufficiently complete for selection and invocation. It explains what the tool does, what it returns, and how to use the results with another tool. The schema handles parameter details, and the output schema handles return-value details. The only minor gap is the lack of explicit comparison to sibling search tools, but the name and description make the scope clear.

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 baseline is 3. The description does not add any additional meaning to the parameters themselves; it only describes output fields. The parameter details are fully captured in the input schema, so no extra value is provided 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 opens with a specific verb and resource: 'Search appellate oral argument audio recordings.' It clearly distinguishes this from sibling tools by specifying the content type (oral arguments) and the action (search vs. get). The scope is also clarified with 'appellate' and 'largest public collection.'

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 on when to use this tool: when searching for oral argument audio recordings. It also gives guidance on a related usage pattern by noting that panel judge IDs can be passed to courtlistener_get_judge for biographical context. However, it does not explicitly state when not to use it or compare it to other search tools (e.g., search_opinions), so it stops short of a 5.

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