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

Beyond the annotations (readOnly/idempotent/openWorld=false), the description discloses that results are metadata only with no opinion text, enumerates the returned cluster fields, and states the collection's coverage cutoff of 2026-09-30. It also explains that every response carries a "note" about source and coverage limits, which is non-obvious behavioral context.

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?

Content is front-loaded: purpose, match semantics, return shape, exclusions, then the coverage caveat. It is dense but nearly every sentence carries unique information; the parenthetical record count ("10,174,547 case records") is slightly heavy but serves to justify the coverage claim.

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 no output schema, the description correctly enumerates the returned cluster fields, and it closes an important interpretive gap by explaining that empty results reflect the mirror's coverage end rather than absence of the case. Nothing an agent needs to invoke or interpret this tool correctly is missing.

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, but the description adds real meaning by explaining that the q parameter is matched via punctuation-insensitive trigram (with a concrete example), which the schema's "case name or fragment" does not convey. Sort, court, and date parameters are left to the schema, which is adequate.

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 a specific verb and resource ("Case-name metadata search over the local CourtListener mirror") and immediately qualifies the matching mechanism (punctuation-insensitive trigram on case name). It distinguishes itself from concept/semantic siblings by stating "not concept search... it finds a case by its name, not by what it is about."

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 an explicit when-not (concept search) and explains how to interpret thin results for recent authority. It stops short of naming which sibling to use instead (e.g., semantic_search or fts), so the agent must infer the routing, but the context is otherwise clear.

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