Skip to main content
Glama
loomiomcp
by soil-dev

create_poll

Create Loomio polls in a group or discussion thread by specifying title, poll type, and options, with a future closing date to open voting and avoid unopened drafts.

Instructions

Create a poll: 1 call (2 with discussion_id). Required title, poll_type, options (NO default options; only 'question' takes none) and group_id (standalone) or discussion_id / topic_id (inside a thread). closing_at (ISO-8601, future) is effectively REQUIRED: without it Loomio saves the poll UNOPENED and the result carries opened: false and a warning. An opening poll is announced because notify_on_open defaults to TRUE; pass notify_on_open: false for a quiet create.

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>",
      "poll_type": "<poll_type>"
    },
    "name": "create_poll"
  }
}

Input Schema

NameRequiredDescriptionDefault
tagsNoTags for a standalone poll's thread.
titleYes
detailsNo
optionsNoOption names in order. REQUIRED except 'question'; ranked_choice/stv need 2+.
group_idNoGroup of a STANDALONE poll (else only cross-checked).
topic_idNoThread id (`topic_id` on any thread row); no extra call.
anonymousNoPermanent. Needs closing_at; not for count, question, meeting.
poll_typeYes'question' has no options; 'meeting' options are ISO-8601 times; 'stv' takes stv_seats.
score_maxNoscore: max per option (default 5); meeting: 2.
score_minNoscore: min per option (default 0).
stv_seatsNostv: seats to fill.
closing_atNoISO-8601, future. Effectively REQUIRED: omitted = unopened draft.
hide_resultsNoDefault 'off'; anonymous polls force 'until_closed'.
discussion_idNoDiscussion to attach to (id or key; +1 call). Prefer topic_id.
reason_promptNoPrompt above the reason box.
details_formatNoDefault 'md'; 'html' when `details` is HTML.
notify_on_openNoAnnounce (`poll_announced`) on opening; Loomio's default is TRUE.
shuffle_optionsNoRandomise option order per voter.
choice_count_maxNoMax options per voter (poll: 1; raise for multi-choice).
choice_count_minNoMin options per voter (ranked_choice: ranks, default 3).
meeting_durationNomeeting: slot minutes. No default through the API.
points_per_voterNodot_vote: points per voter (default 8).
recipient_emailsNoEmails to invite; non-members become guests.
can_respond_maybeNomeeting: allow 'maybe'. API default is false.
notify_recipientsNoEmail/push the named recipients; SEPARATE from notify_on_open.
recipient_messageNoText for the notification.
recipient_audienceNo'group' = every member (needs announce permission).
recipient_user_idsNoUser ids to invite / notify.
specified_voters_onlyNoOnly the named recipients may vote.
notify_on_closing_soonNo24h closing reminder; API default is 'nobody'.
show_none_of_the_aboveNoOffer 'none of the above' (poll, ranked_choice).
stance_reason_requiredNoDefault 'optional'; anonymous polls force 'disabled'.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed11 schema fields changedv0.0.19
    • addedInput schema / properties / choice_count_max
      Added value: +{
      +  "description": "Max options per voter (poll: 1; raise for multi-choice).",
      +  "exclusiveMinimum": 0,
      +  "maximum": 9007199254740991,
      +  "type": "integer"
      +}
    • addedInput schema / properties / choice_count_min
      Added value: +{
      +  "description": "Min options per voter (ranked_choice: ranks, default 3).",
      +  "maximum": 9007199254740991,
      +  "minimum": 0,
      +  "type": "integer"
      +}
    • removedInput schema / properties / dots_per_person
      Removed value: -{
      -  "description": "dot_vote: points per voter (default 8).",
      -  "exclusiveMinimum": 0,
      -  "maximum": 9007199254740991,
      -  "type": "integer"
      -}
    • removedInput schema / properties / max_score
      Removed value: -{
      -  "description": "score: max per option (default 5); meeting: 2.",
      -  "maximum": 9007199254740991,
      -  "minimum": -9007199254740991,
      -  "type": "integer"
      -}
    • removedInput schema / properties / maximum_stance_choices
      Removed value: -{
      -  "description": "Max options per voter (poll: 1; raise for multi-choice).",
      -  "exclusiveMinimum": 0,
      -  "maximum": 9007199254740991,
      -  "type": "integer"
      -}
    • removedInput schema / properties / min_score
      Removed value: -{
      -  "description": "score: min per option (default 0).",
      -  "maximum": 9007199254740991,
      -  "minimum": -9007199254740991,
      -  "type": "integer"
      -}
    • removedInput schema / properties / minimum_stance_choices
      Removed value: -{
      -  "description": "Min options per voter (ranked_choice: ranks, default 3).",
      -  "maximum": 9007199254740991,
      -  "minimum": 0,
      -  "type": "integer"
      -}
    • changedInput schema / properties / notify_on_closing_soon / enum
      Previous value: -[
      -  "nobody",
      -  "author",
      -  "undecided_voters",
      -  "voters"
      -]New value: +[
      +  "nobody",
      +  "author",
      +  "voters_uncast",
      +  "voters"
      +]
    • addedInput schema / properties / points_per_voter
      Added value: +{
      +  "description": "dot_vote: points per voter (default 8).",
      +  "exclusiveMinimum": 0,
      +  "maximum": 9007199254740991,
      +  "type": "integer"
      +}
    • addedInput schema / properties / score_max
      Added value: +{
      +  "description": "score: max per option (default 5); meeting: 2.",
      +  "maximum": 9007199254740991,
      +  "minimum": -9007199254740991,
      +  "type": "integer"
      +}
    • addedInput schema / properties / score_min
      Added value: +{
      +  "description": "score: min per option (default 0).",
      +  "maximum": 9007199254740991,
      +  "minimum": -9007199254740991,
      +  "type": "integer"
      +}
  2. Changed2 schema fields changedv0.0.17
    • addedInput schema / properties / closing_at / maxLength
      Added value: +64
    • changedInput schema / properties / discussion_id / anyOf
      Previous value: -[
      -  {
      -    "pattern": "^[A-Za-z0-9_-]+$",
      -    "type": "string"
      -  },
      -  {
      -    "exclusiveMinimum": 0,
      -    "maximum": 9007199254740991,
      -    "type": "integer"
      -  }
      -]New value: +[
      +  {
      +    "pattern": "^[A-Za-z0-9_-]{1,128}$",
      +    "type": "string"
      +  },
      +  {
      +    "exclusiveMinimum": 0,
      +    "maximum": 9007199254740991,
      +    "type": "integer"
      +  }
      +]
  3. Changed39 schema fields changedv0.0.13
    • changedInput schema / properties / anonymous / description
      Previous value: -"If true, hide voter identities."New value: +"Permanent. Needs closing_at; not for count, question, meeting."
    • addedInput schema / properties / can_respond_maybe
      Added value: +{
      +  "description": "meeting: allow 'maybe'. API default is false.",
      +  "type": "boolean"
      +}
    • changedInput schema / properties / closing_at / description
      Previous value: -"ISO-8601 timestamp at which the poll closes."New value: +"ISO-8601, future. Effectively REQUIRED: omitted = unopened draft."
    • removedInput schema / properties / details / description
      Removed value: -"Optional poll body / context."
    • changedInput schema / properties / details_format / description
      Previous value: -"Format of `details`. Defaults to 'md'."New value: +"Default 'md'; 'html' when `details` is HTML."
    • addedInput schema / properties / discussion_id / anyOf
      Added value: +[
      +  {
      +    "pattern": "^[A-Za-z0-9_-]+$",
      +    "type": "string"
      +  },
      +  {
      +    "exclusiveMinimum": 0,
      +    "maximum": 9007199254740991,
      +    "type": "integer"
      +  }
      +]
    • changedInput schema / properties / discussion_id / description
      Previous value: -"Attach the poll to an existing discussion. When set, group_id is taken from the discussion."New value: +"Discussion to attach to (id or key; +1 call). Prefer topic_id."
    • removedInput schema / properties / discussion_id / exclusiveMinimum
      Removed value: -0
    • removedInput schema / properties / discussion_id / maximum
      Removed value: -9007199254740991
    • removedInput schema / properties / discussion_id / type
      Removed value: -"integer"
    • addedInput schema / properties / dots_per_person
      Added value: +{
      +  "description": "dot_vote: points per voter (default 8).",
      +  "exclusiveMinimum": 0,
      +  "maximum": 9007199254740991,
      +  "type": "integer"
      +}
    • changedInput schema / properties / group_id / description
      Previous value: -"Group the poll belongs to. Required when not attaching to an existing discussion via discussion_id."New value: +"Group of a STANDALONE poll (else only cross-checked)."
    • changedInput schema / properties / hide_results / description
      Previous value: -"Results visibility policy. Defaults to 'off'."New value: +"Default 'off'; anonymous polls force 'until_closed'."
    • addedInput schema / properties / max_score
      Added value: +{
      +  "description": "score: max per option (default 5); meeting: 2.",
      +  "maximum": 9007199254740991,
      +  "minimum": -9007199254740991,
      +  "type": "integer"
      +}
    • addedInput schema / properties / maximum_stance_choices
      Added value: +{
      +  "description": "Max options per voter (poll: 1; raise for multi-choice).",
      +  "exclusiveMinimum": 0,
      +  "maximum": 9007199254740991,
      +  "type": "integer"
      +}
    • addedInput schema / properties / meeting_duration
      Added value: +{
      +  "description": "meeting: slot minutes. No default through the API.",
      +  "exclusiveMinimum": 0,
      +  "maximum": 9007199254740991,
      +  "type": "integer"
      +}
    • addedInput schema / properties / min_score
      Added value: +{
      +  "description": "score: min per option (default 0).",
      +  "maximum": 9007199254740991,
      +  "minimum": -9007199254740991,
      +  "type": "integer"
      +}
    • addedInput schema / properties / minimum_stance_choices
      Added value: +{
      +  "description": "Min options per voter (ranked_choice: ranks, default 3).",
      +  "maximum": 9007199254740991,
      +  "minimum": 0,
      +  "type": "integer"
      +}
    • changedInput schema / properties / notify_on_closing_soon / description
      Previous value: -"Who Loomio notifies as the closing date approaches. Defaults to 'nobody'."New value: +"24h closing reminder; API default is 'nobody'."
    • changedInput schema / properties / notify_on_closing_soon / enum
      Previous value: -[
      -  "nobody",
      -  "author",
      -  "voters",
      -  "undecided_voters",
      -  "all_members"
      -]New value: +[
      +  "nobody",
      +  "author",
      +  "undecided_voters",
      +  "voters"
      +]
    • addedInput schema / properties / notify_on_open
      Added value: +{
      +  "description": "Announce (`poll_announced`) on opening; Loomio's default is TRUE.",
      +  "type": "boolean"
      +}
    • changedInput schema / properties / notify_recipients / description
      Previous value: -"If false, suppress the initial notification email. Defaults to false."New value: +"Email/push the named recipients; SEPARATE from notify_on_open."
    • changedInput schema / properties / options / description
      Previous value: -"Voting options. `proposal` has built-in agree/disagree/abstain options; for poll / count / score / ranked_choice / meeting / dot_vote you MUST supply your own."New value: +"Option names in order. REQUIRED except 'question'; ranked_choice/stv need 2+."
    • changedInput schema / properties / poll_type / description
      Previous value: -"Poll type. One of: proposal, poll, count, score, ranked_choice, meeting, dot_vote."New value: +"'question' has no options; 'meeting' options are ISO-8601 times; 'stv' takes stv_seats."
    • changedInput schema / properties / poll_type / enum
      Previous value: -[
      -  "proposal",
      -  "poll",
      -  "count",
      -  "score",
      -  "ranked_choice",
      -  "meeting",
      -  "dot_vote"
      -]New value: +[
      +  "proposal",
      +  "poll",
      +  "count",
      +  "score",
      +  "ranked_choice",
      +  "meeting",
      +  "dot_vote",
      +  "check",
      +  "question",
      +  "stv"
      +]
    • addedInput schema / properties / reason_prompt
      Added value: +{
      +  "description": "Prompt above the reason box.",
      +  "type": "string"
      +}
    • addedInput schema / properties / recipient_audience / description
      Added value: +"'group' = every member (needs announce permission)."
    • addedInput schema / properties / recipient_emails / description
      Added value: +"Emails to invite; non-members become guests."
    • changedInput schema / properties / recipient_emails / items / pattern
      Previous value: -"^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"New value: +"^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"
    • addedInput schema / properties / recipient_message / description
      Added value: +"Text for the notification."
    • addedInput schema / properties / recipient_user_ids / description
      Added value: +"User ids to invite / notify."
    • addedInput schema / properties / show_none_of_the_above
      Added value: +{
      +  "description": "Offer 'none of the above' (poll, ranked_choice).",
      +  "type": "boolean"
      +}
    • changedInput schema / properties / shuffle_options / description
      Previous value: -"If true, shuffle option display order."New value: +"Randomise option order per voter."
    • changedInput schema / properties / specified_voters_only / description
      Previous value: -"If true, only users in recipient_user_ids / recipient_emails can vote."New value: +"Only the named recipients may vote."
    • addedInput schema / properties / stance_reason_required
      Added value: +{
      +  "description": "Default 'optional'; anonymous polls force 'disabled'.",
      +  "enum": [
      +    "disabled",
      +    "optional",
      +    "required",
      +    "required_for_disagree_or_block",
      +    "required_for_block"
      +  ],
      +  "type": "string"
      +}
    • addedInput schema / properties / stv_seats
      Added value: +{
      +  "description": "stv: seats to fill.",
      +  "exclusiveMinimum": 0,
      +  "maximum": 9007199254740991,
      +  "type": "integer"
      +}
    • addedInput schema / properties / tags
      Added value: +{
      +  "description": "Tags for a standalone poll's thread.",
      +  "items": {
      +    "minLength": 1,
      +    "type": "string"
      +  },
      +  "type": "array"
      +}
    • removedInput schema / properties / title / description
      Removed value: -"Poll title (required)."
    • addedInput schema / properties / topic_id
      Added value: +{
      +  "description": "Thread id (`topic_id` on any thread row); no extra call.",
      +  "exclusiveMinimum": 0,
      +  "maximum": 9007199254740991,
      +  "type": "integer"
      +}
  4. First observedv0.0.6

