officials

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

Beyond the read-only and idempotent annotations, the description adds key behavioral traits: it does NOT label agreement/contradiction (the user judges), outputs are source-linked, and data is organized per topic. This informs the agent of important output semantics not captured in 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 two sentences, front-loaded with the main purpose and followed by a clarifying caveat. Every sentence earns its place, with no filler or redundant information.

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 one-parameter, read-only tool with no output schema, the description adequately covers purpose, output presentation (juxtaposition, source-linked, per topic), and what the tool avoids. It does not mention return format, but given the simplicity and annotations, this is sufficient.

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 schema already describes the single parameter 'id' with 100% coverage, so the baseline is 3. The description only reiterates 'Use official id' without adding new semantic detail, such as how the id relates to other tools or any format constraints, so it adds no significant 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 clearly states the tool compares an official's stated positions against actual roll-call votes per topic, using the verb 'compare' and describing the output as 'juxtaposition.' It distinguishes from siblings by explicitly noting it does NOT label agreement/contradiction and by emphasizing source-linked data, making the purpose specific and unique.

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 provides clear context on when to use: to compare an official's stated positions vs votes, and instructs to use the official id. However, it does not explicitly name alternative tools for different use cases (e.g., politics_positions), so it stops short of full exclusionary guidance.

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 destructiveHint=false. The description adds value by explaining the default return payload (metadata, excerpt, text index) and the token-cap rationale for omitting full text, plus how include_text alters behavior. This goes beyond the annotations' safety profile.

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 core content list and followed by a concise explanation of the default behavior and token-cap warning. No filler words; every clause contributes to understanding.

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 no output schema, the description summarizes return shape (metadata, excerpt, text index) and key data categories. It warns about token caps for full text. However, it does not explain how to interpret the text index or origin proof, nor does it reference the sibling politics_bill_text as an alternative for full text, leaving minor gaps.

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%, with detailed descriptions for both bill_id (including an example) and include_text (enum values, defaults, and token-cap warning). The description does not add new parameter details beyond referencing include_text at a high level, so 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 explicitly enumerates the tool's content: 'vote breakdown, sponsors, cosponsors, status, and origin proof.' It also differentiates from siblings by stating it returns 'metadata, a short text excerpt, and a text index by default' rather than full text, which aligns with the existence of politics_bill_text.

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 implies the tool is for retrieving bill details and warns that full text may exceed token caps, but it does not explicitly recommend when to use this tool over siblings like politics_bill_text. There is no direct mention of alternatives or exclusions, leaving usage context vague.

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 this tool read-only and idempotent, so the safety profile is covered. The description adds that it returns bill metadata and full-text availability, which is useful. However, it does not disclose search behavior such as matching rules, pagination, or whether multiple filters are combined with AND/OR, leaving some behavioral aspects opaque.

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 exactly two short sentences, front-loaded with the primary action and search dimensions. It does not repeat schema details or include fluff, making it highly efficient and easy to parse.

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 no output schema, the description provides only a high-level summary of return content ('bill metadata and whether full text is available') but lacks details like default limit, pagination, or how filters interact. The description is adequate for a basic search tool but leaves several practical questions unanswered.

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 80% (four of five params have descriptions), so the baseline is 3. The description lists 'topic, sponsor, status, or congress' but does not add extra meaning beyond what the schema already states. The 'limit' parameter lacks a schema description and is not mentioned here, so the description does not compensate for that gap.

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 begins with 'Search bills by topic, sponsor, status, or congress' – a specific verb and resource with clear search dimensions. It distinguishes from sibling tools like politics_bill (likely retrieving a single bill) and politics_bill_text (likely retrieving full text) by focusing on search. Additionally, it mentions the return value, which clarifies the tool's output.

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 establishes that this tool is for searching bills by various criteria, providing a clear context for when to use it (when you need to find bills by topic, sponsor, status, or congress). It does not explicitly name alternatives or exclusions, but the purpose is specific enough that the usage context is unambiguous.

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?

