politics_by_stateGet all current officials for a US state — federal senators and representatives, state legislators, and any indexed local officials. Organized by government level.
| Name | Required | Description | Default |
|---|---|---|---|
| state | Yes | State abbreviation (e.g. FL, CA, TX) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable context: 'current' indicates temporal freshness, 'indexed local officials' caveats completeness, and 'organized by government level' discloses return structure. No contradiction 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?
Two sentences with a front-loaded verb ('Get'), a clarifying dash list, and a concise structural note. Every word earns its place; no redundancy or filler.
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, so the description carries the burden of explaining return values. It specifies the categories of officials and the organizational principle (government level). It doesn't describe pagination or exact fields, but for a read-only list tool with one parameter, this is reasonably 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% – the single 'state' parameter is fully described with examples. The tool description doesn't add parameter-specific detail, so it neither helps nor hurts beyond the schema. 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 clearly states the tool retrieves all current officials for a US state, enumerating the specific types (federal senators/reps, state legislators, indexed local officials). This distinguishes it from siblings like politics_official (single official) and politics_candidates.
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 context: it is for state-level aggregation of current officials, organized by government level. It does not explicitly name alternatives or provide when-not-to-use guidance, but the scope is unambiguous enough for an agent to select it appropriately.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add one secure layer between your agents and this server.
Each tool has a clearly distinct purpose covering different aspects of political data: bills (search, details, text slices, TOC), officials (details, search, by state, representation), bridge pages (create, compare, session, letter), and specialized queries (speeches, votes, positions, provenance). No two tools overlap in functionality.
All tools follow a consistent 'politics_<descriptive_name>' pattern using snake_case. Verbs and nouns are combined logically (e.g., 'politics_bills_search', 'politics_candidate_feed'), with no mixing of conventions.
At 25 tools, the set is comprehensive for a political data API but slightly on the high side. However, each tool covers a specific niche (bills, officials, bridge pages, etc.), and the count is justified by the breadth of the domain. It remains manageable and well-scoped.
The tool surface covers major data types (bills, officials, candidates, speeches, votes, positions) and interaction workflows (bridge pages, watchlists). Minor gaps exist, such as missing a direct 'politician by name and state' endpoint, but the search and filtering tools compensate. Overall, the set is thorough.