Get a bill decode

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

Annotations already declare readOnlyHint: true and openWorldHint: false, and the description adds valuable context: AI summaries are auto-checked before publishing, citation resolution defaults to the most recent Congress, and script generation is not available through the API. This goes beyond the base annotations, though it could mention error behavior or data freshness.

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, dense sentence but is structured logically, starting with the core action and then detailing the return payload and a key limitation. It is verbose yet every phrase contributes meaningful detail, with no fluff. Breaking it into two sentences could improve readability without adding bulk.

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 aspects: purpose, input methods, output fields (summary, status, urgency, sponsor, dates, URLs), and a critical limitation. Given the tool's moderate complexity and absence of an output schema, this is largely complete. Minor gaps include no mention of error conditions, rate limits, or handling of invalid slugs/citations, which could be inferred from typical API 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?

While the schema provides basic parameter descriptions, the tool description enriches understanding by explaining that slug takes priority over citation, how citations are resolved, and gives realistic examples. The explicit mention of the precedence rule and the 'most recent Congress' behavior adds semantic value that the schema alone does not convey. This helps the agent use parameters correctly.

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 purpose: getting a full plain-language decode of a federal bill using either a slug or citation. It distinguishes itself from sibling tools by focusing on bill-specific data and explicitly noting it never drafts a phone script, setting it apart from the on-site call flow and other 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 explains how to invoke the tool (by slug or citation) and the priority of slug over citation, which helps in usage. It also clarifies a limitation (no script drafting). However, it does not explicitly compare this tool to siblings like search_bills or what to do when a bill ID is unknown. A direct 'when to use this instead of search_bills' would be an improvement.

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