openfec-mcp-server

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

Annotations already declare readOnlyHint and idempotentHint, so the description's lack of additional behavioral disclosure is partially acceptable. However, the description does not mention pagination behavior, result limits, or the fact that the tool returns a list of events (though output schema exists). It adds value by explaining modes but misses other runtime behaviors.

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 with no filler. The first sentence defines the purpose, the second provides use cases. Information is front-loaded and every word 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?

The description covers the main purpose and common uses, and the output schema exists so return value explanation is not needed. However, it does not explain the 'mode' parameter's central role in filtering, nor mention pagination or sorting. Slight gaps for a complex tool with 12 parameters.

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?

Input schema coverage is 100% with detailed descriptions for all 12 parameters (including enums and defaults). The description does not add meaning beyond the schema; it only provides high-level usage context. Baseline score of 3 is appropriate for complete 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 verb 'look up' and specific resources: FEC calendar events, filing deadlines, and election dates. It provides concrete use cases like 'find upcoming filing windows' and 'locate when a federal election occurred', distinguishing the tool from siblings like openfec_lookup_elections which likely focuses on election-specific lookups.

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

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

The description gives clear usage scenarios (e.g., 'find upcoming filing windows', 'scope ... by date range and category') but does not explicitly state when to avoid this tool or suggest alternatives. The sibling tool list exists but is not referenced in the description, so the agent must infer differentiation from names.

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 idempotency. The description adds value by explaining the two modes (search vs summary), but other behavioral traits like rate limits or pagination are not mentioned. The description does not contradict 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 with no fluff. The first sentence states the core purpose, and the second elaborates on the two modes. Every word contributes meaning.

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 7 parameters, two modes, and an output schema, the description covers the high-level functionality and modes. Some details (e.g., required parameters for non-ZIP searches) are omitted, but the schema covers them. The description is sufficient for an agent to decide if the tool fits the task.

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 comprehensive parameter descriptions. The description adds value by grouping parameters into functional modes (search vs summary) and explaining their purpose in plain language, which goes beyond the schema's individual 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 looks up federal election races and candidate financial summaries, specifying two modes (candidate search with totals or aggregate summary). This verb+resource combination is specific and distinguishes it from sibling tools like openfec_search_candidates which focus on individuals rather than races.

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 explains the two usage modes (search vs summary) and implies the tool is for election race information, not calendar or individual searches. However, it does not explicitly exclude scenarios or compare with siblings, though the differentiation is clear from 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?

Annotations confirm read-only and idempotent behavior. Description adds that providing 'candidate_id' returns a single candidate with full detail and that 'include_totals' defaults to true in that case. This adds behavioral context beyond 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, no unnecessary words. Every sentence provides essential 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?

Given the complexity (14 parameters, many optional) and the presence of an output schema, the description covers the main use cases (search and specific fetch) and key conventions (ID format, totals default). It does not explain pagination, but the output schema likely 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?

All 14 parameters have descriptions in the schema (100% coverage). Description adds value by explaining the candidate ID format and clarifying that 'include_totals' defaults to true when fetching by 'candidate_id', which goes 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?

Description clearly states the tool's purpose: 'Find federal candidates by name, state, office, party, or cycle' and 'Retrieve a specific candidate by FEC ID with financial totals.' It also explains the ID format (H, S, P), distinguishing it from sibling tools that search committees, contributions, etc.

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

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

Provides clear guidance on when to use the tool: for searching candidates with various filters or retrieving a specific candidate by ID. It implies when not to use (e.g., for committees) but does not explicitly mention alternative sibling 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 and idempotentHint, so the description carries a lower burden. It adds context about committee ID format (starts with C followed by digits), but does not disclose additional behavioral traits such as pagination limits or rate limits, which are partially covered by the schema's parameter descriptions.

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-loading the primary function and then specifying the ID retrieval use case. Every sentence adds value with no 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?

Given the 11 parameters, all with schema descriptions, and the existence of an output schema, the description covers the main use cases adequately. It does not discuss pagination behavior explicitly, but the schema parameters for page and per_page are present. The description is complete enough for a 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?

