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 safety profile is covered. The description adds meaningful behavioral context: results are 'pre-aggregated,' return 'one row per two-year cycle,' and the by_entity_type mode supports 'rank or screen' across committees. This goes beyond the annotations 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 exactly two sentences, front-loaded with the core purpose. The first sentence states the resource and content; the second explains the two modes. Every clause adds distinct information — there is zero fluff or repetition of schema/annotation data.

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 15 parameters and complex dual modes, the description covers the key distinctions (single vs. by_entity_type), the per-cycle output shape, and the entity types (presidential, pac, party, etc.). Since an output schema exists and annotations cover safety, the description is fully adequate for an agent to select and invoke the tool correctly.

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

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

Schema coverage is 100% — all 15 parameters have detailed descriptions in the input schema. The description itself only clarifies the mode-dependent roles of committee_id and entity_type, which adds marginal value over the schema. Per the baseline rule for high 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 opens with a specific verb+resource: 'Get pre-aggregated committee financial totals' and enumerates the exact metrics (receipts, disbursements, cash on hand, debts, itemized/unitemized breakdown). It distinguishes itself from sibling tools like openfec_search_contributions by explicitly stating 'without paginating Schedule A' and describes the two modes (single and by_entity_type) that uniquely define this tool.

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 mode-based guidance: 'Use mode "single" ... with a committee_id for one committee's totals' and 'Use mode "by_entity_type" to rank or screen every committee of one type.' It also implies when not to use the tool ('without paginating Schedule A'), suggesting itemized data is better fetched elsewhere, though it doesn't name the alternative sibling tool explicitly.

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, and the description consistently describes a read-only fetch. It adds behavioral context by stating the record is returned 'untouched,' a useful guarantee beyond the annotations. It also clarifies the transformation from document_type to doc_type and the ao_no repetition, which are important behavioral quirks.

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 appropriately sized: a front-loaded core action, followed by a sibling contrast, then shorthand rules for parameter derivation. Every sentence earns its place with concrete examples and no filler. It is dense yet readable.

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 two required parameters, both well-documented, an output schema present, and annotations for safety, the description adds the missing context: how to derive inputs from a search result and what fidelity to expect. It fully equips the agent to invoke the tool correctly.

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

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

Although the schema already has descriptive parameter comments, the description adds meaning by explaining that doc_type is the plural form of the search result's document_type and that no is copied from the result's no field. This provenance guidance is essential for correctly constructing calls and goes beyond what 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 'Fetch one FEC legal document in full — advisory opinion, MUR, ADR, administrative fine, or statute — by its type and number,' clearly stating the verb, resource, and scope. It also distinguishes from the sibling tool openfec_search_legal by explaining the difference in returned data (summary vs. untouched record), making it easy to select the right tool.

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 contrasts with openfec_search_legal, noting that the search tool replaces documents with summaries and truncates votes, while this tool returns the record untouched. This tells the agent exactly when to use this tool (when full documents are needed) and provides an alternative. It also gives precise mapping instructions for doc_type and no from search results.

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 and idempotentHint, establishing the safe, read-only behavior. The description adds no new behavioral traits beyond repeating filterable dimensions (date range, category) already present in the schema. It doesn't 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, front-loaded with the action and resource, and every word contributes value. The second sentence provides practical use cases without padding.

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 and 100% parameter coverage, the description needn't restate return values or parameter syntax. It gives enough selection context to distinguish from search tools, though it could mention mode interactions or explicit alternatives for even fuller guidance.

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

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

Schema description coverage is 100%, so all 12 parameters are already documented with descriptions and enums. The description loosely references 'date range and category' and the three event types, but it adds no real semantic detail beyond what the schema provides. Baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses the specific verb 'Look up' and names the resource 'FEC calendar events, filing deadlines, and election dates,' clearly distinguishing it from sibling search_* tools. It also adds concrete application examples ('find upcoming filing windows for a committee'), reinforcing its 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 explicit scenarios for when to use the tool: 'find upcoming filing windows for a committee, locate when a federal election occurred, or scope FEC events by date range and category.' However, it doesn't name alternative tools or explicitly say when not to use it, so it lacks exclusion 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 readOnlyHint=true and idempotentHint=true already communicate the safety profile. The description adds that the tool returns 'financial summaries' and 'aggregate race summary', providing some output context. However, it does not disclose any additional behavioral traits such as pagination behavior or parameter restrictions beyond what the schema already states.

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 concise sentences. It front-loads the core purpose and immediately follows with the two primary use cases. Every word contributes, with no repetition or fluff.

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

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

