Skip to main content
Glama
Federal Courts Analyst

Federal Courts Analyst

Analyze a cohort

analyze_cohort
Read-onlyIdempotent

Compute case-cohort statistics—counts, fiscal-year trends, medians, disposition and judgment rates—from a find_cases handle, optionally grouped by court, year, NOS group, or origin.

Instructions

Use this after find_cases, to compute a statistic for its cohort handle: count, trend (by fiscal year), median_days_to_disposition, disposition_rates (dismissed / judgment / transferred), judgment_for_rates, share_by_nos_group, pro_se_share or still_pending_share, optionally grouped by court, fiscal_year, nos_group or origin.

Not for published statistics (get_official_figure) or whole-court changes (explain_change); it needs a handle from find_cases.

Returns one value per group with n (cases it's computed over) and a 95% confidence interval (Wilson for shares, order statistics for medians). Groups under 30 cases carry a caution; under 10 the value and n are withheld (null, status 'suppressed'), as is the next smallest group where needed: say there are too few cases rather than guessing. Report n with every figure.

Example: handle from find_cases(courts=['DE'], fy_from=2019, fy_to=2019, nos_codes=['830']), metric='median_days_to_disposition' → 166 days (95% CI 154–183), n=845.

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": {
      "handle": "<handle>",
      "metric": "<metric>"
    },
    "name": "analyze_cohort"
  }
}

Input Schema

NameRequiredDescriptionDefault
handleYesFrom find_cases.
metricYes
group_byNoOptional grouping (≤ 25 groups).

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.7/5.0
Behavior4/5

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

Annotations already declare readOnly/idempotent/closed-world, so the safety profile is covered; the description goes further by disclosing statistical behavior: Wilson intervals for shares, order statistics for medians, a caution under n=30, suppression (null + status 'suppressed') under n=10, and complementary suppression of the next smallest group. The only gap is that it does not say how the handle expires or whether a handle is reusable across metrics.

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?

Front-loaded with the trigger condition and prerequisite, then behavior, then a concrete worked example that anchors the output format. Dense but nearly every sentence carries information; the prose is slightly compressed to the point of feeling run-on in the metric enumeration.

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 statistical tool with suppression semantics, the description plus existing output schema covers everything an agent needs: prerequisites, metric meanings, grouping limits in schema, interval method, suppression thresholds, and the instruction to report n with every figure. Nothing material is missing.

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

Parameters5/5

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

Schema coverage is 67% and the description fills the main hole — the `metric` enum, which has no schema description — by explaining what each metric computes and that trend is by fiscal year and the rate metrics break down by outcome type. It also ties `handle` to find_cases and confirms the allowed group_by dimensions, adding meaning beyond the raw enum lists.

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?

States a specific verb and resource — 'compute a statistic for its cohort handle' — and enumerates the exact metrics (count, trend, median_days_to_disposition, disposition_rates, judgment_for_rates, share_by_nos_group, pro_se_share, still_pending_share) plus optional grouping dimensions. An agent can tell it apart from explain_change, get_official_figure and find_cases without opening any 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?

Explicitly sequences the tool ('Use this after find_cases'), states the prerequisite (needs a coh_ handle), and names two exclusions with the alternative that covers each: published statistics go to get_official_figure, whole-court changes go to explain_change. Both when-to-use and when-not-to-use are covered.

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