us-lobbying-mcp-server

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

Annotations already declare readOnlyHint, idempotentHint and openWorldHint=false, so the safety profile is covered. The description adds that this is a pre-SQL inspection step and enumerates the facets examined (lifecycle, acquisition coverage, provenance), which is real added context, but it says nothing about cost, size of output, or whether inspection reveals staleness/caveats.

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

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

A single dense sentence with the action and the timing constraint front-loaded; there is no filler. The stacked noun list ('lifecycle, acquisition coverage and provenance') is slightly opaque but each item conveys a distinct facet.

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

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

An output schema exists so return values need no explanation, and the two parameters are fully specified structurally. What is missing is conceptual grounding: how a canvas_id is obtained, what 'staged' versus live tables means, and whether inspection is required before querying.

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

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

Schema description coverage is 100% and both parameters are documented there, including the 'omit for every table in this canvas' semantics. The description adds no parameter-level meaning beyond the schema, so baseline 3 applies.

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

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

States a specific verb (inspect) and a specific set of resources (staged table schemas, row counts, lifecycle, coverage, provenance), which is clearly distinct from the query sibling. The phrase 'staged table' is never defined, so an agent unfamiliar with the canvas workflow must infer what is being inspected.

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

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

'before SQL' implies a preflight role ahead of uslobbying_dataframe_query, which is useful implied sequencing. However, the alternative tool is not named, and there is no explicit statement of when not to use this or what to do first (e.g., that a canvas_id must already exist from another tool).

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

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

The description adds important behavior beyond the annotations: one SELECT is executed, the complete result is materialized, and subsequent row retrieval does not rerun SQL. This clarifies the stateful materialization step, which is consistent with readOnlyHint=false, while annotations already cover destructive and idempotent characteristics.

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

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

Two sentences, front-loaded with the primary action, and no wasted text. The prerequisite follows naturally after the workflow description.

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

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

The description covers the core workflow, materialization behavior, retrieval path, and the describe-first prerequisite. With a full output schema and complete parameter descriptions, the remaining details are adequately handled by structured fields, though the next_offset/offset wording could be tightened.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds useful mode semantics around sql, result_table, and offset-based row retrieval, though it refers to 'next_offset' while the schema parameter is 'offset', creating a minor terminology mismatch.

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

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

The description states a specific verb and resource: run one read-only SELECT over staged disclosure tables, materialize results, and retrieve rows by result table. It clearly distinguishes the SQL path from the retrieval path, and points to the sibling describe tool 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.

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

It gives a clear workflow prerequisite: inspect columns with uslobbying_dataframe_describe first. It also explains the two operating modes, SQL versus result_table retrieval, though it does not explicitly compare when to use this tool instead of the other search-oriented siblings.

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

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

Annotations already cover read-only/idempotent/open-world, but the description adds non-obvious behavioral caveats: IDs identify registrant relationships rather than verified corporate identity, typed rows preserve every audit filing, and cursors must be collected before interpreting separate income/expense ledgers. These are real behavioral disclosures beyond the structured fields, though pagination and response-size behavior are only in the schema.

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

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

The description is dense and front-loaded with the core workflow in the first sentence and refinements (cursors, filing UUID handoff, canvas SQL) after. It is jargon-heavy but each sentence carries information; minor tightening could improve it.

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

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

For a 13-parameter, two-mode tool with an output schema and read-only annotations, the description covers the workflow, the ID caveat, cursor handling, and the handoff to search_filings. Return-value details are delegated to the output schema appropriately; only minor gaps (e.g., canvas staging details) remain.

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

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

Schema coverage is 100% so the baseline is 3, but the description adds genuine meaning: it clarifies that candidates[].id should be selected while the secondary client_id is preserved as source data, and explains the resolve/profile mode split. That goes beyond restating schema field descriptions.

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

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

The description states a specific verb and resource ('Resolve client relationship records by client_name') and clearly delineates the two modes (resolve vs profile). It names one downstream sibling (uslobbying_search_filings) but does not distinguish itself from the other search_* siblings, so it is clear but not fully differentiated.

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

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

It gives an explicit two-step workflow (resolve by client_name first, then profile with explicit client_ids and years) and tells the agent to follow collecting cursors before interpreting ledgers. It routes the agent to uslobbying_search_filings for complete filing records, though it does not explicitly say when NOT to use this tool versus the other sibling searches.

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

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

Adds real behavioral context beyond the readOnly/idempotent annotations: original and amended reports are preserved, child predicates must match the same item, matched_item_indexes and full parent lists remain available, and report counts are not donation counts with no cross-report totals inferred. That last point is a meaningful anti-misinterpretation warning not encoded anywhere in the schema.

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

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