Given a rich schema (including conditional requirements like state/district for House/Senate) and an output schema, the description is largely complete. It effectively covers the main purpose and result types. A minor gap is the lack of explicit mention of required parameters (office, cycle), but these are clearly listed in the schema, so the description remains sufficient.

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

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

Schema description coverage is 100%, with detailed parameter descriptions for each of the 9 parameters. The tool description adds no extra parameter semantics beyond what the schema provides. Baseline 3 is appropriate since the schema carries the burden.

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: 'Look up federal election races and candidate financial summaries.' It distinguishes between two modes: finding candidates with fundraising totals or getting an aggregate race summary. This specificity differentiates it from sibling tools like openfec_search_candidates, which searches candidates without race context.

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 when to use the tool: to look up federal election races and financial summaries. However, it does not explicitly mention alternatives or exclusion criteria (e.g., 'use search_candidates for individual candidate details'). The two modes (search vs summary) are implicit but not formally contrasted.

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 adds value by explaining the candidate ID format and that candidate_id returns a single candidate with financial totals. It also discloses the difference between search results and full detail, which annotations cannot convey.

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

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

Two sentences, front-loaded with the primary search capability. No filler; every sentence provides useful information about functionality or ID 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?

The description covers core search and lookup behaviors, while the schema provides comprehensive parameter details and an output schema exists. It does not mention pagination or edge cases, but the annotations and schema fill the gaps. Overall, sufficient for the tool's complexity.

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

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

With 100% schema description coverage, the baseline is 3. The description adds meaning beyond the schema by noting that candidate_id returns full detail and explaining the ID prefix format, which aids parameter selection. This exceeds 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 clearly states the tool's function: 'Find federal candidates by name, state, office, party, or cycle' and 'Retrieve a specific candidate by FEC ID with financial totals.' The verbs 'Find' and 'Retrieve' are specific, and the candidate ID format ('H', 'S', 'P') distinguishes it from sibling tools like openfec_search_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 candidate searches but does not explicitly state when to use it over alternatives like openfec_search_committees or when not to use it. It provides context about parameters but lacks explicit exclusion or alternative guidance.

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

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

Annotations already declare read-only and idempotent, so the bar is lower. The description adds the committee ID format rule and notes that specific ID retrieval returns full detail, which is useful. However, it does not disclose other behavioral traits like pagination behavior, rate limits, or error conditions beyond what annotations provide.

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

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

The description is two sentences, front-loaded with the primary purpose, and every word contributes meaning. It avoids redundancy and fluff while covering the essential scope.

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-parameter schema with full descriptions and an output schema, the high-level description is sufficient to understand the tool's purpose and key special cases. It could explicitly mention pagination or the breadth of filters, but the schema fills those details, making the description appropriately 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 baseline is 3. The description adds conceptual grouping of filters (name, type, candidate affiliation, state) and clarifies the committee ID format, which provides meaning beyond individual schema descriptions. This modest additional value warrants a 4.

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 clear verb 'Find' and names the specific resource 'political committees', then enumerates search dimensions (name, type, candidate affiliation, state) and a special case for FEC ID lookup. This clearly distinguishes it from sibling search tools focused on candidates or 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 operational context by specifying what the tool can do (search by attributes, exact ID lookup), but it does not explicitly state when to prefer this tool over alternatives or mention exclusions. It offers useful guidance but lacks when-not-to-use language.

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 the safety profile. The description adds behavioral context beyond the schema, such as the requirement for committee_id in itemized mode, the ability to use candidate_id for certain aggregates, and the sort behavior note about negative rows. This is meaningful disclosure beyond the annotations.

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

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

