openfec-mcp-server

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the agent knows this is a safe, repeatable read operation. The description adds no behavioral traits beyond this, such as rate limits, authentication needs, or pagination behavior. With annotations covering the core safety profile, a baseline 3 is appropriate as the description doesn't contradict annotations but adds minimal extra context.

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, efficient sentence: 'Look up FEC calendar events, filing deadlines, and election dates.' It's front-loaded with the core purpose, has zero wasted words, and appropriately sized for the tool's complexity.

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 (12 parameters) and rich annotations (readOnlyHint, idempotentHint) plus 100% schema coverage and an output schema, the description is reasonably complete. It states the purpose clearly but lacks guidance on usage versus siblings. With structured data handling most details, the description's gaps are minor, making it nearly 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 description coverage is 100%, with detailed parameter documentation in the input schema. The description mentions 'events, filing deadlines, and election dates' which aligns with the 'mode' parameter but adds no additional semantic context beyond what the schema provides. Given high schema coverage, the baseline score of 3 is justified.

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: 'Look up FEC calendar events, filing deadlines, and election dates.' It uses specific verbs ('look up') and identifies the resource (FEC calendar data). However, it doesn't explicitly differentiate from sibling tools like 'openfec_lookup_elections' which might overlap with election-related data, keeping it from a perfect score.

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. It doesn't mention sibling tools or clarify if this is the primary tool for calendar data versus other lookup/search tools. Usage is implied by the description but not explicitly stated, leaving gaps for an AI agent to determine context.

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 agent knows this is a safe, repeatable read operation. The description adds useful context about what data is returned (financial summaries, fundraising totals, aggregate race summaries) but doesn't disclose rate limits, authentication requirements, or specific behavioral traits beyond what annotations provide. No contradiction with annotations exists.

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 perfectly concise with two sentences that each earn their place. The first sentence establishes the core purpose, and the second provides concrete use cases. No wasted words, and the most important information is 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?

Given the tool has comprehensive annotations (readOnlyHint, idempotentHint), 100% schema description coverage, and an output schema exists, the description provides complete enough context. It clearly explains what the tool does and the two main use cases, which complements the structured data well without needing to explain return values or parameter 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?

