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 safety profile is covered. The description adds meaningful behavior: the row-per-cycle behavior in single mode, the ranking/screening capability in by_entity_type, and a hint about pagination ('you can have more cycles than one page holds'). This goes beyond the annotations to clarify operational traits 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 dense sentences that front-load the core purpose and then unpack the two modes. It conveys a lot of information without redundancy, though the second sentence is long and packs many enumerated values. It is structured and efficient for the complexity involved.

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 high parameter count, the presence of an output schema, and annotations covering read-only/idempotent behavior, the description is nearly complete. It covers mode selection, param applicability, pagination hints, and even cross-references another tool for IDs. Minor gaps like error conditions or rate limits are covered by the output schema and annotations, so nothing critical is missing for correct invocation.

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%, providing a baseline of 3, but the description substantially enhances parameter understanding. It explains mode interplay (which params apply to which mode), the meaning of sort prefixes and cycle semantics, and directs users to another tool for committee IDs. This is far beyond schema descriptions, making parameter usage intuitive even for a 15-parameter interface.

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 a specific verb ('Get') and resource ('pre-aggregated committee financial totals'), enumerating the exact data points (receipts, disbursements, cash on hand, debts, itemized/unitemized breakdown). It clearly distinguishes the two operating modes and implies the tool's niche versus schedule-based pagination, differentiating it from sibling search 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 provides explicit guidance on when to use each mode ('Use mode single... Use mode by_entity_type...') and what each mode accomplishes. It also contrasts with an alternative ('without paginating Schedule A') but does not explicitly state when this tool should NOT be used in favor of a sibling. The mode-specific instructions are clear and actionable.

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 safety profile is covered. The description adds valuable behavioral context beyond that by noting that openfec_search_legal truncates votes and arrays, while this tool returns the record 'untouched' — clarifying what the agent actually receives. 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?

The description is dense but every clause earns its place. It front-loads the purpose, then contrasts with the sibling, then gives parameter mapping details. No redundancy or filler; each sentence conveys necessary information without becoming unwieldy.

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 an output schema present for return format, the description covers everything an agent needs to correctly select and invoke the tool: when to use it, how to map parameters from search results, and what to expect in return. No gaps remain for a caller.

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?

Though the input schema covers 100% of parameters with descriptions, the description adds substantial meaning beyond it: it explains the pluralization rule for doc_type, connects it to the search result's 'document_type' field, and provides concrete examples for the 'no' field across document types (year-serial, digit strings, U.S. Code sections). This elevates parameter understanding well beyond the raw 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 specific verb (fetch) and resource (one FEC legal document in full), and explicitly distinguishes it from the sibling openfec_search_legal, which returns truncated/summarized records. It also enumerates the document types accepted, making 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 explains when to use this tool versus openfec_search_legal: when the full document is needed, contrasting with the search tool's summarization behavior. It also provides explicit mapping instructions for converting the search result's singular 'document_type' to the plural 'doc_type' required here, leaving no inference to the agent.

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, which cover the safety profile. The description adds context about the data scope (events, deadlines, elections) and filtering capability, but does not disclose any additional behavioral traits such as pagination behavior, rate limits, or potential quirks. With annotations covering the core safety, this is adequate but not rich.

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 the resource, the second lists specific use cases. Information is front-loaded, and every word adds value. This is exemplary conciseness for a tool with multiple modes.

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 12 optional parameters, an output schema, and annotations covering safety, the description is largely complete. It names the three main result types (events, filing deadlines, election dates) and the key filtering dimensions (date range, category). It does not explicitly walk through each mode, but the schema covers those details. The only minor gap is not mentioning pagination defaults, but these are in the schema (per_page, page).

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 provides 100% coverage for all 12 parameters, each with descriptive text. The description adds no extra meaning beyond what is in the schema (it mentions date ranges and category, but these are explicitly documented in the schema). Per the baseline for high schema coverage, a 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 states a clear verb-resource combination: 'Look up FEC calendar events, filing deadlines, and election dates.' It lists three distinct resource types and explicitly names the use cases (finding filing windows, locating election dates, and scoping events by date/category). This distinguishes it from sibling tools like openfec_lookup_elections, which is narrower in scope.

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 scenarios where the tool is appropriate ('Use to find upcoming filing windows for a committee, locate when a federal election occurred, or scope FEC events by date range and category'). However, it does not mention when not to use it or point to alternative sibling tools, so it lacks 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 and idempotentHint, lowering the burden on the description. The description adds useful context by distinguishing candidate-level fundraising results from aggregate race summaries, but it does not disclose mode-specific behavioral details such as rejection of election_full in ZIP searches; those are left to 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?

