Skip to main content
Glama

Congress

by io.github.pipeworx-io
OverviewDiscussionsAdmin

Search Bills

search_bills
Read-onlyIdempotent

ANSWERS "what bills about X has Congress introduced" / "recent congressional bills on X" / "federal legislation about X" / "find the Act" — searches US FEDERAL congressional bills (US House & Senate, national laws) BY BILL NAME, SUBJECT OR KEYWORD, including recently introduced ones. Results are RANKED by how well each bill's titles match the query — exact title first, then a title containing the phrase, then all query words, then partial overlap, newer Congress first on ties — so the first result is the best title match and each bill carries its match tier. The current Congress and the two before it are searched in depth plus the first page of matches from every earlier Congress; pass congress to search one Congress exhaustively (e.g. a bill from the 111th). Prefer this over a date-sorted recent-bills listing whenever the question names a topic or a bill, since only this tool can filter by it. Returns bill type, number, title, status, sponsor, and introduction date. Use get_bill with congress + bill_type + number for full details. NOTE: this is the US Congress (federal) ONLY — for STATE legislature bills (e.g. California, Texas, New York, or any US state legislation) use legiscan or openstates instead, not this tool.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
limitNoNumber of results to return (default: 10, max: 100)
queryYesBill name, keywords or subject to match against bill titles, e.g. "Lower Energy Costs Act" or "crypto"
congressNoOptional Congress number (e.g. 111) to search exhaustively. Without it the three most recent Congresses are searched in depth and every earlier one only shallowly, so name a Congress when the bill is older than about six years.

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault
billsYes
queryYesSearch query used
totalYesGovTrack loose keyword-match count for the query (any query word may match any bill title); see total_note
rankingYesHow the bills are ordered: local title-match re-rank (exact > phrase > all_words > partial, newer Congress first on ties); GovTrack order is not by relevance
returnedYesNumber of bills returned
total_noteYesExplains that total is a loose keyword-match count, not the number of bills about the subject
candidates_rankedYesNumber of distinct upstream candidate bills that were scored and ranked
congresses_searchedYesWhich Congresses were searched and how deeply: {in_depth, one_page, plus, hint} by default, or {exhaustive, coverage} when a congress argument was given

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed12 schema fields changed
    • changedInput schema / examples
      Previous value: -[
-  {
-    "query": "climate change"
-  },
-  {
-    "limit": 25,
-    "query": "healthcare reform"
-  }
-]New value: +[
+  {
+    "limit": 10,
+    "query": "Lower Energy Costs Act"
+  },
+  {
+    "limit": 5,
+    "query": "crypto"
+  },
+  {
+    "congress": 111,
+    "limit": 5,
+    "query": "Patient Protection and Affordable Care Act"
+  }
+]
    • addedInput schema / properties / congress
      Added value: +{
+  "description": "Optional Congress number (e.g. 111) to search exhaustively. Without it the three most recent Congresses are searched in depth and every earlier one only shallowly, so name a Congress when the bill is older than about six years.",
+  "type": "number"
+}
    • changedInput schema / properties / query / description
      Previous value: -"Keywords to search for in bill titles"New value: +"Bill name, keywords or subject to match against bill titles, e.g. \"Lower Energy Costs Act\" or \"crypto\""
    • addedOutput schema / properties / bills / items / properties / match
      Added value: +{
+  "description": "How well the bill's titles match the query: exact title, title containing the phrase, all query words present, some words present, or no title-word overlap",
+  "enum": [
+    "exact",
+    "phrase",
+    "all_words",
+    "partial",
+    "none"
+  ],
+  "type": "string"
+}
    • addedOutput schema / properties / bills / items / properties / matched_title
      Added value: +{
+  "description": "The bill title (display, short or official) that produced the match tier, or null",
+  "type": [
+    "string",
+    "null"
+  ]
+}
    • changedOutput schema / properties / bills / items / required
      Previous value: -[
-  "id"
-]New value: +[
+  "id",
+  "match",
+  "matched_title"
+]
    • addedOutput schema / properties / candidates_ranked
      Added value: +{
+  "description": "Number of distinct upstream candidate bills that were scored and ranked",
+  "type": "number"
+}
    • addedOutput schema / properties / congresses_searched
      Added value: +{
+  "description": "Which Congresses were searched and how deeply: {in_depth, one_page, plus, hint} by default, or {exhaustive, coverage} when a congress argument was given",
+  "type": "object"
+}
    • addedOutput schema / properties / ranking
      Added value: +{
+  "description": "How the bills are ordered: local title-match re-rank (exact > phrase > all_words > partial, newer Congress first on ties); GovTrack order is not by relevance",
+  "type": "string"
+}
    • changedOutput schema / properties / total / description
      Previous value: -"Total matching bills available"New value: +"GovTrack loose keyword-match count for the query (any query word may match any bill title); see total_note"
    • addedOutput schema / properties / total_note
      Added value: +{
+  "description": "Explains that total is a loose keyword-match count, not the number of bills about the subject",
+  "type": "string"
+}
    • changedOutput schema / required
      Previous value: -[
-  "query",
-  "total",
-  "returned",
-  "bills"
-]New value: +[
+  "query",
+  "total",
+  "returned",
+  "bills",
+  "total_note",
+  "ranking",
+  "candidates_ranked",
+  "congresses_searched"
+]
  2. Changed2 schema fields changed
    • addedInput schema / examples
      Added value: +[
+  {
+    "query": "climate change"
+  },
+  {
+    "limit": 25,
+    "query": "healthcare reform"
+  }
+]
    • changedOutput schema / (root)
      Previous value: -nullNew value: +{
+  "properties": {
+    "bills": {
+      "items": {
+        "properties": {
+          "bill_type": {
+            "description": "Bill type code",
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "bill_type_label": {
+            "description": "Bill type label",
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "congress": {
+            "description": "Congress number",
+            "type": [
+              "number",
+              "null"
+            ]
+          },
+          "id": {
+            "description": "Bill ID",
+            "type": "number"
+          },
+          "introduced_date": {
+            "description": "Bill introduction date",
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "link": {
+            "description": "GovTrack bill URL",
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "number": {
+            "description": "Bill number",
+            "type": [
+              "number",
+              "null"
+            ]
+          },
+          "sponsor_name": {
+            "description": "Primary sponsor name",
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "status": {
+            "description": "Current status code",
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "status_date": {
+            "description": "Date of current status",
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "status_label": {
+            "description": "Current status label",
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "title": {
+            "description": "Full bill title",
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "title_without_number": {
+            "description": "Bill title without number prefix",
+            "type": [
+              "string",
+              "null"
+            ]
+          }
+        },
+        "required": [
+          "id"
+        ],
+        "type": "object"
+      },
+      "type": "array"
+    },
+    "query": {
+      "description": "Search query used",
+      "type": "string"
+    },
+    "returned": {
+      "description": "Number of bills returned",
+      "type": "number"
+    },
+    "total": {
+      "description": "Total matching bills available",
+      "type": "number"
+    }
+  },
+  "required": [
+    "query",
+    "total",
+    "returned",
+    "bills"
+  ],
+  "type": "object"
+}
  3. Changed2 schema fields changed
    • removedInput schema / examples
      Removed value: -[
-  {
-    "_apiKey": "your-propublica-congress-api-key",
-    "congress": 118,
-    "query": "climate change"
-  },
-  {
-    "_apiKey": "your-propublica-congress-api-key",
-    "query": "infrastructure"
-  }
-]
    • changedOutput schema / (root)
      Previous value: -{
-  "properties": {
-    "bills": {
-      "description": "List of bills (up to 20)",
-      "items": {
-        "properties": {
-          "active": {
-            "description": "Currently active",
-            "type": [
-              "boolean",
-              "null"
-            ]
-          },
-          "bill_id": {
-            "description": "Bill ID",
-            "type": [
-              "string",
-              "null"
-            ]
-          },
-          "bill_type": {
-            "description": "Bill type (H.R., S., etc.)",
-            "type": [
-              "string",
-              "null"
-            ]
-          },
-          "introduced_date": {
-            "description": "Introduction date",
-            "type": [
-              "string",
-              "null"
-            ]
-          },
-          "latest_action": {
-            "description": "Latest major action",
-            "type": [
-              "string",
-              "null"
-            ]
-          },
-          "latest_action_date": {
-            "description": "Latest major action date",
-            "type": [
-              "string",
-              "null"
-            ]
-          },
-          "number": {
-            "description": "Bill number",
-            "type": [
-              "string",
-              "null"
-            ]
-          },
-          "primary_subject": {
-            "description": "Primary subject",
-            "type": [
-              "string",
-              "null"
-            ]
-          },
-          "sponsor_name": {
-            "description": "Sponsor name",
-            "type": [
-              "string",
-              "null"
-            ]
-          },
-          "sponsor_party": {
-            "description": "Sponsor party",
-            "type": [
-              "string",
-              "null"
-            ]
-          },
-          "sponsor_state": {
-            "description": "Sponsor state",
-            "type": [
-              "string",
-              "null"
-            ]
-          },
-          "summary": {
-            "description": "Bill summary",
-            "type": [
-              "string",
-              "null"
-            ]
-          },
-          "title": {
-            "description": "Bill title",
-            "type": [
-              "string",
-              "null"
-            ]
-          }
-        },
-        "type": "object"
-      },
-      "type": "array"
-    },
-    "congress": {
-      "description": "Congress number",
-      "type": "number"
-    },
-    "count": {
-      "description": "Number of results found",
-      "type": "number"
-    },
-    "query": {
-      "description": "Search query",
-      "type": "string"
-    }
-  },
-  "required": [
-    "query",
-    "congress",
-    "count",
-    "bills"
-  ],
-  "type": "object"
-}New value: +null
  4. Changed1 schema field changed
    • changedOutput schema / (root)
      Previous value: -nullNew value: +{
+  "properties": {
+    "bills": {
+      "description": "List of bills (up to 20)",
+      "items": {
+        "properties": {
+          "active": {
+            "description": "Currently active",
+            "type": [
+              "boolean",
+              "null"
+            ]
+          },
+          "bill_id": {
+            "description": "Bill ID",
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "bill_type": {
+            "description": "Bill type (H.R., S., etc.)",
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "introduced_date": {
+            "description": "Introduction date",
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "latest_action": {
+            "description": "Latest major action",
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "latest_action_date": {
+            "description": "Latest major action date",
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "number": {
+            "description": "Bill number",
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "primary_subject": {
+            "description": "Primary subject",
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "sponsor_name": {
+            "description": "Sponsor name",
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "sponsor_party": {
+            "description": "Sponsor party",
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "sponsor_state": {
+            "description": "Sponsor state",
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "summary": {
+            "description": "Bill summary",
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "title": {
+            "description": "Bill title",
+            "type": [
+              "string",
+              "null"
+            ]
+          }
+        },
+        "type": "object"
+      },
+      "type": "array"
+    },
+    "congress": {
+      "description": "Congress number",
+      "type": "number"
+    },
+    "count": {
+      "description": "Number of results found",
+      "type": "number"
+    },
+    "query": {
+      "description": "Search query",
+      "type": "string"
+    }
+  },
+  "required": [
+    "query",
+    "congress",
+    "count",
+    "bills"
+  ],
+  "type": "object"
+}
  5. Changed1 schema field changed
    • addedInput schema / examples
      Added value: +[
+  {
+    "_apiKey": "your-propublica-congress-api-key",
+    "congress": 118,
+    "query": "climate change"
+  },
+  {
+    "_apiKey": "your-propublica-congress-api-key",
+    "query": "infrastructure"
+  }
+]
  6. First observed

TDQS

A4.9/5.0
Behavior5/5

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

Annotations already signal readOnly/idempotent/non-destructive, and the description adds substantial behavior beyond that: the ranking algorithm by title-match tier, the search depth across current and prior Congresses, and the fact that passing congress enables exhaustive search. This tells the agent exactly what result quality to expect.

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

Conciseness5/5

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

The description is thorough but every sentence earns its place: query intent, scope, ranking behavior, search-depth nuance, routing advice, return fields, state-legislature exclusion. It is front-loaded with the user-facing questions and remains structured with a clear NOTE for the most common misuse.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with an output schema and strong annotations, the description covers all decision-relevant context: what it searches, how results are ranked, how to handle older Congresses, what it returns, and which sibling or alternative tool to use next. An agent can invoke it correctly and route follow-ups without further inference.

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

Parameters4/5

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

The schema covers all three parameters, so the baseline is 3. The description adds real meaning beyond the schema by explaining query matching tiers, what 'congress' changes in search depth, and when a Congress number matters for older bills. The limit parameter is not expanded, but the schema already documents it.

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

Purpose5/5

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

The description opens with concrete natural-language queries and then states a specific action: searching US FEDERAL congressional bills by bill name, subject, or keyword. It clearly differentiates this tool from get_recent_bills and get_bill by explaining what it filters on and what it returns.

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

Usage Guidelines5/5

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

Explicit guidance is given: prefer this over a date-sorted recent-bills listing whenever the question names a topic or bill, and use get_bill for full details on a matched bill. It also states a clear exclusion: for state legislature bills, use legiscan or openstates instead.

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

All Congress 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