The description is three sentences, front-loaded with the core purpose, and every sentence provides distinct value: purpose, use case, and mode-specific constraints. 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 tool with 19 parameters and an output schema, the description gives a concise but sufficient overview of modes and prerequisites. It does not explain pagination or all filter options, but the schema covers those details. The description is complete enough to guide initial selection and 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 description coverage is 100%, so the baseline is 3. The description adds some high-level semantics (mode requirements, aggregate alternatives) that are not fully captured in individual parameter descriptions, but the schema already provides rich detail for each parameter. The description does not significantly compensate beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's function: 'Search itemized individual contributions (Schedule A) or get aggregate breakdowns by size, state, employer, or occupation.' It uses a specific verb ('Search') and resource ('itemized individual contributions'), and distinguishes from sibling tools (e.g., search_disbursements, search_expenditures) by focusing on contributions and Schedule A.

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 a clear use case ('Use to answer "who is funding this committee?"') and specifies mode requirements ('Itemized mode requires a committee_id. Aggregate by_size/by_state can use candidate_id instead.'). It does not explicitly name alternative tools for exclusion, but the guidance is sufficient for selecting this tool over 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 and idempotentHint, so the safety profile is covered. The description adds real behavioral context: it explains statutory limits, potential scale ('tens of millions per party'), and the all-years behavior of unscoped queries. This goes beyond what annotations convey.

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 sentences, ~70 words, with the key action front-loaded. Each sentence serves a purpose: definition, differentiation, and scoping guidance. No redundant filler.

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

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

Given the rich schema (11 params, all described) and an output schema, the description doesn't need to explain return values. It covers the tool's purpose, alternatives, and scoping patterns. The only minor gap is not mentioning date/amount filters, but those are fully documented in the schema, so this is sufficient.

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

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

Schema coverage is 100%, so baseline is 3. The description adds semantic meaning by identifying committee_id as the 'spending' committee and candidate_id as the 'benefiting' candidate, and suggests using them as scoping filters. This clarifies how parameters relate, although it doesn't discuss each parameter individually.

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 'Search coordinated party expenditures (Schedule F)' – a specific verb and resource. It then defines what those are and explicitly distinguishes from openfec_search_expenditures and direct contributions, making sibling differentiation clear.

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 explicitly names the alternative: 'Distinct from independent expenditures (openfec_search_expenditures)' and explains when coordinated expenditures are the right category. It also gives scoping guidance with committee_id, candidate_id, or cycle, and warns that unscoped queries span 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?

Annotations already declare readOnlyHint and idempotentHint, so the safety profile is covered. The description adds that there are itemized vs aggregate modes and that all modes require a committee_id, but it does not disclose additional behavioral traits like pagination specifics or potential timeouts. This is acceptable given the annotations, but not exceptionally 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?

The description is only two sentences, front-loaded with the core action and resource, and includes concrete example questions. Every sentence earns its place with no redundancy.

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

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

Given the tool has 17 parameters, rich schema documentation, and an output schema, the description provides sufficient high-level context for an agent to know when and how to approach it. It could be enhanced by explicitly naming sibling tools as alternatives, but it is complete enough for a tool of this complexity.

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

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

Schema description coverage is 100% and parameters are thoroughly documented. The description adds only the high-level note that committee_id is required and mentions aggregate modes, which are already in the schema. It does not meaningfully supplement parameter-level semantics beyond what 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 clearly states the tool searches itemized committee spending (Schedule B) or produces aggregate breakdowns by purpose or recipient, and gives specific use-case questions. This distinguishes it from sibling tools like openfec_search_expenditures (independent expenditures) by naming Schedule B.

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 on when to use the tool: to answer 'what is this committee spending money on?' or 'who is receiving payments from this committee?'. It also notes all modes require a committee_id. However, it does not explicitly mention alternatives or when not to use it versus other search 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?

