Skip to main content
Glama

us-lobbying-mcp-server

Query disclosure tables

uslobbying_dataframe_query

Run one read-only SELECT over staged disclosure tables, materialize the complete result, then retrieve whole rows by result_table and next_offset without rerunning SQL. Each call returns row_limit rows, or the rest of the result when fewer remain. Rows follow the materialized SQL result order set by a top-level ORDER BY; an ORDER BY only inside a CTE or subquery does not guarantee it, and without one the order is fixed once materialized. Inspect columns with uslobbying_dataframe_describe first.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "canvas_id": "<canvas_id>"
    },
    "name": "uslobbying_dataframe_query"
  }
}

Input Schema

NameRequiredDescriptionDefault
sqlNoOne read-only SELECT; exclusive with result_table and offset.
offsetNoRow offset into result_table, default zero, in the materialized SQL result order set by a top-level ORDER BY; an ORDER BY only inside a CTE or subquery does not guarantee it. An offset equal to row_count returns no rows.
canvas_idYesCanvas token returned by a disclosure analytical tool.
row_limitNoWhole rows to return, default 25, at most 100 per call; larger values clamp to 100, then to any lower provider ceiling, and the clamp is disclosed in delivery_limits.
register_asNoFresh result table name for a new SQL call; omit for a generated name.
result_tableNoPreviously materialized result table; exclusive with sql and register_as.

Output Schema

NameRequiredDescriptionDefault
rowsNoWhole JSON-safe rows.
errorNoPresent when the call failed. Absent on success.
offsetNoStarting row offset in the materialized SQL result order, which a top-level ORDER BY sets; an ORDER BY only inside a CTE or subquery does not guarantee it.
columnsNoComplete result schema.
datasetNoMaterialized dataset and routing.
guidanceNoTable names and dataframe instructions.
canvas_idNoTenant-scoped canvas access token.
row_countNoExact materialized result count.
row_orderNoRows follow the materialized SQL result order set by a top-level ORDER BY; an ORDER BY only inside a CTE or subquery does not guarantee it, and without one the order is fixed once materialized.
truncatedNoMore materialized rows remain; continue with next_offset.
query_toolNoQuery or retrieve materialized table rows.
next_offsetNoNext undelivered row offset.
result_tableNoStable materialized result table.
describe_toolNoInspect exact table schemas before SQL.
rows_returnedNoRows actually delivered.
delivery_limitsNoClamped controls for this call; an empty map means no clamp. Immediate cursor replay retains its original values.
output_completeNoWhether this result has no remaining delivery rows.
effective_row_limitNoEffective row limit when a delivery or provider ceiling lowers the requested limit.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed7 schema fields changed
    • changedInput schema / properties / offset / description
      Previous value: -"Canonical row offset for result_table, default zero."New value: +"Row offset into result_table, default zero, in the materialized SQL result order set by a top-level ORDER BY; an ORDER BY only inside a CTE or subquery does not guarantee it. An offset equal to row_count returns no rows."
    • changedInput schema / properties / row_limit / description
      Previous value: -"Maximum whole rows in this response; positive integers clamp to 100, then to any lower provider ceiling."New value: +"Whole rows to return, default 25, at most 100 per call; larger values clamp to 100, then to any lower provider ceiling, and the clamp is disclosed in delivery_limits."
    • changedOutput schema / properties / error / properties / data / properties / reason / description
      Previous value: -"Machine-readable failure mode. Declared by this tool: `invalid_filter`: New SQL and result-table selectors are missing or combined. `canvas_unavailable`: Canvas is not configured. `canvas_not_found`: Canvas token is unknown or expired. `missing_table`: Named table is absent or expired. `invalid_sql`: SQL binding fails. `sql_parse_error`: SQL parsing fails. `sql_execution_error`: SQL execution or conversion fails. `non_select_statement`: SQL is not SELECT. `multi_statement`: SQL contains multiple statements. `denied_function`: SQL uses a prohibited function. `sql_read_only`: SQL violates read-only execution. `plan_operator_not_allowed`: SQL plan contains a prohibited operator. `register_as_clash`: Requested result name already exists. `query_row_too_large`: One complete row or metadata exceeds the wire budget. Other values are possible when a failure originates below the handler."New value: +"Machine-readable failure mode. Declared by this tool: `invalid_filter`: New SQL and result-table selectors are missing or combined, offset passes the result row_count, or row_limit exceeds 100 while the server rejects over-cap values. `canvas_unavailable`: Canvas is not configured. `canvas_not_found`: Canvas token is unknown or expired. `missing_table`: Named table is absent or expired. `invalid_sql`: SQL binding fails. `sql_parse_error`: SQL parsing fails. `sql_execution_error`: SQL execution or conversion fails. `non_select_statement`: SQL is not SELECT. `multi_statement`: SQL contains multiple statements. `denied_function`: SQL uses a prohibited function. `sql_read_only`: SQL violates read-only execution. `plan_operator_not_allowed`: SQL plan contains a prohibited operator. `register_as_clash`: Requested result name already exists. Other values are possible when a failure originates below the handler."
    • changedOutput schema / properties / error / properties / data / properties / reason / examples
      Previous value: -[
      -  "invalid_filter",
      -  "canvas_unavailable",
      -  "canvas_not_found",
      -  "missing_table",
      -  "invalid_sql",
      -  "sql_parse_error",
      -  "sql_execution_error",
      -  "non_select_statement",
      -  "multi_statement",
      -  "denied_function",
      -  "sql_read_only",
      -  "plan_operator_not_allowed",
      -  "register_as_clash",
      -  "query_row_too_large"
      -]New value: +[
      +  "invalid_filter",
      +  "canvas_unavailable",
      +  "canvas_not_found",
      +  "missing_table",
      +  "invalid_sql",
      +  "sql_parse_error",
      +  "sql_execution_error",
      +  "non_select_statement",
      +  "multi_statement",
      +  "denied_function",
      +  "sql_read_only",
      +  "plan_operator_not_allowed",
      +  "register_as_clash"
      +]
    • changedOutput schema / properties / offset / description
      Previous value: -"Canonical-order starting row offset."New value: +"Starting row offset in the materialized SQL result order, which a top-level ORDER BY sets; an ORDER BY only inside a CTE or subquery does not guarantee it."
    • changedOutput schema / properties / row_order / const
      Previous value: -"canonical_values"New value: +"sql_result"
    • changedOutput schema / properties / row_order / description
      Previous value: -"Delivery orders by all materialized values."New value: +"Rows follow the materialized SQL result order set by a top-level ORDER BY; an ORDER BY only inside a CTE or subquery does not guarantee it, and without one the order is fixed once materialized."
  2. First observed