Two sentences with no filler; the first sentence states the purpose and the second expands on the two output modes. Every clause 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?

Given the rich schema with 100% parameter coverage, an output schema, and safety annotations, the description only needs to orient the agent to the tool's purpose and modes. It does that well, though explicit sibling differentiation would make it fully 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%, so the baseline is 3 even without parameter details in the description. The description adds no parameter-level semantics beyond naming the two modes, and the schema already documents ZIP, state, district, and pagination constraints adequately.

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?

States a specific action ('look up') and resource ('federal election races and candidate financial summaries'), then clarifies the two modes: finding candidates with fundraising totals or getting aggregate race summaries. This is clearly distinct from sibling tools focused on candidates, committees, or filings.

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 does not explicitly say when to use this tool versus siblings such as openfec_search_candidates or openfec_get_committee_totals. It implies race-level use but provides no exclusions or alternative routing 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 and idempotentHint, so safety is covered. The description adds behavioral detail: when candidate_id is provided, it returns a single candidate with full detail, and include_totals defaults to true in that case. This goes beyond the annotations and informs the agent about the tool's behavior for different input combinations, which is valuable 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 two sentences with zero unnecessary words. The primary purpose is stated first, followed by a useful technical detail about candidate ID format. It is front-loaded, efficient, and every sentence 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?

The description covers the two main usage modes (search and retrieve by ID) and includes a key format note. With an output schema present, return values need not be explained. It omits detailed filter combinations or pagination behavior, but those are covered by the schema's parameter descriptions. For a search tool with many optional parameters, 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%, so all parameters are already described in the schema. The description reinforces the candidate_id format but does not add new meaning beyond that. Since the schema fully documents parameters, the description's contribution is minimal, warranting the baseline score for high 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 two primary functions: searching federal candidates by various filters (name, state, office, party, cycle) and retrieving a specific candidate by FEC ID with financial totals. It also specifies the ID format, distinguishing candidate IDs from other entity types. This is a specific verb+resource with clear scope.

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 context: it is for finding candidates and for retrieving a single candidate by ID. It does not explicitly compare with sibling tools like openfec_search_committees, but the unique focus on candidates and the distinction between search and ID-based retrieval provide adequate usage guidance. No explicit exclusions or alternatives are mentioned, but the title and description make the tool's purpose 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?

Annotations already declare read-only and idempotent behavior, lowering the bar for the description. The description adds the FEC ID format and the exact-lookup mode, but does not describe pagination behavior, rate limits, or other runtime traits. There is no annotation 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?

Three short sentences, front-loaded with the primary search capability, followed by the exact-lookup mode and the essential ID format. Every sentence contributes information with no 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?

