Skip to main content
Glama
Federal Courts Analyst

Federal Courts Analyst

Ask the statistics office (sandbox)

file_revision_inquiry
Idempotent

Files a tracked inquiry with the statistics office about an unexplained revision to a federal court figure, joining an existing inquiry if one is open. Sends only after user confirms.

Instructions

Use this when the user picked "Ask the statistics office why this changed" for a figure in a saved answer: a figure that was revised between editions with no published explanation (e.g. FY2020 national weighted civil filings per judgeship, 554 → 322). It files one inquiry per revision; if someone already asked, the request joins that inquiry instead.

Not for figures that weren't revised or whose revision is routine (pending counts restated in Table C-1); get_official_figure shows a figure's revision_notes first. Not for free-text messages: an inquiry is always about one revision.

Returns the inquiry, how many requests wait on it, and where it would go (AO Statistics Division for published tables). Sandbox: nothing is sent. Writes only after the user confirms.

Example: request_id=1001, measure='weighted_civil_filings_per_judgeship', court='US', fiscal_year=2020 → inquiry #1, waiting_for_office.

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": {
      "request_id": "<request_id>",
      "measure": "<measure>",
      "fiscal_year": "<fiscal_year>"
    },
    "name": "file_revision_inquiry"
  }
}

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
confirmNoTrue once the user has agreed to this write. False (default) asks the user, or returns a preview if the client can't ask.
measureYesA published statistic (see courts://glossary or explain_term for definitions).
asker_nameNoA display name for the asker (demo identity; the same name must be used for every call about one request).MCP user
request_idYesThe request.
fiscal_yearYes
idempotency_keyNoAny unique string; a retried call with the same key returns the first result instead of writing again.

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 cover the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=true), and the description adds the context an agent actually needs: the call is sandboxed so nothing is sent, it writes only after user confirmation, and repeat requests join an existing inquiry rather than creating duplicates. The return shape (inquiry, waiting count, destination office) is also disclosed.

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 structure is deliberate and front-loaded: trigger, exclusions, return value, sandbox/confirmation caveat, then a worked example. It is longer than average but nearly every sentence carries information; the example at the end is illustrative rather than redundant, though it could be trimmed slightly.

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 non-destructive write with a large enum-heavy schema and an output schema, the description supplies everything an agent needs before calling: eligibility condition, dedup semantics, sandbox status, the confirmation requirement, and the destination office. Return values needn't be fully restated given the output schema, so nothing material 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 86%, so the baseline is 3; the description earns an extra point by walking through the three required parameters in its worked example (request_id=1001, measure='weighted_civil_filings_per_judgeship', court='US', fiscal_year=2020) and by explaining in prose that the confirm gate governs whether a write happens. It does not explain asker_name's stable-identity constraint or idempotency_key, though the schema already documents both.

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 action and resource ('files one inquiry per revision') and immediately clarifies the underlying object is a revised figure in a saved answer, with a concrete example (FY2020 weighted civil filings per judgeship, 554 → 322). It also states the dedup behavior, distinguishing it from any tool that would just read revision notes.

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 trigger tied to a user choice ('when the user picked "Ask the statistics office why this changed"'), then names two exclusions with the alternative: unrevised/routine revisions should go through get_official_figure's revision_notes, and free-text messages are out of scope. Nothing about when-not-to-use is left to inference.

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