politics_bridge_letterDraft a letter to a politician on the citizen's bridge page. The letter gets an origin hash for proof of content. Returns delivery options (email, web form, USPS, phone).
| Name | Required | Description | Default |
|---|---|---|---|
| body | Yes | Letter body text | |
| hash | Yes | Bridge page session hash | |
| subject | No | Letter subject | |
| action_type | No | letter | |
| official_id | Yes | Official to write to |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses useful behavioral traits beyond the sparse annotations: it assigns an origin hash for proof of content and returns delivery options (email, web form, USPS, phone). This adds context about side effects and outputs, and does not contradict any annotation 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 only two sentences long, with no redundant filler. Every clause carries information: the drafting action, the platform context, the hash generation, and the return 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 5 parameters and no output schema, the description covers the core purpose, a notable side effect (origin hash), and the general return type (delivery options). It falls short of describing the exact structure of the return value and the role of the 'action_type' parameter, but overall it is suitably complete for a moderately complex tool.
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 high (80%), so the baseline is 3. The description adds some semantic context for the 'hash' parameter (origin hash for proof) and the overall return (delivery options), but it does not clarify the meaning of 'subject' or 'action_type', or how they relate to the delivery options. It provides marginal value beyond 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 ('Draft a letter to a politician') on a specific resource ('citizen's bridge page'), clearly distinguishing it from sibling tools like politics_bridge_create or politics_represent. It also adds unique details (origin hash, delivery options) that separate it from other politics tools.
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 clearly states what the tool does but offers no guidance on when to use it versus alternatives, no exclusions, and no mention of related tools. Usage context is only implied by the tool's purpose, not explicit.
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.