congressgov-mcp-server

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

Annotations already mark the tool readOnly, idempotent, and openWorld, and the description does not contradict them. It adds substantial behavioral detail beyond those hints: filtering by update date rather than legislative action, 'list' defaulting to most-recently-updated first, 'content' returning a bounded character window, exact offset semantics, and the fact that PDF is not retrieved. This is exactly the kind of non-obvious behavior 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.

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

The description is dense but every sentence earns its place, front-loading the core purpose and the critical 'no keyword search' caveat. It organizes the operation menu and parameter requirements in a compact flow, and it does not repeat annotation or schema content unnecessarily.

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 13 parameters, multiple operation modes, and a rich output schema, the description is remarkably complete. It covers all operation families, their prerequisites, the text-vs-content distinction, format behavior, and pagination semantics. The output schema handles return-value details, so nothing needed to call the tool correctly is missing.

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, but the description goes further by tying parameters to operation semantics: it explains which parameters each operation requires, how 'textVersionIndex' relates to the order returned by 'text', and how 'characterOffset' paginates through long documents. While much parameter detail lives in the schema, this operation-level guidance adds real meaning beyond the individual 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 opens with a specific verb and resource: 'Browse and retrieve U.S. legislative bill data from Congress.gov', and immediately disambiguates scope with 'there is no keyword search'. It enumerates the distinct operations ('list', 'get', 'actions', 'content', etc.), making it easy to separate this tool from the sibling committee, member, and CRS tools.

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 actionable routing: 'Use 'list' to browse', ''get' for full bill detail', and ''text' lists the published versions ... 'content' then reads one version's actual text'. It also states the parameter prerequisites for each mode ('each requires congress + billType + billNumber') and the exclusion ('there is no keyword search'), so an agent can confidently choose an operation.

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 meaningfully extends the readOnlyHint/openWorldHint/idempotentHint annotations by disclosing that date filters apply to summary update time rather than bill action date, which can return recently rewritten summaries of older bills. It also clarifies that each item displays both the action date and the summary update date.

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 four sentences with no filler: it states the resource and use case, clarifies an important behavioral nuance, states defaults, and routes to the alternative tool. Every sentence contributes necessary decision-making 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?

Given six optional parameters, full schema coverage, rich annotations, and an output schema, the description provides the additional context an agent needs: update-time semantics, default date range, and the alternative for targeted single-bill lookup. No critical behavioral gaps 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. The description adds value by explaining the semantic of fromDateTime/toDateTime (update time, not action time) and the default behavior, which is not fully obvious from the schema alone.

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: "Browse recent CRS bill summaries" and clarifies their utility for answering 'what's happening in Congress?'. It explicitly distinguishes itself from congressgov_bill_lookup, which is the sibling for summaries of one specific bill.

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 when-to-use context (recent summaries, plain-language legislative stage overviews) and explicitly names the alternative tool for single-bill summaries. It also explains the default 7-day window, which helps an agent decide whether this tool fits the 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?

