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

The annotations already mark the tool read-only, idempotent, and non-destructive; the description adds meaningful operational detail: it covers 2.2 million dockets, requires no API key, and returns specific fields (caption, docket number, court, filing and termination dates). It also implicitly discloses that full opinion text is outside this tool's scope by directing users to the court-listener pack.

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 roughly sixty words and front-loads action, scope, and output before closing with routing advice. There is no filler; each sentence contributes either coverage, return fields, use cases, or an alternative tool.

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?

Despite having no output schema, the description compensates by enumerating the exact returned fields and naming the court scope, and the input schema covers all five parameters thoroughly. The read-only annotations plus the explicit hand-off to court-listener make the tool's position in the workflow clear. No additional context is needed for an agent to invoke it correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, and each parameter in the schema has its own explanatory text, so the description is not required to repeat parameter syntax. It reinforces the primary search axis ('by party name') but adds no new meaning beyond what the schema already provides. 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 opening line names a specific verb and resource ('Find US FEDERAL APPEALS by party name') and pins down the scope to '2.2 million federal appellate dockets — the circuit courts and the Supreme Court.' It further differentiates itself from opinion retrieval by routing full-text requests to the court-listener pack, so the purpose is 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 states explicit triggers: 'has this case been appealed', 'what is on appeal in the Ninth Circuit', and 'appellate history checks,' and it names the alternative for full-text opinions (court-listener pack). It does not explicitly contrast the sibling federal_appeal_recent or give a when-not-to-use condition, and the Ninth Circuit example under-specifies that the party parameter is required.

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