Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@DocketBird MCP Server search for 'summary judgment' in case 3:23-cv-01234"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
An MCP server for searching and downloading court documents via the DocketBird API. Deployed on DigitalOcean with Docker, using OAuth 2.0 so each user brings their own DocketBird API key.
Research tools work across DocketBird's full index (all courts, all cases); account tools act on your firm's own DocketBird data.
Tool | Description |
| Search ALL cases by name or case number (cursor-paginated) |
| Full-text search of filing bodies across the whole corpus; |
| One case's metadata + complaint pointer (no docket fetch) |
| Full docket sheet: case info + paginated document list |
| Match docket-entry titles/descriptions within one case |
| One document's metadata and download links (no bytes) |
| Extracted plain text of a filing (pageable via |
| Retrieve a single document's content (or save it locally in stdio) |
| List a case's documents with direct download links (or save them locally in stdio) |
| Natural-language questions about parties, attorneys, firms, judges (federal civil, ~30% coverage since July 2025) |
| Look up courts live from the API ( |
| List every covered court system |
| List cases on your account (company or user scope) |
| Calendar entries for a case, or company-wide ( |
| Create an autocalendar for a case (queued; court fees may apply) |
| Follow a case so DocketBird monitors new filings |
Using these tools from an agent: a ready-to-install Claude skill lives in
skills/docketbird-mcp/, covering the case-ID format, each tool, and common research workflows.
Related MCP server: legal-mcp
Python 3.11
uv package manager
Install uv:
curl -LsSf https://astral.sh/uv/install.sh | shCreate and activate a virtual environment:
uv venv
source .venv/bin/activateInstall dependencies:
uv pip install -r requirements.txt# stdio transport (uses DOCKETBIRD_API_KEY env var, no OAuth)
DOCKETBIRD_API_KEY="your-key" python docketbird_mcp.py --transport stdio
# HTTP transport with OAuth (Streamable HTTP at /mcp)
python docketbird_mcp.py --transport http
# Then visit http://localhost:8080/signup to create an accountNote: All diagnostic logging goes to stderr, never stdout. This keeps the stdio JSON-RPC stream clean — writing logs to stdout would corrupt it and break the client.
Variable | Mode | Default | Description |
| stdio | (none) | API key used for all requests in stdio mode (no OAuth). Required for stdio. |
| http |
| Public base URL. Used as the OAuth issuer/resource URL and for redirects. Must match the URL clients connect to. |
| http |
| Directory holding the SQLite auth database. Mounted as a volume in Docker. |
See .env.example for a template.
See docs/CONNECTING.md for the full walkthrough, or DocketBird_MCP_Installation_Guide.pdf for the same guide with screenshots.
Register at https://app.docketbird-mcp.com/signup with your email, password, and DocketBird API key
In Claude.ai or Claude Desktop, add a remote MCP server with URL https://app.docketbird-mcp.com/mcp
Claude auto-discovers OAuth, redirects you to log in, and connects
For Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json) or Cursor (~/.cursor/mcp.json):
{
"mcpServers": {
"docketbird-mcp": {
"command": "uv",
"args": [
"run",
"--directory",
"/path/to/docketbird-mcp-plus",
"python",
"docketbird_mcp.py"
],
"env": {
"DOCKETBIRD_API_KEY": "YOUR_KEY"
}
}
}
}The server uses OAuth 2.0 with PKCE for HTTP mode. Each user registers with their own DocketBird API key, which is stored server-side and attached to OAuth tokens. The SDK handles the protocol endpoints automatically:
/.well-known/oauth-authorization-server - OAuth metadata discovery
/register - Dynamic Client Registration
/authorize - Authorization endpoint (redirects to /login)
/token - Token exchange and refresh
In stdio mode, the DOCKETBIRD_API_KEY env var is used directly (no OAuth).
OAuth 2.0 with PKCE (no shared API key on the server)
Per-user DocketBird API keys stored in SQLite with bcrypt-hashed passwords
Rate limiting: 30 requests per 60 seconds per IP
HTTPS-only downloads with SSRF domain allowlist
Path traversal protection on file downloads
Container runs as non-root mcpuser
GitHub Actions pinned to commit SHAs
Dependencies pinned to exact versions
Expired tokens, auth codes, and pending sessions are purged hourly (in both stdio and HTTP modes)
Downloads — where files go: over a remote (HTTP) connection the download tools return document content and links to your client; a
save_pathis ignored (it would write to the server, not your machine). In local stdio mode, pass asave_pathto save to your own machine.
Install the dev extras and run the test suite:
uv pip install -e ".[dev]" # or: pip install -e ".[dev]"
pytestThe suite (tests/) runs fully offline — network calls are faked — and covers
the security helpers (path/URL validation, filename sanitization), pagination
math, the rate limiter, error formatting, the streaming download size cap, and
the remote-vs-local download behavior (inline content / links vs save-to-disk).
For a deeper look at how the server is wired together (OAuth flow, request
lifecycle, database schema, security model), see
docs/ARCHITECTURE.md.
stdio client shows JSON parse errors: ensure nothing in your environment writes to stdout. This server logs to stderr by design; custom forks should keep it that way.
No DocketBird API key available: in stdio mode set DOCKETBIRD_API_KEY;
in HTTP mode complete the OAuth login at /signup → connect from Claude.
OAuth login loops or "Invalid redirect URI": confirm SERVER_URL exactly
matches the public URL clients use (scheme + host, no trailing slash).
Changed your DocketBird API key but tools still fail: use /change-api-key.
It validates the new key against DocketBird and clears stale access tokens so
the new key takes effect immediately.
Deployed via Docker and GitHub Actions. Pushes to main trigger automatic deployment.
Domain: app.docketbird-mcp.com
Docker volume: docketbird-data at /app/data (SQLite auth database)
Health check: https://app.docketbird-mcp.com/health — returns
{"status":"ok","service":"docketbird-mcp","version":"<git-sha>"}, where
version is the deployed commit (set by the deploy workflow via GIT_SHA), so
a single curl confirms exactly which build is live.
Caddy reverse proxy handles HTTPS (Let's Encrypt)
docker build -t docketbird-mcp:latest .
docker run -d \
--name docketbird-mcp \
--restart=always \
-e SERVER_URL="http://localhost:8040" \
-v docketbird-data:/app/data \
-p 8040:8080 \
docketbird-mcp:latestcase_types.json - Case type abbreviations and examples (no API endpoint exists for these)
courts.json - Historical snapshot of court codes, frozen 2026-05-31. No longer read by any tool — docketbird_list_courts serves the live GET /courts endpoint.
This project is built upon the original docketbird-mcp developed in conjunction with @federicoburman and the Gravix.AI team.
Ask a natural-language question of DocketBird's litigation graph: parties, attorneys, law firms, judges, courts, and their connections.
This is the ONLY source of party/attorney/firm/judge relationships — the
docket endpoints do not return them. Examples: "What attorneys appeared
for Google in the Northern District of California?", "Every case where
Firm A appeared opposite Firm B", "What judges has Quinn Emanuel appeared
before?".
COVERAGE CEILING — read before trusting absence: the graph covers federal
civil cases active in DocketBird's data flows since July 2025 (roughly 30%
of federal civil cases). No criminal, bankruptcy, or state-court matters.
Zero records means "not in the graph," NEVER "no such cases exist" — do
not present an empty result as a finding that something doesn't exist.
Behavior:
- Slow: responses can take 10-25 seconds (an AI model interprets the
question, then queries the graph).
- Result shape varies with the question; entity IDs accompany names.
- At most 200 records per response; 'truncated' means more matches exist —
narrow the question to see the rest.
- Attorney email addresses are never included. This tool reports exactly
what the API returned — it never invents contact details.
Args:
question: The natural-language question (max 1000 characters).
| Name | Required | Description | Default |
|---|---|---|---|
| question | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds substantial behavioral context: slow 10-25s response, variable result shape, 200-record limit with truncated flag, no email addresses, and no invented data. No contradictions with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear sections (overview, coverage, behavior, args) and front-loaded with purpose. While every sentence adds value, it could be slightly more concise (e.g., the coverage ceiling explanation is repeated in two different ways).
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (NL query over graph, variable output), the description covers key expectations: coverage limits, slowness, result shape, truncation, and data policies. The existence of an output schema (mentioned in context) reduces the need for exhaustive return field documentation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single parameter 'question' has 0% schema description coverage. The description compensates fully by specifying it is natural-language, max 1000 characters, and provides usage context through examples. This adds clear meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool answers natural-language queries about the litigation graph, listing entities (parties, attorneys, etc.) and explicitly distinguishes it from siblings: 'This is the ONLY source of party/attorney/firm/judge relationships — the docket endpoints do not return them.' The verb 'ask' and resource 'litigation graph' are specific.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance on when to use the tool (for relationship queries), includes examples, and explains coverage limitations and empty result interpretation. It indirectly tells when not to use (not for criminal/bankruptcy/state) and names alternatives (docket endpoints).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create an autocalendar for a case, so its deadlines and hearings appear in your company's calendar (docketbird_get_calendar).
Practice scope: acts on YOUR DocketBird account. Creation is queued — the
case's docket sheet is updated first, then the autocalendar is built.
Court (PACER) fees may apply for the docket update.
When to use:
- Adding a case's deadlines to the firm's calendar
- After following a case you need to track dates for
Args:
case_id: DocketBird case ID (e.g., 'txnd-3:2007-cv-01697')
| Name | Required | Description | Default |
|---|---|---|---|
| case_id | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses queued creation, docket sheet update, and potential PACER fees. This goes beyond annotations (which only mark openWorldHint=true) by explaining side effects and costs.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Concise, well-structured: purpose, scope, behavior, usage, args. Every sentence adds value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers purpose, behavior, usage, parameter with examples. Output schema exists, so return info is not needed. References related tool for viewing calendar. Complete for a creation tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, but description provides domain context (DocketBird case ID) and an example format, adding significant meaning over the schema's bare type definition.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states verb (create), resource (autocalendar for a case), and outcome (deadlines and hearings appear in calendar). Distinguishes from sibling docketbird_get_calendar by referencing it and from docketbird_follow_case by specifying different action.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit 'When to use' section with two scenarios. Mentions practice scope and queuing behavior. Lacks explicit when-not-to-use or alternatives, but provides sufficient context for selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Download a specific document by ID.
Returns the document content to **you** (the client) as an embedded resource
so you can read or save it — this works over the remote HTTP connection. In
local stdio mode, passing ``save_path`` instead writes the file to that folder
on your own machine (the server runs locally there).
When to use:
- User wants to retrieve a specific filing
- After searching for documents
- Downloading individual documents
Args:
document_id: DocketBird document ID
save_path: Local folder to save into. Only honored in local stdio mode,
where the server shares your filesystem. Ignored over a remote
HTTP connection (the file would land on the server, not your
machine), where the content is returned to you directly.
Returns:
- Remote, or local with no save_path: a list of content blocks — a text
summary plus an embedded resource holding the document bytes (base64),
capped at MAX_INLINE_SIZE. If the document exceeds that cap, returns a
text message with its direct download URL instead of inlining it.
- Local stdio with save_path: a text confirmation of the saved file path.
- On error / unavailable / restricted: a plain text message.
| Name | Required | Description | Default |
|---|---|---|---|
| save_path | No | ||
| document_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description thoroughly discloses behavior beyond annotations: explains remote vs local modes, inline content vs URL fallback based on MAX_INLINE_SIZE, and error handling. This level of detail is valuable given the openWorldHint and no destructiveHint.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a summary, mode explanation, When to use, Args, and Returns sections. While slightly verbose, each sentence adds value and the information is front-loaded. No unnecessary repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the lack of output schema, the description covers all critical aspects: usage scenarios, parameter details, return types for remote/local modes, size cap behavior, and error cases. It is fully sufficient for an agent to invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema coverage, the description fully describes both parameters: document_id as the DocketBird document ID, and save_path with its mode-dependent behavior (ignored remotely, used locally). This adds essential meaning missing from the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Download a specific document by ID.' and differentiates itself from siblings by detailing two modes (remote vs local stdio), making its purpose distinct among tools like docketbird_get_document and docketbird_download_files.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The 'When to use' section explicitly lists three scenarios: retrieving a specific filing, after searching for documents, and downloading individual documents. While it lacks explicit 'when not to use' guidance, the context is clear enough for an agent to determine appropriate use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List or save every available document for a case.
A case can hold many large PDFs, so over a remote HTTP connection this returns
a list of per-document **direct download links** (pre-signed, short-lived)
rather than inlining every file — fetch the ones you need, or call
``docketbird_download_document`` for a single document's content. In local
stdio mode, passing ``save_path`` instead streams every file to that folder on
your own machine.
When to use:
- User wants the complete case file archive
- Bulk document retrieval
- Surveying which filings are available to download
Args:
case_id: DocketBird case ID
save_path: Local folder to save into. Only honored in local stdio mode,
where the server shares your filesystem. Over a remote HTTP
connection it is ignored and download links are returned instead.
Returns:
str: Markdown. Remote (or local with no save_path) lists each available
document's title, ID, and direct download URL, plus counts of
restricted/unavailable filings. Local stdio with save_path reports how
many files were saved to disk and any that were skipped or failed.
| Name | Required | Description | Default |
|---|---|---|---|
| case_id | Yes | ||
| save_path | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses that remote mode returns pre-signed short-lived download links, while local stdio with save_path streams files to disk. Describes return format as Markdown with counts. No contradictions with annotations (readOnlyHint=false, etc.).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with clear sections, but somewhat verbose. Could be slightly more concise while retaining all necessary information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Comprehensive coverage of tool's behavior across modes, return format, and edge cases (restricted/unavailable filings). Output schema exists but description still adds value.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but description explains both parameters: case_id as DocketBird case ID, save_path as local folder, noting it is only honored in local stdio mode. Fully compensates for missing schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states 'List or save every available document for a case' and distinguishes itself from sibling docketbird_download_document by noting that it provides links for bulk retrieval while the sibling handles single documents.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly lists when to use (complete archive, bulk retrieval, surveying filings) and implies when not to use (single document, instead call docketbird_download_document). Also explains mode-specific behavior (remote vs local stdio).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Follow a court case so DocketBird monitors it for new filings.
When to use:
- User wants to track/monitor a case for new documents
- Setting up ongoing monitoring of a docket
Followed federal cases are checked about twice weekly; state cases about
once weekly. New filings trigger DocketBird's new-documents notifications.
Args:
case_id: DocketBird case ID (e.g., 'txnd-3:2007-cv-01697')
| Name | Required | Description | Default |
|---|---|---|---|
| case_id | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations set readOnlyHint=false (mutation) and destructiveHint=false (non-destructive). The description adds behavioral context: monitoring frequency and that it triggers notifications. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-organized with a 'When to use' section, but it redundantly includes an 'Args' block that restates the parameter name from the schema. Could omit that section for conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given low complexity (1 required param, output schema exists), the description covers purpose, usage context, parameter format, and monitoring frequency. It is sufficient for an agent to use the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0% (only title 'Case Id'), but the description adds concrete meaning with an example format 'txnd-3:2007-cv-01697', compensating for the sparse schema. This helps the agent understand the expected input format.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb+resource combination ('Follow a court case so DocketBird monitors it for new filings') and clearly distinguishes from siblings like docketbird_search_cases or docketbird_get_case_details by focusing on ongoing monitoring.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The 'When to use' section explicitly states tracking/monitoring use cases. It also provides monitoring frequency (twice weekly for federal, once weekly for state), which helps the agent set expectations. However, it does not directly contrast with sibling tools, but the guidance is clear enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Full-text search of the BODIES of court filings across DocketBird's entire document index — all courts, all cases, not just your account.
This searches what the filings actually say, not what they are titled. To
match docket-entry titles within one case, use docketbird_search_documents.
When to use:
- Scanning recent filings for a company, industry, or legal topic
(e.g. new suits naming a target company — set sort='recency')
- Finding every filing whose text mentions a term, phrase, or citation
- Practice research inside your firm's own cases (set my_cases_only=True)
Scope boundary: with my_cases_only=False (default) this is cross-corpus
RESEARCH over public court records. With my_cases_only=True it is limited
to cases associated with your firm's account (resolved from your API key).
Query syntax:
- space / and: all terms must appear. or: either term.
- -term: exclude (the word 'not' is NOT supported).
- term* or term!: word endings (end of word only).
- /n, /s, /p: terms within n words / same sentence / same paragraph.
- "...": exact phrase. Email addresses and legal symbols (§, ¶) work.
Pagination contract (upstream cursors, bounded requests):
- next_cursor is the ONLY end-of-results signal. A page may hold fewer
than `size` documents — even zero — while more remain, because
restricted documents are removed after matching. Keep following the
cursor until it is null. The 'found' count may include documents that
will never be returned. Result window is the first 10,000 matches —
narrow with court_id/case_id/dates if you need the deep tail.
Args:
query: Full-text query (max 500 chars), e.g. '"summary judgment" and forfeit* -insurance'
court_id: Comma-separated court restriction; each entry may be a slug
('nysd'), an abbreviation ('S.D.N.Y.'), or a full court name.
case_id: Restrict to a single case by DocketBird case ID.
filed_after: Only documents filed on/after this date (YYYY-MM-DD).
filed_before: Only documents filed on/before this date (YYYY-MM-DD).
my_cases_only: True = only your firm's cases (practice scope);
False = the whole corpus (research/marketing scope).
sort: 'relevance' (default) or 'recency' (most recently filed first).
size: Results per page (default 25, max 50).
cursor: Pagination cursor from a previous response's next-page note.
| Name | Required | Description | Default |
|---|---|---|---|
| size | No | ||
| sort | No | relevance | |
| query | Yes | ||
| cursor | No | ||
| case_id | No | ||
| court_id | No | ||
| filed_after | No | ||
| filed_before | No | ||
| my_cases_only | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations (readOnlyHint, idempotentHint, etc.), the description discloses important behavioral details: cross-corpus vs. account-scoped search, pagination behavior (cursor, how to handle empty pages, result window limit of 10,000), and the fact that found count may be inaccurate due to removed documents. These enrich the agent's understanding of the tool's actions and constraints.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear sections (intro, differentiation, when-to-use, scope, query syntax, pagination, args). It is relatively long but every sentence serves a purpose, given the complexity of the tool (9 parameters, query syntax, pagination rules). Minor redundancy (scope boundary repeats some of 'when to use') prevents a perfect score.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (9 parameters, query syntax, pagination, scope boundaries), the description covers all necessary aspects: purpose, usage, parameter semantics, behavioral constraints, and edge cases. An output schema exists but is not shown; still, the description provides sufficient context for an AI agent to invoke the tool correctly without needing further clarification.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% description coverage, so the description must fully compensate. It provides an extensive 'Args' section that explains every parameter with meaning, constraints (e.g., query max 500 chars, date format YYYY-MM-DD, court_id formats), defaults, and examples (e.g., query: '"summary judgment" and forfeit* -insurance'). This adds substantial value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it performs full-text search of the bodies of court filings across the entire DocketBird index, and explicitly distinguishes itself from the sibling tool docketbird_search_documents by contrasting what is searched (text content vs. docket entry titles). This meets the standard of specific verb+resource with sibling differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit scenarios for when to use the tool (e.g., scanning recent filings, finding documents mentioning a term, practice research with my_cases_only=True) and contrasts it with docketbird_search_documents. It lacks a direct 'when not to use' statement, but the given guidance is clear and helpful for decision-making.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get calendar entries (deadlines, hearings, conferences) from your company's autocalendars — for one case, or company-wide.
Practice scope: this reads YOUR company's autocalendars (requires a full
DocketBird account with autocalendars created; see
docketbird_create_autocalendar).
Two scopes, one tool:
- With case_id: every calendar entry for that case.
- Without case_id: entries across ALL cases your company has active
autocalendars for, within the next `days` days — "what deadlines does my
firm have coming up?"
The company-wide scope is served from a pre-computed rollup; if it has
never been built, the API starts building it and this tool says to retry
in a minute or two.
Args:
case_id: DocketBird case ID (e.g., 'txnd-3:2007-cv-01697').
Omit for the company-wide scope.
days: Company-wide scope only: how many days ahead to include,
starting today (default 7, clamped to 1-90 upstream).
Ignored when case_id is given.
| Name | Required | Description | Default |
|---|---|---|---|
| days | No | ||
| case_id | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations (readOnlyHint, idempotentHint, destructiveHint) already indicate safe, read-only, idempotent behavior. The description adds that the company-wide scope uses a pre-computed rollup that may need building, and the tool will ask to retry if not built. No contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is well-structured with sections, clear scoping, and no wasted words. It is slightly lengthy but every sentence adds value. Could be trimmed slightly but remains highly organized.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given two optional parameters, no required params, and an output schema (not shown), the description covers all necessary context: usage scopes, prerequisites, rollup behavior, how days interacts with case_id. An AI agent can confidently decide when and how to invoke.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so description fully explains both parameters: case_id (format, default empty, omit for company-wide) and days (company-wide only, default 7, clamped 1-90, ignored with case_id). This provides comprehensive meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the tool retrieves calendar entries (deadlines, hearings, conferences) from autocalendars. It distinguishes two scopes: with case_id for a single case, and without for company-wide view. The verb 'get' and resource 'calendar entries' are specific, and the tool is distinct from all siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Description explicitly tells when to use case_id vs. omit it, explains the company-wide scope and its pre-computed rollup behavior, and references prerequisite docketbird_create_autocalendar. It also notes days is ignored when case_id is provided, giving clear usage boundaries.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get one case's metadata, including a pointer to its complaint.
A lightweight, research-scope lookup: works for any case in DocketBird's
index (not just your account's cases) and does NOT fetch the docket, so it
can't hit the large-docket timeout. Use docketbird_get_case_details for the
full docket sheet, and docketbird_ask_litigation_graph for parties/attorneys.
When to use:
- Resolving a case ID (e.g. from docketbird_search_cases) to its metadata
- Jumping straight to the initiating complaint
- Checking PACER case ID / client code without pulling the docket
Args:
case_id: DocketBird case ID (e.g., 'txwd-1:2022-cv-00398')
| Name | Required | Description | Default |
|---|---|---|---|
| case_id | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Adds context beyond annotations: lightweight, research-scope, works for any case in index (not just user's), does NOT fetch docket. No contradiction with annotations. Could mention rate limits or auth, but still strong.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with bullet points for usage scenarios and args. Concise but includes necessary details. Could be slightly shorter, but very readable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given output schema exists, description appropriately covers purpose, behavior, and parameter. Mentions return content (metadata and pointer to complaint). Complete for a simple lookup tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Despite 0% schema coverage, the description explains the case_id parameter with format and example ('txwd-1:2022-cv-00398'), compensating well for the missing schema description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the action is to get a case's metadata including a pointer to its complaint. Distinguishes from siblings by contrasting with get_case_details (full docket) and ask_litigation_graph (parties/attorneys).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly lists when to use (resolving case ID, jumping to complaint, checking PACER ID) and why not to use alternatives. Also notes it does not fetch docket to avoid timeout, providing clear context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a case's full docket sheet: case info plus its list of documents.
When to use:
- User wants the docket sheet (every filing in the case)
- Before downloading documents (to see what's available)
Notes:
- Parties and attorneys are NOT available from the docket endpoints; for
them, use docketbird_ask_litigation_graph.
- The upstream /documents endpoint has no pagination: the entire docket is
always fetched, and page/page_size only shape this response. Very large
dockets can hit DocketBird's own ~29s gateway timeout (a 504).
- For a case's metadata alone (no docket fetch), use docketbird_get_case.
Args:
case_id: DocketBird case ID (e.g., 'txnd-3:2007-cv-01697')
Format: {court_id}-{district}:{year}-{type}-{number}
page: Page number for documents (starts at 1, default 1)
page_size: Number of documents per page (default 20, max 50)
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | ||
| case_id | Yes | ||
| page_size | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint true, but the description adds crucial behavioral details: the upstream /documents endpoint has no pagination (entire docket fetched, page/page_size only shape response), potential 504 timeout for large dockets, and that parties/attorneys are not available from docket endpoints. This goes beyond 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.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear sections (When to use, Notes, Args) and front-loaded with a summary. While slightly long, every sentence provides value. A minor reduction could improve conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the output schema exists, the description covers purpose, usage, behavioral notes, and parameter details comprehensively. Sibling distinctions and limitations are addressed. The description leaves no critical gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the tool description fully explains all three parameters: case_id format with example, page defaults, and page_size defaults and max. This provides essential meaning the schema lacks.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves a case's full docket sheet including case info and list of documents. It distinguishes from the sibling docketbird_get_case, which provides only metadata. The verb 'get' and resource 'docket sheet' are specific.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use (when user wants the docket sheet or before downloading documents) and when not to use (for parties/attorneys, use docketbird_ask_litigation_graph). It also notes that for case metadata alone, use docketbird_get_case.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get one document's metadata and download links — without the bytes.
Lightweight lookup for a single filing: title, filing date, restricted
status, and (when retrieved) a direct PDF download link. Use
docketbird_download_document for the file content itself, or
docketbird_get_document_text for the extracted text.
When to use:
- Checking whether a filing is available/restricted before downloading
- Getting a direct PDF link to hand to the user
- Resolving a document ID from search results to its metadata
Args:
document_id: DocketBird document ID (e.g., 'txwd-1:2022-cv-00398-00177')
| Name | Required | Description | Default |
|---|---|---|---|
| document_id | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=true and destructiveHint=false. The description adds context: lightweight lookup, returns specific metadata, and mentions 'without the bytes'. No contradiction. Some behavioral details like link expiry are not covered, but overall sufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with distinct sections for purpose, return values, alternatives, usage scenarios, and argument description. Every sentence adds value, no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With one parameter, explicit usage guidance, and an output schema present, the description covers all necessary context. It addresses when to use versus siblings, making it complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single parameter 'document_id' is explained with a clear description and an example format. Schema coverage is 0%, so the description fully compensates.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves metadata and download links for one document without bytes. It specifies the returned fields (title, filing date, restricted status, PDF link) and distinguishes from sibling tools like docketbird_download_document and docketbird_get_document_text.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit 'When to use' section listing three specific scenarios. It also implies when not to use by naming alternatives for file content and extracted text.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the extracted plain text of a court filing.
Returns what the document says (for summarizing, quoting, comparing) rather
than its metadata or PDF — those come from docketbird_get_document /
docketbird_download_document.
Availability varies: some documents aren't downloaded yet, some are scans
with no text layer, some docket entries are text-only stubs with no
document. When no text is available this returns a clear message — the PDF
may still be retrievable via docketbird_get_document.
When to use:
- Reading, summarizing, or quoting a filing's contents
- Pulling the complaint's text after docketbird_get_case points to it
Args:
document_id: DocketBird document ID (e.g., 'txwd-1:2022-cv-00398-00177')
offset: Character offset into the text to start from (for paging
through long documents; default 0).
max_chars: Maximum characters to return (default 50000, max 200000).
| Name | Required | Description | Default |
|---|---|---|---|
| offset | No | ||
| max_chars | No | ||
| document_id | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint, idempotentHint, destructiveHint. The description adds behavioral context about text availability (scans, text-only stubs, not downloaded) and explains that a clear message is returned when text is unavailable, without contradicting annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with sections and bullet points, front-loaded purpose. While slightly long, every sentence adds value, and no unnecessary words are present.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (3 parameters, output schema exists), the description covers purpose, usage guidelines, parameter semantics, availability nuances, and sibling differentiation. It is fully sufficient for an agent to select and invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, but the description fully explains each parameter: document_id with example, offset for paging, max_chars with default and maximum. This adds essential meaning not present in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool gets extracted plain text of a court filing and distinguishes it from sibling tools that return metadata or PDFs (docketbird_get_document, docketbird_download_document). It uses specific verbs and resources.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit 'When to use' section lists reading/summarizing/quoting and pulling text after docketbird_get_case. Also discusses availability limitations and when other tools are appropriate, providing clear context for alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the cases on YOUR DocketBird account (practice scope).
This is your firm's tracked caseload only. To search all cases across all
courts, use docketbird_search_cases.
When to use:
- User wants to see their own/their firm's tracked cases
- Finding case IDs for calendar, follow, or autocalendar operations
Args:
scope: 'company' for all company cases, 'user' for personal cases
page: Page number (starts at 1, default 1)
page_size: Results per page (default 20, max 50)
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | ||
| scope | Yes | ||
| page_size | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnly, idempotent, and non-destructive behavior. The description adds the important context that only tracked cases (practice scope) are returned. While it doesn't discuss auth or rate limits, the added scope detail justifies a slightly above-baseline score.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise (about 100 words) and well-structured with a heading, a note about alternative, bullet-point usage scenarios, and a clean args list. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple listing functionality, rich annotations, and presence of an output schema, the description covers all essential aspects: purpose, scope, parameter details, and usage guidance. No gaps remain.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description carries full responsibility. It explains each parameter: scope enum values, page starting at 1, page_size default and max. This compensates fully for the lack of schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists cases on the user's DocketBird account (practice scope). It uses specific verbs and resources, and explicitly distinguishes from the sibling tool 'docketbird_search_cases' for searching all courts.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit when-to-use scenarios: viewing own/firm's tracked cases and finding case IDs for other operations. It also directs to an alternative tool for broader searches, giving clear usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Look up the courts DocketBird covers (live from the API).
Research scope — the full court set, independent of your account.
Behavior:
- No arguments: the curated set (~300 rows: all federal courts plus named
state courts), followed by the case-type reference for the case ID format.
- search: free-text lookup by court name ('Southern District of New York'),
abbreviation ('S.D.N.Y.'), or court_id ('nysd'); returns up to 25 ranked
matches from the FULL set of enabled courts, including several thousand
unlisted state courts. The fastest way to resolve a court to its court_id.
- court_system: browse every court inside one system (identifier from
docketbird_list_court_systems), including unlisted ones.
Args:
search: Free-text court lookup (name, abbreviation, or court_id).
court_system: Court-system identifier to browse (e.g. 'uc-tx-distct').
court_type: Optional filter: 'federal' or 'state'.
| Name | Required | Description | Default |
|---|---|---|---|
| search | No | ||
| court_type | No | ||
| court_system | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark it as readOnly and idempotent. The description adds key behavioral details: live API data, the curated vs full set behavior, search result limits (up to 25 ranked matches), and the use of court_system to include unlisted state courts. No contradictions with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with bold headers and bullet points, front-loading the main purpose. Every sentence adds value, though it is slightly verbose; the verbosity is justified by the need to explain multiple modes.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the three parameters and lack of schema descriptions, the description covers all modes and parameter effects. It includes behavior for no arguments, search, and court_system, as well as the optional court_type filter. The output schema handles return structure, so no further details needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, but the description thoroughly explains each parameter: search for free-text lookup, court_system for browsing a system, court_type as an optional filter. It also describes default behavior. This fully compensates for the missing schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists courts covered by DocketBird, live from the API, with three distinct lookup modes (none, search, court_system). It distinguishes itself from sibling docketbird_list_court_systems by focusing on individual courts rather than court systems.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains when to use each argument: no arguments returns a curated set, search is the fastest way to find a court_id, and court_system browses all courts in a system. It indirectly contrasts with search tools but does not explicitly list when not to use this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List every court system DocketBird covers (live from the API).
Returns the federal system plus each state court system, with a
human-readable name and how many covered courts each holds. Use a
court_system_id with docketbird_list_courts(court_system=...) to browse the
courts inside a system, including unlisted courts that don't appear in the
default listing. Changes rarely; safe to cache.
When to use:
- Discovering what state-court coverage exists
- Getting the identifier to browse one system's courts
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds the behavioral trait 'Changes rarely; safe to cache' beyond the annotations (readOnlyHint, idempotentHint, etc.). It also notes the data is live from the API, giving a complete picture of freshness and cacheability. No contradictions with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the primary purpose, uses bullet points for usage guidance, and every sentence adds relevant information. It is concise without being terse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given zero parameters and an output schema, the description fully covers what the tool does, when to use it, and how to interpret and apply the results. No gaps remain.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so baseline is 4. The description adds value by explaining the output structure (federal + state systems with names and court counts) and how to use the returned identifiers with docketbird_list_courts.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists every court system DocketBird covers, specifying the federal system and state court systems with human-readable names and court counts. It distinguishes from sibling tools like docketbird_list_courts by explicitly mentioning how to use a court_system_id to browse courts within a system.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description includes a 'When to use' section with concrete scenarios: discovering state-court coverage and getting identifiers to browse courts. It also references docketbird_list_courts as the follow-up tool, providing clear context and differentiation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search ALL cases in DocketBird's index by case name or case number.
Research scope: this covers every court and every case DocketBird knows
about — not just cases on your account (that's docketbird_list_cases).
Matching: case-number-shaped queries (e.g. '2:2017-bk-00112' or
'17-bk-112') match on filing year, case type, and terminating digits;
anything else matches against case names.
Date filters match in tiers: cases with an exact filing date match at day
precision; cases with only a known filing year match at year granularity;
cases with no known date are included unless exclude_unknown_dates=True.
When to use:
- Finding a case's DocketBird ID from a name or number
- Checking whether a company has been sued (pair with
docketbird_ask_litigation_graph for who represented whom)
Args:
query: Case name (e.g. 'Immedia Semiconductor') or case number
(e.g. '4:2022-cv-04775'). Max 500 chars.
court_id: Comma-separated court restriction; each entry may be a slug
('nysd'), an abbreviation ('S.D.N.Y.'), or a full court name.
filed_after: Only cases filed on/after this date (YYYY-MM-DD, inclusive).
filed_before: Only cases filed on/before this date (YYYY-MM-DD, inclusive).
exclude_unknown_dates: Drop cases whose filing date and year are both
unknown from date-filtered results (default False).
size: Results per page (default 25, max 50).
cursor: Pagination cursor from a previous response's next-page note.
| Name | Required | Description | Default |
|---|---|---|---|
| size | No | ||
| query | Yes | ||
| cursor | No | ||
| court_id | No | ||
| filed_after | No | ||
| filed_before | No | ||
| exclude_unknown_dates | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Adds significant behavioral detail beyond annotations: research scope (all courts), matching logic for case numbers vs names, date filter tier behavior, and pagination via cursor. No contradictions with readOnlyHint, idempotentHint, etc.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with summary, bullet points for scope/matching/dates, when-to-use, and Args. Every sentence is informative and no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Complete given 7 params, 1 required, output schema exists. Covers all parameters, behavior, scope, matching, date filtering, pagination, and usage guidance. No gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema coverage, description fully compensates by explaining each parameter: query (max 500 chars), court_id (formats), date params (inclusive, format), exclude_unknown_dates, size (bounds), cursor. Adds meaning beyond schema defaults.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it searches ALL cases by name or number, and explicitly distinguishes from sibling tool docketbird_list_cases which only covers user's account. The verb 'Search' and resource 'cases' are specific.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides a 'When to use' section with two concrete use cases and suggests pairing with docketbird_ask_litigation_graph. Not explicitly stating when not to use, but the guidance is clear and helpful.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find docket entries in ONE case whose title/description contains a term.
This matches docket-entry METADATA only (the title and description shown on
the docket sheet), not the text inside the filings. To search the full text
of filing bodies — across all courts or within one case — use
docketbird_fulltext_search instead.
When to use:
- User wants filings TITLED a certain way in a known case
(e.g. docket entries labeled "motion to dismiss")
- Narrowing down a docket sheet before download
Note: the upstream /documents endpoint has no pagination, so the entire
docket is always fetched and matched in memory; very large dockets can hit
DocketBird's own ~29s gateway timeout (a 504).
Args:
case_id: DocketBird case ID
search_term: Term to match against docket-entry titles/descriptions
page: Page number (starts at 1, default 1)
page_size: Results per page (default 20, max 50)
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | ||
| case_id | Yes | ||
| page_size | No | ||
| search_term | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations (readOnlyHint, etc.), it discloses the lack of pagination and potential 504 timeout for large dockets, and clarifies that it only searches metadata not full text.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-organized with a clear first sentence, bulleted usage guidance, a notable caveat, and a parameter list. Every sentence adds value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given output schema exists, return values are covered. The description explains scope, limitations, and parameter details, fully addressing the tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Despite 0% schema description coverage, the Args section explains each parameter's purpose, defaults, and constraints (e.g., page_size max 50).
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it finds docket entries in one case matching metadata (title/description), distinguishing itself from the sibling fulltext search tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit when-to-use scenarios (e.g., filings titled a certain way in a known case) and when-not-to-use (full text search), naming the alternative tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Each tool has a clearly distinct purpose. Full-text search vs. docket entry search, single document download vs. bulk, metadata-only vs. full docket, and the unique litigation graph tool prevent any ambiguity.
All tools follow a consistent 'docketbird_verb_noun' pattern in snake_case, with verbs like search, get, list, download, create, follow, ask. No mixing of conventions.
16 tools cover the essential functionalities of searching, listing, downloading, calendar management, and litigation graph queries without being excessive or sparse.
Core workflows (search, retrieve, download, calendar, monitor) are covered. Minor gaps like missing unfollow_case or delete_autocalendar exist, but agents can still operate effectively.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Search U.S. case law, fetch opinions, and ask matter-aware legal questions over your documents.
Official EUR-Lex, UK, US, and gazette search, metadata fetch, and change-only watches.
Resolve, search and verify legal citations against the official sources, with provenance.
Search US court opinions, federal dockets, judges, citations, and oral arguments via CourtListener.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/AIF-Of-Counsel/docketbird-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