The description discloses significant behavioral detail beyond the annotations: it specifies the response includes part, total_parts, next_part, part_sha256, and a whole-bill content_hash, and explains the verification scheme (concatenating parts hashes to content_hash). This adds context about pagination and data integrity that annotations do not cover.

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, front-loaded with the core purpose, and every sentence carries essential information (purpose, response structure, verification method). There is no fluff 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?

With no output schema, the description must explain return values, and it does: it describes the response fields (part, total_parts, next_part, hashes) and the concatenation rule for verification. It also addresses the pagination use case and constraints (bounded slices, max_chars indirectly), making the tool's behavior clear for an agent.

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 the description largely reinforces the schema (e.g., 'addressed by part number or section label' mirrors the section and part parameters). It does not add meaningful new semantics about formats or defaults beyond what the schema already provides, though it does tie the part parameter to the response's total_parts and next_part.

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 'One signed, bounded slice of a bill's full legislative text, addressed by part number or section label,' which clearly specifies the tool's function and distinguishes it from siblings like politics_bill_toc. The verb 'slice' and resource 'bill's full legislative text' make the purpose 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 implies usage for bills too large to return in a single response ('a bill too large to return in a single response remains verifiable as complete and unaltered'), but it never explicitly names alternatives like politics_bill or politics_bill_toc, nor does it state when not to use this tool. This is implied guidance rather than explicit direction.

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 readOnly, idempotent, and non-destructive behavior. The description adds valuable context about the exact payload structure (offsets, lengths, content_hash, total length), which is not present in the schema. 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 two sentences, front-loaded with the core purpose, and contains no filler. It efficiently conveys both what the tool does and the nature of its response.

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 one-parameter tool with no output schema, the description adequately explains the return values and hints at its lightweight nature. It could be improved by explicitly referencing sibling tools like politics_bill_text to clarify scope, but it is otherwise 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?

The single parameter bill_id is fully documented in the input schema with an example. The description does not add additional parameter-level meaning, but since schema coverage is 100%, the baseline score 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 clearly defines the tool as a section index for a bill, listing exactly what it returns: SEC. N headings with offsets and lengths, content_hash, and total text length. This distinguishes it from siblings like politics_bill_text (full text) and politics_bill (bill details).

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 phrase 'small response that describes the structure of a large bill' implies it is intended for structural overview rather than full content. However, it does not explicitly name alternatives or specify when not to use it, so usage guidance is implied rather than explicit.

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 are minimal (all flags false) and the description does not disclose that this is a write operation (saving a comparison). The wording 'Compare' could imply read-only, which conflicts with the title and the readOnlyHint=false annotation. No disclosure of side effects or state changes.

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 single, readable sentence with a clear list of comparison dimensions. However, the mismatch between the verb 'compare' and title 'Save' reduces its effectiveness slightly.

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 description does not explain what a 'bridge page' is, what the hash parameter represents, or what happens after saving. For a state-changing tool with no output schema, the description is incomplete and lacks necessary context.

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 all parameters (hash, title, topic, official_ids) are documented in the schema. The description adds no extra meaning about the parameters, so the baseline 3 applies.

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 uses the verb 'Compare' but the title says 'Save Comparison Set', creating ambiguity about the core action. It identifies the resource (politicians on a bridge page) but does not explicitly state that this tool saves/comparison sets. No differentiation from sibling bridge 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?

No information is provided about when to use this tool versus alternatives like politics_bridge_create or politics_bridge_session. There are no exclusions, prerequisites, or context for selecting this tool.

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?