With readOnlyHint and idempotentHint already present, the description adds valuable non-obvious behaviors: committee code inference from the prefix, approximate fuzzy-match labels, the 'bills' default ordering, and the upstream limitation that bill titles are omitted. These go well beyond what annotations or schema could 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 dense but every sentence adds decision-relevant detail: operation flow, code syntax, chamber handling, ordering behavior, and data limitations. Information is front-loaded with the overall purpose, then logically progresses from discovery to retrieval to chaining.

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 eight parameters, five operations, and an output schema, the description covers all necessary context: operation selection, parameter dependencies, default behaviors, Senate-only restriction, and how to overcome the missing-titles gap by chaining to another tool. Nothing an agent needs to invoke it correctly is absent.

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%, establishing a baseline of 3, but the description substantially enriches parameter semantics. It explains the internal structure and case-insensitivity of committeeCode, reveals that any non-blank value is auto-resolved as a committee name, and clarifies the order parameter's scope and defaults beyond the schema's enum text.

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-resource pair ('Browse congressional committees and their legislation, reports, and nominations') and enumerates the exact sub-operations, making it immediately distinguishable from sibling bill, member, and report tools. It also names the chaining target (congressgov_bill_lookup get), reinforcing its role in the broader tool family.

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 an explicit workflow: use 'list' (with optional 'filter') to discover committee codes, then use 'get' or sub-resources. It also gives exclusion guidance ('nominations' is Senate-only) and explains when chamber should be passed explicitly versus inferred, leaving no ambiguity about operation selection.

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 description is not required to repeat those. It adds valuable behavioral context: 'text' returns format URLs, 'content' reads a bounded character window, and PDF is explicitly not retrieved (pointing to the format URLs). It also describes the exact offset semantics ('never snapped to a section or paragraph break') and the windowing trick (using nextOffset). These go beyond the annotations and provide operational transparency.

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, well-structured paragraph of three sentences. It front-loads the primary purpose, then logically transitions to report types and the text/content workflow. No filler or redundant statements; every sentence carries information needed to understand the tool's behavior.

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 (9 parameters, 4 operations, multiple report types), the description provides a solid high-level overview and the crucial text-vs-content distinction. The output schema typically documents return values, so the lack of return-format discussion is acceptable. It does not mention pagination of list results (limit/offset) but those are clearly documented in the parameter descriptions. Overall, an agent would have enough context to use the tool correctly, though a note about list pagination would make it fully 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?

The schema descriptions cover 100% of parameters in detail (e.g., format, characterLimit, characterOffset). The tool description adds meaning by tying operations to parameters—explaining that 'text' lists URLs and 'content' reads text with a character window—which clarifies how operation, reportType, reportNumber, and the character parameters interact. This is a modest but useful supplement to the already rich schema, so it earns 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 clear verb ('Browse and retrieve'), a specific resource ('committee reports from Congress.gov'), and explains what reports contain. It distinguishes itself from sibling tools by focusing solely on committee reports, and the operation types (list, get, text, content) map directly to the schema. The addition of report type examples ('hrpt', 'srpt', 'erpt') further grounds the 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 implies a clear usage workflow: use 'text' to get format URLs, then 'content' to read the actual text. It also notes that reports accompany legislation reported out of committee, giving context for when this tool is relevant. However, it does not explicitly contrast with sibling tools (e.g., when to use bill_summaries instead) or state exclusions, so the guidance is implied rather than exhaustive.

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, establishing safe read-only behavior. The description adds behavioral context by noting that 'get' provides authors, topics, summary, and download formats, and that report IDs follow a letter-number pattern (e.g., R40097). This enhances the agent's understanding of what to expect without contradicting 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.

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

The description is two compact sentences with no redundancy. The first sentence establishes what CRS reports are, and the second explains the operations and ID format. The key actionable information (list vs get, ID format) is front-loaded, making it efficient for an agent to parse.

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 an output schema and well-documented parameters, the description adequately covers the essential usage details: the operations, the report ID format, and what 'get' returns. It doesn't mention pagination or error handling, but those are covered by the schema and the tool's read-only nature. Minor omission of how 'list' results are returned is tolerable given the output schema exists.

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 already documents all parameters with 100% coverage, including descriptions and defaults. The description adds value by specifying the concrete report number format ('R40097', 'RL33612', 'IF12345') and clarifying that reportNumber is required for 'get', which reinforces the schema's conditional requirement. This goes beyond the schema's generic wording.

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 browses and retrieves CRS reports, explicitly describing them as nonpartisan policy analyses covering policy areas, legislative proposals, and legal questions. This distinguishes it from sibling tools for bills, committee reports, and other congressional documents, making 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 how to use the two operations: 'Use 'list' to browse available reports or 'get' for full detail'. It also clarifies the report ID format required for 'get'. While it doesn't explicitly contrast with sibling tools or state when not to use this tool, the topic distinction (CRS reports vs. other congressional documents) is implied through the description's content.

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?

