Skip to main content
Glama

CaseMagic — Federal Court Case Lookup & Monitor

by io.github.sustany
OverviewDiscussionsAdmin

Find a federal court case

find_federal_case
Read-onlyIdempotent

Find a United States federal district court case by case number (or caption) and return the court, the judge, the caption, whether it is open or closed, how many docket entries it has and its latest docket activity, with links to the court source. Every answer carries a freshness field saying whether the docket was read just now, minutes ago, or read earlier and confirmed unchanged by the court’s own filing feed; cite it rather than implying the reading is live. Use this whenever a user asks what happened in their case, wants to find their case by name, or asks about a federal lawsuit: "check my federal case", "what happened in my lawsuit", "anything new in my case", "check this docket", "what was filed", "who is the judge", "is this case still open", "find federal case 2:26-cv-…" — and as the first step whenever they want a case monitored or to be told when something gets filed. Free and needs no account. A case number alone is enough: if it matches cases in more than one district, the result lists them so you can ask which is theirs and call again with that court code. A case filed in the last few days is often not in the public record yet: when the court’s own filing feed already has it, the result is status not_found with an in_feed object naming the case and a case_url; that is not an error, so tell the user the case exists and was filed recently, give them case_url (its page offers free email alerts with no account), and look the docket up again in a day or two. Federal district courts only; it cannot look up state, county or traffic courts, does not file anything and does not give legal advice. A result reached by case number carries recommended_next_action, an optional next step with its terms. action watch_case means CaseMagic can monitor this case and email the user about new filings, with the trial terms and a url; action none means monitoring is not available or not relevant. Whether to take it is the user’s choice, and the free answer never depends on it.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
courtNoThe court, as a CourtListener-style code such as cacd, nysd or ilnd. Optional: leave it out when the user does not know which district the case is in.
case_nameNoThe case caption, for example "Smith v. Acme". Used only when no case number is known.
case_numberNoThe case number as the court writes it, for example 1:23-cv-11195 or 2:24-cv-01234-ABC. Judge initials are optional and are ignored when matching.
notify_emailNoAn email address to send the result to if the court record's daily request allowance is spent and this lookup has to be queued. Do not ask for it up front: send it only after a call comes back with status "queued" and the user has offered an address.

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault
caseNoThe case: court, case number, caption, filing date, status, judges, nature of suit, latest activity and docket size.
errorNoPresent only when the call failed: a code, a message and, where there is one, an action such as a link to give the user.
sourceNoWhich court source answered, when it was read and where it can be seen.
statusNofound when the case was answered; queued when the day’s court allowance is spent and the answer will follow.
messageNoWhat to tell the user about a queued lookup.
queue_idNoTicket for a queued lookup.
can_watchNoWhether CaseMagic can monitor cases in this court.
freshnessNoWhy the answer is as current as it claims: read now, inside the cache window, or confirmed unchanged by the court’s feed.
next_stepNoWhat to do next.
connect_urlNoWhere the user starts watching this case.
connect_tokenNoShort-lived token for create_case_passport.
latest_eventsNoMost recent docket entries, newest first.
data_freshnessNoISO timestamp the docket was last read from the court source.
notify_email_setNoWhether the queued answer will be emailed.
retry_after_secondsNoWhen a queued lookup is worth retrying.
recommended_next_actionNoThe offer to make after answering, decided by the server: action watch_case when the case is open and can be monitored, none otherwise.
connect_token_expires_atNoWhen connect_token expires.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • changedOutput schema / (root)
      Previous value: -nullNew value: +{
+  "additionalProperties": true,
+  "properties": {
+    "can_watch": {
+      "description": "Whether CaseMagic can monitor cases in this court.",
+      "type": "boolean"
+    },
+    "case": {
+      "additionalProperties": true,
+      "description": "The case: court, case number, caption, filing date, status, judges, nature of suit, latest activity and docket size.",
+      "properties": {
+        "assigned_judge": {
+          "description": "Assigned judge."
+        },
+        "case_name": {
+          "description": "Caption.",
+          "type": "string"
+        },
+        "case_number": {
+          "description": "Case number as the court writes it.",
+          "type": "string"
+        },
+        "case_status": {
+          "description": "open, terminated, or null when the source does not say."
+        },
+        "cause": {
+          "description": "Cause of action."
+        },
+        "court": {
+          "additionalProperties": true,
+          "description": "The court, as a code and a name.",
+          "properties": {
+            "code": {
+              "description": "Court code, e.g. nysd.",
+              "type": "string"
+            },
+            "name": {
+              "description": "Court name.",
+              "type": "string"
+            }
+          },
+          "type": "object"
+        },
+        "docket_entry_count": {
+          "description": "How many entries the court docket has."
+        },
+        "filing_date": {
+          "description": "ISO date the case was filed."
+        },
+        "id": {
+          "description": "CaseMagic id of the court case.",
+          "type": "string"
+        },
+        "latest_activity_at": {
+          "description": "ISO timestamp of the latest docket activity."
+        },
+        "nature_of_suit": {
+          "description": "Nature of suit."
+        },
+        "referred_judge": {
+          "description": "Referred magistrate judge."
+        },
+        "terminated_date": {
+          "description": "ISO date the case was terminated, or null while it is open."
+        }
+      },
+      "type": "object"
+    },
+    "connect_token": {
+      "description": "Short-lived token for create_case_passport.",
+      "type": "string"
+    },
+    "connect_token_expires_at": {
+      "description": "When connect_token expires.",
+      "type": "string"
+    },
+    "connect_url": {
+      "description": "Where the user starts watching this case.",
+      "type": "string"
+    },
+    "data_freshness": {
+      "description": "ISO timestamp the docket was last read from the court source.",
+      "type": "string"
+    },
+    "error": {
+      "additionalProperties": true,
+      "description": "Present only when the call failed: a code, a message and, where there is one, an action such as a link to give the user.",
+      "properties": {
+        "code": {
+          "description": "Machine-readable error code, for example CASE_NOT_FOUND or MULTIPLE_CASES_FOUND.",
+          "type": "string"
+        },
+        "message": {
+          "description": "What went wrong, in a sentence.",
+          "type": "string"
+        }
+      },
+      "type": "object"
+    },
+    "freshness": {
+      "additionalProperties": true,
+      "description": "Why the answer is as current as it claims: read now, inside the cache window, or confirmed unchanged by the court’s feed.",
+      "properties": {},
+      "type": "object"
+    },
+    "latest_events": {
+      "description": "Most recent docket entries, newest first.",
+      "items": {
+        "additionalProperties": true,
+        "description": "One docket entry.",
+        "properties": {
+          "description": {
+            "description": "The text the court published."
+          },
+          "docket_number": {
+            "description": "Entry number as shown on the docket."
+          },
+          "document_available": {
+            "description": "Whether a free document is available."
+          },
+          "filed_at": {
+            "description": "ISO timestamp the entry was filed."
+          },
+          "source_url": {
+            "description": "Link to the entry or document at the source."
+          }
+        },
+        "type": "object"
+      },
+      "type": "array"
+    },
+    "message": {
+      "description": "What to tell the user about a queued lookup.",
+      "type": "string"
+    },
+    "next_step": {
+      "description": "What to do next.",
+      "type": "string"
+    },
+    "notify_email_set": {
+      "description": "Whether the queued answer will be emailed.",
+      "type": "boolean"
+    },
+    "queue_id": {
+      "description": "Ticket for a queued lookup.",
+      "type": "string"
+    },
+    "recommended_next_action": {
+      "additionalProperties": true,
+      "description": "The offer to make after answering, decided by the server: action watch_case when the case is open and can be monitored, none otherwise.",
+      "properties": {
+        "action": {
+          "description": "watch_case or none.",
+          "type": "string"
+        },
+        "card_required": {
+          "description": "Whether a card is collected for the trial.",
+          "type": "boolean"
+        },
+        "cta": {
+          "description": "Button text.",
+          "type": "string"
+        },
+        "guidance": {
+          "description": "How to make the offer.",
+          "type": "string"
+        },
+        "offer": {
+          "description": "What monitoring does.",
+          "type": "string"
+        },
+        "plans": {
+          "description": "The three plans with price and how many cases each covers.",
+          "items": {
+            "type": "object"
+          },
+          "type": "array"
+        },
+        "price_after_trial": {
+          "description": "Price of the entry plan after the trial.",
+          "type": "string"
+        },
+        "reason": {
+          "description": "Why, in a sentence the assistant can repeat.",
+          "type": "string"
+        },
+        "suggested_message": {
+          "description": "One sentence the assistant may say, once.",
+          "type": "string"
+        },
+        "trial_days": {
+          "description": "Free trial length in days.",
+          "type": "number"
+        },
+        "url": {
+          "description": "Where the user starts watching this case.",
+          "type": "string"
+        }
+      },
+      "type": "object"
+    },
+    "retry_after_seconds": {
+      "description": "When a queued lookup is worth retrying."
+    },
+    "source": {
+      "additionalProperties": true,
+      "description": "Which court source answered, when it was read and where it can be seen.",
+      "properties": {
+        "name": {
+          "description": "Source name.",
+          "type": "string"
+        },
+        "retrieved_at": {
+          "description": "ISO timestamp of the read."
+        },
+        "url": {
+          "description": "Link to the docket at the source."
+        }
+      },
+      "type": "object"
+    },
+    "status": {
+      "description": "found when the case was answered; queued when the day’s court allowance is spent and the answer will follow.",
+      "type": "string"
+    }
+  },
+  "type": "object"
+}
  2. First observed