Schema coverage is 100%, so baseline is 3. The description adds some summarization of search capabilities but does not provide new meaning beyond the already detailed schema property descriptions. It reinforces the ID format, but this adds minimal incremental 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 tool finds political committees by various criteria and can retrieve a specific committee by FEC ID. It uses specific verbs like 'Find' and 'Retrieve' and names the resource (political committees), effectively distinguishing it from sibling search tools for candidates, contributions, etc.

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 intent on when to use the tool (search by name, type, candidate, state, or retrieve by ID), but does not explicitly state when not to use it or mention alternative tools. However, the context signals show distinct sibling tools, so the purpose is sufficiently differentiated.

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 value by explaining the keyset pagination in itemized mode, sort options, and the deafult cycle behavior. No contradiction with annotations. It could mention rate limits or other traits but is otherwise solid.

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-loading purpose and key constraints. Every phrase is necessary, no fluff. It efficiently communicates the core function and mode-specific requirements.

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 18 parameters, 100% schema coverage, existing output schema, and annotations, the description sufficiently covers behavioral aspects like pagination, mode differences, and ID dependencies. An AI agent can confidently invoke the tool based on this 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 coverage is 100%, so baseline is 3. The description adds some value by grouping parameters by mode (e.g., 'Itemized only') and providing cross-reference hints like 'Get IDs from openfec_search_candidates results'. However, it does not add significant syntax or format details beyond what the schema already provides.

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 it searches itemized individual contributions (Schedule A) or gets aggregate breakdowns by size, state, employer, or occupation. It includes the specific use-case question 'who is funding this committee?' and distinguishes from sibling tools like openfec_search_committees by focusing on contributions.

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 when-to-use guidance for different modes: itemized mode requires a committee_id, while by_size/by_state can use candidate_id. It implies alternatives by referencing other tools for candidate/committee IDs. However, it does not explicitly state when not to use this tool or provide exclusions.

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

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

Annotations already declare readOnlyHint and idempotentHint, so the agent knows the tool is safe and idempotent. The description does not add extra behavioral details such as rate limits, data freshness, or pagination behavior beyond what is in the parameter schema. It does not contradict 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 concise sentences: first states core function and modes, second gives usage guidance. No fluff, 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 (5 modes, 16 params, output schema exists), the description covers core purpose and usage context. It does not explain each mode's output or pagination but relies on schema and output schema; almost 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%, so the baseline is 3. The description adds high-level context (e.g., 'itemized' vs 'aggregate') but does not explain each parameter beyond what the schema provides. No additional semantic 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 tool searches itemized committee spending (Schedule B) and provides aggregate breakdowns by purpose or recipient. It specifies the required committee_id and gives example queries that differentiate it from sibling tools like search_contributions or search_expenditures, although not explicitly contrasted.

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 mentions all modes require a committee_id and gives two example use cases. However, it does not explicitly state when not to use this tool (e.g., for contributions) or mention alternatives among sibling tools; the context is clear but lacks explicit exclusions.

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

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

Description aligns with annotations (readOnlyHint, idempotentHint) by stating 'Search'. It adds limited behavioral context beyond annotations, such as covering outside spending. With annotations covering safety, this score reflects adequate but not enhanced 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?

Two efficiently written sentences. First sentence defines purpose and coverage; second sentence gives usage guidance. No superfluous words. Front-loaded with the most important 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?

Given 18 parameters with excellent schema descriptions, existing output schema, and annotations covering safety, the description provides sufficient high-level context (modes, coverage, entity types). It does not need to explain returns or paging details. Slight gap: no mention of read-only nature, but annotations fill this.

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 baseline is 3. The description does not add parameter-level details beyond the schema; it only gives high-level purpose. No extra value is provided for individual parameters.

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?

Description clearly states 'Search independent expenditures' and specifies it covers 'outside spending supporting or opposing federal candidates'. It distinguishes between two modes (itemized, by_candidate) and differentiates from sibling tools like contributions and disbursements by focusing on independent expenditures and Schedule E.

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?

Description tells when to use each mode ('Use itemized mode for individual expenditure records, or by_candidate for aggregated totals per candidate') and covers the target entities (Super PACs, party committees). It does not explicitly exclude alternatives or provide when-not-to-use guidance, but the context 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 indicate read-only and idempotent behavior. The description does not add additional behavioral context such as pagination limits or data freshness, but does not contradict 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 resource, and contains no unnecessary 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?

The description covers the main search dimensions and lists common form types. An output schema exists, so return values are handled. Minor omission: no mention of sorting or default ordering, but adequate for a 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?

The input schema has 100% description coverage for all parameters. The description provides general context and examples of form types but does not add meaning beyond the schema's parameter 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 searches FEC filings and reports, and lists specific form types (F3, F3P, etc.), distinguishing it from sibling tools that search other entities 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 implies usage for filings by committee, candidate, form type, or date range. It does not explicitly exclude other scenarios, but the sibling tool names make the differentiation 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 and idempotentHint true, so the description adds no further behavioral info. No mention of rate limits, pagination behavior, or other traits 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 a single concise sentence (13 words) with no wasted words, and it front-loads the core purpose.

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?

Despite having 13 optional parameters and an output schema, the description does not provide guidance on typical usage patterns (e.g., minimum filters). It is adequate but lacks completeness for a moderately complex 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?

Schema description coverage is 100%, so the description adds minimal value beyond what the schema already provides for parameters. 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 searches FEC legal documents and lists the specific types (advisory opinions, MURs, ADRs, admin fines), distinguishing it from sibling tools that search other entities 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 implies usage for legal documents but does not explicitly state when to use this tool versus alternatives like openfec_search_candidates. The sibling context makes it clear, but no explicit 'when-to-use' guidance is provided.

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