Three sentences, each carrying distinct information: scope, item-matching rule, and counting caveat. Front-loaded with what is retrieved; no filler.

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

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

With 21 fully documented parameters and an output schema, the description supplies the remaining semantic guardrails (amendments, item-level matching, donation-vs-report counting). It does not explain pagination/cursor interaction with max_pages across calls, which is the main residual gap.

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

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

Schema coverage is 100%, so parameters are already documented; the description only reinforces the 'same item' semantics of the amount predicates and the availability of parent lists, which the schema descriptions largely repeat. Baseline 3 is appropriate.

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

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

States a specific verb and resource ('Retrieve complete semiannual LD-203 reports, contributions, PAC relationships and certifications'), which is clearly distinct from search_filings or get_issue_spending. It does not name a sibling or explicitly contrast with one, so it stops short of a 5.

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

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

Usage is implied by the resource (LD-203 contribution retrieval) and the caveats steer interpretation, but there is no explicit when-to-use vs. when-to-use-an-alternative guidance against the eight sibling tools. Nothing tells the agent whether to prefer this over search_filings for a given question.

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

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

Annotations already declare readOnly and idempotent, but the description adds substantive behavior: whole-filing association rather than allocated amounts, overlapping issue buckets, all versions acquired before latest-period selection and local issue filtering, and a real latency warning ('can take hours'). The cursor instruction ('follow collecting cursors before interpreting final typed rows or SQL datasets') discloses a non-obvious execution contract that would otherwise cause misreads.

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

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

Purpose and the key caveat are front-loaded in the first two sentences, then performance, cursor, and handoff notes follow in priority order. It is dense but every sentence carries operational information; only the repeated references to versions/cursors verge on redundancy.

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

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

For a 13-parameter aggregation tool with an output schema and full annotation coverage, the description supplies the remaining load-bearing context: association semantics, overlap caveat, latency, cursor discipline, and cross-tool handoffs. An agent has enough to call it correctly and to interpret the results without over-reading them as allocated issue spending.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning the schema does not: years is an explicit analytical scope, issue_code must come from uslobbying_list_reference topic issue_codes on the first call, and client_id should be resolved from uslobbying_get_client_profile candidates. The cursor guidance further frames how row_sets and continuation interact with acquisition and totals.

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

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

The first sentence names a specific verb (aggregate) and resource (income/expense amounts on quarterly filings keyed to issue_code across explicit years). It immediately disambiguates the semantics with 'whole-filing association, not allocated issue spending; issue buckets overlap', which no sibling would claim. The handoff sentence to uslobbying_search_filings clarifies the boundary against that sibling.

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

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

It gives concrete operating advice: 'Broad scans can take hours; narrow client_id or registrant_id when appropriate', and tells the agent to pass a selected filing UUID to uslobbying_search_filings for the complete record. That covers when to narrow and where to escalate, but there is no explicit when-not-to-use versus siblings like uslobbying_get_contributions or uslobbying_dataframe_query.

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

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

Annotations only cover read-only/idempotent/closed-world, but the description adds substantial behavior: cursor results are 'pinned windows' that ignore or repeat the original topic/filter, oversized values must be fetched back through this same tool via record_handle + record_path, and countries mix LDA codes with non-ISO FARA source labels that are explicitly not normalized. These are exactly the non-obvious traits an agent would otherwise get wrong.

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

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

Four front-loaded sentences, each carrying distinct information (scope, filter semantics, paging/overflow mechanics, data caveat) with no filler. Density is high but justified; a slightly clearer split between the list vs. explain modes would improve scanability.

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

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

With an output schema present, return shapes need not be explained. All seven parameters are fully documented in-schema, and the description closes the remaining gaps (continuation semantics, overflow retrieval, country-code caveat) for what is otherwise a fairly complex paging-plus-reference tool.

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

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

Schema coverage is 100%, so the baseline is 3; the description still adds relational meaning the schema does not spell out, namely that record_handle and record_path are used together on this tool to unpack oversized entries, and that cursor payloads override or repeat topic/filter. It does not add format detail for record_path (JSON Pointer) or record_offset, which the schema already carries.

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

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

The description names a specific verb (list / explain) and enumerates the exact resource set: issue codes, filing types, government entities, contribution types, countries, plus explanatory topics. This vocabulary-topic framing cleanly distinguishes it from all siblings, which are search/get tools over filings and agents.

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

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

It gives clear operating context: filter is optional and does token-AND literal matching, cursors drive continuation, and record_handle/record_path are for oversized entries. It stops short of naming alternatives or stating when not to use it (e.g., use search_filings rather than this reference tool for record lookups).

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

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