Combined with full parameter documentation, annotations, and an output schema, the description is nearly complete for a read-only search tool. The main remaining gap is lack of explicit routing between this and sibling search tools, though the clear resource naming partially mitigates 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% for all 11 parameters, so the baseline is 3. The description's FEC ID format note is useful but duplicates the committee_id parameter description, and the top-level text adds no new parameter semantics beyond what the schema already documents.

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 identifies the resource ('political committees') and the actions ('Find...', 'Retrieve a specific committee by FEC ID'), with useful category examples. It does not explicitly distinguish itself from sibling search tools such as openfec_search_candidates, though the committee resource and FEC ID format make the target obvious.

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 this tool is for committee lookups by name, type, state, candidate affiliation, or FEC ID, and the candidate_id schema text points to openfec_search_candidates for source IDs. However, the main description never states when to choose this over committee totals, candidate search, or other siblings, nor gives when-not-to-use 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 readOnlyHint=true and idempotentHint=true, so the safety profile is covered. The description adds useful contextual behavior like the committee_id requirement for itemized mode and the candidate_id fallback for some aggregate modes, but it does not go deeper into pagination behavior, cursor constraints, or sorting quirks that are left to 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 two sentences, front-loads the primary function, then adds the use case and the essential mode/ID constraints. Every sentence earns its place with no filler or redundant restatement of the tool name.

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 19 parameters, a rich schema, an output schema, and read-only annotations, the description covers the key selection and invocation context: what the tool returns, who should use it, and the central committee_id/candidate_id distinction. It does not mention by_employer/by_occupation ID requirements explicitly, but the schema fills that gap.

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 itself documents all 19 parameters thoroughly. The description adds one meaningful cross-parameter constraint (itemized requires committee_id; by_size/by_state can use candidate_id), but since candidate_id's schema description already says it "Enables by_size and by_state aggregates without a committee_id," the added semantic value is modest and stays at the 3 baseline.

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 a specific verb and resource: "Search itemized individual contributions (Schedule A) or get aggregate breakdowns by size, state, employer, or occupation." It also names the core question the tool answers, "who is funding this committee?", and clearly distinguishes incoming contributions from sibling outgoing-money tools like search_disbursements and search_expenditures.

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 a clear use case ("who is funding this committee?") and an explicit mode constraint: "Itemized mode requires a committee_id." It also notes that "Aggregate by_size/by_state can use candidate_id instead." However, it does not explicitly name alternatives or state when not to use this tool, such as directing spending-related questions to search_disbursements.

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 safety profile is covered. The description adds domain context (statutory limits, scale) but no extra behavioral detail like pagination or rate limits. Since the bar is lower with annotations, a 3 is appropriate—it contributes some value but not rich behavioral specifics.

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 with zero fat. It front-loads the purpose, then contrasts with siblings, then gives scoping guidance. Every sentence earns its place and the structure is logical.

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 output schema exists and annotations cover safety, the description is complete for an agent to use correctly. It covers what the tool does, how to scope, and when not to use it (independent expenditures). Nothing essential 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 provides 100% coverage with detailed descriptions for all 11 parameters. The description only adds a high-level scoping hint ('Scope with a spending committee_id, a benefiting candidate_id, or a cycle'), which minimally supplements the schema. Baseline 3 is correct.

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 identifies the tool as searching coordinated party expenditures (Schedule F), with a precise verb and resource. It explicitly differentiates from the sibling openfec_search_expenditures (independent expenditures) and direct contributions, making its 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?

It names the alternative tool (openfec_search_expenditures) and the condition that distinguishes them (coordination vs. not). It also provides scoping guidance (committee_id, candidate_id, or cycle) and notes the default behavior of unscoped queries spanning all years.

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 safety profile is covered. The description itself mainly restates the capability (itemized vs. aggregates) without adding behavioral details like pagination edge cases or the cycle default, which are already thoroughly documented in the schema. Since the schema carries the behavioral burden, the description adds minimal extra value, keeping it at a 3.

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 redundancy. It front-loads the primary function (Search itemized committee spending or get aggregates) and immediately follows with example use cases. Every word adds value, and the structure makes it easy to parse quickly. This is exemplary conciseness.

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 (17 params, output schema, full schema descriptions, and annotations), the description covers the essential context: what it searches, the modes, and the required parameter. It doesn't need to explain return values (output schema exists) or reiterate safety (annotations cover). The main gap is that it doesn't hint at the pagination quirks, but those are in the schema, so the description is sufficiently complete for an agent to call it 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 description coverage is 100%, so every parameter is already explained in the schema. The description does not add parameter-level semantics; it only mentions that committee_id is required and lists the modes, which are already in the schema. With full coverage, the baseline of 3 is appropriate—the description contributes no additional parameter insight.

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: searching committee spending (Schedule B) with itemized or aggregate modes. It names the specific resource (Schedule B) and gives concrete question examples ('what is this committee spending money on?', 'who is receiving payments?'). This distinguishes it from sibling tools like search_contributions or search_expenditures, making the agent's choice 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 specifies when to use the tool: to answer spending-related questions about a committee. It also notes the prerequisite ('All modes require a committee_id'). While it doesn't explicitly state when NOT to use it or compare to alternatives, the provided example questions and resource scoping give clear usage context. The absence of exclusion criteria keeps this at a 4 rather than a 5.

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?

