openstates-mcp-server

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 covered. The description adds behavioral context by explaining what include does for votes and actions (full tally, per-legislator positions, complete history), and states that 'full detail' is returned. However, it doesn't clarify the default response when include is not specified, nor does it describe the response structure or potential errors. This is adequate given annotations but leaves some behavioral ambiguity.

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 compact, with exactly four sentences that are front-loaded: the first sentence states the core purpose, the second explains parameter options, the third gives examples of include behavior, and the fourth provides a preference tip. No word is wasted, and the structure is logical for an agent to parse quickly.

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 tool's complexity (5 parameters, output schema present, annotations covering safety), the description covers the essential aspects: how to identify the bill, the include parameter's role and common uses, and the preferred parameter choice. It does not mention error handling, rate limits, or defaults, but these are less critical for correct invocation. The existence of an output schema reduces the need to explain return values. Overall, it is sufficiently complete for an agent to use the tool 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?

The input schema provides descriptions for each parameter, covering 100% of them. The description adds value by explaining the relationship between parameters: it clarifies that jurisdiction, session, and bill_id form a three-part path, and that openstates_id is an alternative and preferred. This relational knowledge goes beyond the schema's individual parameter descriptions, so the description compensates well.

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 clearly states the tool 'Fetch full detail for a specific state bill.' It specifies the resource (bill) and the action (fetch), and distinguishes it from sibling tools like search_bills (which searches) and get_committee/get_event (which target different entity types). It also clarifies the two identification methods, removing ambiguity.

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 provides clear guidance: it recommends preferring openstates_id when available to avoid session identifier lookup, and suggests using include to request related data in one call instead of searching again. This implies a workflow (first search, then get). It does not explicitly mention alternatives like search_bills for when no ID exists, but the guidance is sufficient and actionable.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the description does not need to restate safety. It adds meaningful behavioral context: 'Experimental — not all states have committee data' warns the agent about potential empty results. This goes beyond annotations by alerting to incomplete dataset coverage. No contradictions.

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 two sentences, front-loaded with the primary action and resource. The first sentence states what and when (with include=memberships), the second adds the experimental caveat and sourcing direction. No redundant phrasing; every clause earns its place.

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?

An output schema exists, so return format is covered. The description covers the essential context: the lookup key (OCD ID), optional include values (implicitly via schema but also mentioned for memberships), availability caveat, and how to obtain the ID. For a simple fetch-by-ID tool, this is complete.

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% for both parameters, so the baseline is 3. The description adds value by explicitly tying committee_id to its source ('from openstates_search_committees results') and by mentioning the effect of include=memberships in its opening sentence, reinforcing the schema's description. It does not add syntax beyond schema but provides operational context that helps correct invocation.

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 clearly states the function: 'Fetch committee detail by OCD organization ID.' It specifies the exact resource (committee) and the identifying parameter. It also indicates what is returned ('Returns name, classification, and membership roster') and differentiates from sibling search tools by referencing how to obtain the ID from openstates_search_committees.

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 provides concrete usage guidance: it states the prerequisite (obtain committee_id from openstates_search_committees) and flags the experimental nature with state availability caveat. However, it does not explicitly contrast with alternative get_* tools or state when to use search instead, though the 'obtain from' hint implies a workflow. This is clear context but lacks explicit exclusions.

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

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