Annotations already declare readOnlyHint, idempotentHint and openWorldHint, so the safety profile is covered. The description adds value beyond that: amounts are separate nullable USD strings (not one aggregate), disclosure text is untrusted record data (a prompt-injection warning), and issue_code is applied post-fetch rather than upstream. It does not cover rate limits or page-budget interaction with max_pages.

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

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

Four sentences, front-loaded with the primary capability before filter details and caveats. Dense and telegraphic in places ('Native filters include posting dates, reported amounts, client location and foreign entities'), but essentially every clause carries operational information.

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

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

With 27 optional parameters, an output schema, and full schema descriptions, the description supplies the remaining pieces an agent needs: the two invocation modes, cursor-based paging, local-vs-native filtering, and data-trust caveats. Paging budget behavior (max_pages/page_size defaults and clamps) is left entirely to the schema, which is a minor gap.

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

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

Schema coverage is 100%, so the baseline is 3; the description earns above that by explaining filter semantics the schema does not, specifically that issue_code filters activities locally and cannot narrow upstream requests, and that amounts are separate nullable strings. Several parameter groups (paging, record_*) are only described in the schema.

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

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

States a specific verb and resource ('Search federal lobbying registrations and activity reports') plus a second mode ('retrieve a complete filing by filing_uuid'). The two-mode structure lets an agent distinguish search vs. fetch, but it never names or contrasts the nearby siblings such as uslobbying_search_lobbyists or uslobbying_search_foreign_agents.

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

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

Gives real routing context: filing_uuid mode is for retrieving complete records from evidence or analytical selections, and 'Follow next_cursor for all versions' tells the agent how to page to completion. It also warns that issue_code filters locally and cannot narrow upstream requests, which prevents a wrong usage pattern. Missing only explicit when-not-to-use guidance against sibling search tools.

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

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

Annotations already cover read-only, idempotent and open-world behavior, yet the description adds real context: cursors bind to pinned local windows (so filter resubmission matters), status semantics vary by entity, and disclosure records carry no implication of wrongdoing. It omits any mention of the deferred record_handle workflow, but against annotation coverage this is a solid additive contribution.

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

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

Three compact sentences with the mode distinction front-loaded and no filler. Some phrasing is opaque jargon ('pinned local windows', 'retrieve one registration principal, short-form or document collection') that costs a little clarity for its density.

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

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

With 13 parameters, an output schema and full annotation coverage, the description handles the primary search/detail split, cursors and status caveats adequately. However, the deferred record_handle / record_path / record_offset retrieval pattern — a non-obvious two-phase workflow for this tool — gets no mention at all, leaving a meaningful gap for a tool of this complexity.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds genuine semantic meaning beyond the schema: that cursor continuation is pinned to a local window and that identical status values mean different things for registrants vs foreign principals. Navigation parameters (record_path, record_offset, record_limit) are left entirely to the schema.

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

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

States specific verbs (search / retrieve) and specific resources (FARA daily registrant or foreign-principal snapshots, registration detail collections), which lets an agent distinguish this FARA-oriented tool from the lobbying-focused siblings like search_filings and search_lobbyists. It never names those siblings explicitly, so differentiation is implicit rather than stated.

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

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

The FARA/disclosure framing implies when the tool applies, and 'principal status differs from registrant status' hints at a selection consideration. But there is no explicit when-to-use vs when-to-use-an-alternative guidance, and nothing routes the agent between this tool and the sibling search tools.

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

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

The annotations already cover read-only, open-world, and idempotent behavior, and the description adds useful caveats: covered positions are disclosed text rather than verified employment, activity mode checks the requested lobbyist locally, and cursors should be followed. It does not discuss rate limits or auth requirements, but the annotation set reduces that burden.

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

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

The description is dense but front-loaded and free of filler. The caveat about covered positions is relevant, though the overall wording is somewhat compressed and could be easier to scan.

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

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

Given the rich input schema, annotations, and output schema, the description supplies the key operational context an agent needs: mode selection, required activity inputs, filing handoff, disclosure caveat, and pagination behavior.

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

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

Schema description coverage is 100%, so the schema already defines all 15 parameters. The description still adds cross-parameter meaning by explaining mode-dependent requirements and the cursor-based continuation pattern, which goes beyond isolated schema descriptions.

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

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

The description gives a specific verb and resource, "Find lobbyists by name or registrant," and clearly separates the two operating modes, search and activity. It also distinguishes this from uslobbying_search_filings by explaining the handoff for complete filings.

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

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

It states that search is the default mode and that activity requires lobbyist_id and filing_year, and it names uslobbying_search_filings as the alternative for complete filing evidence. It does not explicitly describe when not to use this tool versus other siblings such as uslobbying_get_client_profile.

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