Skip to main content
Glama
Federal Courts Analyst

Federal Courts Analyst

Explain a change

explain_change
Read-onlyIdempotent

Explain why federal court statistics rose or fell between two fiscal years, with exact breakdowns by district and case type and labeled drivers.

Instructions

Use this when the user asks why a number went up or down, or what drove a change between two fiscal years: "Why did civil filings jump in FY2020?", "what drove the drop in terminations", "break the change down by district and case type". Works for civil cases filed, terminated and pending, and for filings per judgeship (weighted or unweighted).

Not for a single year's figure (use get_official_figure) or a ranking (use compare_courts).

Returns the official change (Table C-1 or X-1A), breakdowns by district and by case type that sum exactly to the change, the change excluding directly filed MDL cases (filings), and drivers, each labelled by what backs it: official, idb_derived, inferred (our reasoning, not an official statement: say so) or context. A plain "civil filings" means civil_cases_filed (the count); pass measure='civil_filings' only when the user asks about workload without saying count or per judgeship.

Example: measure='civil_cases_filed', court='US', period_from=2019, period_to=2020 → +172,704; N.D. Fla. +199,881, driven by directly filed MDL cases (MDL 2885, 3M earplugs).

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": {
      "measure": "<measure>",
      "period_from": "<period_from>",
      "period_to": "<period_to>"
    },
    "name": "explain_change"
  }
}

Input Schema

NameRequiredDescriptionDefault
courtNoCourt code: US (all district courts), a circuit (CIR-01 … CIR-11, CIR-DC) or a district (state postal code, plus -N/-E/-S/-W/-M/-C for divided states: FL-N = N.D. Fla., NY-S = S.D.N.Y., DC = D.D.C.).US
measureYesA published statistic. If the user didn't say whether they mean weighted or unweighted filings, pass 'filings_per_judgeship' (or 'civil_filings') and the server will ask them.
period_toYesLater fiscal year.
period_fromYesEarlier fiscal year.

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

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

Annotations already declare readOnly, idempotent, non-destructive, closed-world, so safety is covered; the description goes well beyond by disclosing the returned content (official change from Table C-1/X-1A, breakdowns that sum exactly, an MDL-excluded change) and, critically, the provenance labels (official, idb_derived, inferred, context) plus the obligation to flag inferred reasoning as not an official statement. That is behavioral context an agent could not get from the annotations or schema.

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 scenario, then scope, then exclusions, then return contents, then a concrete example — a logical progression with little filler. Slightly long, and the measure-disambiguation sentence partially restates the schema's own guidance, but the example earns its space by demonstrating output shape.

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 4-parameter analytical tool with an output schema, annotations, and full schema coverage, the description supplies everything the agent still needs: trigger conditions, sibling routing, scope of supported measures, and how to present provenance-labelled drivers. Nothing an agent needs to invoke or relay results correctly is missing.

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?

Schema coverage is 100%, so the baseline is 3; the description still adds meaning by explaining the ambiguous measure choice in user terms — plain "civil filings" means civil_cases_filed, and measure='civil_filings' is only for workload questions not mentioning count or per judgeship. The worked example also shows court='US' plus a fiscal-year pair in practice, though court-code and year semantics are largely left 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 analytical operation (explaining why a published statistic changed between two fiscal years) and lists the measures it covers (civil filed/terminated/pending, filings per judgeship weighted or unweighted). The opening user-question examples make it instantly distinguishable from siblings like get_official_figure and compare_courts.

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 states explicitly when to use it ("why did a number go up or down", "what drove the drop", "break the change down by district") and names two concrete alternatives with their selecting conditions: get_official_figure for a single year's figure and compare_courts for a ranking. No inference is required from the agent.

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