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

With no annotations provided, the description carries the full burden, and it delivers: it discloses the separate-API-call cost model, notes that analyses and citations are populated only for deeper-coverage states, and explains the detail:true shortcut. It does not mention rate limits, auth requirements, or error/not-found behavior, but for a read-only fetch tool it is substantially transparent.

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 long but dense, with the core purpose front-loaded and the include list serving a dual role of naming values and explaining them. The status_id mapping adds useful context, and there is little outright filler, though the single-paragraph format makes the enumeration harder to scan than bullet points would.

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 complex tool with 12 sub-resources, 4 parameters, no output schema, and no annotations, the description covers most of what an agent needs: how to obtain bill_id, what each include means, when to use detail, and coverage caveats. Minor gaps remain, such as what a response with no include looks like and behavior for invalid bill_ids, but the description is still sufficient 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 baseline is 3, but the description adds real meaning beyond the schema: it defines each include value in context (e.g., 'citations (statutes the bill touches)', 'sast (same-as / similar-to companion bills)') and explains the cost difference between include and detail. It also provides status_id value mappings that help interpret results, though those are not input parameters.

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: 'Fetch a single bill by its numeric bill_id,' which clearly distinguishes it from siblings like get_bill_diff and get_bill_text. It also names the source of the required identifier (search_bills / semantic_search_bills), eliminating ambiguity about what the tool operates on.

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 context for choosing between include lists and detail:true, explicitly warning that each include is a separate API call and that detail:true is the cheapest one-round-trip alternative. It does not explicitly contrast this tool with sibling retrieval tools such as get_bill_text or get_roll_call, so it stops one step short of full when-not guidance.

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