Skip to main content
Glama
Federal Courts Analyst

Federal Courts Analyst

Find cases (cohort)

find_cases
Read-onlyIdempotent

Filter FY2015–FY2025 federal civil cases by nature of suit, court, jurisdiction, disposition, pro se status, class action or MDL, then return a cohort handle and count for analysis.

Instructions

Use this when the question needs case-level filters the published tables don't have: a case type (nature of suit), origin (for example directly filed MDL cases), jurisdiction, disposition, pro se status, class actions or an MDL docket, for FY2015–FY2025 civil cases in the FJC Integrated Database. "How many employment discrimination cases were filed in N.D. Ill. in FY2024?"

Never guess a nature-of-suit code: for a case type in words ("patent"), get the code from explain_term first, then check case_types in the result.

Not for published totals without filters (use get_official_figure: it is authoritative) or for rankings (compare_courts).

Returns a cohort handle (coh_…), the count, the label of each nature-of-suit code filtered on (case_types) and a small preview (by fiscal year, top courts, top case types, MDL share); never case rows or party names. Pass the handle to analyze_cohort for medians, outcome rates and trends, or to sample_dockets for example dockets. To narrow a cohort, call again with parent_handle and the extra filters.

Example: courts=['FL-N'], fy_from=2020, fy_to=2020, origins=['mdl_direct'] → 202,463 cases, handle coh_1385a2b1481d.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "fy_from": "<fy_from>",
      "fy_to": "<fy_to>"
    },
    "name": "find_cases"
  }
}

Input Schema

NameRequiredDescriptionDefault
basisNoCases filed in those years, or terminations in them.filed
fy_toYesLast fiscal year.
courtsNoDistricts or circuits; omit for all districts.
pro_seNo
fy_fromYesFirst fiscal year.
originsNoe.g. ['mdl_direct'] for directly filed MDL cases.
nos_codesNoNature-of-suit codes the user gave or explain_term returned, never guessed: e.g. ['442'] employment discrimination, ['830'] patent.
mdl_docketNoMDL docket number, e.g. '2885'.
nos_groupsNoTable C-2 groups, e.g. ['Civil Rights'].
exclude_mdlNoDrop MDL cases (direct and transferred).
class_actionNo
dispositionsNo
jurisdictionsNo
parent_handleNoRefine this cohort: its filters plus the ones given.
nos_categoriesNo

Output Schema

NameRequiredDescriptionDefault
dataNo
statusNook
declinedNo
warningsNo
provenanceNo
clarificationNo
suggested_nextNoHints for a follow-up call.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.1.0

TDQS

A4.6/5.0
Behavior4/5

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

Annotations already declare a safe, idempotent, closed-world read, so the bar is lower. The description still adds meaningful behavior: results are a cohort handle plus count, code labels and a small preview, never case rows or party names, and refining produces a superset-of-filters cohort via parent_handle. It does not discuss cost or limits on large cohorts, which keeps it just short of a 5.

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

Conciseness4/5

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

The opening sentence front-loads the use case, followed by a routing rule, a code-safety warning, a return-shape note and a worked example. Every block is functional, though the return-shape parenthetical is dense and the description is long overall for a tool whose schema documents most fields.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 15-parameter cohort builder with annotations and an output schema, the description supplies everything an agent needs: when to use it, which siblings handle adjacent questions, how to obtain valid codes, what comes back, and how to chain or refine. No correctness-relevant gap remains.

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

Parameters4/5

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

With 67% schema coverage and 15 parameters, the schema carries most of the load, but the description adds real meaning where it matters: it explains the nos_codes constraint (only codes the user supplied or explain_term returned), shows concrete origins and courts examples ('mdl_direct', 'FL-N'), and clarifies that parent_handle composes existing filters with new ones. Several parameters (basis, pro_se, dispositions, exclude_mdl) are left entirely to the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description names a specific operation and resource — cohort-style case filtering over FY2015–FY2025 civil cases in the FJC Integrated Database — and enumerates the filterable dimensions (nature of suit, origin, jurisdiction, disposition, pro se, class action, MDL docket). It explicitly separates itself from published-totals and ranking queries, so an agent can tell which tool applies without opening the schema.

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

Usage Guidelines5/5

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

It gives an explicit when-to-use trigger (questions needing case-level filters the published tables lack), explicit when-not rules routing to get_official_figure for authoritative totals and compare_courts for rankings, and a prerequisite step (resolve nature-of-suit codes via explain_term, never guess). It also states the forward path — pass the handle to analyze_cohort or sample_dockets, or re-call with parent_handle to narrow.

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