With annotations already declaring readOnlyHint and idempotentHint, the description's job is lighter, yet it adds substantial behavioral context: pagination differences (keyset vs page-based), rejection of certain parameters in by_candidate mode, the sorting quirk with negative amounts, the default-cycle behavior, and the explicit timeout risk for unscoped scans. This goes well beyond the structured fields and contains no contradictions.

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 a concise purpose statement, then delivers all critical usage details in a dense but organized paragraph. Every sentence earns its place—mode requirements, pagination, sorting, cycle defaults, and timeout warnings are all included without redundancy. It is long but information-dense, with 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 20-parameter tool with two modes and many constraints, this description is remarkably complete. It covers mode selection, required vs optional parameters, pagination behavior, sorting, cycle handling, and even failure modes (timeouts, rejections). With an output schema present, no return-value explanation is needed. An agent has everything required to call this 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?

Even though schema description coverage is 100%, the tool description adds significant meaning: it explains that by_candidate requires candidate_id or full race scope, that cursor is only valid for identical calls, that most_recent only applies to itemized, and that certain parameters are rejected in by_candidate. It also clarifies sorting semantics with a concrete example (ascending leads with negative rows). This is far more than the schema 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 opens with a specific verb and resource: 'Search independent expenditures (Schedule E) — outside spending supporting or opposing federal candidates.' It clearly distinguishes from siblings like coordinated expenditures by naming the filing type, and explains the two modes (itemized vs by_candidate) and their use cases. The purpose is unambiguous and does not rely on the tool name.

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, including the parameter requirements for by_candidate (candidate_id or full race scope) and the default-cycle behavior to avoid upstream timeouts. It does not explicitly name alternatives among sibling tools, but the resource (Schedule E) is specific enough that an agent can infer when this tool is appropriate. A clear 'use this for independent expenditures, not coordinated' would push it to 5.

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 safety profile is covered. The description adds no additional behavioral context (e.g., rate limits, response structure, or side effects), but it also does not contradict the annotations. Given the high annotation coverage, a 3 is appropriate.

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 lists relevant form types, all in a compact structure that is easy for an agent 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 (13 optional parameters, rich schema, and an output schema), the description fully conveys the core purpose and scope. It mentions the key filter dimensions and example form types, while the schema and output schema handle the remaining details. Nothing essential 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?

Schema description coverage is 100%, so every parameter has a description. The tool description broadly mentions filters but adds no extra detail beyond what the schema provides (e.g., specific examples or relationships). The description is largely redundant with the schema, so 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 identifies a specific verb ('Search') and resource ('FEC filings and reports') with explicit filter dimensions (committee, candidate, form type, date range). It also lists concrete form types, distinguishing it from sibling tools that target other 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 for filings and reports but provides no explicit guidance on when to use this tool versus alternatives like openfec_search_contributions or openfec_search_expenditures. The purpose is clear enough to infer, but no when-not or alternative selection is stated.

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 declare readOnlyHint=true and idempotentHint=true, so the safety profile is covered, but the description adds zero behavioral context on top of that. It discloses nothing about pagination defaults, type-specific filter behavior (e.g. penalty params filtering only enforcement cases), or conditional parameter relationships. The description neither contradicts nor meaningfully extends 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?

A single sentence, front-loaded with the verb and resource, then a colon-separated list of document types—zero wasted words. The structure is efficient, though the brevity trades away the behavioral and usage guidance that a 14-parameter tool would benefit from; it is concise rather than merely under-specified.

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?

This is a high-complexity tool—14 parameters, no required fields, conditional requirements (min_date/max_date require both type and date_kind), and type-specific behaviors (statutes cannot be date-filtered; penalty amounts only filter murs/adrs). The description omits all of this. The rich schema compensates substantially and an output schema exists, but for a tool this complex the one-line description does not adequately preview the conditional logic an agent must navigate.

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 per-parameter notes (notably the date_kind enum's per-type documentation and the conditional 'admin_fines is slow' caveat), so the baseline of 3 applies. The description itself adds no parameter-level meaning, but the schema fully compensates, so no penalty is warranted.

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 ('Search') and resource ('FEC legal documents') and enumerates the document categories (advisory opinions, MURs, ADRs, administrative fines), clearly delimiting its scope. This separates it cleanly from the sibling search tools (candidates, committees, contributions, expenditures, filings), which operate on entirely different content domains.

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 document-type list implies when to use this tool (for legal/advisory/enforcement documents) versus the candidate/committee/expenditure search siblings, but there is no explicit when/when-not guidance or named alternatives. Some operational guidance exists in the schema (e.g. 'admin_fines is slow without a query or respondent filter'), but the description itself carries none of it.

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