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

Annotations already declare readOnlyHint, openWorldHint, and idempotentHint, so the safety profile is clear. The description adds valuable behavioral context: it reveals the default call returns the complete inventory by 'fetching and merging the pages server-side' (a non-obvious implementation detail), describes the return metadata (latest update times, optional sessions), and warns that session formats vary widely by state. These details go beyond what annotations provide, though it doesn't cover potential rate limits or error cases, which are not critical for this read-only, idempotent 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 well structured: it opens with the core purpose, then details the count and return metadata, follows with a specific use case, and ends with a caveat about session formats. Each sentence adds meaningful information; there's no fluff. It's slightly long but appropriate given the tool's nuances (session formats, include option). The key information is front-loaded, making it easy to scan.

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 simple list endpoint with an output schema (not shown here), the description covers all essential aspects: what it returns, the default complete response, the optional includes, and the primary use case for session discovery. It doesn't explicitly mention the classification or page parameters, but those are fully documented in the schema. Given the output schema exists and annotations cover safety, the description is complete enough for an agent to call the tool correctly without ambiguity.

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. The description adds meaning beyond the schema by emphasizing the include parameter's role: 'The legislative_sessions include option returns all historical and current sessions — always check valid session identifiers here before using them in bill searches.' This provides practical guidance on when to set include=legislative_sessions, which is not fully expressed in the schema alone. It also clarifies the default behavior of per_page and classification, but those are already covered in the schema.

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 immediately states the precise scope: 'List all jurisdictions covered by Open States — all 50 states, DC, and 5 US territories' and notes the total count (56). This is a specific verb+resource definition, and it distinguishes itself from sibling tools by emphasizing it is a list operation, implicitly contrasting with openstates_get_jurisdiction which targets a single entity. The added detail about returning the complete inventory in one call further clarifies the tool's function.

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 explicitly says 'Use this when you need to discover valid session identifiers for a state before calling openstates_search_bills with a session filter.' This gives a clear condition for when to use the tool. It also instructs to 'always check valid session identifiers here before using them in bill searches', which is actionable. However, it does not explicitly mention alternatives like openstates_get_jurisdiction for other use cases, so it lacks a direct comparison for the listing vs. single-jurisdiction scenario.

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