congressgov-mcp-server

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

The description discloses important behavioral details beyond annotations. It explains that date filtering is by 'update date — when Congress.gov last touched the record — not by the bill's latest legislative action.' It also specifies parameter requirements for each operation (e.g., 'each requires congress + billType + billNumber'). These nuances add value beyond the readOnlyHint/openWorldHint/idempotentHint annotations.

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 a single, information-dense paragraph with three sentences. It front-loads the purpose, states limitations, and enumerates operations and requirements. Although it is somewhat long, every clause adds necessary guidance and no filler is present.

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 main capabilities, operation modes, and parameter dependencies, and it explicitly mentions the absence of keyword search. With an output schema present and comprehensive parameter descriptions, the description doesn't need to explain return values. It leaves a minor gap on what 'related' returns, but this is acceptable given the output schema.

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 baseline is 3. The description adds meaningful parameter relationships and operation-specific constraints: 'list' requires congress, while 'get' and sub-resources require congress + billType + billNumber. It also clarifies the semantics of 'order' (sorts by update date) and 'fromDateTime' (filters by update date), which supplements the 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 clearly states the tool's function: 'Browse and retrieve U.S. legislative bill data from Congress.gov.' It distinguishes from sibling tools by focusing on bills and lists specific operations (list, get, actions, amendments, etc.). The scope is precise, including the absence of keyword search, which makes the purpose unambiguous.

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 description provides explicit guidance on when to use each operation: 'Use 'list' to browse (requires congress, defaults to most-recently-updated first), 'get' for full bill detail... or drill into a specific bill with...' It also notes a clear limitation: 'there is no keyword search.' However, it does not explicitly compare against sibling tools (e.g., congressgov_committee_lookup), though it mentions 'committees' as a sub-resource.

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, openWorldHint, and idempotentHint. The description adds valuable behavioral context beyond those: date filters apply to summary update time rather than bill action date, results can include recently rewritten summaries of older bills, and each item displays both dates. No contradictions with annotations.

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 focused sentences: primary purpose, key date behavior, and alternative usage. Every sentence earns its place with no filler or 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?

Given an output schema exists and annotations cover safety/idempotency, the description covers essential nuances: purpose, date semantics, defaults, item contents, and sibling differentiation. No critical gaps for selection and invocation.

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% per context signals, so baseline is 3. The description adds meaning beyond schema by explaining the non-obvious semantics of fromDateTime/toDateTime (update time vs action date) and the default 7-day window. This is significant but not exhaustive, so 4 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?

Description opens with 'Browse recent CRS bill summaries' — a specific verb+resource pairing. It clarifies the tool's scope ('at each legislative stage') and explicitly distinguishes it from the sibling tool congressgov_bill_lookup by directing one-bill requests there.

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?

Provides explicit guidance on when to use an alternative ('For summaries of one specific bill, use congressgov_bill_lookup with operation='summaries' instead'). Also explains usage context: useful for 'what's happening in Congress?' and clarifies the meaning of date filters relative to update time, with defaults stated.

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 state readOnly/openWorld/idempotent hints. The description adds substantial behavioral context: committee code format (chamber-prefix + abbreviation + 2-digit number), chamber inference from code prefix, order semantics for the 'bills' sub-resource, Senate-only restriction for nominations, client-side fuzzy matching for filter, and the upstream omission of bill titles. All disclosed behaviors align with annotations; no contradictions.

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 every sentence serves a purpose: purpose, code discovery, operation usage, chamber inference, ordering behavior, and data omission/workaround. It is front-loaded with the primary action, follows a logical progression, and avoids filler or repetition of schema definitions.

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 tool's complexity (8 parameters, 5 operations, multiple sub-resources, output schema present), the description covers all critical aspects: operation selection, code discovery, chamber inference/override, ordering behavior, Senate-only sub-resource, upstream data limitations, and recommended chaining to bill_lookup. The presence of an output schema means return value details are not the description's responsibility.

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?