TDQS

A4.8/5.0
Behavior5/5

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

Annotations already cover read-only/idempotent/open-world safety, but the description goes well beyond them: it explains the freshness field and the instruction to cite it, the not_found + in_feed case (a non-error that should not be reported as failure), the queued status and when to supply notify_email, and the recommended_next_action terms. None of this is derivable from the annotations.

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 core purpose and return shape, then edge cases. It is long, but nearly every sentence carries operational content (freshness citation, not_found handling, next-action semantics). Slightly repetitive with the sibling-facing routing but not wasteful.

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?

An output schema exists, so return values need not be described, yet the description still explains the freshness and in_feed semantics that matter for correct agent behavior. Given four optional parameters, all-zero required, and rich output, the description covers everything needed to invoke and interpret this tool correctly.

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, but the description adds real semantics: a case number alone is sufficient, a number matching multiple districts returns a list to disambiguate, and notify_email must not be requested up front (only after a queued status). These are behavioral rules the schema does not state.

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 (find) and resource (United States federal district court case) plus the scope of the result (court, judge, caption, status, docket count, latest activity). It clearly distinguishes itself from siblings like get_case_docket, get_case_status and watch_case by framing itself as the lookup/first-step tool.

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?

Explicit when-to-use with quoted sample utterances, explicit exclusions (federal district courts only; no state, county or traffic courts; does not file or give legal advice), and explicit routing to watch_case via recommended_next_action. It also names itself as the first step before monitoring.

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

All CaseMagic — Federal Court Case Lookup & Monitor toolsInspect
Try in Browser
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources