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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false, covering safety. The description adds behavioral detail: 'recent actions default to 15 and relationships to 20 with explicit stored totals and truncation flags' – indicating the tool returns totals and flags, and mentions per-record XML hash and snapshot provenance, which are useful data-quality signals. No contradiction 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 information-dense but well-organized: it leads with the combination of components, then gives example prompts, then coverage and defaults. No wasted words, though it's longer than typical. It's front-loaded with the core value proposition and structured logically.

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 effectively enumerates what the tool returns (identity, aggregates, citations, subjects, committee path, version lineage, actions, related measures, URLs, hashes, provenance), covers the scope limitation, and states defaults and truncation behavior. Since there is no output schema, this description provides an agent with a clear expectation of the result. It is complete for 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 coverage is 100%, so all four parameters (bill_type, bill_number, action_limit, response_format) are already documented in the schema. The description adds the default for action_limit (15) and mentions relationships bound at 20 with truncation flags, clarifying behavior beyond the schema. This is a modest addition, so a 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?

The description is explicit about what the tool does: it combines a bill's identity, sponsor/cosponsor aggregates, law citations, policy subjects, committee path, text-version lineage, recent actions, related measures, URLs, hashes, and provenance. It also gives concrete natural-language use cases ('build an evidence pack for H.R. 2670') and distinguishes it from simpler siblings like govinfo_legislation_committee_path or congress_bill_details by describing it as a combined evidence pack.

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 scenarios for when to use it (evidence packing, source trail documentation, due diligence summaries) and states its coverage limitation (118th Congress HR/S only) and defaults. However, it doesn't explicitly state when to prefer a lighter sibling tool (e.g., 'for just the committee path use govinfo_legislation_committee_path'), so it lacks explicit exclusions. It still implies usage context well.

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