With readOnlyHint, openWorldHint, and idempotentHint already provided by annotations, the description adds genuine behavioral context: the hierarchical navigation flow, the fact that 'articles' returns format URLs, and that 'content' reads a bounded character window at a time. This goes beyond what annotations alone 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 well-structured and compact: a front-loaded purpose, then the operation hierarchy, then concrete usage instructions. Every sentence contributes either scope or navigation guidance, with no filler or repetition.

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 4-operation, 9-parameter tool, the description covers the operation flow, the relationship between operations, and the bounded-window content model. The output schema and 100% parameter coverage supply the remaining return-value and parameter details, so nothing needed for correct invocation is missing.

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 carries the parameter detail. The description adds high-level operation semantics and the windowed-reading behavior, but it does not need to restate what the schema already documents. It earns the baseline rather than exceeding it.

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 direct verb-resource statement ('Browse the daily Congressional Record') and names concrete contents: floor speeches, debates, and legislative text. It then maps the four operations to a hierarchy, making the tool's role clear and distinguishing it from sibling bill/committee-focused tools.

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 explicit routing guidance among the tool's own operations: 'Use list to find recent volumes, issues to see what's in a volume, and articles to access individual speeches.' It does not explicitly contrast with sibling tools, but the daily-record scope is plainly distinct from the sibling bill and committee 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, so the description doesn't need to restate safety. It adds meaningful behavioral context by explaining that 'get' returns the origin bill record with the law citation on the 'laws' array, including an example. This goes beyond the schema and gives the agent an expectation of the output shape. No contradictions with annotations were found.

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 three sentences with zero fluff. The first sentence states the overall scope, the second explains 'list', and the third explains 'get'. The most important differentiator (list's filtering ability) is front-loaded, and the example citation is compact and concrete. Every sentence earns its place.

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 two operations, six parameters, and an output schema present, the description handles the essentials well: it explains each operation's purpose and return, and it ties lawType and lawNumber to the operations. Pagination (limit/offset) is left to the schema, which is acceptable given the schema is explicit. The description could mention the typical workflow (list then get) more explicitly, but it's implied strongly enough that an agent can infer it. Overall, it's complete for correct 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%, so the schema already defines every parameter. The description adds genuine semantic value beyond the schema: it clarifies the meaning of 'pub' vs 'priv' (public/private laws) and explains that lawNumber is carried from a 'list' row's laws[].number, with the prefix matching congress. This extra context helps disambiguate the lawNumber parameter's dual forms, which the schema describes but the description makes operationally clear.

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 clear purpose: browse enacted public and private laws from Congress.gov by congress and law type. It explicitly names the two operations ('list' and 'get') and what each does, and it differentiates from the sibling bill_lookup by noting that 'list' offers enactment-status and law-type filtering that bill_lookup lacks. This gives an agent a confident understanding of what the tool does and how it differs from nearby tools.

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 identifies the discovery path ('list') and the retrieval path ('get'), and it explicitly calls out that bill_lookup does not offer the filtering 'list' provides, giving a concrete when-to-use hint. It doesn't enumerate all alternative tools or provide explicit exclusions for every sibling, but the domain (enacted laws) is distinct enough that the usage context is clear. A bit more explicit 'use this when...' phrasing would push it to 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 supply readOnly, idempotent, and openWorld hints. The description adds meaningful behavioral context beyond those: it states that name search is not supported, that currentMember=true restricts to currently serving members, and that 'list' filtering follows specific combination patterns. 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?

Three sentences carry a large amount of operational guidance without fluff. The most important scoping caveat ('No name search') and the filtering rules are front-loaded, and the workflow progression from list to get/sponsored/cosponsored is logically 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?

For an 8-parameter tool with four operations, the description covers filter combinations, required dependencies, operation selection once bioguideId is known, and an explicit exclusion. Combined with a 100% described schema, rich annotations, and an output schema, nothing essential is missing for an agent to invoke it correctly.

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 baseline is 3. The description adds value by clarifying relationships: district requires stateCode, stateCode can pair with congress, and bioguideId is the key for get/sponsored/cosponsored. Concrete examples (e.g., 'CA district 12 in the 118th') reinforce parameter semantics beyond dry schema text.

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 the resource ('congressional members and their legislative activity') with a clear verb ('Discover') and immediately delimits scope with 'No name search.' It also names the four operation modes, making the tool's purpose and boundaries obvious relative to sibling lookup tools.

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 explicit usage patterns for the 'list' operation—filter by stateCode, optionally with district, by congress, or both—and explains when to switch to 'get' or 'sponsored'/'cosponsored' once a bioguideId is known. It doesn't explicitly compare to sibling tools, but the domain and operation guidance are clear enough for correct invocation.

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 meaningful behavioral context: house data comes from the Congress.gov API while senate data comes from the Senate's LIS feed, list returns newest first by default, and 'get' returns specific fields (question, result, tallies, party breakdown, associated bill/nomination/amendment). This goes beyond the annotations without contradicting them.

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 three sentences, front-loaded with the core purpose, and each sentence earns its place. It efficiently packs chamber sourcing, operation types, and return content without redundancy or filler. The structure is scannable and immediately actionable for an agent.

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 operation semantics, chamber selection, data sources, and default ordering. The input schema documents all parameters, and an output schema exists, so return values are already specified. Minor gaps like pagination behavior are handled by the schema; overall, the agent has everything needed to select and invoke the tool correctly. A 4 is appropriate given the tool's 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 description coverage is 100%, so the baseline is 3. The description does not add much parameter-level meaning beyond the schema: it mentions operation-to-parameter mapping and the chamber data source, but the schema already documents voteNumber's requirement for 'get'/'members' and the chamber-specific roll call reset behavior. No significant param semantics are added beyond what the schema 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 a specific verb-resource pair ('Retrieve U.S. congressional roll call votes and individual member voting positions') and immediately distinguishes the tool's domain from the sibling tools (bill lookup, committee reports, etc.). It further clarifies scope by chamber and by operation, leaving no ambiguity about what the tool does.

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 operation selection guidance: 'Use 'list'...', 'get' for vote details..., or 'members' for how each member voted.' It also distinguishes data sources for house vs senate. It does not explicitly state when not to use this tool versus a sibling, but the sibling tools are clearly different domains, so exclusion guidance is unnecessary.

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?

Beyond the readOnly/idempotent/openWorld annotations, the description discloses crucial non-obvious behavior: parent nominations like PN1000 carry activity, while multi-part parents like PN851 carry none and require partitioned children. It even provides a diagnostic rule—'get on a parent that has no nominees array signals the partitioned form is needed'—which is exactly the kind of behavioral nuance 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.

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

The description is dense but every sentence earns its place: purpose, operation routing, numbering scheme, parent/child quirk, and a detection heuristic. The most important operational constraint is front-loaded with concrete examples, and there is 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?

Given the tool's complexity—six operations, nuanced multi-part nominations, and partition behavior—the description covers everything needed to select and invoke it correctly. The presence of an output schema means return values need not be explained in prose, and the HTTP-like safety profile is covered by annotations.

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 the input schema already documents operation, nominationNumber, ordinal, congress, limit, and offset in detail. The description adds a useful decision procedure for choosing bare vs partitioned nomination numbers, but largely restates semantics already present in the schema, so the baseline of 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?

The description opens with a specific verb and resource: 'Browse presidential nominations to federal positions and track the Senate confirmation process.' It then enumerates the exact operations and what each returns, making the tool's purpose unmistakable and clearly distinct from the unrelated congressional siblings.

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 explicit operation-by-operation routing: 'Use list to browse, get for nomination detail, actions/committees/hearings for confirmation pipeline data, or nominees to retrieve individual appointees.' It also explains when to use bare versus partitioned nomination numbers, so an agent knows exactly how to select parameters for the right data.

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