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

Annotations already declare readOnlyHint, openWorldHint, and idempotentHint, so the description's job is to add behavioral nuance beyond that. It adds a critical caveat about the upstream timeout for q-only searches, explains the inline include behaviors, and clarifies session discovery via a sibling tool. This is more than just echoing annotations. It does not, however, mention pagination limits or rate limits, but those are less central for a read-only search tool.

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 dense but efficient, packing essential usage rules into six short sentences. The core purpose is front-loaded, followed by the most critical usage caveat (timeout on q-only searches), then concrete recommendations for include and sort, and finally a pointer to a sibling for session IDs. No filler or repetition; every sentence adds value.

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 tool with 15 parameters and a rich filter set, the description covers all the crucial contextual information: the required and recommended parameter combinations, timeout behavior, inline data inclusion, sort semantics, and how to obtain valid session identifiers. The schema already documents individual parameter formats and constraints, and the output schema presumably describes return structure, so the description addresses the higher-level usage context. Nothing essential for correct invocation is missing.

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 each parameter has a description, but the tool description significantly amplifies parameter meaning. It explains that q and jurisdiction are conditionally required, how to pair them for reliability, the purpose of include (sponsorships/actions for most research needs), the meaning of sort=latest_action_desc, and where to get session identifiers. This is invaluable guidance that goes well beyond the schema's individual parameter descriptions, directly helping an agent select and combine 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 opens with a clear verb and resource: 'Search state legislative bills across all covered US jurisdictions.' It also immediately distinguishes itself from siblings like openstates_search_committees or openstates_get_bill by emphasizing the search scope and filter dimensions (full-text, jurisdiction, session, subjects, sponsors, sort). The purpose is unambiguous.

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 actionable guidance: it explains that jurisdiction or q is required, strongly recommends pairing them to avoid timeouts, and gives a concrete example of a timeout (q-only common term). It also recommends include=sponsorships,actions for inline data, sort=latest_action_desc for moving bills, and points to openstates_get_jurisdiction for session identifiers. However, it does not explicitly state when to use this tool over a sibling like openstates_get_bill for a known bill ID, so it's not fully explicit about alternatives.

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