Election.org

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

Annotations already declare read-only, idempotent, non-destructive, open-world behavior, so the safety profile is covered. The description adds genuinely new behavioral context: it discloses coverage limits, that missing summaries are returned as null, and that outside-spending totals are separately labeled — details an agent cannot get from the annotations or 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?

Purpose and scope are front-loaded in the first sentence, followed by return-shape notes and interpretive caveats. The three caution sentences ('balances are not net worth', 'contributions do not establish influence') are slightly verbose but defensible for a sensitive-data tool.

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 an output schema exists, the description need not enumerate return fields, and it nonetheless flags the key ones (reporting periods, sources, coverage limits) plus the null-handling contract. For a single-parameter read tool this covers everything an agent needs to invoke and interpret 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?

There is a single parameter with 100% schema description coverage, including the pattern and an example, so the schema already carries the semantics. The description only restates 'for an FEC candidate ID' without adding format or sourcing guidance, which is the baseline 3 case.

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

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

The description opens with a specific verb ('Retrieve') and an enumerated resource list (receipts, spending, cash, debts, linked committees, outside-spending totals) scoped to 2026 federal races and keyed by FEC candidate ID. That is immediately distinguishable from the sibling search_* and get_election_* tools, which locate candidates or return electoral outcomes rather than financial disclosures.

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

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

The phrase 'for an FEC candidate ID' implies the prerequisite (an ID already obtained elsewhere), but the description never names the alternative tool for finding one, nor states when this should not be used. Usage is inferable rather than guided.

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

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

Annotations already declare readOnly, idempotent, non-destructive, open-world, so the safety profile is covered. The description adds real value beyond them: dates carry source attribution and a tentative/changeable status, and it warns the agent to confirm actionable dates with the state election authority. Rate limits and pagination are not mentioned, which is a minor gap.

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, front-loaded with what is returned, followed by status/sourcing metadata, then the exclusion and caveat. No filler and every clause carries information an agent would act on.

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, return shape need not be described, and annotations cover the safety profile; the description covers scope, sourcing, and caveats well. The only unaddressed detail is the exact behavior when the state filter is omitted (national-only vs. all jurisdictions), which is left to inference.

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

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

Schema coverage is 100% and the schema's own state description is strong ('public records being researched, not the user's location'). The description only echoes that the filter is optional and jurisdictional, so it neither needs to nor does add much beyond the structured field.

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?

Specific verb plus resource plus scope: 'Return the published 2026 federal general election date and congressional primary/runoff schedule.' It also draws a clear negative boundary ('Does not include every local election, registration deadline or polling location'), which separates it from siblings like get_election_results and search_candidates without opening either schema.

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?

States the optional state filter and explicitly lists what the tool will not cover, nudging the agent to other sources for local races and deadlines. It does not name the specific sibling tools to use instead, so the routing is implied rather than explicit.

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

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

Annotations already declare readOnly, idempotent, non-destructive, openWorld, so the safety profile is covered. The description still adds real behavior: the enumerated supported years, the hard-fail (not fallback) semantics for unsupported years, and the presence of calculation caveats and record links. No auth or rate-limit context, but the error contract is the important disclosure here.

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?

Five short sentences, front-loaded with the verb and resource, then scope, then the supported-year constraint, then the negative boundaries. No filler and no repetition of 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?

Return values need not be explained since an output schema exists, and the year contract is fully covered. The gap is the four undocumented optional filters (limit, office, district, candidate): an agent cannot tell from the definition how to narrow a query to a specific race without reverse-engineering the schema.

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 17% — only `state` is documented. The description meaningfully narrows `year` from the schema's 1900–2100 range down to five supported values, which is a genuine semantic addition. However, `limit`, `office`, `district`, and `candidate` receive no explanation in either schema or description, leaving most of the filtering surface opaque.

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 verb (Retrieve) and resource (U.S. House and Senate election results) with a precise scope qualifier ('explicitly requested year'). It also carves itself away from adjacent tools by naming what it is not: live returns, projections, presidential results — which separates it from get_election_calendar and get_campaign_finance.

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?

Clear when-not guidance: other years produce an unsupported-year error and never substituted historical results, and the tool explicitly excludes live returns, projections, and presidential results. It stops short of naming a sibling as the alternative for presidential or live-race queries, so it is strong context without full routing.

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 cover read-only/idempotent/non-destructive, and the description still adds substantial value beyond them: it names the two returned collections, discloses the heterogeneous Mississippi state-authority source with unmatched candidates, discloses ordering ('by reported receipts, not an endorsement'), and warns that neither collection proves ballot certification or complete coverage. That is exactly the kind of caveat an agent cannot get from structured fields.

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?

