Skip to main content
Glama

us-lobbying-mcp-server

Uslobbying List Reference

uslobbying_list_reference
Read-onlyIdempotent

List official LDA issue codes, filing types, government entities, contribution types, countries and states, or explain identifiers, methodology and FARA rules. Optional filter performs case-insensitive literal token-AND matching across the complete vocabulary. Each call returns a fixed window of up to 125 whole entries; follow next_cursor for the rest. LDA filter codes are the value of entries with source lda, such as US or CN for countries and WA for states. Countries also list FARA country/location labels (source fara) for the uslobbying_search_foreign_agents country filter; they are source spellings, not ISO codes, and never valid LDA filter values.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "uslobbying_list_reference"
  }
}

Input Schema

NameRequiredDescriptionDefault
topicNoVocabulary or explanatory topic; required on the first call.
cursorNoPinned continuation; omit original topic/filter or repeat them unchanged.
filterNoEvery whitespace-separated token must occur literally in an entry.

Output Schema

NameRequiredDescriptionDefault
errorNoPresent when the call failed. Absent on success.
topicNoRequested vocabulary.
offsetNoEntries delivered before this window.
entriesNoWhole entries delivered in this fixed 125-entry window.
noticesNoSource limitations and empty-result recovery.
truncatedNoMore matched entries remain; follow next_cursor.
next_cursorNoOpaque continuation of the pinned vocabulary.
source_urlsNoOfficial source references.
retrieved_atNoRetrieval timestamp: the shared LDA constants fetch for LDA topics (the older of the LDA and FARA retrievals for countries), the call time for explanatory topics.
total_entriesNoEntries before local filtering.
matched_entriesNoEntries matching every literal filter token.
output_completeNoWhether every matched entry has been delivered.
records_returnedNoWhole entries delivered in this window.
cursor_expires_atNoAbsolute expiry of the pinned vocabulary and its continuations.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed22 schema fields changed
    • removedInput schema / properties / record_handle
      Removed value: -{
      -  "description": "Tenant/tool-bound deferred record handle.",
      -  "type": "string"
      -}
    • removedInput schema / properties / record_limit
      Removed value: -{
      -  "default": 25,
      -  "description": "Maximum object entries or array items, clamped to 25; text fragments use the response byte budget.",
      -  "minimum": 1,
      -  "multipleOf": 1,
      -  "type": "number"
      -}
    • removedInput schema / properties / record_offset
      Removed value: -{
      -  "default": 0,
      -  "description": "Key, item or Unicode-code-point offset.",
      -  "maximum": 9007199254740991,
      -  "minimum": 0,
      -  "type": "integer"
      -}
    • removedInput schema / properties / record_path
      Removed value: -{
      -  "default": "",
      -  "description": "JSON Pointer to a stored value; empty selects the root.",
      -  "type": "string"
      -}
    • changedInput schema / properties / topic / enum
      Previous value: -[
      -  "issue_codes",
      -  "filing_types",
      -  "government_entities",
      -  "contribution_types",
      -  "countries",
      -  "identifiers",
      -  "methodology",
      -  "fara_rules"
      -]New value: +[
      +  "issue_codes",
      +  "filing_types",
      +  "government_entities",
      +  "contribution_types",
      +  "countries",
      +  "states",
      +  "identifiers",
      +  "methodology",
      +  "fara_rules"
      +]
    • removedOutput schema / $defs
      Removed value: -{
      -  "__schema0": {
      -    "anyOf": [
      -      {
      -        "type": "string"
      -      },
      -      {
      -        "type": "number"
      -      },
      -      {
      -        "type": "boolean"
      -      },
      -      {
      -        "type": "null"
      -      },
      -      {
      -        "items": {
      -          "$ref": "#/$defs/__schema0"
      -        },
      -        "type": "array"
      -      },
      -      {
      -        "additionalProperties": {
      -          "$ref": "#/$defs/__schema0"
      -        },
      -        "propertyNames": {
      -          "type": "string"
      -        },
      -        "type": "object"
      -      }
      -    ]
      -  }
      -}
    • changedOutput schema / anyOf
      Previous value: -[
      -  {
      -    "not": {
      -      "required": [
      -        "error"
      -      ]
      -    },
      -    "required": [
      -      "topic",
      -      "total_entries",
      -      "matched_entries",
      -      "retrieved_at",
      -      "source_urls",
      -      "notices",
      -      "truncated"
      -    ]
      -  },
      -  {
      -    "required": [
      -      "error"
      -    ]
      -  }
      -]New value: +[
      +  {
      +    "not": {
      +      "required": [
      +        "error"
      +      ]
      +    },
      +    "required": [
      +      "topic",
      +      "entries",
      +      "total_entries",
      +      "matched_entries",
      +      "retrieved_at",
      +      "source_urls",
      +      "notices",
      +      "output_complete",
      +      "truncated",
      +      "offset",
      +      "records_returned",
      +      "cursor_expires_at"
      +    ]
      +  },
      +  {
      +    "required": [
      +      "error"
      +    ]
      +  }
      +]
    • changedOutput schema / properties / cursor_expires_at / description
      Previous value: -"Absolute expiry of retained entries and continuations."New value: +"Absolute expiry of the pinned vocabulary and its continuations."
    • removedOutput schema / properties / delivery_limits
      Removed value: -{
      -  "additionalProperties": {
      -    "additionalProperties": false,
      -    "description": "Requested and effective delivery control.",
      -    "properties": {
      -      "effective": {
      -        "description": "Applied delivery ceiling.",
      -        "exclusiveMinimum": 0,
      -        "maximum": 9007199254740991,
      -        "type": "integer"
      -      },
      -      "requested": {
      -        "description": "Caller-requested positive integer.",
      -        "exclusiveMinimum": 0,
      -        "multipleOf": 1,
      -        "type": "number"
      -      }
      -    },
      -    "required": [
      -      "requested",
      -      "effective"
      -    ],
      -    "type": "object"
      -  },
      -  "description": "Clamped controls for this call; an empty map means no clamp. Immediate cursor replay retains its original values.",
      -  "propertyNames": {
      -    "type": "string"
      -  },
      -  "type": "object"
      -}
    • changedOutput schema / properties / entries / description
      Previous value: -"Complete entries delivered in this pinned vocabulary window."New value: +"Whole entries delivered in this fixed 125-entry window."
    • changedOutput schema / properties / error / properties / data / properties / reason / description
      Previous value: -"Machine-readable failure mode. Declared by this tool: `invalid_filter`: Topic is missing, continuation scope changes, or record selectors conflict or select an invalid path. `cursor_invalid`: A cursor or record handle is unavailable, expired or belongs to another tenant or tool. `acquisition_storage_unavailable`: Storage cannot retain the complete vocabulary or its checkpoint safely. `result_too_large`: Complete metadata leaves no space for a result window. `source_schema_changed`: Source vocabulary violates its verified schema. `snapshot_unavailable`: Required FARA country snapshot is unavailable. Other values are possible when a failure originates below the handler."New value: +"Machine-readable failure mode. Declared by this tool: `invalid_filter`: The first call omits topic. `cursor_invalid`: A cursor is unavailable or expired, belongs to another tenant or tool, or arrives with a changed topic or filter. `acquisition_storage_unavailable`: Storage cannot retain the complete vocabulary or its checkpoint safely. `source_schema_changed`: Source vocabulary violates its verified schema. `snapshot_unavailable`: Required FARA country snapshot is unavailable. Other values are possible when a failure originates below the handler."
    • changedOutput schema / properties / error / properties / data / properties / reason / examples
      Previous value: -[
      -  "invalid_filter",
      -  "cursor_invalid",
      -  "acquisition_storage_unavailable",
      -  "result_too_large",
      -  "source_schema_changed",
      -  "snapshot_unavailable"
      -]New value: +[
      +  "invalid_filter",
      +  "cursor_invalid",
      +  "acquisition_storage_unavailable",
      +  "source_schema_changed",
      +  "snapshot_unavailable"
      +]
    • changedOutput schema / properties / offset / description
      Previous value: -"Start position in the pinned filtered vocabulary."New value: +"Entries delivered before this window."
    • changedOutput schema / properties / output_complete / description
      Previous value: -"Every matched entry has been delivered or deferred."New value: +"Whether every matched entry has been delivered."
    • removedOutput schema / properties / record_handles
      Removed value: -{
      -  "description": "Oversized entries retrievable through this same tool.",
      -  "items": {
      -    "additionalProperties": false,
      -    "description": "Deferred parent retrieval.",
      -    "properties": {
      -      "expires_at": {
      -        "description": "Retained parent expiry ISO timestamp.",
      -        "type": "string"
      -      },
      -      "record_bytes": {
      -        "description": "Serialized parent UTF-8 bytes.",
      -        "maximum": 9007199254740991,
      -        "minimum": 0,
      -        "type": "integer"
      -      },
      -      "record_handle": {
      -        "description": "Opaque retained parent handle.",
      -        "type": "string"
      -      },
      -      "retrieval_tool": {
      -        "description": "Source tool for record windows.",
      -        "type": "string"
      -      },
      -      "source_id": {
      -        "description": "Original source identity.",
      -        "type": "string"
      -      }
      -    },
      -    "required": [
      -      "record_handle",
      -      "source_id",
      -      "record_bytes",
      -      "expires_at",
      -      "retrieval_tool"
      -    ],
      -    "type": "object"
      -  },
      -  "type": "array"
      -}
    • removedOutput schema / properties / record_window
      Removed value: -{
      -  "description": "Exact recursive window of a deferred vocabulary entry.",
      -  "oneOf": [
      -    {
      -      "additionalProperties": false,
      -      "description": "Complete or deferred object children.",
      -      "properties": {
      -        "complete": {
      -          "description": "This path and included children are fully delivered.",
      -          "type": "boolean"
      -        },
      -        "entries": {
      -          "description": "Key-ordered object window.",
      -          "items": {
      -            "additionalProperties": false,
      -            "description": "Key and pointer; value only when it fits.",
      -            "properties": {
      -              "key": {
      -                "description": "Original key.",
      -                "type": "string"
      -              },
      -              "path": {
      -                "description": "Child JSON Pointer.",
      -                "type": "string"
      -              },
      -              "value": {
      -                "$ref": "#/$defs/__schema0",
      -                "description": "Whole child value only when it fits."
      -              }
      -            },
      -            "required": [
      -              "key",
      -              "path"
      -            ],
      -            "type": "object"
      -          },
      -          "type": "array"
      -        },
      -        "kind": {
      -          "const": "object",
      -          "description": "Object-entry window.",
      -          "type": "string"
      -        },
      -        "next_offset": {
      -          "description": "Next undelivered position.",
      -          "maximum": 9007199254740991,
      -          "minimum": 0,
      -          "type": "integer"
      -        },
      -        "offset": {
      -          "description": "Start position.",
      -          "maximum": 9007199254740991,
      -          "minimum": 0,
      -          "type": "integer"
      -        },
      -        "path": {
      -          "description": "Selected JSON Pointer.",
      -          "type": "string"
      -        },
      -        "record_handle": {
      -          "description": "Stored parent handle.",
      -          "type": "string"
      -        },
      -        "returned": {
      -          "description": "Delivered entries or code points.",
      -          "maximum": 9007199254740991,
      -          "minimum": 0,
      -          "type": "integer"
      -        },
      -        "total": {
      -          "description": "Total keys, items or code points at this path.",
      -          "maximum": 9007199254740991,
      -          "minimum": 0,
      -          "type": "integer"
      -        }
      -      },
      -      "required": [
      -        "record_handle",
      -        "path",
      -        "total",
      -        "offset",
      -        "returned",
      -        "complete",
      -        "kind",
      -        "entries"
      -      ],
      -      "type": "object"
      -    },
      -    {
      -      "additionalProperties": false,
      -      "description": "Array items preserving original indexes.",
      -      "properties": {
      -        "complete": {
      -          "description": "This path and included children are fully delivered.",
      -          "type": "boolean"
      -        },
      -        "items": {
      -          "description": "Indexed array window.",
      -          "items": {
      -            "additionalProperties": false,
      -            "description": "Original index and child pointer.",
      -            "properties": {
      -              "index": {
      -                "description": "Original child index.",
      -                "maximum": 9007199254740991,
      -                "minimum": 0,
      -                "type": "integer"
      -              },
      -              "path": {
      -                "description": "Child JSON Pointer.",
      -                "type": "string"
      -              },
      -              "value": {
      -                "$ref": "#/$defs/__schema0",
      -                "description": "Whole child value only when it fits."
      -              }
      -            },
      -            "required": [
      -              "index",
      -              "path"
      -            ],
      -            "type": "object"
      -          },
      -          "type": "array"
      -        },
      -        "kind": {
      -          "const": "array",
      -          "description": "Array-item window.",
      -          "type": "string"
      -        },
      -        "next_offset": {
      -          "description": "Next undelivered position.",
      -          "maximum": 9007199254740991,
      -          "minimum": 0,
      -          "type": "integer"
      -        },
      -        "offset": {
      -          "description": "Start position.",
      -          "maximum": 9007199254740991,
      -          "minimum": 0,
      -          "type": "integer"
      -        },
      -        "path": {
      -          "description": "Selected JSON Pointer.",
      -          "type": "string"
      -        },
      -        "record_handle": {
      -          "description": "Stored parent handle.",
      -          "type": "string"
      -        },
      -        "returned": {
      -          "description": "Delivered entries or code points.",
      -          "maximum": 9007199254740991,
      -          "minimum": 0,
      -          "type": "integer"
      -        },
      -        "total": {
      -          "description": "Total keys, items or code points at this path.",
      -          "maximum": 9007199254740991,
      -          "minimum": 0,
      -          "type": "integer"
      -        }
      -      },
      -      "required": [
      -        "record_handle",
      -        "path",
      -        "total",
      -        "offset",
      -        "returned",
      -        "complete",
      -        "kind",
      -        "items"
      -      ],
      -      "type": "object"
      -    },
      -    {
      -      "additionalProperties": false,
      -      "description": "Unicode-code-point text fragment.",
      -      "properties": {
      -        "complete": {
      -          "description": "This path and included children are fully delivered.",
      -          "type": "boolean"
      -        },
      -        "kind": {
      -          "const": "string",
      -          "description": "Unicode text window.",
      -          "type": "string"
      -        },
      -        "next_offset": {
      -          "description": "Next undelivered position.",
      -          "maximum": 9007199254740991,
      -          "minimum": 0,
      -          "type": "integer"
      -        },
      -        "offset": {
      -          "description": "Start position.",
      -          "maximum": 9007199254740991,
      -          "minimum": 0,
      -          "type": "integer"
      -        },
      -        "path": {
      -          "description": "Selected JSON Pointer.",
      -          "type": "string"
      -        },
      -        "record_handle": {
      -          "description": "Stored parent handle.",
      -          "type": "string"
      -        },
      -        "returned": {
      -          "description": "Delivered entries or code points.",
      -          "maximum": 9007199254740991,
      -          "minimum": 0,
      -          "type": "integer"
      -        },
      -        "text": {
      -          "description": "Complete-code-point text fragment.",
      -          "type": "string"
      -        },
      -        "total": {
      -          "description": "Total keys, items or code points at this path.",
      -          "maximum": 9007199254740991,
      -          "minimum": 0,
      -          "type": "integer"
      -        }
      -      },
      -      "required": [
      -        "record_handle",
      -        "path",
      -        "total",
      -        "offset",
      -        "returned",
      -        "complete",
      -        "kind",
      -        "text"
      -      ],
      -      "type": "object"
      -    },
      -    {
      -      "additionalProperties": false,
      -      "description": "Unfragmented non-text scalar.",
      -      "properties": {
      -        "complete": {
      -          "description": "This path and included children are fully delivered.",
      -          "type": "boolean"
      -        },
      -        "kind": {
      -          "const": "scalar",
      -          "description": "Complete scalar value.",
      -          "type": "string"
      -        },
      -        "next_offset": {
      -          "description": "Next undelivered position.",
      -          "maximum": 9007199254740991,
      -          "minimum": 0,
      -          "type": "integer"
      -        },
      -        "offset": {
      -          "description": "Start position.",
      -          "maximum": 9007199254740991,
      -          "minimum": 0,
      -          "type": "integer"
      -        },
      -        "path": {
      -          "description": "Selected JSON Pointer.",
      -          "type": "string"
      -        },
      -        "record_handle": {
      -          "description": "Stored parent handle.",
      -          "type": "string"
      -        },
      -        "returned": {
      -          "description": "Delivered entries or code points.",
      -          "maximum": 9007199254740991,
      -          "minimum": 0,
      -          "type": "integer"
      -        },
      -        "total": {
      -          "description": "Total keys, items or code points at this path.",
      -          "maximum": 9007199254740991,
      -          "minimum": 0,
      -          "type": "integer"
      -        },
      -        "value": {
      -          "anyOf": [
      -            {
      -              "description": "Null value.",
      -              "type": "null"
      -            },
      -            {
      -              "description": "Boolean value.",
      -              "type": "boolean"
      -            },
      -            {
      -              "description": "Finite numeric value.",
      -              "type": "number"
      -            }
      -          ],
      -          "description": "Exact scalar value."
      -        }
      -      },
      -      "required": [
      -        "record_handle",
      -        "path",
      -        "total",
      -        "offset",
      -        "returned",
      -        "complete",
      -        "kind",
      -        "value"
      -      ],
      -      "type": "object"
      -    }
      -  ]
      -}
    • removedOutput schema / properties / records_deferred
      Removed value: -{
      -  "description": "Oversized entries retained behind handles.",
      -  "maximum": 9007199254740991,
      -  "minimum": 0,
      -  "type": "integer"
      -}
    • changedOutput schema / properties / records_returned / description
      Previous value: -"Complete entries delivered in this window."New value: +"Whole entries delivered in this window."
    • removedOutput schema / properties / retrieval_tool
      Removed value: -{
      -  "const": "uslobbying_list_reference",
      -  "description": "Tool used to retrieve deferred vocabulary entries.",
      -  "type": "string"
      -}
    • changedOutput schema / properties / retrieved_at / description
      Previous value: -"Vocabulary retrieval timestamp."New value: +"Retrieval timestamp: the shared LDA constants fetch for LDA topics (the older of the LDA and FARA retrievals for countries), the call time for explanatory topics."
    • changedOutput schema / properties / topic / enum
      Previous value: -[
      -  "issue_codes",
      -  "filing_types",
      -  "government_entities",
      -  "contribution_types",
      -  "countries",
      -  "identifiers",
      -  "methodology",
      -  "fara_rules"
      -]New value: +[
      +  "issue_codes",
      +  "filing_types",
      +  "government_entities",
      +  "contribution_types",
      +  "countries",
      +  "states",
      +  "identifiers",
      +  "methodology",
      +  "fara_rules"
      +]
    • changedOutput schema / properties / truncated / description
      Previous value: -"More entries or deferred record values remain retrievable."New value: +"More matched entries remain; follow next_cursor."
  2. First observed