The description goes beyond the annotations by disclosing the return value (a shareable URL for collaboration) and the optional auto-population of state representatives. Annotations already indicate a non-read-only, non-idempotent operation, and the description adds meaningful behavioral context without contradicting them. It does not address rate limits or duplicate creation, but the annotations cover the safety profile.

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 at two sentences, with the core action front-loaded ('Create a citizen bridge page'). It efficiently conveys the workspace purpose, return value, and optional behavior without redundant detail, making every sentence value-adding.

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 (3 optional params, no output schema), the description is sufficient for an agent to invoke it correctly. It specifies what is created, what is returned (shareable URL), and the optional auto-population behavior, covering the essential aspects needed for correct usage.

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 already fully describes all three parameters (zip, state, topics) with 100% coverage. The description's mention of auto-populating representatives adds a bit of context but does not materially improve understanding beyond the schema, which already states that state 'auto-adds federal representatives' and zip is for 'precise district matching'. Therefore the baseline score 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 clearly states the action ('Create') and the resource ('citizen bridge page'), and explains its purpose as a personalized workspace for tracking representatives, comparing positions, and taking action. It also distinguishes itself from sibling tools like politics_bridge_compare and politics_bridge_letter by focusing on the creation of the workspace itself.

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: use this to create a new bridge workspace and get a shareable URL. It implies a distinct role among sibling tools but does not explicitly mention alternatives or when-not-to-use scenarios. It also notes an optional behavior (auto-populating representatives) that helps in understanding when it might be used.

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?

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.

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

The annotations already declare readOnlyHint=true and idempotentHint=true, so the tool's safety profile is clear. The description adds useful context about what the workspace contains but does not disclose behaviors like session-not-found errors, freshness of data, or whether it accepts a hash. This is reasonable given the strong annotations, but it doesn't go beyond them.

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 single sentence with no filler. It front-loads the core meaning ('Current state') and then enumerates the contents concisely. Every word 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?

