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

Annotations already establish read-only, non-destructive, open-world behavior, and the description adds important operational context: include calls are separate API calls, detail avoids that cost, and analyses/citations are only populated for deeper-coverage states. It also supplies status_id and aggregate-bucket semantics that help interpret results.

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 definition is front-loaded with the core fetch behavior and then organizes includes, coverage caveats, and status semantics. It is somewhat long and duplicates the include enum, but the added status mapping is useful enough to justify most of the length.

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 schema and annotations, the description covers the main calling decisions: where to get bill_id, whether to use include or detail, coverage limitations, and status/aggregate meanings. Since there is no output schema, the return shape could be described more fully, but the key semantic context is present.

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 adds meaning beyond the schema by explaining what several include values contain and how detail:true overrides include. max_items is left to the schema, which is acceptable given full coverage.

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: fetch a single bill by numeric bill_id via GET /v1/bills/{bill_id}. It also names the search tools that supply bill_id, so an agent can distinguish this from broad bill search.

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 says to get bill_id from search_bills or semantic_search_bills and explains the include-vs-detail tradeoff: each include is a separate API call, while detail:true fetches everything in one round trip. It does not explicitly compare against siblings like get_bill_text or get_bill_statutes, so it stops short of full when-to-use guidance.

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