Skip to main content
Glama

us-lobbying-mcp-server

Uslobbying Get Issue Spending

uslobbying_get_issue_spending
Read-onlyIdempotent

Aggregate separate income and expense amounts across explicit years on selected filings mentioning issue_code, or, when registrant_id is given without issue_code, on every selected filing in that registrant scope, broken out per client relationship in clients. Issue association is whole-filing, not allocated issue spending; issue buckets overlap. All versions are acquired before latest-period selection and local issue filtering. Broad scans can take hours; narrow client_id or registrant_id when appropriate. Follow collecting cursors before interpreting final typed rows or SQL datasets. Activity descriptions and lobbyist lists appear in typed rows only when include names them; pass a selected filing UUID to uslobbying_search_filings for its complete record.

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

Input Schema

NameRequiredDescriptionDefault
yearsNoRequired explicit analytical year scope; sorted and deduplicated.
cursorNoContinue the original scope; omit the other fields or repeat them unchanged, since a changed value (page_size included) fails cursor_invalid. Only max_pages may change per call.
includeNoLobbying-activity fields to return in selected_filings, raw_filings and activities: activity_descriptions (description) and activity_lobbyists (lobbyists). Fields left out are removed from delivered rows only; totals and SQL datasets are unaffected. Default []. Fixed for the scan: a continuation omits it or repeats it unchanged.
row_setsNoInline analytical sets; omit for all sets. Selection never limits acquisition, totals or SQL staging. Omitted sets remain available from a new call with another selection or staged tables. On a continuation, omit row_sets or list the sets of the first call in any order; listing every set after a first call that omitted row_sets fails cursor_invalid.
canvas_idNoReuse this canvas only after complete analytical acquisition.
client_idNoOptional client relationship record ID from candidates[].id in uslobbying_get_client_profile resolve mode; candidates[].client_id is secondary.
max_pagesNoMost upstream pages fetched per call, at most 5; larger values clamp and are disclosed in delivery_limits. Discovery fetches only while fewer than page_size matches are pending. Default one for discovery, five for analysis.
page_sizeNoWhole analytical rows delivered per call: default 25, at most 250; larger values clamp to it and are disclosed in delivery_limits. Not the upstream page size; a page is short only at the end of the result or while acquisition is still collecting.
issue_codeNoFirst-call code from uslobbying_list_reference topic issue_codes. Required unless registrant_id is given; omit it with registrant_id for ledgers across every issue.
registrant_idNoOptional native registrant scope; without issue_code, ledgers cover every issue.

Output Schema

