Skip to main content
Glama
Federal Courts Analyst

Federal Courts Analyst

Reconcile IDB vs official

reconcile
Read-onlyIdempotent

Compares IDB civil case counts or a find_cases handle against official federal court Table C-1 figures, reporting variance and match status by court and fiscal year.

Instructions

Use this when the user asks whether case-level data matches the official tables, or how far an IDB count is from the published one: civil cases filed, terminated or pending for a court and fiscal year (Table C-1), or a find_cases handle that corresponds to one (courts, one year, no filters).

Not for the official figure itself (get_official_figure) or for explaining a change over time (explain_change).

Returns the official value (latest edition, with every edition), the IDB rebuild, the variance and a badge: matched, explained_variance (with the quantified cause: a restated figure, repeat records, undated reopenings or snapshot drift) or unexplained.

Example: measure='civil_cases_pending', court='US', fiscal_year=2017 → official 366,195 (JB-2018, restated from 339,131), IDB 363,601, matched.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "reconcile"
  }
}

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
handleNoOr: a find_cases handle to reconcile instead.
measureNoThe count to rebuild (with court and fiscal_year).
fiscal_yearNo

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 cover the safety profile (readOnly, idempotent, non-destructive, closed-world), and the description adds genuine behavioral substance: it returns official value at the latest edition plus every edition, the IDB rebuild, the variance, and a three-state badge whose middle state is defined with its quantified causes (restated figure, repeat records, undated reopenings, snapshot drift). That badge taxonomy is the kind of interpretive detail an agent could not infer from annotations or the output schema alone.

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

Conciseness5/5

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

Four compact blocks — trigger condition, exclusions with named alternatives, return shape, worked example — with the operative condition front-loaded. The example is dense with real values and directly demonstrates the matched badge case rather than restating the prose.

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

Completeness4/5

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

With an output schema present, the description does not need to enumerate return fields, and it still supplies the badge vocabulary and variance logic an agent needs to interpret the response. The remaining gap is the all-optional parameter set: it never states what a call with no measure, year, or handle does, so an agent could mis-fire with defaults.

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 75%, so the schema already documents court codes, the handle pattern, and the measure enum. The description still adds meaning: it ties measure/court/fiscal_year together as a single mode, presents handle as the alternative rather than an additive parameter, and warns the handle must correspond to a case-level count (courts, one year, no filters) — a compatibility constraint the schema does not express.

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 opening sentence names the specific task (reconcile case-level IDB counts against official tables) and enumerates the exact scope: civil cases filed/terminated/pending, a court and fiscal year (Table C-1), or a find_cases handle. It explicitly names what it is not (get_official_figure, explain_change), so an agent can separate it from the two nearest siblings 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?

It gives both the trigger condition (the user asks whether data matches, or how far an IDB count is from published) and explicit exclusions with the correct alternatives named for each. It also states the permitted input shapes — courts + one year + no filters, or a find_cases handle — which further constrains when this tool is the right call.

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