TDQS

A4.1/5.0
Behavior4/5

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

Annotations already declare readOnly/idempotent/closed-world, yet the description still adds real behavior: a fixed window of up to 125 whole entries per call, `next_cursor` continuation, and case-insensitive literal token-AND matching semantics. It also warns that FARA labels are source spellings, not ISO codes, and never valid LDA filter values — a genuine correctness caveat an agent could not infer. Minor gap: nothing about invalid topic/cursor behavior.

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

Conciseness4/5

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

Front-loaded with the resource list, then pagination, then the filter/semantics caveats — no filler sentences. It is dense and the final sentence about countries and FARA labels is long, but each clause carries usable information.

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

Completeness4/5

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

An output schema exists and parameter schema is fully documented, so return values and params need not be explained; the description correctly focuses on pagination and code semantics. What remains slightly under-specified is the interplay between topic, filter, and cursor across successive calls, though the cursor schema description covers most of it.

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

Parameters3/5

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

Schema description coverage is 100% and the schema already documents topic, cursor, and filter, including the token-AND rule, so the baseline of 3 applies. The description does add value by clarifying case-insensitivity and by explaining what the enum values actually yield (LDA code values vs. FARA source labels), but it largely restates schema content.

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

Purpose5/5

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

States a specific verb (List) plus the exact resources it serves — LDA issue codes, filing types, government entities, contribution types, countries, states — and the explanatory topics (identifiers, methodology, FARA rules). That enumeration makes it clearly distinct from every sibling, which are all search/get tools over filings, lobbyists, contributions, or clients.

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?

Explains what the returned values are for (LDA filter codes feed `source lda` entries; FARA labels feed the `uslobbying_search_foreign_agents` country filter), which is implicit guidance on when to come here before searching. It stops short of an explicit when-not-to-use statement or a rule like "call this first whenever you need a valid filter value," so it is strong but not complete.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.