NameRequiredDescriptionDefault
errorNoPresent when the call failed. Absent on success.
firmsNoFirm breakdowns in this window.
yearsNoExplicit requested years.
offsetNoRecords delivered before this window.
sourceNoOfficial source system.
statusNoSource acquisition status, separate from row delivery.
clientsNoClient relationship breakdowns in this window.
datasetNoComplete SQL metadata on the first final window and its replay.
noticesNoLimitations and success notices.
coverageNoAcquisition progress, independent of delivery.
guidanceNoTable names and dataframe instructions.
canvas_idNoTenant-scoped canvas access token.
truncatedNoMore data is available through next_cursor; no source data was discarded.
activitiesNoSelected activities in this window, with no money columns; description and lobbyists appear only when include names them.
issue_codeNoRequested issue membership code; absent for registrant-wide ledgers.
query_toolNoQuery or retrieve materialized table rows.
selectionsNoVersion-selection decisions in this window.
attributionNoRequired verbatim attribution for LDA data.
issue_codesNoOverlapping issue breakdowns in this window; with issue_code set, every row covers only selected filings that also mention issue_code.
methodologyNoAccounting limitations.
next_cursorNoNext acquisition or output window cursor.
raw_filingsNoAll acquired versions in this window, including selected versions; activity description and lobbyists appear only when include names them.
retrieved_atNoRetrieval ISO timestamp.
describe_toolNoInspect exact table schemas before SQL.
total_recordsNoExact final record count when known.
annual_ledgersNoComplete-year ledgers in this window; absent while collecting.
row_set_totalsNoExact all-set totals after acquisition completes.
delivery_limitsNoClamped controls for this call; an empty map means no clamp. Immediate cursor replay retains its original values.
output_completeNoWhether all result rows have been delivered.
row_set_offsetsNoSelected-set rows delivered before this window; others zero.
canvas_availableNoSQL canvas support is enabled.
records_returnedNoWhole records delivered in this window.
selected_filingsNoSelected filings in this window; activity description and lobbyists appear only when include names them.
attribution_basisNoWhole filings mentioning an issue; buckets overlap.
cursor_expires_atNoContinuation expiry ISO timestamp.
effective_filtersNoNormalized effective scope.
targeted_entitiesNoTargeted entities in this window.
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. Changed37 schema fields changed
    • changedInput schema / properties / cursor / description
      Previous value: -"Continue the original scope; other query fields may be omitted."New value: +"Continue the original scope; omit the other fields or repeat them unchanged, since a changed value (page_size included) fails cursor_invalid. Only max_pages may change per call."
    • addedInput schema / properties / include
      Added value: +{
      +  "description": "Lobbying-activity fields to return in selected_filings, raw_filings and activities: activity_descriptions (description) and activity_lobbyists (lobbyists). Fields left out are removed from delivered rows only; totals and SQL datasets are unaffected. Default []. Fixed for the scan: a continuation omits it or repeats it unchanged.",
      +  "items": {
      +    "enum": [
      +      "activity_descriptions",
      +      "activity_lobbyists"
      +    ],
      +    "type": "string"
      +  },
      +  "type": "array"
      +}
    • changedInput schema / properties / issue_code / description
      Previous value: -"Required first-call code from uslobbying_list_reference topic issue_codes."New value: +"First-call code from uslobbying_list_reference topic issue_codes. Required unless registrant_id is given; omit it with registrant_id for ledgers across every issue."
    • changedInput schema / properties / max_pages / description
      Previous value: -"Source pages per call; positive integers clamp to five, default one for discovery, five for analysis."New value: +"Most upstream pages fetched per call, at most 5; larger values clamp and are disclosed in delivery_limits. Discovery fetches only while fewer than page_size matches are pending. Default one for discovery, five for analysis."
    • changedInput schema / properties / page_size / description
      Previous value: -"Upstream rows per page; positive integers clamp to 25, default 25."New value: +"Whole analytical rows delivered per call: default 25, at most 250; larger values clamp to it and are disclosed in delivery_limits. Not the upstream page size; a page is short only at the end of the result or while acquisition is still collecting."
    • 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 / registrant_id / description
      Previous value: -"Optional native registrant scope."New value: +"Optional native registrant scope; without issue_code, ledgers cover every issue."
    • changedInput schema / properties / row_sets / description
      Previous value: -"Inline analytical sets; omit for all sets. Selection never limits acquisition, totals or SQL staging. Omitted sets remain available from a new call with another selection or staged tables. Continue with omitted or equivalent row_sets."New value: +"Inline analytical sets; omit for all sets. Selection never limits acquisition, totals or SQL staging. Omitted sets remain available from a new call with another selection or staged tables. On a continuation, omit row_sets or list the sets of the first call in any order; listing every set after a first call that omitted row_sets fails cursor_invalid."
    • changedInput schema / properties / row_sets / items / enum
      Previous value: -[
      -  "annual_ledgers",
      -  "selections",
      -  "firms",
      -  "issue_codes",
      -  "targeted_entities",
      -  "selected_filings",
      -  "activities",
      -  "raw_filings"
      -]New value: +[
      +  "annual_ledgers",
      +  "selections",
      +  "firms",
      +  "clients",
      +  "issue_codes",
      +  "targeted_entities",
      +  "selected_filings",
      +  "activities",
      +  "raw_filings"
      +]
    • changedOutput schema / $defs / LdaAnnualLedger / properties / ambiguous_group_count / description
      Previous value: -"Equal-latest groups excluded from sums."New value: +"Equal-latest groups excluded from sums; counted on annual_ledgers, always 0 on firm, client and issue breakdown ledgers."
    • changedOutput schema / properties / activities / description
      Previous value: -"Selected activities in this window; no money columns."New value: +"Selected activities in this window, with no money columns; description and lobbyists appear only when include names them."
    • addedOutput schema / properties / clients
      Added value: +{
      +  "description": "Client relationship breakdowns in this window.",
      +  "items": {
      +    "additionalProperties": false,
      +    "description": "Client relationship breakdown; each selected filing belongs to exactly one.",
      +    "properties": {
      +      "annual_ledgers": {
      +        "description": "Relationship year ledgers.",
      +        "items": {
      +          "$ref": "#/$defs/LdaAnnualLedger"
      +        },
      +        "type": "array"
      +      },
      +      "client_id": {
      +        "description": "Client relationship record ID.",
      +        "type": "string"
      +      },
      +      "filing_uuids": {
      +        "description": "Selected report UUIDs.",
      +        "items": {
      +          "type": "string"
      +        },
      +        "type": "array"
      +      },
      +      "name": {
      +        "description": "Client name.",
      +        "type": "string"
      +      },
      +      "registrant_id": {
      +        "description": "Firm ID of this relationship.",
      +        "type": "string"
      +      }
      +    },
      +    "required": [
      +      "client_id",
      +      "name",
      +      "registrant_id",
      +      "filing_uuids",
      +      "annual_ledgers"
      +    ],
      +    "type": "object"
      +  },
      +  "type": "array"
      +}
    • changedOutput schema / properties / error / properties / data / properties / reason / description
      Previous value: -"Machine-readable failure mode. Declared by this tool: `invalid_filter`: Invalid scope, identifier, reference code or mode combination. `cursor_invalid`: Unknown, expired, stale or mismatched continuation. `acquisition_storage_unavailable`: Storage cannot safely retain a checkpoint. `pagination_invalid`: Invalid or nonprogressing upstream pagination. `source_schema_changed`: Successful source response violates its verified schema. `canvas_unavailable`: Explicit staging without a configured canvas. `canvas_not_found`: Supplied canvas expired or unknown. Other values are possible when a failure originates below the handler."New value: +"Machine-readable failure mode. Declared by this tool: `invalid_filter`: Invalid scope, identifier, reference code or mode combination, or an over-cap page_size or max_pages while clamping is disabled. `cursor_invalid`: Unknown, expired, stale or mismatched continuation. `acquisition_storage_unavailable`: Storage cannot safely retain a checkpoint. `pagination_invalid`: Invalid or nonprogressing upstream pagination. `source_schema_changed`: Successful source response violates its verified schema. `canvas_unavailable`: Explicit staging without a configured canvas. `canvas_not_found`: Supplied canvas expired or unknown. Other values are possible when a failure originates below the handler."
    • changedOutput schema / properties / issue_code / description
      Previous value: -"Requested issue membership code."New value: +"Requested issue membership code; absent for registrant-wide ledgers."
    • changedOutput schema / properties / issue_codes / description
      Previous value: -"Overlapping issue breakdowns in this window."New value: +"Overlapping issue breakdowns in this window; with issue_code set, every row covers only selected filings that also mention issue_code."
    • changedOutput schema / properties / methodology / properties / client_identity / const
      Previous value: -"caller_selected_relationships"New value: +"relationship_records"
    • changedOutput schema / properties / methodology / properties / client_identity / description
      Previous value: -"No corporate identity is inferred."New value: +"Each client is one relationship record; no corporate identity is inferred."
    • changedOutput schema / properties / methodology / properties / selection_method / description
      Previous value: -"Latest posting within relationship and quarter."New value: +"Latest posting within relationship and reporting period, quarter or half-year."
    • changedOutput schema / properties / offset / description
      Previous value: -"Final record delivery offset."New value: +"Records delivered before this window."
    • changedOutput schema / properties / raw_filings / description
      Previous value: -"All acquired versions in this window, including selected versions."New value: +"All acquired versions in this window, including selected versions; activity description and lobbyists appear only when include names them."
    • removedOutput schema / properties / record_handles
      Removed value: -{
      -  "description": "Deferred complete parents.",
      -  "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": "Lossless stored parent window.",
      -  "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 parents available through handles.",
      -  "maximum": 9007199254740991,
      -  "minimum": 0,
      -  "type": "integer"
      -}
    • changedOutput schema / properties / records_returned / description
      Previous value: -"Complete records delivered in this window."New value: +"Whole records delivered in this window."
    • removedOutput schema / properties / retrieval_tool
      Removed value: -{
      -  "description": "Tool that retrieves this parent.",
      -  "type": "string"
      -}
    • changedOutput schema / properties / row_set_offsets / description
      Previous value: -"Selected-set rows delivered or deferred before this window; others zero."New value: +"Selected-set rows delivered before this window; others zero."
    • addedOutput schema / properties / row_set_offsets / properties / clients
      Added value: +{
      +  "description": "Client relationship breakdown records.",
      +  "maximum": 9007199254740991,
      +  "minimum": 0,
      +  "type": "integer"
      +}
    • changedOutput schema / properties / row_set_offsets / required
      Previous value: -[
      -  "annual_ledgers",
      -  "selections",
      -  "firms",
      -  "issue_codes",
      -  "targeted_entities",
      -  "selected_filings",
      -  "activities",
      -  "raw_filings"
      -]New value: +[
      +  "annual_ledgers",
      +  "selections",
      +  "firms",
      +  "clients",
      +  "issue_codes",
      +  "targeted_entities",
      +  "selected_filings",
      +  "activities",
      +  "raw_filings"
      +]
    • addedOutput schema / properties / row_set_totals / properties / clients
      Added value: +{
      +  "description": "Client relationship breakdown records.",
      +  "maximum": 9007199254740991,
      +  "minimum": 0,
      +  "type": "integer"
      +}
    • changedOutput schema / properties / row_set_totals / required
      Previous value: -[
      -  "annual_ledgers",
      -  "selections",
      -  "firms",
      -  "issue_codes",
      -  "targeted_entities",
      -  "selected_filings",
      -  "activities",
      -  "raw_filings"
      -]New value: +[
      +  "annual_ledgers",
      +  "selections",
      +  "firms",
      +  "clients",
      +  "issue_codes",
      +  "targeted_entities",
      +  "selected_filings",
      +  "activities",
      +  "raw_filings"
      +]
    • changedOutput schema / properties / selected_filings / description
      Previous value: -"Complete selected filings in this window."New value: +"Selected filings in this window; activity description and lobbyists appear only when include names them."
    • changedOutput schema / properties / selections / items / properties / exclusion_reason / description
      Previous value: -"Why excluded."New value: +"Why excluded. non_quarterly: a period that is neither quarterly nor semiannual. off_cycle_period: a quarterly period through 2007 or semiannual period from 2008, in a registrant/client/year that also filed the statutory grain."
    • changedOutput schema / properties / selections / items / properties / exclusion_reason / enum
      Previous value: -[
      -  "registration",
      -  "non_quarterly",
      -  "unknown_variant",
      -  "missing_relationship"
      -]New value: +[
      +  "registration",
      +  "non_quarterly",
      +  "off_cycle_period",
      +  "unknown_variant",
      +  "missing_relationship"
      +]
    • changedOutput schema / properties / truncated / description
      Previous value: -"More data is available through next_cursor or record_handles; no source data was discarded."New value: +"More data is available through next_cursor; no source data was discarded."
  2. First observed

