Run a real election or board vote: price it, check state HOA rules, draft the ballot and voter list.
Scored across 13 tools
Most tools target distinct resources/actions (election, survey, voters, pricing, state rules). The main ambiguity is the pair create_election_draft vs start_election_draft (both build a draft election, differing only by whether the user has an account) and the several informational get_* tools, but descriptions clearly delineate these cases.
Every tool follows a consistent snake_case verb_noun pattern: add_voters, create_election_draft, create_survey, get_election, get_state_hoa_rules, list_elections, publish_election, start_election_draft. The get_*_overview variants are also predictable and readable.
13 tools is well within the appropriate 3-15 range for a voting/election service. It leans a bit heavy on informational tools (platform overview, governance center, competitor comparison, price quote, review record) relative to the handful of action tools, but nothing is redundant.
Core lifecycle is covered (create draft, list, get, add voters, publish), but the surface lacks update/edit, delete/cancel, and voter-removal operations, and there is no explicit way to modify a draft after creation. Invitation sending is deliberately out of scope, but the missing modify/delete operations are notable gaps.
Add eligible voters (email, optional name and unit) to a DRAFT election in the connected account. Idempotent: people already on the list are skipped. Returns how many were added and the updated price. For a published election, voters are added by the organizer on the election page, because a larger list can change the price.
| Name | Required | Description | Default |
|---|---|---|---|
| voters | Yes | The eligible voters (the roster), one per owner/member. Email addresses only; people reached by text or mail are added by the organizer on the election page. | |
| election | Yes | The draft's id or slug. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare idempotentHint=true and destructiveHint=false, so the idempotency sentence is partly redundant with structured data. However, the description adds genuinely new behavior: the skip-if-present semantics, the effect on price ('updated price'), and that a larger list can change pricing on published elections. No contradiction with 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?
Three tight sentences with zero filler: scope first, then idempotency/return, then the published-election exclusion. Nothing is buried and nothing is repeated unnecessarily.
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?
No output schema exists, and the description compensates by stating the return payload (count added and updated price). Combined with the safety annotations and full schema coverage, an agent has everything needed to call this 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 email/name/unit semantics and the 2000-item cap are already documented in the schema. The description only restates the field list (email, optional name and unit) without adding format or ordering guidance, so the baseline of 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?
States a specific verb (add) and resource (eligible voters / roster) with an explicit scope qualifier: DRAFT election. The draft-vs-published distinction lets an agent separate this from the publish_election and list_elections siblings without opening any 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?
Gives both the when and the when-not: use for draft elections, and for a published election the organizer adds voters on the election page instead. It also implies the eligibility constraint (email; text/mail contacts handled by the organizer), so the agent knows the boundaries of a valid call.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Honest head-to-head between vote.direct and a named competitor — including the cases where the competitor is the better choice — with published prices checked on the competitor’s own pages, plus a vendor disclosure. Without a competitor, returns which-platform-for-which-need guidance.
| Name | Required | Description | Default |
|---|---|---|---|
| competitor | No | Competitor to compare against (optional) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint and non-destructive, so the safety profile is covered. The description adds substantive context the annotations cannot: the comparison is deliberately honest and includes cases where the competitor wins, prices are sourced from the competitor's own pages, and a vendor disclosure is attached.
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 densely-packed sentence that front-loads the core purpose before the fallback behavior. Every clause (honesty, price sourcing, disclosure, no-competitor mode) carries distinct information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single optional-enum, read-only tool with no output schema, the description covers purpose, both input branches, the sourcing of comparison data, and a disclosure caveat. Nothing an agent needs to invoke or interpret it 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 coverage is 100% and the enum is fully self-documenting, so baseline is 3. The description goes further by explaining the semantic consequence of omitting the optional competitor parameter, which is genuinely useful for deciding whether to pass it.
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+resource (head-to-head comparison of vote.direct against a named competitor) and a distinct scope from siblings like get_platform_overview and get_price_quote. An agent can tell immediately what this tool produces and how it differs from the overview 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?
Explicitly describes both call modes: with a competitor it produces a comparison with vendor disclosure, and without one it returns which-platform-for-which-need guidance. It does not, however, name when to prefer get_platform_overview or get_price_quote instead of this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a DRAFT election in the connected account: the ballot, schedule, verification, secrecy, results visibility, optional quorum and state-law checks, and optionally the voter list (emails). A draft charges nothing and contacts nobody. Returns the draft's id, what still blocks publishing, the exact price, and the finish link where the person reviews, pays if needed, and publishes. Ask the person for anything you do not know (closing date and time zone, seats, candidates) rather than guessing: this is a binding vote.
| Name | Required | Description | Default |
|---|---|---|---|
| state | No | Two-letter US state code of the association (e.g. CA). Turns on that state's election-law checks before publishing. | |
| title | Yes | Election title voters see, e.g. "2026 Board of Directors Election". | |
| quorum | No | Optional quorum: {type: "percentage" | "count", threshold}. E.g. {type: "percentage", threshold: 25} means a quarter of eligible voters must vote. | |
| voters | No | The eligible voters (the roster), one per owner/member. Email addresses only; people reached by text or mail are added by the organizer on the election page. | |
| results | No | after_close (default): voters see results once voting closes. live: running totals while voting is open. owner_only: only the organizer sees results. | |
| opens_at | No | When voting opens, ISO 8601 with offset. Omit to open when published. | |
| timezone | Yes | IANA timezone of the association, e.g. America/Denver. Voters see times in it. | |
| closes_at | Yes | When voting closes, ISO 8601 with offset, e.g. 2026-11-12T17:00:00-07:00. Must be in the future. | |
| questions | Yes | The ballot, in order. | |
| vote_type | No | What the vote decides, for the state-law checks. | |
| description | No | Optional instructions or background shown above the ballot. Plain text. | |
| verification | No | email: every voter confirms a code sent to their email (included free). email_or_sms: voters may also confirm by text message (paid elections only; elections of 25 voters or fewer are email-only). | |
| secret_ballot | No | Keep who voted for what private from the organizer. Defaults to true. | |
| community_type | No | hoa or condo, when the state rules differ between them. | |
| organization_name | No | Association name shown to voters and used as the email sender name. Defaults to the account's organization. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations cover only the generic profile (not read-only, not destructive, not idempotent, closed-world); the description supplies the domain-specific behavior that matters: no charge, no voter contact, and the four things the response carries back (id, publishing blockers, exact price, finish link). That is real context beyond the 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?
Four sentences, front-loaded with what the tool creates, then what it costs/costs nobody, then what it returns, then the elicitation rule. Nothing is repeated from the schema and no sentence is 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?
For a 15-parameter, nested, no-output-schema mutation tool, the description is complete: it states side effects (no charge, no contact), enumerates the return payload, and warns that the data supplied is binding. An agent has everything needed to invoke it responsibly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3, but the description adds semantic framing the schema does not: it groups the fifteen fields into ballot/schedule/verification/secrecy/results/quorum/roster and singles out the values the agent must elicit from the person (closing date and time zone, seats, candidates). It stops short of explaining individual field semantics like the results enum or verification tiers, which live in 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?
States a specific verb+resource ('Create a DRAFT election') and enumerates the exact surfaces it configures (ballot, schedule, verification, secrecy, results visibility, quorum, state-law checks, voter list). The emphasis on DRAFT also separates it from publish_election and list_elections.
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?
Usage context is clear: a draft charges nothing and contacts nobody, so an agent knows this is the safe pre-publish step, and the closing instruction ('ask the person for anything you do not know') rules out guessing. It stops short of naming siblings explicitly, leaving the agent to infer create_election_draft vs. start_election_draft, which is the one ambiguity that matters here.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a free, anonymous survey in the connected account and publish it (or save it as a draft with publish: false). Surveys are for feedback, not binding votes: anyone with the link can answer and respondents are not verified. For anything binding (a board election, a bylaw amendment, an assessment) use create_election_draft. Question types: single (pick one), multiple (checkboxes), yes_no, rating (1-5 by default; settings {scale: "nps"} makes a 0-10 Net Promoter Score), ranking, open_text. Returns the share link.
| Name | Required | Description | Default |
|---|---|---|---|
| title | Yes | ||
| publish | No | Publish now (default true) or save a draft. | |
| settings | No | Optional: showResultsDuring, showResultsAfter, requireAllQuestions, collectEmail, collectName. | |
| timezone | No | IANA timezone for the close time. Defaults to UTC. | |
| closes_at | No | Optional close time, ISO 8601. | |
| questions | Yes | ||
| description | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare write/not-destructive/not-idempotent, and the description adds genuinely new behavioral context: anonymous, unverified respondents, anyone with link can answer, publish:false saves a draft, and the share link is returned. It does not mention idempotency or failure modes, but the added context is substantive 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?
Front-loads the core action and scope, then the alternative, then question types. Dense but every sentence carries information; only the long parenthetical field lists approach bloat.
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 7-param nested tool with no output schema, the description covers the return value ('Returns the share link'), the anonymous/non-binding contract, draft vs publish, and question-type semantics. Gap remains around settings/timezone/closes_at, but those are documented in the schema itself.
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 57%, and the description compensates by defining question type semantics (single = pick one, multiple = checkboxes, rating 1-5, settings {scale:'nps'} = 0-10 NPS, ranking, open_text) and the publish:false draft behavior. It doesn't cover timezone/closes_at/settings fields, but the key enum-driven semantics are explained.
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 (Create) plus resource (survey) and immediately scopes it: free, anonymous, publishable or draft. It explicitly distinguishes itself from create_election_draft for binding use cases, so an agent can route between the two siblings without inspecting schemas.
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?
Explicit when-to-use and when-not-to-use: 'Surveys are for feedback, not binding votes' and 'For anything binding ... use create_election_draft.' Names the alternative tool directly, leaving nothing to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
One election or survey in the connected account: schedule, ballot, voters, ballots cast, turnout and quorum, and links. For a DRAFT election it also reports what still blocks publishing and the exact price the publish step would charge, and who pays it (free, plan, prepaid balance, or card at the finish link). Per-question results are on the election page link; this tool reports counts only.
| Name | Required | Description | Default |
|---|---|---|---|
| election | Yes | The election's id or slug, from list_elections or create_election_draft. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds genuine behavioral value beyond that: it discloses that DRAFT elections additionally return publishing blockers, the exact price the publish step would charge, and the payer (free, plan, prepaid balance, card), and it clarifies that only counts are reported with per-question results living on the election page link.
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?
It is compact and front-loads the core resource, then layers the DRAFT-specific behavior and the counts-only caveat. The enumeration of returned fields is dense but each clause carries information; a slightly tighter phrasing would earn a 5.
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 no output schema, the description must convey what comes back, and it does so thoroughly, including the special DRAFT case and the counts-only limitation. It is close to complete for an agent to call it correctly, missing only explicit guidance on when this is preferred over its siblings.
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 there is a single required parameter, so the schema fully documents 'election' including its source (id or slug from list_elections or create_election_draft). The description adds no further parameter semantics, so the baseline of 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 states a specific resource ('One election or survey in the connected account') and enumerates the aspects reported (schedule, ballot, voters, turnout, quorum, links), making the retrieval intent unambiguous. It implicitly separates itself from list_elections by scoping to a single item, though it never names the sibling explicitly.
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?
There is no statement of when to use this tool versus list_elections, get_price_quote, or publish_election. The only routing hint ('from list_elections or create_election_draft') lives in the schema's parameter description, not the tool description, so the description itself provides no usage context or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
governance.center, the second product from this team: the Board Office for a volunteer-run HOA, condo, nonprofit board, club or congregation. Returns the annual price for a given community size from the same constants Stripe bills, what every band includes, what is priced per use, what the product deliberately does not do, and the support line. Annual price first; the monthly figure is only an explainer.
| Name | Required | Description | Default |
|---|---|---|---|
| members | No | How many members, owners or units the community has. Returns the band that covers them. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish readOnly, idempotent and non-destructive, so the safety profile is covered. The description adds genuinely new context: prices come from 'the same constants Stripe bills' (data provenance/authority), the response deliberately includes what the product does not do, and it clarifies annual is authoritative while monthly is only an explainer.
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?
Content is front-loaded onto the product identity, which is good, but the second sentence is a long run-on enumerating five returned items. Phrases like 'the second product from this team' consume space without helping selection, and the annual-vs-monthly rule is buried at the end.
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 no output schema, the description carries the burden of describing the return, and it does so specifically: annual price, band inclusions, per-use pricing, deliberate non-capabilities, support line. The optional 'members' parameter's absence behavior is the one meaningful 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 single 'members' parameter is fully documented by the schema, including the band-covering behavior. The description only restates the 'for a given community size' framing without adding format, boundary behavior, or what happens when members is omitted despite being optional.
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?
It states a specific resource (governance.center) and what the call yields: the annual price for a community size plus band contents, per-use pricing, exclusions and support line. It partly differentiates from siblings by positioning governance.center as 'the second product from this team', but never names the alternative tools (get_platform_overview, get_price_quote) it must be distinguished from.
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?
There is no explicit when-to-use or when-not-to-use guidance, and no sibling tool is named as the alternative. The closest thing to routing is the passing phrase 'the second product from this team', which is descriptive, not directive. An agent must infer the trigger condition from the return contents.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Factual overview of vote.direct: free tier and pricing model, verification ladder, ballot-secrecy modes, the dispute-evidence pack (audit trail, results certificate, receipts), voting channels, question types, the full feature list with the no-tier-lock rule, who owns and runs the company, the founder's direct line, and where to read more.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, openWorldHint=false, so the safety profile is fully covered. The description adds the useful scope fact that the return is a static factual snapshot rather than live data, but it discloses no error behavior, freshness guarantees, or result shape beyond the topic list.
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 front-loaded sentence that opens with the resource before enumerating coverage. The topic list is long but each item earns its place by signaling returned content; slightly list-like sprawl keeps it from a 5.
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 no parameters and no output schema, the description carries the burden of describing returns, and the topic enumeration does that well for a static overview tool. It is not quite complete about data staleness or how much detail each topic receives.
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 tool takes zero parameters, so the baseline is 4; there is no parameter semantics for the description to clarify or omit.
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?
Names a specific verb+resource ('Factual overview of vote.direct') and enumerates the exact topics covered, so an agent knows what content it returns. It does not, however, explicitly distinguish itself from siblings like get_price_quote, compare_platforms, or get_governance_center_overview, leaving some overlap to inference.
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?
Usage is only implied: the topic list suggests calling it for general platform questions (pricing, features, ownership). There is no explicit statement of when to use this rather than get_price_quote for pricing or compare_platforms for comparisons, and no exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Exact, current vote.direct pricing for an election: flat rate by voter count (email verification included, SMS on paid elections), optional government-ID and mailed-letter add-ons, promotional pricing status, and whether a subscription would beat paying per election. Same constants the product bills against.
| Name | Required | Description | Default |
|---|---|---|---|
| voters | Yes | How many voters will be invited | |
| gov_id_voters | No | Voters needing assisted government-ID verification (optional) | |
| mailed_letters | No | Mailed access letters to send (optional) | |
| elections_per_year | No | If provided, compares per-election cost against subscriptions |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish readOnly, idempotent, non-destructive, closed-world behavior, so the safety burden is covered. The description adds real behavioral context beyond them: what is included in the rate (email verification, SMS on paid elections), the optional add-ons, and the guarantee that these are 'the same constants the product bills against,' which tells the agent the numbers are authoritative.
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 dense sentence that front-loads the core promise ('exact, current pricing') and then lists the components. No filler sentences, though the mid-sentence parentheticals make it slightly heavier than ideal.
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?
There is no output schema, so the description must convey what comes back, and it does: rate, add-ons, promo status, subscription comparison. For a simple read-only pricing tool with a fully documented schema, this is close to complete; only pagination/format details are absent, which are not relevant here.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description goes further by mapping parameters to meaning: 'flat rate by voter count' explains voters, gov-ID and mailed-letter add-ons explain the two optional integer params, and the subscription clause explains what elections_per_year triggers.
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 names a specific verb+resource (exact current pricing for an election) and enumerates the components returned: flat rate by voter count, add-ons, promotional status, subscription comparison. It clearly differs from a general overview tool, though it never explicitly distinguishes itself from the closest sibling, compare_platforms.
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?
Usage is implied rather than stated: an agent can infer this is for pricing a specific election, and the elections_per_year parameter hints at subscription-comparison scenarios. There is no explicit when-to-use/when-not guidance and no named alternative for platform-vs-platform comparison.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The complete third-party review record for vote.direct — every published Capterra and Trustpilot review quoted verbatim with links, including the honest caveats (small record, TrustScore explanation, which reviewers had actually run an election).
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the safety profile (read-only, idempotent, non-destructive, closed-world), so the description's job is to add context — and it does: it discloses the record is small, explains the TrustScore, and notes which reviewers actually ran an election. That is genuine value beyond the annotations, though pagination/size is not quantified.
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?
One sentence, front-loaded with the resource and what it contains. It is slightly padded by persuasive framing, but every clause conveys content the agent can use.
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 no parameters, no output schema, and annotations carrying the safety profile, the description adequately conveys what the agent will receive. Minor gaps (volume, whether it is a single document vs a list) keep it short of full completeness.
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 tool takes zero parameters and the schema coverage is 100%, so there is nothing for the description to disambiguate. The baseline of 4 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?
States a specific resource (the complete third-party review record for vote.direct) and enumerates its contents (Capterra and Trustpilot reviews, verbatim, with links). An agent can distinguish it from siblings like get_platform_overview or compare_platforms, though the marketing tone ('the honest caveats') adds flavor rather than precision.
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?
There is no explicit when-to-use or when-not-to-use guidance, and no alternatives are named. The agent must infer that this is the source for third-party review evidence rather than platform comparisons.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Stored HOA/condo voting-rule summary for any US state: whether electronic voting is expressly allowed, key statutes with citations, quorum, notice and proxy rules, and whether vote.direct may serve as inspector of elections there. Summaries support review; they are not legal advice.
| Name | Required | Description | Default |
|---|---|---|---|
| state | Yes | State name, two-letter abbreviation, or slug (e.g. "Texas", "TX", "texas") |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds meaningful context beyond them: the data is 'stored' (a precomputed summary rather than a live legal lookup) and carries an explicit 'not legal advice' disclaimer, which is exactly the kind of caveat an agent needs.
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 waste; the resource and scope are front-loaded, the enumerated contents follow, and the disclaimer closes. 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?
There is no output schema, so the description carries the return-value burden, and it does so by listing the summary's components plus the inspector-of-elections question it answers. Combined with full schema coverage and read-only annotations, an agent has everything needed to call and interpret this tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the single 'state' parameter already documents accepted forms (name, abbreviation, slug) with examples. The description's 'for any US state' confirms scope but adds no syntax or format detail beyond the schema, so the 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?
States a specific verb and resource: retrieves a stored HOA/condo voting-rule summary scoped to a US state, and enumerates the exact contents (e-voting allowance, statutes with citations, quorum, notice, proxy, inspector eligibility). This is clearly distinguishable from siblings like compare_platforms or get_price_quote.
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?
Usage is implied by the domain: look up state-level HOA voting rules. However, the description never states when to use this versus siblings such as get_governance_center_overview or compare_platforms, and offers no exclusions or prerequisites beyond the 'not legal advice' caveat.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Elections and surveys in the connected vote.direct account, newest first: id, slug, title, kind (election or survey), status (draft, scheduled, live, closed), schedule, voters and ballots cast, and the links to hand the person.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | How many to return. Defaults to 20. | |
| status | No | Only this status. Defaults to all. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=false and destructiveHint=false, so safety is covered structurally. The description adds real context on top of that: results are sorted newest first and the concrete field set (status values, schedule, voters, ballots, links) that an agent will receive.
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 with a front-loaded resource and scope, followed by a colon list of returned fields; nothing is padded. The trailing 'links to hand the person' is slightly colloquial but still economical and informative.
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?
There is no output schema, so the description usefully compensates by enumerating the return shape (id, slug, title, kind, status, schedule, voters, ballots, links). For a read-only list tool with two optional, fully-documented parameters, this is close to complete; only ordering/pagination caveats are 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 100%, so limit (default 20, max 50) and status (default all, enum values) are already fully documented in the schema. The description restates the status vocabulary and implies ordering but adds no filtering or pagination semantics beyond the schema, so the 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?
States a specific verb (implicit list) and resource (elections and surveys) scoped to 'the connected vote.direct account', and enumerates the returned fields, so the agent knows exactly what comes back. It does not explicitly distinguish itself from get_election (singular) or the create/publish siblings, which keeps it short of a 5.
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?
Usage is only implied: the tool is for browsing the account's elections/surveys, with defaults for limit and status mentioned only via the schema. There is no statement of when to prefer this over get_election or get_governance_center_overview, nor any exclusion for archived or other-account resources.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Publish a DRAFT election in the connected account, running every check the publish button runs (ballot, schedule, voter list, state law, price) and charging the price from the account's prepaid balance or plan. Free elections (up to 25 voters) publish at no cost. If the balance does not cover it, nothing is charged and the person pays by card at the finish link instead. Publishing does NOT send invitations: the organizer sends them from the election page. Confirm with the person before calling this; it can spend their money.
| Name | Required | Description | Default |
|---|---|---|---|
| election | Yes | The election's id or slug, from list_elections or create_election_draft. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only flag destructive/non-idempotent/non-readonly; the description goes far beyond by disclosing what the publish runs (ballot, schedule, voter list, state law, price checks), that it charges the prepaid balance or plan, the free tier (up to 25 voters), and the fallback where an insufficient balance results in no charge and card payment at the finish link. That financial consequence and side-effect detail is exactly what 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?
The most consequential fact, that this spends money and requires confirmation, is placed prominently, and every sentence carries non-redundant information (checks, cost, free tier, fallback, invitations). 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?
For a one-parameter destructive mutation with no output schema, the description covers the checks performed, the billing behavior and its fallback, the invitation side-effect boundary, and the confirmation requirement, leaving nothing an agent needs to invoke it safely unstated.
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 a single parameter and 100% schema description coverage, the schema already documents the election id/slug and its provenance (list_elections or create_election_draft). The description adds no additional syntax or format meaning, so the baseline of 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?
Opens with a specific verb+resource+scope: publishing a DRAFT election in the connected account. An agent can immediately distinguish this from create_election_draft, start_election_draft, and get_election among the siblings.
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 explicit preconditions ('Confirm with the person before calling this; it can spend their money') and clarifies the boundary of the action ('Publishing does NOT send invitations: the organizer sends them from the election page'). It does not name a competing sibling to use instead, but the draft-versus-publish distinction is clear from the required DRAFT state.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Build a complete election (ballot, schedule, verification, voter emails) for a person who does not have a vote.direct account yet, and get the link where they claim it: they open it, create an account with their email, and the election appears in their dashboard ready to review and publish. Nothing is charged and no voter is contacted until they do. The link expires in 48 hours. For a person who has an account, or will sign in, create_election_draft works in their account directly.
| Name | Required | Description | Default |
|---|---|---|---|
| state | No | Two-letter US state code of the association (e.g. CA). Turns on that state's election-law checks before publishing. | |
| title | Yes | Election title voters see, e.g. "2026 Board of Directors Election". | |
| quorum | No | Optional quorum: {type: "percentage" | "count", threshold}. E.g. {type: "percentage", threshold: 25} means a quarter of eligible voters must vote. | |
| voters | No | The eligible voters (the roster), one per owner/member. Email addresses only; people reached by text or mail are added by the organizer on the election page. | |
| results | No | after_close (default): voters see results once voting closes. live: running totals while voting is open. owner_only: only the organizer sees results. | |
| opens_at | No | When voting opens, ISO 8601 with offset. Omit to open when published. | |
| timezone | Yes | IANA timezone of the association, e.g. America/Denver. Voters see times in it. | |
| closes_at | Yes | When voting closes, ISO 8601 with offset, e.g. 2026-11-12T17:00:00-07:00. Must be in the future. | |
| questions | Yes | The ballot, in order. | |
| vote_type | No | What the vote decides, for the state-law checks. | |
| description | No | Optional instructions or background shown above the ballot. Plain text. | |
| verification | No | email: every voter confirms a code sent to their email (included free). email_or_sms: voters may also confirm by text message (paid elections only; elections of 25 voters or fewer are email-only). | |
| secret_ballot | No | Keep who voted for what private from the organizer. Defaults to true. | |
| community_type | No | hoa or condo, when the state rules differ between them. | |
| organization_name | No | Association name shown to voters and used as the email sender name. Defaults to the account's organization. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=false, destructiveHint=false, idempotentHint=false, openWorldHint=false, so the safety profile is partly covered, but the description adds substantial behavior beyond them: nothing is charged and no voter is contacted until the recipient acts, and the claim link expires in 48 hours. It stops short of describing what happens to a draft that is never claimed or any auth/rate considerations, so it is not 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?
Front-loaded with the core action and the claim-link behavior, then the cost/contact guarantee, expiry, and the sibling alternative. It is on the longer side for a description, but each sentence carries a distinct fact, so almost nothing is wasted.
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 complex 15-parameter creation tool with no output schema, the description covers the outcome (a claim link that materializes the election in the recipient's dashboard ready to review and publish), the safety-relevant guarantees, and the sibling alternative. It does not explain what the tool returns at call time versus at claim time, a minor remaining 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% with 15 rich nested parameters, including enums, quorum semantics, and voting-type rules, all documented in the schema itself. The description adds almost no parameter-level detail (it mentions ballot, schedule, verification, voter emails at a high level only), so 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 states a specific action (build a complete election) on a specific resource (ballot, schedule, verification, voter emails) and names the exact mechanism: a claim link for a person without an account. It explicitly distinguishes itself from the sibling create_election_draft by naming it and stating the alternative condition (person already has or will create an account in their own account).
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?
Explicit routing: use this tool for a person without an account; use create_election_draft for a person who has an account or will sign in. The exclusion condition is stated plainly, so an agent can select between the two siblings without inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
add_voterscreate_election_draftcreate_surveyget_electionlist_electionspublish_electioncompare_platformsget_governance_center_overviewget_platform_overviewget_price_quoteget_review_recordget_state_hoa_rulesstart_election_draftSend documents for signature: upload, place fields, draft, and send once a human agrees.
Mail real US letters, postcards and certified mail from an agent, quoted before sending.
Prepare USPS Certified Mail letters from any AI assistant; a person reviews, pays and authorizes.
Send a USPS Certified Mail letter to any US address from ChatGPT, Claude or Grok. The assistant prepares the letter and hands back a review link; a person reads it, checks the recipient, pays and authorizes. Nothing is printed, mailed or charged without that approval. $16.17 with the electronic return receipt, $13.18 without. No subscription, and no account needed to see a price. Docs: https://piloxa.com/send-a-certified-letter-online
Add one secure layer between your agents and this server.