Annotations already cover readOnlyHint, openWorldHint, and idempotentHint, so the description need not repeat them. It adds valuable context by stating what is returned (agenda, participants, media links, associated documents) and the experimental limitation. This goes beyond the annotations and gives the agent a fuller understanding of the tool's behavior.

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 two sentences with no fluff. The primary purpose is front-loaded in the first sentence, with return details and a caveat in the second, and a practical source hint in the third. Every sentence earns its place.

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 tool's moderate complexity (two parameters, one required, an output schema exists, and annotations declare safety properties), the description is fully sufficient. It covers the input source, expected return types, and a limitation. Nothing an agent needs to call the tool correctly 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% for both parameters, so the schema already provides detailed descriptions. The description adds no new information about the parameters beyond what the schema states — the event_id hint ('from openstates_search_events') duplicates the schema's own wording, and the include explanation mirrors the schema's enum descriptions. With full schema coverage, a baseline of 3 is appropriate.

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 'Fetch full event detail by OCD event ID' which is a clear verb+resource. It distinguishes from sibling tools like openstates_get_bill and openstates_get_committee by focusing specifically on events, and even directs the agent to the correct source tool for the ID, showing awareness of the tool's role.

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 instructs to 'Obtain the event_id from openstates_search_events', which is a clear usage guideline. It also warns that the tool is 'Experimental — event coverage is limited', setting correct expectations. It does not explicitly exclude alternatives, but since this is the only event-fetching tool, the guidance is sufficient.

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

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint, so the safety profile is covered. The description adds value by describing the returned metadata (sessions, identifiers, coverage dates) and accepted ID formats, which goes beyond the annotations. There is no contradiction with the read-only and idempotent hints.

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 three sentences with no filler. It is front-loaded with the action and purpose, then gives the use case and ID formats. Every sentence contributes essential information, making it concise and well-structured.

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 presence of an output schema and annotations that cover safety, the description provides everything an agent needs: the purpose, the trigger condition, the parameter formats, and what data to expect. No critical information is missing for correct 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 description coverage is 100% and both parameters are well documented in the schema. The description reinforces the jurisdiction_id formats but adds little beyond that. It implies sessions are always included, whereas the 'include' parameter makes them optional, which is slightly ambiguous. Thus the description provides only marginal added value over 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 states a specific action ('fetch full metadata'), a clear resource ('a specific jurisdiction'), and the key content returned (legislative sessions, identifiers, coverage dates). It also gives a concrete use case (getting session identifiers for bill searches) and names the exact OCD format, which distinguishes it from sibling tools like list_jurisdictions or search_bills.

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 clearly instructs when to use this tool: 'Use when you need to know the exact session identifier for a state before filtering bill searches.' This is a strong contextual trigger. However, it does not explicitly mention alternatives or when not to use it, so it falls short of the full 'when-not/alternatives' criterion.

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

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

Annotations already declare readOnlyHint: true, openWorldHint: true, and idempotentHint: true, so the safety profile is covered. The description adds genuinely useful behavior context: the jurisdictional classification nuance ('jurisdiction.classification separates the tiers... current_role.org_classification does not') and the include=offices tip. No contradiction with annotations, and the added context goes beyond what annotations provide, though it doesn't detail pagination or error cases, which are minor.

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?

Five sentences, each packing a distinct piece of information: purpose, tier breakdown, classification nuance, geocoding limitation, and include advice. No repetition of schema text, and the structure front-loads the core action. It is slightly long but does not waste words; every sentence earns its place.

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?

With an output schema present, the description need not explain return values. It covers all essential operational context: both tiers, classification caveat, no geocoding, and the include trick. For a read-only, idempotent lookup tool, nothing an agent needs to invoke it correctly 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 baseline is 3, but the description adds substantial meaning: it gives concrete coordinate examples ('47.6062 for Seattle, WA'), explains the include enum values in detail (offices, links, other_names, etc.), and explicitly calls out that include=offices returns contact information. This is far beyond the schema and helps an agent construct proper calls without guesswork.

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 'Find every legislator representing a geographic coordinate — both tiers,' which is a specific verb, resource, and scope. It immediately distinguishes this from siblings like 'search_people' by focusing on location-based lookup and explicitly mentions both state and federal tiers, making its unique purpose unmistakable.

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 clearly states use cases ('constituent-to-representative matching, address-based policy research, and electoral boundary analysis') and provides an important limitation ('This server does not geocode addresses — the caller must provide decimal-degree coordinates'). However, it does not explicitly contrast with alternative tools (e.g., when to prefer search_people), so it lacks an exclusion clause. Still, the context is strong enough to guide an agent.

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

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.

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.

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

