Skip to main content
Glama
Federal Courts Analyst

Federal Courts Analyst

Explain a term

explain_term
Read-onlyIdempotent

Looks up definitions for federal court terms, codes, and statistics, returns sources and related terms, and maps case types to nature-of-suit codes for case searches.

Instructions

Use this when the user asks what a term, code or statistic means: "weighted filings", "directly filed MDL", "nature of suit 442", "statistical year", "what is Judicial Facts and Figures", "Table X-1A". Also use it to get the nature-of-suit code for a case type named in words ("patent cases", "employment discrimination", "ERISA") before calling find_cases.

Not for numbers (use get_official_figure) or for why they changed (explain_change).

Returns the definition with its source (glossary, measure registry or the IDB codebook), related terms, and the measure id or nature-of-suit group when there is one. For a case type, nos_matches lists every matching code (or the whole Table C-2 group): pass those to find_cases. Unknown terms return found=false with "did you mean" suggestions instead of a guess.

Example: term='patent' → 830 Patent, plus 835 Patent – abbreviated new drug application in nos_matches; term='nature of suit 442' → Employment (civil rights), Table C-2 group Civil Rights.

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": {
      "term": "<term>"
    },
    "name": "explain_term"
  }
}

Input Schema

NameRequiredDescriptionDefault
termYes

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 (readOnlyHint, idempotentHint, openWorldHint=false), yet the description still adds non-obvious behavior: the answer is attributed to a source (glossary, measure registry, IDB codebook) and unknown terms return found=false with 'did you mean' suggestions rather than a fabricated guess. That fallback contract is the most valuable disclosure here; the only omission is any limit on lookup breadth or failure modes beyond unknown terms.

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, then exclusions, then return contract, then a worked example — a clear progression where each block has a job. It is on the long side, and the example sentence partially restates the earlier term examples, which is the only redundancy.

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 one-parameter lookup tool with an output schema, the definition supplies everything the schema does not: when to reach for it, which sibling to use instead, what the response contains, how nos_matches chains into find_cases, and what an unsuccessful lookup looks like. Nothing an agent needs before calling it 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 0% and the single 'term' parameter has no description at all, so the definition must carry the burden — and it does, by showing the acceptable shapes of a term (quoted phrase, code like 'nature of suit 442', table id, or a plain-language case type such as 'patent cases') and how nos_matches feeds into find_cases. It stops short of stating the 120-character bound or that the input must be a single term, which is why it is not a 5.

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 states a specific verb (explain) and resource (term/code/statistic) and enumerates concrete examples ('weighted filings', 'nature of suit 442', 'Table X-1A'), so an agent can tell exactly what this resolves. It also explicitly separates itself from get_official_figure (numbers) and explain_change (why they changed).

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 ('when the user asks what a term ... means'), a named exclusion ('Not for numbers ... or for why they changed'), and a pre-condition workflow: get the nature-of-suit code here before calling find_cases. Both the when and the when-not are stated, not implied.

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