TDQS

A4.6/5.0
Behavior5/5

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

Annotations only declare read-only/open-world/idempotent, but the description adds substantive behavior: issue association is whole-filing rather than allocated and issue buckets overlap, all versions are acquired before latest-period selection and local filtering, broad scans can take hours, cursors must be drained, and include gates which fields are delivered without affecting totals. These are exactly the interpretive caveats an agent needs.

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 operation and every sentence carries operational weight (fallback scope, overlap caveat, performance, cursor discipline, include behavior, sibling routing). The sentences are long and dense, making it harder to parse than necessary, but there is no filler.

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 10-parameter, multi-mode aggregate with an output schema, the description covers the pitfalls an agent must know: performance limits, cursor continuation, include gating, and the whole-filing association semantics that would otherwise cause misreading of totals. Output shape needn't be explained because an output schema exists.

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?

Schema coverage is already 100%, so baseline is 3; the description adds meaning beyond the schema by explaining the issue_code/registrant_id fallback ('every selected filing in that registrant scope') and how include affects only delivered typed rows, not totals or SQL datasets. It does not add format or syntax details for years/cursor/page_size, which the schema already handles.

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 concrete verb and resource: aggregate separate income and expense amounts across explicit years on filings mentioning issue_code, broken out per client relationship. It also distinguishes the two operating modes (issue_code vs registrant-only scope) and routes the agent to uslobbying_search_filings for full filing records, so it is separable from siblings.

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?

Gives real usage context: narrow client_id or registrant_id when scanning broadly, follow collecting cursors before interpreting rows, and use the filing UUID with uslobbying_search_filings for complete records. It lacks an explicit statement of when to prefer uslobbying_get_contributions or profile tools instead, so not a full 5.

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.