Although schema description coverage is 100%, the description meaningfully enriches parameter understanding. It clarifies that committeeCode can be a code or a name to resolve, chamber is inferred from the prefix unless overridden, order only applies to 'bills' (with concrete 'recent' vs 'oldest' meanings), and filter fetches the full chamber set and matches client-side with approximate labels. This goes well beyond the schema's standalone 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 opens with a specific verb and resource: 'Browse congressional committees and their legislation, reports, and nominations.' It clearly distinguishes this tool from siblings by identifying its committee-centric scope and enumerating sub-resources. The detailed operational examples (list/filter, get, bills, reports, nominations) further reinforce its unique purpose.

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 description provides concrete workflow guidance: use 'list' with optional 'filter' to discover committee codes, then use 'get' or sub-resources. It also explains chamber inference/override and points to chaining congressgov_bill_lookup for missing bill titles. However, it does not explicitly contrast with sibling tools like congressgov_committee_reports or state when not to use this tool, so it falls short of full 'when/when-not' guidance.

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, openWorldHint, and idempotentHint, so the safety profile is covered. The description adds context about report types and content but does not disclose additional behavioral traits such as auth requirements, rate limits, or operation-specific behavior. With annotations present, a 3 is appropriate.

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 two sentences, front-loaded with the tool's action and resource, and every sentence contributes meaningful context (what reports are, report types). There is no fluff or redundancy, making it highly concise and well-structured.

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 6 parameters, an output schema, and rich annotations, the description covers the domain (committee reports) and report types, but does not explain the differences between the list/get/text operations. The schema does describe these operations and their required fields, so the tool is still complete enough, but a brief mention of operation semantics would elevate it to 5.

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 all parameters are documented in the schema. The description adds value by explaining the report types (hrpt=House, srpt=Senate, erpt=Executive), which is not present in the schema's enum descriptions. This extends the meaning of the reportType parameter beyond the schema, justifying a 4.

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 ('Browse and retrieve') and resource ('committee reports from Congress.gov'), clearly distinguishing it from sibling tools like committee_lookup or bill_summaries. It also explains what committee reports contain, leaving no ambiguity about the tool's function.

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 description provides clear context for when to use the tool by explaining that committee reports accompany legislation reported out of committee and include purpose, amendments, dissenting views, and vote. However, it does not explicitly mention alternatives or when not to use this tool, so it falls short of a 5.

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 indicate readOnly, openWorld, and idempotent hints. The description adds useful context about report IDs and what 'get' returns, but does not disclose additional behavioral traits such as rate limits, error behaviors, or prerequisites. Given the high annotation coverage, this is adequate.

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 two well-structured sentences, front-loaded with the core purpose, followed by essential ID and operation details. Every sentence adds value with no 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?

Given the output schema exists, the description does not need to explain return values. It provides sufficient context about the subject domain, ID format, and operations. It omits mention of pagination parameters, but these are documented in the schema and not critical for selection.

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?

The schema covers all 4 parameters with descriptions, so baseline is 3. The description adds extra meaning by providing report ID format examples (e.g., R40097) and clarifying that 'get' returns authors, topics, summary, and download formats—details not fully 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?

The description clearly states 'Browse and retrieve CRS reports' with a specific verb and resource. It differentiates from sibling tools by naming CRS reports and explaining their nature, making it unmistakable which tool to select for this content.

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 description clearly defines the tool's purpose but does not explicitly mention when not to use it or provide alternatives like the sibling tools. It gives clear operational guidance ('Use list to browse... or get for full detail'), but lacks exclusions relative to other congressional 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 declare readOnlyHint, openWorldHint, and idempotentHint. The description adds behavioral context about the hierarchical navigation structure (volumes → issues → articles), which is useful beyond the annotations. No contradictions.

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 with no redundant words. First sentence states purpose; second explains the navigation flow. Perfectly front-loaded.

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 tool's complexity (5 params, 3 operations), the description covers purpose, navigation, and each operation's role. Output schema exists, so return values need no explanation. It is complete for agent understanding.

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 covers 100% of parameters. The description adds semantic meaning by mapping each operation to the hierarchy (list for volumes, issues for issues, articles for articles), supplementing the schema's parameter 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 clearly states 'Browse the daily Congressional Record — floor speeches, debates, and legislative text published each day Congress is in session.' It uses a specific verb and resource, and distinguishes itself from sibling tools by naming its unique content area.

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 provides explicit navigation guidance: 'Use 'list' to find recent volumes, 'issues' to see what's in a volume, and 'articles' to access individual speeches and debate sections.' It doesn't explicitly mention alternatives, but the hierarchical instructions serve as clear usage guidance.

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 and idempotentHint, so the description adds value by detailing the returned bill fields (sponsor, actions, summaries, text) and the law citation structure on the laws array. It also explains the difference between list and get operations, which is beyond what structured fields provide.

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 useful information: purpose, operation differentiation, and return format. No filler or redundant details.

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 read-only tool with two operations, the description covers the key behavioral differences and return content. Combined with 100% schema description coverage and the law-citation example, an agent has enough context to correctly select and invoke the 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 adds depth by defining lawType semantics ('pub' vs 'priv'), operation-specific behavior (list vs get), and provides a concrete JSON example of the law citation, elevating the meaning beyond raw schema entries.

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 opens with 'Browse enacted public and private laws from Congress.gov' — a specific verb and resource. It clearly distinguishes list from bill_lookup by noting the filtering capability 'bill_lookup does not offer', and clarifies get returns the origin bill record with a law citation.

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?

