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

Annotations already declare read-only, non-destructive, open-world behavior. The description adds value beyond them: sort order (newest first), the fact that has_transcript:true rows expose a verbatim transcript sized transcript_chars, and a pointer to get_hearing for reading it. It stops short of stating pagination behavior or result volume limits, but the key behavioral traits are disclosed.

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?

Four sentences, each load-bearing: purpose+scope, use case, transcript behavior, and sibling routing. Purpose is front-loaded and there is no redundant restatement of the schema.

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?

No output schema exists, yet the description still conveys row shape (has_transcript, transcript_chars), ordering, and how to drill into a record. Combined with five optional, fully documented parameters and a safe-read annotation profile, an agent has everything needed to call this 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 limit/offset/since/state are already documented. The description adds real meaning to has_transcript beyond the schema's filter wording by explaining the consequence of the flag (a verbatim transcript of transcript_chars length read via get_hearing), and frames 'jurisdiction and start date' as the primary filter axes.

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?

Specific verb+resource (committee hearings and meetings), with explicit endpoint, ordering ('newest first'), and filter dimensions. It is clearly distinguishable from get_hearing (single record), get_committee, get_bill, and list_floor_transcripts, which are all named.

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?

Gives a concrete use case ('what is being heard this week', tracking next committee meeting) and then routes to alternatives with explicit conditions: get_committee with include:['hearings'] for a single committee, get_bill with include:['calendar'] for a single bill, list_floor_transcripts for floor sessions.

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