For a read-only tool with two well-documented parameters and strong annotations, the description adequately explains what the tool returns (the workspace's current contents). It doesn't discuss error cases or structure, but the lack of an output schema is somewhat offset by the explicit list of contained items. Adequate for the tool's simplicity.

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 schema provides full descriptions for both parameters (hash and agent_id), covering 100% of the parameter semantics. The description does not add further parameter-level details, but it doesn't need to since the schema is complete. Baseline 3 applies.

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 resource ('citizen bridge workspace') and its contents (tracked officials, saved comparisons, drafted actions, messages). It implies a read operation via 'Current state' and the title 'Read Bridge Workspace'. While it doesn't explicitly contrast with sibling bridge tools, the scope is specific enough to distinguish it from create/compare/letter.

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 no guidance on when to use this tool versus alternatives such as politics_bridge_create or politics_bridge_compare. There is no mention of prerequisites (e.g., needing a hash) or scenarios where this tool is appropriate. The title and name imply it reads a workspace, but explicit usage context is absent.

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, 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.

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

Annotations already declare readOnly, idempotent, and non-destructive. The description adds valuable behavioral context: every response is signed, the standalone signed feed is at /official/{id}/candidate.json, and the tier ('rootz-compiled' vs 'candidate-signed') indicates verification status. This goes beyond the annotations and is crucial for trust decisions. No contradiction.

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 dense sentences that efficiently convey purpose, content, signing, URL, and tier. While slightly long, every sentence adds meaningful information and the key action is front-loaded. No wasted words.

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 description covers the tool's purpose, the exact data included, the signed nature, tier semantics, and the standalone URL. With no output schema, it offers enough detail for an agent to understand the expected response. It could have mentioned pagination behavior for positions_offset, but the schema handles that.

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%, with each parameter already documented clearly (id, expand, bioguide_id, positions_limit, positions_offset). The description does not add parameter-specific semantics beyond what the schema provides, so the baseline of 3 applies.

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 uses the specific verb 'Get' and identifies the exact resource: a candidate's Campaign Data Standard (CDS) feed. It enumerates the feed's contents (identity, offices, positions with source links, voting record, data gaps), which clearly distinguishes it from sibling tools like politics_positions or politics_official that focus on subsets.

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: an AI or reporter uses this feed to grab and verify a candidate's positions. It implies the tool is for obtaining a complete, signed record in one request. However, it does not explicitly state when to use alternative tools (e.g., politics_positions for just positions) or when not to use this feed.

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, idempotentHint=true, and destructiveHint=false, so the bar is lower. The description adds useful context by specifying the election cycle, filterable dimensions, and return content (campaign website, social media, FEC data, position/speech counts), which goes beyond the annotations. It does not disclose pagination behavior, but that is not a major gap given the safety 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?

Two concise sentences front-load the core purpose and filters, followed by return data. Every sentence contributes useful information with no redundancy or fluff.

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 no output schema, the description partially compensates by listing return content. It covers key filter dimensions and the election cycle, but omits pagination details and the exact meaning of 'position and speech counts'. Given the read-only nature and rich annotations, this is sufficient for a list 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 coverage is 100%, so baseline is 3. The description adds marginal value by summarizing filters (state, office, party, has_url) and enumerating office values, but this largely restates schema. It does not provide additional parameter semantics beyond the schema 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 clearly states the tool returns registered federal candidates for the 2026 election cycle, with filtering by state, office, party, and URL presence. It distinguishes from siblings by its specific focus on federal candidates and the data returned (campaign website, FEC data, counts), though it lacks an explicit verb like 'list' or 'get'.

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 implies usage through its filter options and return fields, but it does not explicitly state when to use this tool versus alternatives like politics_candidate_feed or politics_search. No exclusions or alternative tool recommendations are provided, so guidance is minimal.

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 destructiveHint=false, so the description builds on this by adding that each change links to before/after snapshots with origin proof. This provides useful behavioral context beyond the structured fields without contradicting them.

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 scope, then adds a concise detail about the output. Every word adds value with no redundancy.

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 read-only listing tool with two optional parameters and no output schema, the description provides sufficient context: what it returns (changes with links), scope (all politicians), and examples. It could mention pagination or default limit, but the schema partially covers those.

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 schema covers only 50% of parameters (since has a description, limit does not). The description adds no information about either the 'limit' or 'since' parameters, leaving the undocumented 'limit' param entirely unexplained. This does not compensate for the schema's partial coverage.

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 'Get recent changes detected across all politicians' with specific examples like 'position shifts, website updates, new data.' It distinguishes itself as a global changes feed, but does not explicitly contrast with siblings like politics_timeline or politics_candidate_feed.

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 implies usage for checking recent changes across all politicians but does not provide explicit alternatives or exclusions. It suggests a broad scope ('across all politicians') but never tells the agent when to prefer this over per-politician tools.

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. The description adds interpretive context beyond annotations by explaining that silence indicates missing capture, not absence. This adds value without contradicting the 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, front-loaded with the core concept 'Coverage map', followed by concrete examples and a usage directive. Every word earns its place; 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?

For a zero-parameter read-only tool with no output schema, the description is complete. It covers what the tool does, the granularity (per-state, per-dataset), the contrast (federal vs local), and the interpretation of silence. No critical information 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?

The input schema has zero parameters, so the description cannot add parameter meaning. Per the rubric, 0 parameters yields a baseline score of 4. The description's examples of coverage dimensions (per-state, per-dataset) are not parameter-related but contextual.

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 'Coverage map: per-state, per-dataset completeness' with specific examples (officials by level, positions, finance, state-legislative votes). It distinguishes itself from siblings like politics_by_state by focusing on WHERE data is deep vs sparse, not on retrieving state data.

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 provides an explicit usage instruction: 'Use it to know whether silence means "no data captured" rather than "nothing there".' This clearly tells the agent when to invoke this tool, though it does not mention alternatives or when not to use it.

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 provide minimal safety hints (all false), so the description carries the burden of disclosure. It reveals two important side effects: sends a double-opt-in confirmation email and returns the bridge workspace URL. This goes beyond the structural metadata and gives the agent insight into the tool's behavior, though it does not mention repeated-call consequences or permissions.

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 wasted words. It front-loads the core purpose and then adds behavioral details in the second sentence. Every phrase earns its place, and the structure is easy to parse.

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 (8 parameters) and absence of an output schema, the description adequately covers the key elements: what it creates, the scope of parameters, the email confirmation, and the return value (URL). It does not explain prerequisites like email format or state-town pairing, but these are implicit in the schema. Overall, it is sufficiently complete for an agent to select and invoke 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?

Schema coverage is 100%, so the baseline is 3. The description adds the concept of 'any combination' of officials, topics, and town/state, which is a meaningful integration note not present in the schema. However, it does not elaborate on individual parameter syntax or relationships beyond that, leaving the schema descriptions as the primary source.

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's function: 'Creates a Just the Facts watchlist bound to an email address'. The verb 'Creates' is specific, and the resource (watchlist) is defined. It also distinguishes itself from sibling tools, which are mostly search/retrieval operations, by being the only creation tool for watchlists.

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 on when to use this tool: when you need to create a watchlist with officials, topics, or local meetings. It does not explicitly state exclusions or alternatives, but the sibling context makes it obvious this is the intended tool for watchlist creation. The description's mention of 'any combination' implies flexibility but not specific conditions.

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 the tool as read-only, idempotent, and non-destructive. The description adds valuable behavioral context beyond annotations: it details what content is included (algorithm, signals, weights, trust levels, sources, schedule) and explicitly discloses limitations ('what we can and cannot prove'). This enriches the agent's understanding of the informational output.

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 but packs significant detail: the core purpose, a list of contents, and a clarification of its openness. It is front-loaded with the action and resource, and every clause adds value without redundancy.

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 simplicity (no parameters, no output schema) and strong annotations, the description is fully complete. It explains exactly what the tool returns (methodology details) and its limitations, so an agent can decide to call it without any further context.

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 tool has zero parameters, so schema coverage is moot. The baseline for zero-parameter tools is 4. The description compensates by explaining the nature of the returned information, which is all the parameter semantics an agent needs in this case.

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 uses a specific verb ('Get') and clearly identifies the resource ('full transparency methodology'). It enumerates concrete contents (collection, assessment, extraction, signing, verification, algorithm, trust levels, sources, schedule, limitations), making it distinct from sibling tools like provenance or origin.

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 implies when to use this tool: whenever one needs the complete methodology or documentation of how political data is processed. It does not explicitly mention alternatives or exclusions, but given the unique nature of a methodology reference tool, the context 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 readOnly, idempotent, and non-destructive behavior. The description adds meaningful context: coverage ('every incorporated place in the US with coordinates') and return fields (website, platform, meeting calendar, board/commission info where available). This goes beyond annotation defaults and helps set expectations without contradicting them.

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?

Four concise, information-dense sentences. Each sentence contributes distinct value: the search target, scope coverage, filter options, and return data. No redundant phrases or filler. Front-loaded with the primary action, 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?

The tool has no output schema, but the description explicitly states what is returned ('website, platform, meeting calendar, and board/commission info where available'). It also clarifies data coverage ('every incorporated place... with coordinates'). With all 4 parameters documented in the schema and annotations covering safety, this is fully sufficient for an agent to select and invoke 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?

Schema descriptions cover 100% of parameters, including partial match for name and two-letter state code. The description's mention of 'Filter by state, name, or type' adds no new semantic information beyond what the schema already provides. Baseline 3 is appropriate as the structured data carries the meaning.

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's purpose: 'Search US municipalities' and lists common types (cities, towns, villages, counties). The verb 'Search' plus resource 'municipalities' distinguishes it from sibling tools like politics_search (general) and politics_bills_search (bills). It also specifies filters and return data, making the scope 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?

The description provides clear context for when to use this tool: when needing municipality data. It does not explicitly mention alternatives or exclusions, but the specialized scope (municipalities only) makes the appropriate use case obvious. No direct sibling comparison is given, but the context 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 the tool as read-only, idempotent, and non-destructive. The description adds meaningful context beyond annotations by stating that all data includes source URLs for verification, which informs the user about the response's provenance. 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 a single, well-structured sentence that leads with the action and resource, then efficiently lists content categories and the verification feature. Every clause earns its place with no redundancy.

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 read-only get-by-ID tool with five parameters and no output schema, the description adequately covers the core functionality and response characteristics (source URLs). It does not mention pagination or response bounding, but these are documented in the schema, so the description is sufficiently complete for typical use.

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?

All five parameters are fully described in the input schema (100% coverage), so the description does not need to add parameter-level details. The description does not go beyond the schema, so a baseline score 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 uses a specific verb 'Get' with a clear resource ('full details for a specific official by ID') and enumerates the content (biography, party, office, etc.), making it easy to understand what the tool does. It also differentiates itself from sibling search tools by focusing on ID-based lookup.

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 implies that this tool should be used when you have an official ID (likely from politics_search), but it does not explicitly state when to use it or when to prefer alternatives. The schema's id parameter description reinforces the source, but the description itself lacks explicit usage guidance.

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, idempotentHint=true, and destructiveHint=false. The description adds value by revealing what the statistics include (e.g., unique URLs, origin proofs) but doesn't discuss response format, pagination, or other behavioral details. 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, front-loaded with the action and immediately listing the key outputs. No wasted words, every phrase 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 simple parameterless tool with strong annotations, the description is functionally complete. It explains the kind of information returned and the overall purpose. Slight gap: doesn't clarify how it differs from politics_stats or whether the statistics are historical or current, but this isn't critical.

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 tool has zero parameters, so the schema imposes no burden. The description compensates by explaining what data is returned, which is the primary semantic content. Baseline 4 for a parameterless tool 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 uses a specific verb ('Get') and resource ('origin archive statistics'), and lists the concrete metrics included (snapshots, changes, proofs, URLs). It distinguishes itself from generic 'stats' tools by emphasizing the 'origin archive' and 'political wayback machine', but doesn't explicitly contrast with sibling tools like politics_stats.

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 implies usage when archive depth/statistics are needed, but offers no explicit guidance on when to use this instead of related tools such as politics_stats or politics_changes. Context is clear but lacks exclusions or alternative references.

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 mark the tool as read-only, idempotent, and non-destructive. The description adds behavioral details beyond that: compact records by default, inclusion of source URL and origin hash, total count, and pagination behavior via compact and offset. This gives the agent a good understanding of what to expect without contradicting the 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 two sentences, front-loaded with the core purpose, then succinctly covering output format and pagination. Every sentence provides necessary information with no redundancy or fluff.

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 no output schema, the description compensates by listing the compact record fields, total count, and pagination mechanics. It does not detail full-row fields, but the 'compact parameter controls row detail' hint is sufficient for a tool with a manageable parameter set. The main limitations are lack of explicit sibling differentiation and full-row field details.

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% and the parameter descriptions are already detailed (topic labels, limit defaults, offset pagination, compact mode). The description reinforces the role of compact and offset but does not add new parameter-specific meaning 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's function: listing policy positions across officials by topic, with specific example topics (crypto, stablecoins, AI, healthcare, guns). It distinguishes itself from siblings by focusing on officials' stances on issues rather than bills, speeches, or individual official details.

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 implies the use case—finding who supports or opposes an issue—and mentions the topic-based filtering. However, it does not explicitly contrast with sibling tools like politics_search or politics_bills_search, nor does it state when not to use it. The context is clear but lacks explicit exclusions or 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, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds useful context about the response scope (every data source, content hash, quality assessment, snapshot history, verification instructions). However, it does not disclose return format, pagination, or error behavior, so it adds only modest value beyond the 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 two sentences, front-loaded with the core action and then enumerating the specific elements included. Every word contributes, with 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?

For a one-parameter read-only tool with no output schema, the description adequately explains what the tool returns by listing the components of the provenance chain. It gives an agent sufficient context to invoke the tool and understand the expected response, even if minor details like error handling are absent.

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 schema already fully documents the single parameter official_id with a description. The description adds no further meaning about the parameter (e.g., format, constraints, or relationship to the provenance chain). Given 100% schema description 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 uses a specific verb 'Get' and a well-defined resource: the complete origin proof chain for an official, listing concrete components (data source, content hash, quality assessment, snapshot history, verification instructions). This clearly distinguishes the tool from siblings like politics_origin by focusing on the full provenance chain.

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?

No guidance is provided on when to use this tool versus alternatives, nor are there any exclusions or prerequisites. The description merely states what the tool does, leaving usage context to be inferred from the name and description.

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, idempotentHint=true, and destructiveHint=false. The description adds valuable behavioral context beyond this: the specific set of officials returned and the guaranteed presence of source_url and source_link fields on each official. This enriches the output contract beyond what annotations provide.

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 long, front-loads the core purpose, and each clause serves a purpose: defining the input, listing the output scope, and noting the source fields. No wasted words.

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 one parameter and no output schema, the description carries the responsibility of explaining return values. It covers the main expected data (officials and their source links) but does not describe the overall response envelope, error handling for invalid ZIPs, or edge cases like multiple districts. Still, it is sufficiently complete for a simple lookup 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?

The input schema fully describes the only parameter (zip) with format guidance ('5-digit US ZIP code, e.g. 04101'), so schema coverage is 100%. The description only restates 'US ZIP code' without adding additional semantic detail, so the baseline score 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 clearly states a specific verb and resource: 'Representation lookup for a US ZIP code.' It enumerates exactly what is returned (both Senators, House member, statewide executives), which distinguishes this tool from sibling tools like politics_bill or politics_candidates that serve different purposes.

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: use this tool to look up representatives for a US ZIP code. It does not explicitly mention alternatives or when-not-to-use, but the scope is unambiguous and excludes other political lookup scenarios implicitly.

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 provide readOnlyHint and idempotentHint, and the description adds behavioral detail about the return payload: 'returns the best match with a 0-1 confidence score and ranked alternatives.' This is useful context beyond the annotations, though it doesn't cover failure modes or rate limits.

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, front-loaded with purpose and example, then workflow. Every word earns its place; no redundancy or fluff.

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, but the description explains the key return elements (best match, confidence, alternatives) and the follow-up workflow. Given the tool's simplicity and 3 parameters, this is complete for an agent to select and invoke 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?

Schema coverage is 100%, so the baseline is 3. The description reinforces the 'state' parameter's purpose ('Add state to disambiguate') and gives example inputs, but adds minimal new meaning beyond the schema 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 ('Resolve') and resource ('messy name string to a canonical official'), with concrete examples ('Rep. Johnson', 'cornyn'). It clearly distinguishes from sibling tools by framing it as the name-to-ID resolution step, contrasting with subsequent calls to politics_official.

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?

Explicitly states when to use: 'Use this first when you have a name but not an ID; then call politics_official with best.id.' It also provides disambiguation guidance ('Add state to disambiguate'), giving clear context for use versus 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 the tool read-only, idempotent, and non-destructive. The description adds value beyond annotations by disclosing that results include current office, party, and contact info, and by specifying the scope of levels covered. It does not contradict annotations or mention default status/pagination, but those details are available in the schema.

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 composed of three concise sentences, front-loaded with the main action, followed by filter options and return content. Every sentence adds relevant information without redundancy or fluff.

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 absence of an output schema, the description sufficiently explains the return content (current office, party, contact info) and the search scope. It covers the essential context for a search tool, while default status and pagination are appropriately left to the schema. Sibling tools exist but do not reduce completeness here.

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?

All 9 parameters are fully described in the schema (100% coverage), so the baseline is 3. The description enumerates the main filterable fields (name, state, party, level, chamber, office) but adds little beyond what the schema already documents, such as partial-match behavior or default status.

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 for politicians and elected officials across all levels of US government, with a specific verb and resource. It lists key filters and return fields, making the purpose unambiguous. However, it does not explicitly distinguish itself from sibling tools like politics_candidates or politics_by_state, so it falls short of a 5.

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 implies usage as a general search tool by mentioning broad coverage and filterable fields, but it provides no explicit when-to-use or when-not-to-use guidance, nor does it name alternatives. This is implied usage rather than clear contextual guidance.

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, destructiveHint=false, and idempotentHint=true, covering the safety profile. The description adds value beyond this by disclosing that results include verbatim text, an origin proof hash, and a citable GPO URL—useful behavioral details not present in 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 no filler; the first sentence states purpose and filters, the second explains output value. Very efficient and front-loaded.

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 optional parameters but no output schema; the description compensates by summarizing the return type (verbatim text, hash, GPO URL). Combined with strong annotations and full schema coverage, this is sufficient for an agent to invoke correctly, though examples of param combinations would improve completeness.

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%, with each parameter described (e.g., bioguide_id examples, date format). The description's mention of search fields (official, topic, date range, keyword) aligns with the schema but adds no new semantic detail beyond what the schema provides. 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 action ('Search Congressional Record floor speeches') with specific filters (official, topic, date range, keyword), and the resource is distinct from sibling tools like politics_bills_search. It uses a specific verb and names the resource and scope, making it easy to distinguish.

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 for when to use the tool (searching speeches by official, topic, date, or keyword) but does not explicitly mention exclusions or name alternative tools. The lack of a 'use X instead' directive prevents a 5, but the implied usage is clear.

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, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds return field details (bill title, vote result, yes/no counts), but it does not disclose pagination behavior, default limits, authentication needs, or the bill_id filter that appears in the schema. This adds some value but leaves gaps in behavioral transparency.

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 single concise sentence (23 words) that front-loads the main action and scope, followed by filters and return fields. Every word contributes value, with no filler or redundancy.

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 5 optional parameters and no output schema, the description covers the core purpose and return shape, but it omits the bill_id filter from its filter list and does not mention default date ranges or result limits. Given the schema provides parameter details, the description is adequate but not fully comprehensive.

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 has 100% coverage with descriptions for all 5 parameters, so the schema already explains each parameter. The description's mention of filtering by state, topic, or date adds no new semantic meaning and actually omits the bill_id parameter. Since schema coverage is high, the baseline of 3 applies.

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 uses the specific verb 'Search' with the resource 'state legislature votes' and scope 'across 26+ US states,' making the tool's purpose unambiguous. It also lists filters and return fields, which clearly distinguishes it from sibling tools like politics_bills_search and politics_bill that focus on bills rather than votes.

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 conveys a clear use case for searching state legislature votes, but it does not explicitly state when to use this tool over alternatives like politics_bills_search or exclude scenarios. The context is implied rather than directly stated, so it lacks explicit when/when-not guidance.

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 read-only and non-destructive behavior. The description adds value by disclosing the specific breakdowns and the 'coverage completeness' output, which goes beyond what annotations provide. No contradictions found.

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 main action ('Get summary statistics'), and every word adds information. 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?

Given the low complexity (no parameters), rich annotations, and clear output explanation, the description is complete. It tells the agent exactly what to expect from the tool without needing an output schema or further detail.

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 tool has zero parameters, so schema coverage is 100% by default. The description does not need to explain parameters; instead, it describes what the output will contain, which is useful for understanding the tool's behavior.

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 gets summary statistics for the politics.rootz.global database, listing specific breakdowns (level, party, state, chamber) and coverage completeness. This distinguishes it from sibling tools like politics_candidates or politics_official, which handle individual records rather than aggregate stats.

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 usage context is implied: when you need an overview of database contents and coverage, not detailed records. However, it does not explicitly mention when not to use it or name alternative tools, so it falls short of clear usage guidance.

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 readOnly, idempotent, and non-destructive behavior. The description adds context about the output content: every snapshot, every position change, sources with hash proof, and the 'wayback machine' concept. This goes beyond annotations by explaining what the timeline contains and its provenance nature, though it does not address pagination or response size.

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 concise sentences that front-load the core action, add a vivid metaphor, and elaborate on the output. There is no wasted language; each sentence contributes to understanding the tool's purpose and outcome.

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 description explains the tool's value proposition well for a read-only timeline endpoint, covering what the timeline shows and its data sources. However, with no output schema and multiple sibling tools, it could benefit from clarifying how this differs from politics_changes or politics_origin, but overall it is largely 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?

The schema describes 'id' as 'Official ID' and gives 'limit' a default but no description. The description does not explain either parameter explicitly. The phrase 'full origin timeline' might imply limit caps entries, but that is an inference. With 50% schema coverage and no compensating parameter explanation in the description, it adds little 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 clearly states the tool retrieves 'the full origin timeline for a politician' with specific contents: every page snapshot, every position change, and every data source with hash proof. The 'political wayback machine' metaphor reinforces its archival purpose. This distinguishes it from siblings like politics_origin or politics_changes by focusing on the complete timeline with provenance.

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 implies use when needing a historical audit trail of a politician's data with source verification, stating 'Shows what changed, when, and where the data came from.' It provides clear context but does not explicitly exclude alternatives or name when to use sibling tools like politics_changes or politics_provenance, so it scores just below the explicit level.

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