vote.direct

Start an election for someone without an account

start_election_draft

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.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "title": "<title>",
      "questions": "<questions>",
      "timezone": "<timezone>"
    },
    "name": "start_election_draft"
  }
}

Input Schema

Name	Required	Description
`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`	No	When voting closes, ISO 8601 with offset, e.g. 2026-11-12T17:00:00-07:00. Must be in the future. Leave it out when nobody said: voting then closes at 5pm in `timezone` seven days from today, and the result says the exact time so it can be relayed and changed.
`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.

Schema Changelog

Changes observed during successful MCP inspections.

Changed2 schema fields changedOct 19, 2026

changedInput schema / properties / closes_at / description

Previous value: -"When voting closes, ISO 8601 with offset, e.g. 2026-11-12T17:00:00-07:00. Must be in the future."New value: +"When voting closes, ISO 8601 with offset, e.g. 2026-11-12T17:00:00-07:00. Must be in the future. Leave it out when nobody said: voting then closes at 5pm in `timezone` seven days from today, and the result says the exact time so it can be relayed and changed."

changedInput schema / required

Previous value: -[
-  "title",
-  "questions",
-  "closes_at",
-  "timezone"
-]New value: +[
+  "title",
+  "questions",
+  "timezone"
+]

Changed1 schema field changedOct 8, 2026
- changedInput schema / properties / voters / maxItems
```
Previous value: -2000New value: +5000
```
First observedSep 30, 2026

TDQS

A4.3/5.0

Behavior4/5

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

Annotations only declare the generic write profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false, openWorldHint=false). The description adds real behavioral context beyond that: no charge and no voter contact until the draft is claimed, the link expires in 48 hours, and the claim flow creates the account and surfaces the election in their dashboard. It does not mention that repeat calls create additional drafts (consistent with idempotentHint=false), which is the one gap.

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

Conciseness4/5

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

Front-loaded with the primary action, then the claim/expiry mechanics, then the sibling alternative — a sensible order with no filler. The phrase 'until they do' is a slightly loose referent for 'until the recipient claims the link', the only wordiness cost.

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

Completeness4/5

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

For a 15-parameter nested-schema tool with no output schema, the description covers the operation's end-to-end consequence (link returned, 48-hour expiry, claim flow, dashboard handoff), which is what an agent needs. It does not describe any other returned fields, but the link plus expiry is the actionable output.

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

Parameters3/5

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

Schema description coverage is 100% and the schema is unusually detailed (enum semantics, defaults, ISO formats, quorum shape), so the baseline is 3. The description only gestures at the parameter groups ('ballot, schedule, verification, voter emails') without adding syntax or constraints beyond the schema.

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

Purpose5/5

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

States a specific verb and resource — building a complete election draft for a person without a vote.direct account — and explicitly names the sibling create_election_draft as the path for someone who already has an account. An agent can distinguish the two 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.

Usage Guidelines5/5

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

Gives an explicit routing rule: use this tool for a person with no account; use create_election_draft when they have an account or will sign in. It also clarifies the side-effect boundary (nothing charged, no voter contacted until the recipient claims the draft).

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

All vote.direct tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources

Need Help?