Skip to main content
Glama

us-lobbying-mcp-server

Search foreign agents

uslobbying_search_foreign_agents
Read-onlyIdempotent

Search official FARA daily snapshots of registrants, foreign principals or short-form registrants, or fetch one registration's live foreign-principal, short-form or document collection. Short forms are the individuals working under a registration, searched by first and last name; a hit is a name match only and establishes no identity across registrations or with LDA lobbyists. Each call returns page_size whole records; follow next_cursor through the pinned result. Principal and short-form status differ from registrant status (registrant_status). Disclosure records do not establish wrongdoing or influence.

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_search_foreign_agents"
  }
}

Input Schema

NameRequiredDescriptionDefault
modeNoSearch daily snapshots or fetch one registration detail collection; defaults to search.
cursorNoOpaque continuation; original filters may be omitted or repeated unchanged.
detailNoDetail collection, default foreign_principals; unavailable in search mode.
entityNoSearch entity, default registrants; short_forms finds the individuals filed under a registration by first and last name. Unavailable in detail mode.
statusNoStatus of the selected record itself, default active; documents require all.
countryNoExact represented country/location label, foreign-principal search only.
page_sizeNoWhole records per window, default 25, at most 1,000; larger values clamp to 1,000 and are disclosed in delivery_limits. Part of the scope: omit it or repeat it unchanged on continuations.
name_containsNoSearch-only literal case-insensitive token-AND match over entity names; a short-form name is its first and last name joined. Short-form hits are name matches only, with no identity across registrations or with LDA lobbyists.
registration_numberNoLossless digit-string registration number, required for detail mode.

Output Schema

NameRequiredDescriptionDefault
modeNoOriginal acquisition mode.
errorNoPresent when the call failed. Absent on success.
detailNoSelected detail collection.
entityNoSelected search entity.
offsetNoRecords delivered before this window.
sourceNoOfficial source system.
statusNoEffective selected entity status.
noticesNoLimitations and success notices.
recordsNoWhole normalized records delivered in this window.
coverageNoAcquisition progress, independent of delivery.
truncatedNoMore records remain through next_cursor; no source data was discarded.
attributionNoRequired verbatim attribution for LDA data.
next_cursorNoOpaque continuation to the next window.
source_urlsNoOfficial source URLs actually acquired.
retrieved_atNoRetrieval ISO timestamp.
total_matchesNoExact matched records in the pinned acquisition.
delivery_limitsNoClamped controls for this call; an empty map means no clamp. Immediate cursor replay retains its original values.
output_completeNoWhether every matched record has been delivered.
records_returnedNoWhole records delivered in this window.
cursor_expires_atNoContinuation expiry ISO timestamp.
effective_filtersNoNormalized effective scope.
snapshot_source_urlsNoOfficial snapshot URLs.
snapshot_retrieved_atNoFARA snapshot retrieval timestamp.
snapshot_last_modifiedNoUpstream Last-Modified header.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed22 schema fields changed
    • changedInput schema / properties / entity / description
      Previous value: -"Search entity, default registrants; unavailable in detail mode."New value: +"Search entity, default registrants; short_forms finds the individuals filed under a registration by first and last name. Unavailable in detail mode."
    • changedInput schema / properties / entity / enum
      Previous value: -[
      -  "registrants",
      -  "foreign_principals"
      -]New value: +[
      +  "registrants",
      +  "foreign_principals",
      +  "short_forms"
      +]
    • changedInput schema / properties / name_contains / description
      Previous value: -"Search-only literal case-insensitive token-AND match over entity names."New value: +"Search-only literal case-insensitive token-AND match over entity names; a short-form name is its first and last name joined. Short-form hits are name matches only, with no identity across registrations or with LDA lobbyists."
    • changedInput schema / properties / page_size / description
      Previous value: -"Maximum records in one local output window; positive integers clamp to 25, default 25."New value: +"Whole records per window, default 25, at most 1,000; larger values clamp to 1,000 and are disclosed in delivery_limits. Part of the scope: omit it or repeat it unchanged on continuations."
    • removedInput schema / properties / record_handle
      Removed value: -{
      -  "description": "Opaque tenant/tool-bound deferred record handle; exclusive with source selectors and cursor.",
      -  "minLength": 1,
      -  "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 / status / description
      Previous value: -"Selected entity status, default active; documents require all."New value: +"Status of the selected record itself, default active; documents require all."
    • changedOutput schema / anyOf
      Previous value: -[
      -  {
      -    "not": {
      -      "required": [
      -        "error"
      -      ]
      -    },
      -    "required": [
      -      "source",
      -      "retrieved_at",
      -      "effective_filters",
      -      "notices",
      -      "coverage",
      -      "truncated"
      -    ]
      -  },
      -  {
      -    "required": [
      -      "error"
      -    ]
      -  }
      -]New value: +[
      +  {
      +    "not": {
      +      "required": [
      +        "error"
      +      ]
      +    },
      +    "required": [
      +      "source",
      +      "retrieved_at",
      +      "effective_filters",
      +      "notices",
      +      "coverage",
      +      "truncated",
      +      "mode",
      +      "status",
      +      "source_urls",
      +      "records",
      +      "total_matches",
      +      "records_returned",
      +      "offset",
      +      "output_complete"
      +    ]
      +  },
      +  {
      +    "required": [
      +      "error"
      +    ]
      +  }
      +]
    • changedOutput schema / properties / entity / enum
      Previous value: -[
      -  "registrants",
      -  "foreign_principals"
      -]New value: +[
      +  "registrants",
      +  "foreign_principals",
      +  "short_forms"
      +]
    • changedOutput schema / properties / error / properties / data / properties / reason / description
      Previous value: -"Machine-readable failure mode. Declared by this tool: `invalid_filter`: Required detail identifier is absent, selectors conflict, or country/status is invalid. `cursor_invalid`: Continuation or record handle is unavailable, expired or belongs to another scope. `acquisition_storage_unavailable`: Retained-data capacity prevents a safe checkpoint. `source_schema_changed`: A source response violates the verified schema or uses an unsupported redirect. `snapshot_unavailable`: Required bulk snapshot cannot be downloaded or decoded. `source_rate_limited`: FARA returns HTTP 429 after bounded retries. `result_too_large`: Complete result metadata exceeds the response window. Other values are possible when a failure originates below the handler."New value: +"Machine-readable failure mode. Declared by this tool: `invalid_filter`: Required detail identifier is absent, selectors conflict, country/status is invalid, or page_size exceeds 1,000 where clamping is disabled. `cursor_invalid`: Continuation is unavailable, expired, belongs to another tenant, or arrives with changed filters or page_size. `acquisition_storage_unavailable`: Retained-data capacity prevents a safe checkpoint. `source_schema_changed`: A source response violates the verified schema or uses an unsupported redirect. `snapshot_unavailable`: Required bulk snapshot cannot be downloaded or decoded. `source_rate_limited`: FARA returns HTTP 429 after bounded retries. 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",
      -  "source_schema_changed",
      -  "snapshot_unavailable",
      -  "source_rate_limited",
      -  "result_too_large"
      -]New value: +[
      +  "invalid_filter",
      +  "cursor_invalid",
      +  "acquisition_storage_unavailable",
      +  "source_schema_changed",
      +  "snapshot_unavailable",
      +  "source_rate_limited"
      +]
    • changedOutput schema / properties / next_cursor / description
      Previous value: -"Opaque next local result window."New value: +"Opaque continuation to the next window."
    • changedOutput schema / properties / offset / description
      Previous value: -"Start position in the pinned result set."New value: +"Records delivered before this window."
    • changedOutput schema / properties / output_complete / description
      Previous value: -"Whether every matched parent has been delivered or deferred."New value: +"Whether every matched record has been delivered."
    • removedOutput schema / properties / record_handles
      Removed value: -{
      -  "description": "Retained oversized parents, excluded from full records delivered.",
      -  "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 retained parent.",
      -  "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"
      -    }
      -  ]
      -}
    • changedOutput schema / properties / records / description
      Previous value: -"Complete normalized parent records delivered in this window."New value: +"Whole normalized records delivered in this window."
    • removedOutput schema / properties / records_deferred
      Removed value: -{
      -  "description": "Oversized parents represented by handles.",
      -  "maximum": 9007199254740991,
      -  "minimum": 0,
      -  "type": "integer"
      -}
    • changedOutput schema / properties / records_returned / description
      Previous value: -"Full records delivered in this window."New value: +"Whole records delivered in this window."
    • changedOutput schema / properties / truncated / description
      Previous value: -"More data is available through next_cursor, record_handles or record windows; no source data was discarded."New value: +"More records remain through next_cursor; no source data was discarded."
  2. First observed

