Skip to main content
Glama

congressgov-mcp-server

by io.github.cyanheads
OverviewDiscussionsAdmin

Congress.gov Bill Lookup

congressgov_bill_lookup
Read-onlyIdempotent

Browse and retrieve U.S. legislative bill data from Congress.gov. Discover bills by filtering on congress, bill type, and date range — there is no keyword search. Use 'list' to browse (requires congress, defaults to most-recently-updated first), 'get' for full bill detail (sponsor, policy area, CBO estimates, law info), or drill into a specific bill with 'actions', 'amendments', 'cosponsors', 'committees', 'subjects', 'summaries', 'text', 'titles', or 'related' (each requires congress + billType + billNumber). 'text' lists the published versions and their format URLs; 'content' then reads one version's actual text, a bounded character window at a time. 'summaries' takes an optional versionCode selector and returns each row's text a bounded character window at a time — a row past the window carries textTotalCharacters/textTruncated/textNextOffset, and characterOffset reads on from there.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
limitNoResults per page (1-250).
orderNoSort order for 'list' (sorts by update date). 'recent' (default) is newest first; 'oldest' is ascending. Ignored by other operations.recent
formatNoDocument format for 'content'. 'text' is GPO's Formatted Text — plain, pre-formatted print output, published for every document checked. 'xml' prefers United States Legislative Markup and falls back to Formatted XML; it exists on some bill text versions and on no committee report or Congressional Record article. PDF is not retrieved — read one at the format URLs 'text'/'articles' return.text
offsetNoPagination offset.
billTypeNoBill type code. Required for get and sub-resource operations.
congressYesCongress number (e.g., 118, 119).
operationYesWhich data to retrieve.
billNumberNoBill number. Required for get and sub-resource operations. Accepts the digit-string form list rows carry (e.g. "9479") as well as a number.
toDateTimeNoEnd of date range filter (ISO 8601). Same field semantics as fromDateTime.
versionCodeNoWhich summary version 'summaries' returns — the versionCode a summary row carries ('00' introduced, '49' public law). Selection runs over the bill's whole summary list, which Congress.gov publishes no filter for, and limit/offset then page the matching rows. Omit to return every version. Ignored by other operations.
fromDateTimeNoStart of date range filter (ISO 8601). Filters by the bill's update date — when Congress.gov last touched the record — not by the bill's latest legislative action.
characterLimitNoMaximum characters to return (1-100000) — for the document window on 'content', and for each row's summary text on 'summaries'. Legislative documents run past a million characters and an enacted bill's summary past two hundred thousand, so either takes several windows.
characterOffsetNoFirst character to return, 0-based — of the document on 'content', and of every returned row's summary text on 'summaries'. Offsets are exact and are never snapped to a section or paragraph break, so feeding back the response's nextOffset (or a summary row's textNextOffset) walks the whole text with every character returned exactly once.
textVersionIndexNoWhich text version 'content' reads, 0-based against the same order 'text' returns — 0 is the most recent version. Ignored by other operations.

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault
billNoDynamic upstream JSON record.
dataNoResult rows. Per-tool item shape is rendered in the markdown body.
errorNoPresent when the call failed. Absent on success.
noticeNoGuidance when results are empty, a page is past the end, or a caveat applies.
contentNoDynamic upstream JSON record.
paginationNoPagination metadata: total count and next offset.
totalCountNoTotal results across all pages.
effectiveQueryNoThe browse scope and applied filters.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed4 schema fields changed
    • changedInput schema / properties / characterLimit / description
      Previous value: -"Maximum characters to return for 'content' (1-100000). Legislative documents run past a million characters, so a full bill takes several windows."New value: +"Maximum characters to return (1-100000) — for the document window on 'content', and for each row's summary text on 'summaries'. Legislative documents run past a million characters and an enacted bill's summary past two hundred thousand, so either takes several windows."
    • changedInput schema / properties / characterOffset / description
      Previous value: -"First character to return for 'content', 0-based. Offsets are exact and are never snapped to a section or paragraph break, so feeding the response's nextOffset back walks the whole document with every character returned exactly once."New value: +"First character to return, 0-based — of the document on 'content', and of every returned row's summary text on 'summaries'. Offsets are exact and are never snapped to a section or paragraph break, so feeding back the response's nextOffset (or a summary row's textNextOffset) walks the whole text with every character returned exactly once."
    • addedInput schema / properties / versionCode
      Added value: +{
+  "description": "Which summary version 'summaries' returns — the versionCode a summary row carries ('00' introduced, '49' public law). Selection runs over the bill's whole summary list, which Congress.gov publishes no filter for, and limit/offset then page the matching rows. Omit to return every version. Ignored by other operations.",
+  "type": "string"
+}
    • changedOutput schema / properties / error / properties / data / properties / reason / description
      Previous value: -"Machine-readable failure mode. Declared by this tool: `not_found`: A requested bill, member, committee, report, vote, or nomination does not exist in Congress.gov. `rate_limited`: The Congress.gov API rate limit (5,000 requests/hour per key) was exceeded. `invalid_request`: Congress.gov rejected the request as malformed — a bad date range or an identifier with an unexpected shape. `upstream_error`: Congress.gov returned an unexpected error (5xx or another non-2xx status). `document_unavailable`: The 'content' selection resolves to no retrievable document — the text version or article index is past the end of the list, the record publishes no formats at all, or Congress.gov does not hold the file its own metadata names. `format_unavailable`: The document exists but publishes nothing in the requested 'format' — some text versions and committee reports ship PDF only, and no Congressional Record article publishes XML. `document_fetch_failed`: www.congress.gov did not return a readable document — a non-2xx status, a network failure, an empty body, or a content type that is not text or XML. `document_too_large`: The document is larger than the byte ceiling this server retrieves, so no character window can be served from it. `offset_past_end`: characterOffset is at or beyond the last character of the document, so the window would be empty. Other values are possible when a failure originates below the handler."New value: +"Machine-readable failure mode. Declared by this tool: `not_found`: A requested bill, member, committee, report, vote, or nomination does not exist in Congress.gov. `rate_limited`: The Congress.gov API rate limit (5,000 requests/hour per key) was exceeded. `invalid_request`: Congress.gov rejected the request as malformed — a bad date range or an identifier with an unexpected shape. `upstream_error`: Congress.gov returned an unexpected error (5xx or another non-2xx status). `document_unavailable`: The 'content' selection resolves to no retrievable document — the text version or article index is past the end of the list, the record publishes no formats at all, or Congress.gov does not hold the file its own metadata names. `format_unavailable`: The document exists but publishes nothing in the requested 'format' — some text versions and committee reports ship PDF only, and no Congressional Record article publishes XML. `document_fetch_failed`: www.congress.gov did not return a readable document — a non-2xx status, a network failure, an empty body, or a content type that is not text or XML. `document_too_large`: The document is larger than the byte ceiling this server retrieves, so no character window can be served from it. `offset_past_end`: characterOffset is at or beyond the last character of every text the call would window — the document on 'content', or every returned row's summary text on 'summaries' — so the window would be empty. Other values are possible when a failure originates below the handler."
  2. Changed2 schema fields changed
    • addedOutput schema / properties / bill
      Added value: +{
+  "additionalProperties": {},
+  "description": "Dynamic upstream JSON record.",
+  "properties": {},
+  "type": "object"
+}
    • addedOutput schema / properties / content
      Added value: +{
+  "additionalProperties": {},
+  "description": "Dynamic upstream JSON record.",
+  "properties": {},
+  "type": "object"
+}
  3. Changed6 schema fields changed
    • changedInput schema / $schema
      Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"
    • addedInput schema / additionalProperties
      Added value: +false
    • changedOutput schema / $schema
      Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"
    • addedOutput schema / anyOf
      Added value: +[
+  {
+    "not": {
+      "required": [
+        "error"
+      ]
+    },
+    "required": [
+      "effectiveQuery",
+      "totalCount"
+    ]
+  },
+  {
+    "required": [
+      "error"
+    ]
+  }
+]
    • addedOutput schema / properties / error
      Added value: +{
+  "additionalProperties": {},
+  "description": "Present when the call failed. Absent on success.",
+  "properties": {
+    "code": {
+      "description": "JSON-RPC error code for this failure.",
+      "maximum": 9007199254740991,
+      "minimum": -9007199254740991,
+      "type": "integer"
+    },
+    "data": {
+      "additionalProperties": {},
+      "properties": {
+        "reason": {
+          "description": "Machine-readable failure mode. Declared by this tool: `not_found`: A requested bill, member, committee, report, vote, or nomination does not exist in Congress.gov. `rate_limited`: The Congress.gov API rate limit (5,000 requests/hour per key) was exceeded. `invalid_request`: Congress.gov rejected the request as malformed — a bad date range or an identifier with an unexpected shape. `upstream_error`: Congress.gov returned an unexpected error (5xx or another non-2xx status). `document_unavailable`: The 'content' selection resolves to no retrievable document — the text version or article index is past the end of the list, the record publishes no formats at all, or Congress.gov does not hold the file its own metadata names. `format_unavailable`: The document exists but publishes nothing in the requested 'format' — some text versions and committee reports ship PDF only, and no Congressional Record article publishes XML. `document_fetch_failed`: www.congress.gov did not return a readable document — a non-2xx status, a network failure, an empty body, or a content type that is not text or XML. `document_too_large`: The document is larger than the byte ceiling this server retrieves, so no character window can be served from it. `offset_past_end`: characterOffset is at or beyond the last character of the document, so the window would be empty. Other values are possible when a failure originates below the handler.",
+          "examples": [
+            "not_found",
+            "rate_limited",
+            "invalid_request",
+            "upstream_error",
+            "document_unavailable",
+            "format_unavailable",
+            "document_fetch_failed",
+            "document_too_large",
+            "offset_past_end"
+          ],
+          "type": "string"
+        },
+        "recovery": {
+          "additionalProperties": {},
+          "description": "Actionable next step for the caller.",
+          "properties": {
+            "hint": {
+              "type": "string"
+            }
+          },
+          "required": [
+            "hint"
+          ],
+          "type": "object"
+        },
+        "retryable": {
+          "description": "Whether retrying may succeed.",
+          "type": "boolean"
+        }
+      },
+      "type": "object"
+    },
+    "message": {
+      "description": "Human-readable description of what went wrong.",
+      "type": "string"
+    }
+  },
+  "required": [
+    "code",
+    "message"
+  ],
+  "type": "object"
+}
    • removedOutput schema / required
      Removed value: -[
-  "effectiveQuery",
-  "totalCount"
-]
  4. Changed10 schema fields changed
    • addedInput schema / properties / billNumber / anyOf
      Added value: +[
+  {
+    "description": "Positive integer form.",
+    "exclusiveMinimum": 0,
+    "maximum": 9007199254740991,
+    "type": "integer"
+  },
+  {
+    "description": "Digit-string form, as list rows carry it.",
+    "pattern": "^0*[1-9]\\d*$",
+    "type": "string"
+  }
+]
    • changedInput schema / properties / billNumber / description
      Previous value: -"Bill number. Required for get and sub-resource operations."New value: +"Bill number. Required for get and sub-resource operations. Accepts the digit-string form list rows carry (e.g. \"9479\") as well as a number."
    • removedInput schema / properties / billNumber / exclusiveMinimum
      Removed value: -0
    • removedInput schema / properties / billNumber / maximum
      Removed value: -9007199254740991
    • removedInput schema / properties / billNumber / type
      Removed value: -"integer"
    • addedInput schema / properties / characterLimit
      Added value: +{
+  "default": 25000,
+  "description": "Maximum characters to return for 'content' (1-100000). Legislative documents run past a million characters, so a full bill takes several windows.",
+  "maximum": 100000,
+  "minimum": 1,
+  "type": "integer"
+}
    • addedInput schema / properties / characterOffset
      Added value: +{
+  "default": 0,
+  "description": "First character to return for 'content', 0-based. Offsets are exact and are never snapped to a section or paragraph break, so feeding the response's nextOffset back walks the whole document with every character returned exactly once.",
+  "maximum": 9007199254740991,
+  "minimum": 0,
+  "type": "integer"
+}
    • addedInput schema / properties / format
      Added value: +{
+  "default": "text",
+  "description": "Document format for 'content'. 'text' is GPO's Formatted Text — plain, pre-formatted print output, published for every document checked. 'xml' prefers United States Legislative Markup and falls back to Formatted XML; it exists on some bill text versions and on no committee report or Congressional Record article. PDF is not retrieved — read one at the format URLs 'text'/'articles' return.",
+  "enum": [
+    "text",
+    "xml"
+  ],
+  "type": "string"
+}
    • changedInput schema / properties / operation / enum
      Previous value: -[
-  "list",
-  "get",
-  "actions",
-  "amendments",
-  "cosponsors",
-  "committees",
-  "subjects",
-  "summaries",
-  "text",
-  "titles",
-  "related"
-]New value: +[
+  "list",
+  "get",
+  "actions",
+  "amendments",
+  "cosponsors",
+  "committees",
+  "subjects",
+  "summaries",
+  "text",
+  "titles",
+  "related",
+  "content"
+]
    • addedInput schema / properties / textVersionIndex
      Added value: +{
+  "default": 0,
+  "description": "Which text version 'content' reads, 0-based against the same order 'text' returns — 0 is the most recent version. Ignored by other operations.",
+  "maximum": 9007199254740991,
+  "minimum": 0,
+  "type": "integer"
+}
  5. Changed6 schema fields changed
    • removedOutput schema / description
      Removed value: -"Detail-mode key 'bill' carries: Bill record (sponsor, policy area, latest action, CBO estimates, law citation) for `get`; absent for `list` and sub-resources."
    • addedOutput schema / properties / effectiveQuery
      Added value: +{
+  "description": "The browse scope and applied filters.",
+  "type": "string"
+}
    • addedOutput schema / properties / notice
      Added value: +{
+  "description": "Guidance when results are empty, a page is past the end, or a caveat applies.",
+  "type": "string"
+}
    • removedOutput schema / properties / query
      Removed value: -{
-  "description": "Echo of the applied filters for list-mode queries. Rendered as the first line of the response.",
-  "type": "string"
-}
    • addedOutput schema / properties / totalCount
      Added value: +{
+  "description": "Total results across all pages.",
+  "type": "number"
+}
    • addedOutput schema / required
      Added value: +[
+  "effectiveQuery",
+  "totalCount"
+]
  6. Changed4 schema fields changed
    • changedOutput schema / description
      Previous value: -"Bill data from Congress.gov API."New value: +"Detail-mode key 'bill' carries: Bill record (sponsor, policy area, latest action, CBO estimates, law citation) for `get`; absent for `list` and sub-resources."
    • addedOutput schema / properties / data
      Added value: +{
+  "description": "Result rows. Per-tool item shape is rendered in the markdown body.",
+  "items": {
+    "additionalProperties": {},
+    "description": "Upstream JSON record. Per-tool item shape is rendered in the markdown body.",
+    "properties": {},
+    "type": "object"
+  },
+  "type": "array"
+}
    • addedOutput schema / properties / pagination
      Added value: +{
+  "additionalProperties": false,
+  "description": "Pagination metadata: total count and next offset.",
+  "properties": {
+    "count": {
+      "description": "Total result count across all pages.",
+      "maximum": 9007199254740991,
+      "minimum": 0,
+      "type": "integer"
+    },
+    "nextOffset": {
+      "anyOf": [
+        {
+          "maximum": 9007199254740991,
+          "minimum": 0,
+          "type": "integer"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "Offset to pass for the next page, or null when there are no more pages."
+    }
+  },
+  "required": [
+    "count"
+  ],
+  "type": "object"
+}
    • addedOutput schema / properties / query
      Added value: +{
+  "description": "Echo of the applied filters for list-mode queries. Rendered as the first line of the response.",
+  "type": "string"
+}
  7. Changed3 schema fields changed
    • changedInput schema / properties / fromDateTime / description
      Previous value: -"Start of date range filter (ISO 8601). Filters by latest action date."New value: +"Start of date range filter (ISO 8601). Filters by the bill's update date — when Congress.gov last touched the record — not by the bill's latest legislative action."
    • addedInput schema / properties / order
      Added value: +{
+  "default": "recent",
+  "description": "Sort order for 'list' (sorts by update date). 'recent' (default) is newest first; 'oldest' is ascending. Ignored by other operations.",
+  "enum": [
+    "recent",
+    "oldest"
+  ],
+  "type": "string"
+}
    • changedInput schema / properties / toDateTime / description
      Previous value: -"End of date range filter (ISO 8601)."New value: +"End of date range filter (ISO 8601). Same field semantics as fromDateTime."
  8. Changed3 schema fields changed
    • removedOutput schema / properties / bill
      Removed value: -{
-  "additionalProperties": {},
-  "description": "Bill detail for operation=\"get\".",
-  "properties": {
-    "congress": {
-      "anyOf": [
-        {
-          "type": "number"
-        },
-        {
-          "type": "string"
-        }
-      ],
-      "description": "Congress number when Congress.gov includes it."
-    },
-    "latestAction": {
-      "additionalProperties": {},
-      "description": "Latest action summary when provided by Congress.gov.",
-      "properties": {
-        "actionDate": {
-          "description": "Latest action date when provided by Congress.gov.",
-          "type": "string"
-        },
-        "text": {
-          "description": "Latest action text when provided by Congress.gov.",
-          "type": "string"
-        }
-      },
-      "type": "object"
-    },
-    "number": {
-      "anyOf": [
-        {
-          "type": "number"
-        },
-        {
-          "type": "string"
-        }
-      ],
-      "description": "Bill number when provided by Congress.gov."
-    },
-    "title": {
-      "description": "Bill title when provided by Congress.gov. Omitted when unknown.",
-      "type": "string"
-    },
-    "type": {
-      "description": "Bill type code when provided by Congress.gov.",
-      "type": "string"
-    },
-    "updateDate": {
-      "description": "Last update timestamp when provided by Congress.gov.",
-      "type": "string"
-    }
-  },
-  "type": "object"
-}
    • removedOutput schema / properties / data
      Removed value: -{
-  "description": "List or sub-resource records for list and drill-down operations. Preserves upstream item shapes instead of narrowing them.",
-  "items": {},
-  "type": "array"
-}
    • removedOutput schema / properties / pagination
      Removed value: -{
-  "additionalProperties": false,
-  "description": "Pagination metadata for list and sub-resource operations.",
-  "properties": {
-    "count": {
-      "description": "Total number of matching records.",
-      "maximum": 9007199254740991,
-      "minimum": 0,
-      "type": "integer"
-    },
-    "nextOffset": {
-      "anyOf": [
-        {
-          "maximum": 9007199254740991,
-          "minimum": 0,
-          "type": "integer"
-        },
-        {
-          "type": "null"
-        }
-      ],
-      "description": "Offset to request the next page, or null when there is no next page."
-    }
-  },
-  "required": [
-    "count",
-    "nextOffset"
-  ],
-  "type": "object"
-}
  9. Changed3 schema fields changed
    • addedOutput schema / properties / bill
      Added value: +{
+  "additionalProperties": {},
+  "description": "Bill detail for operation=\"get\".",
+  "properties": {
+    "congress": {
+      "anyOf": [
+        {
+          "type": "number"
+        },
+        {
+          "type": "string"
+        }
+      ],
+      "description": "Congress number when Congress.gov includes it."
+    },
+    "latestAction": {
+      "additionalProperties": {},
+      "description": "Latest action summary when provided by Congress.gov.",
+      "properties": {
+        "actionDate": {
+          "description": "Latest action date when provided by Congress.gov.",
+          "type": "string"
+        },
+        "text": {
+          "description": "Latest action text when provided by Congress.gov.",
+          "type": "string"
+        }
+      },
+      "type": "object"
+    },
+    "number": {
+      "anyOf": [
+        {
+          "type": "number"
+        },
+        {
+          "type": "string"
+        }
+      ],
+      "description": "Bill number when provided by Congress.gov."
+    },
+    "title": {
+      "description": "Bill title when provided by Congress.gov. Omitted when unknown.",
+      "type": "string"
+    },
+    "type": {
+      "description": "Bill type code when provided by Congress.gov.",
+      "type": "string"
+    },
+    "updateDate": {
+      "description": "Last update timestamp when provided by Congress.gov.",
+      "type": "string"
+    }
+  },
+  "type": "object"
+}
    • addedOutput schema / properties / data
      Added value: +{
+  "description": "List or sub-resource records for list and drill-down operations. Preserves upstream item shapes instead of narrowing them.",
+  "items": {},
+  "type": "array"
+}
    • addedOutput schema / properties / pagination
      Added value: +{
+  "additionalProperties": false,
+  "description": "Pagination metadata for list and sub-resource operations.",
+  "properties": {
+    "count": {
+      "description": "Total number of matching records.",
+      "maximum": 9007199254740991,
+      "minimum": 0,
+      "type": "integer"
+    },
+    "nextOffset": {
+      "anyOf": [
+        {
+          "maximum": 9007199254740991,
+          "minimum": 0,
+          "type": "integer"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "Offset to request the next page, or null when there is no next page."
+    }
+  },
+  "required": [
+    "count",
+    "nextOffset"
+  ],
+  "type": "object"
+}
  10. First observed

TDQS

A4.5/5.0
Behavior5/5

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

Annotations already mark the tool as read-only and idempotent, and the description adds substantial behavior beyond that: bounded character windows with exact offsets, textTotalCharacters/textTruncated/textNextOffset cursor mechanics, filtering by update date rather than legislative action, format fallback rules for XML, and PDF non-retrieval. This is far more than annotations alone provide.

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

Conciseness4/5

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

The description is dense and front-loaded with the purpose, and every sentence conveys useful information. However, it is a long single paragraph that mixes operation guidance with parameter nuances; bulleted or labeled sub-sections would improve scanability without adding length.

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?

Given the tool's complexity (14 parameters, 12 operations, output schema present), the description covers operation-specific requirements, pagination and windowing mechanics, date filtering semantics, and format behaviors. Little is left for the agent to infer, and the existing output schema handles return-value documentation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Although schema coverage is 100%, the description enriches several parameters well beyond their schema entries. Examples include 'fromDateTime' filtering semantics, the digit-string form for 'billNumber', the versionCode selection behavior, textVersionIndex ordering, and the exactness of characterOffset. This significantly reduces misconfiguration risk.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific resource and verb: 'Browse and retrieve U.S. legislative bill data from Congress.gov.' It also scopes the tool by noting the absence of keyword search. However, it does not explicitly differentiate from the sibling congressgov_bill_summaries, which overlaps with the 'summaries' operation offered here, so sibling distinction is incomplete.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Clear internal guidance is provided: 'Use ''list'' to browse', ''get'' for full bill detail', and 'drill into a specific bill with...' operations, including required parameters for each. It does not, however, discuss when to prefer a sibling tool over this one, so no exclusions or alternative selection criteria are given.

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

All congressgov-mcp-server 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