Beyond the readOnlyHint and idempotentHint annotations, the description discloses important behavioral traits: the cycle default and upstream timeout, the sort-order quirk with negative corrections, cursor invalidation when other arguments change, and the most_recent amendment behavior. These are substantive details that help the agent predict tool behavior, going far beyond what annotations alone 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 dense and long (three sentences), but it packs in critical usage rules and mode distinctions. It is front-loaded with the primary purpose and then expands into mode-specific guidance. While some information repeats schema descriptions, the structure is coherent and every sentence adds a needed constraint or context.

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, the description covers the key decision points (mode selection, candidate_office scope combinations, cycle default and timeout, cursor usage, sort quirks, amendment handling) without explaining return values since an output schema exists. It is sufficiently complete to allow correct invocation and to avoid common pitfalls like undesired ascending negative sorts or an unscoped cycle scan.

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 already carries detailed documentation in the input schema. The description's main body adds an overview and mode-specific constraints, but for individual parameters it largely duplicates the schema text (e.g., sort's 'Itemized only; OpenFEC sorts by "-expenditure_date" when omitted' appears both places). There is no significant semantic enrichment 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 opens with a specific verb and resource: 'Search independent expenditures (Schedule E) — outside spending supporting or opposing federal candidates.' It clearly distinguishes from siblings by naming independent expenditures rather than coordinated or contributions, and the 'Schedule E' reference further pins down the FEC report type.

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 explicit when-to-use guidance: 'Use itemized mode for individual expenditure records, or by_candidate for aggregated totals per candidate.' It also gives prerequisites for by_candidate (candidate_id or full race scope), notes which filters are rejected by which mode, and warns that an unscoped cycle scan times out, steering users to pass an explicit cycle.

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 scope details (form types, date range) but does not disclose other behavioral aspects like pagination defaults, filter combination logic, or potential large result sets. With annotations present, 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, front-loaded with the core purpose and a concise enumeration of form types. Every clause carries useful information with zero fluff 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 output schema exists and parameter schemas are fully described, the description doesn't need to explain return values. It provides a sufficient overview for a search tool, but it omits guidance on how filters combine or the behavior of a no-filter query. For 13 optional parameters, this is a minor gap, not a major deficiency.

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. The description adds a high-level overview of filter dimensions (committee, candidate, form type, date range) but does not provide additional syntax, examples, or relationships beyond what the schema already documents. It neither improves nor harms parameter understanding.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb ('Search'), identifies the resource ('FEC filings and reports'), and lists the key dimensions (committee, candidate, form type, date range). It clearly distinguishes this tool from sibling search tools by focusing on filings rather than candidates, committees, or 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 context on what the tool searches and even enumerates specific form types covered. However, it does not explicitly state when NOT to use this tool or point to alternatives (e.g., use openfec_search_candidates for candidate lookups). The context is strong 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?

The annotations already declare readOnlyHint=true and idempotentHint=true, so the safety profile is clearly conveyed. The description adds the document categories but does not disclose additional behavioral traits such as performance caveats (e.g., 'admin_fines is slow' appears only in the schema, not the tool description) or pagination behavior.

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 focused sentence that names the action, resource, and scope. It is front-loaded and contains no filler, every word earning its place.

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

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

For a tool with 14 parameters, no required fields, and a rich schema plus output schema, the one-sentence description is sufficient to set context. It does not attempt to explain return values (unnecessary given the output schema), but it does not provide optional guidance on how to compose a search or when to use specific filters—though the schema's parameter descriptions largely compensate.

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% description coverage of all 14 parameters, with detailed explanations and constraints. The tool description itself contributes no parameter-specific semantics, so it neither adds nor detracts from the schema's already comprehensive guidance.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb ('Search') and resource ('FEC legal documents'), and explicitly enumerates the document types covered. This clearly distinguishes it from the sibling tool 'openfec_get_legal_document', which likely retrieves a single document rather than performing a search.

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

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

The description implies the tool's intended use—searching legal documents—but does not explicitly state when to use it over alternatives or mention exclusions. The sibling tool name suggests a distinction from document retrieval, but the description does not articulate this trade-off.

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