TDQS

A4.3/5.0
Behavior4/5

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

Annotations already establish this is a non-read-only, non-idempotent, non-destructive write. The description adds genuinely valuable behavioral consequences beyond them: omitting `closing_at` saves the poll UNOPENED and returns `opened: false` plus a warning, and `notify_on_open` defaults to TRUE so opening announces the poll.

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 call shape and required parameters, then the critical `closing_at` caveat, then the announcement default. It is dense but almost every clause carries actionable information; minor density cost keeps it from a 5.

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 32-parameter creation tool with no output schema, the description covers the essential creation paths, required-field pitfalls, and side effects. Per-type option details are correctly delegated to the schema descriptions, though a brief note on what a successful response contains could help.

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

Parameters4/5

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

Schema coverage is already 94%, so the baseline is 3, but the description meaningfully elevates it by stating conditional requirements that the schema only partially encodes: `options` is effectively required except for 'question', and a group or thread identifier is needed in practice. It also distinguishes `notify_on_open` from other notification behavior.

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?

Opens with a specific verb and resource ('Create a poll') and immediately adds consequential scope detail: one call, or two when `discussion_id` is used. It is trivially distinguishable from siblings like `update_poll`, `delete_poll`, and `list_polls`.

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

Usage Guidelines4/5

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

Gives clear when-to-use context: `group_id` for a standalone poll versus `discussion_id`/`topic_id` inside a thread, and explains the quiet-create case via `notify_on_open: false`. It does not explicitly route to `update_poll` for later changes, but the create-vs-update distinction is implicit and clear.

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