Annotations already declare readOnlyHint, openWorldHint, and idempotentHint. The description adds valuable behavioral context beyond these: notes the experimental nature, coverage gaps (not all states have data), the timeout risk if unscoped, and the coverageNote field in output. This is transparent about limitations and usage constraints without contradicting annotations.

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 concise despite covering multiple aspects—requirement, timeout warning, experimental status, filter usage, and coverageNote. Each sentence serves a purpose and the most critical constraint (jurisdiction) is front-loaded. No filler or repetition.

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 output schema exists, return values need not be explained. The description covers all essential context: required parameter, timeout constraint, experimental limitations, filter options, and output note. For a 7-parameter tool with an output schema, this is complete and actionable.

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 baseline is 3. The description adds meaningful parameter guidance: explains the purpose of chamber (upper/lower), classification (subcommittee filtering), and include=memberships (full roster with roles). It also reinforces the critical jurisdiction requirement. This adds value beyond the schema's field descriptions.

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 ('List') and resource ('committees') with an explicit scope ('for a jurisdiction'). It distinguishes itself from sibling search tools by focusing on committees and emphasizing the required jurisdiction scoping. The purpose is unambiguous and distinct from tools like openstates_search_bills or openstates_get_committee.

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?

Provides explicit when-to-use guidance: 'jurisdiction is required' and warns about timeout, directing to openstates_list_jurisdictions as an alternative for picking a state. It also gives concrete usage examples for chamber, classification, and include filters. This is exemplary guidance that prevents misuse.

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

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

Annotations declare readOnlyHint, openWorldHint, and idempotentHint, which cover safety and repeatability. The description adds meaningful behavioral context beyond that: the experimental nature, the fact that most states lack event data, and the interpretation of empty results. No contradictions with annotations.

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 about four sentences and front-loads the core purpose and the mandatory jurisdiction constraint. It is reasonably tight, though some advice (like require_bills and include) is also present in the schema and could be considered slightly redundant, keeping it from a 5.

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?

With an output schema present, the description need not explain return values. It covers the sole required parameter, the experimental caveat, common filters, and empty-result interpretation—everything an agent needs to correctly scope and call the tool. It is fully complete for the tool's complexity.

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 already has solid descriptions. The description adds extra value by explaining the rationale behind jurisdiction (no all-states search), suggesting after for upcoming hearings, and highlighting require_bills for tracking legislation. This goes just beyond the schema, warranting a 4.

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 clearly states the tool searches hearings, floor sessions, and committee meetings, which is a specific verb and resource. It distinguishes from sibling get_event by focusing on search, and the opening sentence leaves no ambiguity about what the tool does.

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 explicit, actionable guidance: jurisdiction is required and why, use openstates_list_jurisdictions to choose one, use after/before for date scoping, require_bills for filtering, and include for context. It also warns about experimental status and how to interpret empty results, which directly informs usage decisions.

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

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

Annotations already declare readOnlyHint, openWorldHint, and idempotentHint, so safety and non-mutating behavior are covered. The description goes beyond that with critical behavioral details: the all-jurisdiction timeout, the page-ordering semantics for 'legislature' (upper then lower), the non-equivalence of omitting org_classification vs 'legislature', and the behavior of include options. This adds meaningful context not present in annotations alone.

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 a dense paragraph but is front-loaded with purpose and core constraints. Each sentence adds distinct information (timeout, alternatives, ID usage, include options, org_classification nuance). While it is long, it earns its length given the tool's complexity. It could be restructured with bullets for readability, but no sentence is redundant.

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?

The tool has 8 parameters, an output schema, and complex filtering logic. The description covers all the essential usage aspects: the required scoping, the distinction between filters, the integration with other tools' output IDs, and the behavior of include options. It leaves nothing ambiguous for an agent to resolve at runtime.

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 schema already documents each parameter in detail (e.g., id, jurisdiction, org_classification, include). The description reinforces but does not significantly extend parameter semantics beyond what the schema provides. For instance, the optionality and timeout constraint are restated, but the schema already explains the required-ness and the meaning of org_classification values. Thus baseline 3 is appropriate.

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 the exact resource ('state legislators and officials'), the actions ('search by name, jurisdiction, chamber, or district, or fetch specific people by OCD person ID'), and clearly distinguishes it from sibling search tools. It uses specific verbs and mentions the key distinguishing capability (fetching by ID), which sets it apart from openstates_search_bills, _committees, and _events.

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?

Provides explicit when-to-use and when-not-to-use guidance: 'Use openstates_list_jurisdictions to pick a jurisdiction, or openstates_get_legislators_by_location when you have coordinates but no state.' It also states the hard constraint that jurisdiction or id is required and explains the timeout limitation, which tells the agent not to attempt unscoped searches. The alternatives are named and conditions for choosing them are clear.

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