Front-loaded with purpose and query surface, then caveats — good ordering with no filler paragraphs. A few clauses ('No party is excluded', 'not an endorsement') read as legal boilerplate and could be compressed, but each still carries an anti-bias signal an agent might otherwise over-interpret.

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 5-param, zero-required search with an output schema, this is close to complete: it explains both result collections, coverage limits, and a hand-off rule. It stops short on how results are truncated/paged when `limit` caps at 20 and on office code semantics, which an agent may need to call 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 only 20% (only 'state' is documented), so the description must carry the load and it covers roughly half: it maps q to 'public name or FEC ID' and lists state/office/district as filters. It never explains the H/S/P office codes, the two-digit district format, or what `limit` (default 5, max 20) controls, leaving real gaps.

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?

Opens with a specific verb+resource+scope: 'Search Election.org's 2026 FEC candidate filings by public name or FEC ID, state, office, or district.' It implicitly separates itself from get_campaign_finance via 'Do not request federal finance for a null FEC ID,' but never names that sibling or search_offices explicitly, so discrimination is good rather than airtight.

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?

Gives concrete operational direction: 'Check both collections' (data.records and data.state_authority_records), and the negative rule 'Do not request federal finance for a null FEC ID' tells the agent when to stop and hand off to finance tooling. Missing an explicit statement of when to prefer search_offices or get_election_results instead, so not a full 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 readOnly, idempotent, openWorld and non-destructive, so the safety profile is covered. The description adds real value beyond them: it discloses what comes back (source-backed institution records, office contacts, enriched coverage, record links) and warns that results are directory entries that may not reflect current officials or exact boundaries. It does not mention result caps 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?

Front-loads purpose, then return contents, then caveats — a sensible order with no filler. The caveat sentences are short and each carries a distinct constraint, though the block of four trailing disclaimers is slightly dense relative to the one-line core.

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?

An output schema exists, so return values need no further explanation, and annotations carry the safety profile. The description covers what the tool searches, what it returns, and the main interpretive pitfalls, which is sufficient for a 3-parameter read-only search.

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 67%, with the schema already explaining the query-matching behavior for `q` and the state-vs-user-location distinction for `state`. The description adds nothing about parameters, and `limit` (default 3, max 5) is undocumented in both schema and description, leaving a real gap it does not compensate for.

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 verb (Search) and a precise resource set (named cities, counties, school systems and special districts) within a named directory, which cleanly separates it from siblings like search_candidates and search_offices. An agent can tell from the first sentence that this is the jurisdiction-lookup tool, not a people or office lookup.

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

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

Gives clear scope boundaries — similar names may be different jurisdictions, inclusion doesn't establish current officials, and it does not locate a user's home or private contacts. It stops short of explicitly naming an alternative tool or stating when a sibling (e.g. search_offices) is the better pick, so routing is implied rather than prescribed.

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 establish read-only, idempotent, open-world, non-destructive behavior, so the description correctly spends its words elsewhere. It adds genuinely non-obvious behavioral context: partial local coverage, an obligation to retain source verification dates, and the caveat that a missing holder is not proof of a vacancy. It does not discuss result ordering or pagination, keeping it below a 5.

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

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

Four short sentences, front-loaded with the core purpose followed by coverage scope and interpretive caveats. Every sentence carries information, though the phrasing is telegraphic and the coverage/sourcing points could be consolidated slightly.

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

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

An output schema exists, so return-value detail is not required, and annotations cover the safety profile. The description fills the remaining gaps an agent needs for correct interpretation — incomplete local coverage, sourcing dates, and the vacancy caveat. The main residual gap is sibling routing, which is left implicit.

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 50%: 'level' and 'state' are documented in-schema (including the useful 'not the user's location' clarification). The description adds meaning to 'q' by enumerating acceptable match keys (official name, office title, jurisdiction), but says nothing about 'limit' or how the keys combine.

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 first sentence gives a specific verb and resource ('Search permanent public offices and their sourced holders') plus the three search keys (official name, office title, jurisdiction). It also carves out a scope boundary ('Not an address-to-representative lookup'), which helps separate it from lookup-style tools. It stops short of naming how it differs from siblings like search_governments or search_candidates.

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

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

Coverage guidance ('federal, state, executive and selected local ... local coverage is incomplete') and an explicit exclusion ('Not an address-to-representative lookup') give some sense of fit, but no sibling alternative is named for the excluded use case. An agent must still infer whether to route to search_governments or search_candidates.

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