TDQS

A3.9/5.0
Behavior4/5

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

Annotations already cover read-only, idempotent, open-world, so the marginal bar is lower, and the description clears it by disclosing snapshot semantics, that results are pinned and must be paged via next_cursor, that page_size clamps at 1,000, and that a short-form hit is a name match only. It does not cover auth, rate limits, or what a detail fetch returns when the registration is missing, so it falls short of the top mark.

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

Conciseness4/5

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

Front-loaded with the core capability, then caveats, with no filler sentences. It is dense and packs multiple clauses into single sentences (the short-form sentence is long), but every clause carries information an agent could act on.

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 annotations cover the safety profile, so the remaining burden is workflow semantics, which the description supplies: paging, clamping, snapshotting, and the identity caveat. The one omission is that it never states detail mode requires registration_number, though the schema does declare that requirement.

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%, so baseline is 3; four enums are already self-documenting. The description adds modest value with the caveat that principal/short-form status differs from registrant status and with the name-match-is-not-identity warning, but most parameter meaning (literal token-AND matching, cursor reuse, detail default) is duplicated from the schema rather than extended.

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?

Opens with a specific verb and resource (search FARA daily snapshots of registrants, foreign principals, short-form registrants) and states the second capability (fetch one registration's live detail collections). The two modes are named explicitly, and the short-form description distinguishes it from registrant/principal records, which is enough to tell this apart from uslobbying_search_filings or uslobbying_search_lobbyists.

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

Usage Guidelines3/5

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

The description clarifies the search-vs-detail pivot and what a short-form hit means, which helps an agent choose entity values. It stops short of naming when to prefer a sibling tool or when not to use this one, and the guidance that exists largely restates what the mode/entity/status enums already imply.

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.