Explicitly positions list as an alternative to bill_lookup for enactment-status and law-type filtering. For get, it describes what is returned, making its use case clear, though it does not name an alternative for get or state when not to use it.

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 indicate read-only, idempotent, and open-world behavior, lowering the bar. The description adds behavioral context by explaining filter combinations and the dependency on bioguideId for certain operations, which is not fully captured by annotations or schema alone. No contradiction with annotations.

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 well-structured sentences front-load the main purpose and then detail usage patterns. Every sentence adds functional value without 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?

With 8 parameters and multiple operations, the description covers the main usage scenarios and limitations. The output schema exists, so return values need not be described. It omits edge cases like pagination or specific parameter requirements, but these are in the schema, making it sufficiently complete.

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 baseline is 3. The description adds semantic value by explaining how to combine filters (e.g., stateCode with district, congress with stateCode) and why bioguideId is needed for get/sponsored/cosponsored, going beyond the schema's field-level 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 clearly states the tool discovers congressional members and their legislative activity, distinguishing it from sibling tools like bills or committees. It enumerates specific operations (list, get, sponsored, cosponsored), making its purpose unambiguous.

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?

Provides clear guidance on when to use each operation: 'list' with filters by stateCode, district, congress, or currentMember; 'get' and legislative portfolio operations once a bioguideId is obtained. It also notes 'No name search' as a limitation. However, it doesn't explicitly compare against sibling tools, so it loses a point.

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 substantial behavioral context beyond the readOnly/idempotent annotations: house data comes from Congress.gov API, senate from the Senate's LIS feed, House sorting by vote update date with offset=0 returning the newest page, Senate sorting by roll call number, and operation-specific outputs. This is exactly the kind of nuance that annotations alone do not convey.

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 concise sentences: the first states the overall purpose, the second covers chamber selection and data sources, the third enumerates the operations with their specific outputs. Every sentence earns its place, and the most important information is front-loaded.

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 and 100% parameter description coverage, the description only needs to provide decision-level context. It covers the key choices (operation, chamber, sorting behavior) and crucial constraints (voteNumber required for certain operations), making the tool fully invocable based on the description plus schema.

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 baseline is 3. The description adds value by explaining operation semantics ('list' returns newest first; 'get' returns question, result, tallies, party breakdown; 'members' returns individual votes), the chamber data sources, and that voteNumber is required for get/members. It does not repeat every parameter but complements the schema effectively.

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?

Description explicitly states 'Retrieve U.S. congressional roll call votes and individual member voting positions for either chamber,' which is a specific verb+resource that clearly distinguishes this tool from sibling congressgov tools about bills, committees, reports, etc. It also immediately introduces the house/senate distinction, reinforcing its unique scope.

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 description gives clear operational guidance: use 'list' to find votes, 'get' for details, and 'members' for individual voting positions, plus how to choose chamber. It does not explicitly name sibling alternatives or state when not to use this tool, but the context is clear enough for an agent to select it for roll-call vote queries.

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 the tool read-only and idempotent, so the description does not need to restate safety. It adds a non-obvious behavioral trait: multi-part parents (e.g., PN851) carry no activity of their own, with all confirmation pipeline data on children (PN851-1, PN851-2). This explains the parent/child data model and the signal for when partitioning is required, which is exactly the kind of context annotations cannot convey.

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 a tight five-sentence paragraph: it leads with the core purpose, immediately moves to actionable operation guidance, then presents the critical exception/partitioning rule. Every sentence earns its place, and the structure front-loads the most important information while keeping the nuance at the end.

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 tool's moderate complexity (six operations, multi-part nomination edge cases) and the presence of a rich output schema and parameter descriptions, the description fully covers what an agent needs: it defines the resource, lists all operations, explains how to disambiguate parent vs child data, and signals when to use the partitioned form. No critical usage aspect is left unexplained.

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 baseline is 3. The tool description reinforces the PN numbering and partitioned form concepts, but these are already thoroughly described in the schema's `nominationNumber` and `ordinal` parameter descriptions (e.g., 'use the partitioned form (e.g. '851-1') for sub-resources'). The description adds narrative context but no new parameter-level semantics beyond what the schema already provides.

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 opens with 'Browse presidential nominations to federal positions and track the Senate confirmation process' – a specific verb+resource that clearly distinguishes this tool from siblings focused on bills, committees, and members. It also enumerates the distinct operations ('list', 'get', 'actions', etc.), making the tool's scope unambiguous.

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 explicitly prescribes which operation to use for what ('Use 'list' to browse, 'get' for nomination detail...') and explains the crucial partitioned-form rule for multi-part nominations (PN851 vs PN851-1). It also tells the agent when the partitioned form is needed: when 'get' on a parent returns no `nominees` array. This is clear, actionable usage guidance beyond the schema's enum.

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