With 100% schema description coverage, the input schema already documents all 7 parameters thoroughly. The description mentions the two modes (search and summary) which aligns with the mode parameter's enum values, but doesn't add significant semantic meaning beyond what the schema provides. The baseline of 3 is appropriate when the schema does the heavy lifting.

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 specific action ('Look up federal election races and candidate financial summaries') and distinguishes this tool from siblings by focusing on election races rather than candidates, committees, contributions, or other entities. It provides two concrete use cases: finding who's running with fundraising totals or getting aggregate race summaries.

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 about when to use this tool ('Find who's running in a race with fundraising totals, or get an aggregate race summary'), but doesn't explicitly mention when not to use it or name specific alternatives among the sibling tools. The input schema's mode parameter description helps differentiate between search and summary modes, but the tool description itself lacks explicit sibling comparison.

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, indicating safe, repeatable operations. The description adds valuable context beyond annotations: it specifies that candidate IDs start with H, S, or P followed by digits, and notes that financial totals are included when fetching by candidate_id. This enhances understanding without contradicting annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with the core purpose in the first sentence, followed by specific details in the second. Both sentences are essential, providing clear value without redundancy. It efficiently conveys key information in a compact format.

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 (14 parameters, 100% schema coverage, annotations, and an output schema), the description is complete enough. It covers the tool's purpose, key behavioral details (like candidate ID format and financial totals), and relies on structured fields for parameter and output documentation, avoiding unnecessary repetition.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema fully documents all 14 parameters. The description adds minimal semantic context, such as the structure of candidate IDs and the inclusion of financial totals with candidate_id, but does not significantly enhance parameter understanding beyond what the schema provides. Baseline 3 is appropriate given high schema 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 the tool's purpose with specific verbs ('Find', 'Retrieve') and resources ('federal candidates'), and distinguishes it from siblings by focusing on candidate search rather than committees, contributions, or other entities. It explicitly mentions retrieving by FEC ID with financial totals, which differentiates it from general search operations.

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 examples (e.g., 'by name, state, office, party, or cycle') but does not explicitly state when to use this tool versus alternatives like openfec_lookup_elections or openfec_search_committees. It provides context for filtering but lacks explicit guidance on tool selection among siblings.

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, indicating safe, repeatable operations. The description adds valuable context beyond this: it specifies that committee IDs start with 'C' followed by digits (e.g., C00358796), which aids in correct usage. However, it does not mention behavioral details like pagination defaults or rate limits, leaving some gaps.

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 front-loaded with the core purpose in the first sentence, followed by specific details in the second. Both sentences are essential, with zero waste or redundancy, making it highly efficient and well-structured.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (11 parameters) and the presence of rich annotations (readOnlyHint, idempotentHint) and an output schema, the description is complete enough. It covers the purpose, usage context, and key behavioral details (committee ID format), without needing to explain return values or repeat schema information.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema fully documents all 11 parameters. The description adds minimal parameter semantics beyond the schema, only noting the format for committee_id (starts with 'C' followed by digits). This meets the baseline of 3, as the schema does the heavy lifting, but the description provides limited extra value.

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 verb ('Find', 'Retrieve') and resource ('political committees') with specific examples of committee types (campaign, PAC, Super PAC, party). It distinguishes this tool from siblings by focusing on committees rather than candidates, contributions, or other entities, making the purpose highly specific and differentiated.

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: to search committees by various criteria (name, type, candidate affiliation, state) or retrieve a specific one by FEC ID. However, it does not explicitly mention when not to use it or name alternatives among sibling tools (e.g., openfec_search_candidates for candidate-related searches), which prevents a perfect score.

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 adds valuable behavioral context beyond the annotations. While annotations indicate read-only and idempotent operations, the description reveals that itemized mode uses keyset pagination, different modes have different parameter requirements, and there are specific ID requirements for different query types. This provides practical implementation guidance 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 efficiently structured in two sentences that directly address purpose and usage. The first sentence establishes the dual functionality, and the second provides critical implementation guidance. Every word serves a clear purpose 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?

Given the presence of comprehensive annotations (readOnlyHint, idempotentHint), 100% schema description coverage, and an output schema, the description provides exactly what's needed. It explains the tool's purpose, when to use it, and key behavioral considerations without duplicating information available in structured fields.

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?

With 100% schema description coverage, the input schema already thoroughly documents all 18 parameters. The description adds minimal parameter-specific information beyond the schema, mainly noting that committee_id is required for itemized mode and candidate_id can be used for some aggregate modes. This meets the baseline expectation when schema coverage is complete.

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 itemized individual contributions (Schedule A) or gets aggregate breakdowns by specific categories. It specifies the resource (contributions) and distinguishes from siblings by focusing on funding analysis rather than other FEC data types like candidates or committees.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly states when to use this tool ('to answer "who is funding this committee?"') and provides clear guidance on parameter requirements for different modes (itemized mode requires committee_id, aggregate modes can use candidate_id). It distinguishes usage scenarios based on the mode parameter.

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 adds valuable behavioral context beyond the annotations. While annotations already declare readOnlyHint=true and idempotentHint=true, the description clarifies the tool's dual functionality (itemized vs. aggregate modes) and provides real-world use cases. It doesn't contradict annotations and adds meaningful operational context about what types of questions the tool can answer.

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 perfectly concise with two focused sentences. The first sentence establishes core functionality, the second provides usage examples. Every word earns its place with zero redundancy or wasted text. It's front-loaded with the essential information about what the tool does.

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 comprehensive annotations (readOnlyHint, idempotentHint), 100% schema description coverage, and presence of an output schema, the description provides exactly what's needed. It explains the tool's purpose, when to use it, and provides concrete examples without duplicating information available elsewhere in the structured data. The description is complete for this well-documented 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?

With 100% schema description coverage, the schema already documents all 16 parameters thoroughly. The description doesn't add specific parameter semantics beyond what's in the schema, but it does provide high-level context about the different modes (itemized vs. aggregate) which helps understand parameter applicability. This meets the baseline expectation for high schema 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 the tool's purpose with specific verbs ('search itemized committee spending' and 'get aggregate breakdowns') and identifies the resource ('Schedule B disbursements'). It distinguishes this tool from siblings by focusing specifically on committee spending rather than contributions, elections, filings, or other FEC data types.

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 explicit usage guidance with concrete examples ('answer "what is this committee spending money on?" or "who is receiving payments from this committee?"'). It specifies the mandatory requirement ('All modes require a committee_id') and implicitly distinguishes from siblings by focusing on disbursements rather than contributions, expenditures, or other data types.

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, covering safety and repeatability. The description adds valuable behavioral context by explaining what the two modes return (individual records vs. aggregated totals) and mentioning pagination approaches (keyset vs. page-based). However, it doesn't mention rate limits, authentication requirements, or data freshness constraints that might be relevant for this API.

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 perfectly structured in two sentences: the first establishes purpose and domain context, the second provides crucial usage guidance. Every word earns its place, with zero redundancy or filler content. It's front-loaded with the most important information about what the tool does.

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 comprehensive annotations (readOnly, idempotent), 100% schema coverage, and existence of an output schema, the description provides exactly what's needed. It explains the tool's purpose, distinguishes it from siblings, and clarifies the critical mode selection decision. The description doesn't need to explain return values or parameter details since those are covered elsewhere.

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?

With 100% schema description coverage, the schema already documents all 18 parameters thoroughly. The description adds minimal parameter semantics beyond the schema - it only clarifies the purpose of the 'mode' parameter. While this is helpful context, it doesn't significantly enhance understanding of other parameters like date ranges, amounts, or filtering options.

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 specific action ('Search independent expenditures'), identifies the resource ('Schedule E'), and provides domain context ('outside spending supporting or opposing federal candidates'). It explicitly distinguishes this tool from siblings by focusing on expenditures rather than candidates, committees, contributions, or other FEC data types.

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 explicit guidance on when to use each mode: 'Use itemized mode for individual expenditure records, or by_candidate for aggregated totals per candidate.' This gives clear alternatives within the tool itself, helping the agent choose between detailed records vs. aggregated summaries based on the user's need.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the agent knows this is a safe, repeatable read operation. The description adds valuable behavioral context beyond annotations by specifying the scope of coverage (financial reports, statements of candidacy, organizational filings, etc.) and mentioning amendments. However, it doesn't describe pagination behavior or rate limits, which would be helpful additional context.

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 efficiently structured in two sentences: the first states the core purpose and searchable fields, and the second provides specific examples of form types covered. Every word contributes to understanding the tool's scope without redundancy or fluff, making it easy to parse quickly.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (13 parameters) and the presence of both rich annotations (readOnlyHint, idempotentHint) and an output schema, the description is reasonably complete. It clearly defines the search scope and form types, which helps the agent understand what data is accessible. However, it could benefit from mentioning pagination behavior or typical use cases to fully guide the agent in a complex search scenario.

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 all 13 parameters thoroughly documented in the schema itself. The description adds minimal parameter semantics beyond the schema—it mentions searching by committee, candidate, form type, or date range, which aligns with parameters like committee_id, candidate_id, form_type, and date parameters, but doesn't provide additional syntax or format details. This meets the baseline expectation when schema coverage is high.

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 specific verb ('Search') and resource ('FEC filings and reports'), and distinguishes this tool from siblings by specifying the exact scope of what it searches (committee, candidate, form type, date range) and listing specific form types covered. This makes it immediately clear this is a search tool for filings, not for candidates, committees, contributions, or other entities.

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 context by listing what can be searched (committee, candidate, form type, date range) and providing examples of form types, but it doesn't explicitly state when to use this tool versus alternatives like openfec_search_candidates or openfec_search_committees. There's no guidance on prerequisites or exclusions, leaving the agent to infer appropriate usage from the parameter descriptions.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the agent knows this is a safe, repeatable read operation. The description adds valuable context about the specific document types being searched, which goes beyond what annotations provide. However, it doesn't mention performance characteristics (like the schema note about admin_fines being slow) or result format expectations.

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, efficient sentence that front-loads the core purpose. Every word earns its place by specifying the resource and providing concrete examples of document types. There's zero wasted text 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?

Given the tool has comprehensive annotations (readOnlyHint, idempotentHint), 100% schema description coverage, and an output schema exists, the description provides adequate context. It clearly states what the tool searches for, though it could benefit from mentioning the search scope or result format. The combination of structured data and description is mostly complete for this search 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?

With 100% schema description coverage, all 13 parameters are well-documented in the schema itself. The description doesn't add any parameter-specific information beyond what's already in the schema descriptions. The baseline of 3 is appropriate when the schema does the heavy lifting of parameter documentation.

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 verb ('Search') and resource ('FEC legal documents') with specific examples of document types (advisory opinions, enforcement cases, etc.). It distinguishes itself from sibling tools like openfec_search_candidates or openfec_search_committees by focusing exclusively on legal documents rather than other FEC data types.

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 context by listing the document types, but doesn't explicitly state when to use this tool versus alternatives. There's no guidance on prerequisites, performance considerations, or comparisons with other search tools. The context is clear but lacks explicit when/when-not instructions.

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