TDQS

A4.3/5.0
Behavior5/5

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

Beyond the annotations, it discloses the full lifecycle: SQL is executed once, the complete result is materialized, and later calls page through it without rerunning SQL. It also explains row_limit clamping to 100 then to any provider ceiling disclosed in delivery_limits, that offset equal to row_count returns nothing, and the critical ordering caveat that an ORDER BY inside a CTE or subquery does not fix row order. This is exactly the behavioral context an agent cannot get from the annotations.

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?

Three sentences, all of which carry payload: mode description, pagination/limit behavior, and ordering guarantees, front-loaded in that order. The first sentence is long and packs two distinct modes, and the 'next_offset' misnomer is a small blemish, but there is no filler.

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?

With an output schema present, return values need not be explained, and the description covers the materialization/pagination model, clamping, and ordering well enough for correct invocation. Remaining gaps are minor: it does not say how canvas_id is obtained beyond the schema note, nor address the tension between 'read-only SELECT' and the tool's readOnlyHint=false state-creating behavior.

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 the schema already documents sql, offset, row_limit, register_as, result_table and the ORDER BY caveat in detail; the description largely restates that. It also refers to 'next_offset' while the actual parameter is 'offset', a naming slip that could momentarily mislead an agent looking for a nonexistent parameter. Baseline 3 is appropriate.

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 a specific verb and resource: 'Run one read-only SELECT over staged disclosure tables,' and then explains the second mode ('retrieve whole rows by result_table ... without rerunning SQL'). An agent can tell this is the SQL/materialization tool rather than a search or profile lookup, and it names uslobbying_dataframe_describe as the companion for column inspection.

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?

It gives an explicit prerequisite ('Inspect columns with uslobbying_dataframe_describe first') and implicitly routes between the two modes via the sql/result_table exclusivity described in both schema and prose. It does not state which non-sibling use cases belong elsewhere, but the mode-selection guidance is clear and actionable.

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.