Skip to main content
Glama
loomiomcp
by soil-dev

update_poll

DestructiveIdempotent

Edit an open Loomio poll by ID or key to change its title, details, options, closing time, or settings; poll type and anonymity stay fixed.

Instructions

Edit an OPEN poll by id_or_key: 1 call (2 with options). Pass only what changes: title, details (REPLACES the text), closing_at (future; opening a draft announces unless notify_on_open is false), options (names to ADD: merged with the current list, so it never removes an option it saw; not atomic), settings. Cannot change poll_type, anonymous, group or tags; a closed poll answers 403.

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": {
      "id_or_key": "<id_or_key>"
    },
    "name": "update_poll"
  }
}

Input Schema

NameRequiredDescriptionDefault
titleNo
detailsNo
optionsNoNames to ADD (+1 call): merged with the stored names, so it never removes an option it saw. Not atomic.
id_or_keyYesPoll id or short key.
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; omitted = unchanged. To end voting soon pass the next full hour.
hide_resultsNoCannot leave 'until_closed' once set.
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 / id_or_key / 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. Addedv0.0.13

TDQS

A4.6/5.0
Behavior5/5

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

Goes well beyond the annotations: `details` REPLACES existing text, `options` is additive-only and non-atomic, opening a draft auto-announces unless `notify_on_open` is false, and a closed poll returns 403. The call-cost note (1 call, 2 with `options`) adds operational context the annotations cannot express, and nothing conflicts with destructiveHint=true.

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

Conciseness5/5

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

A single front-loaded block that leads with the action and call cost, then enumerates mutable fields and finally hard constraints. No filler sentences; every clause carries a fact an agent needs before calling.

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 27-parameter mutation tool with no output schema, the description covers the dangerous and non-obvious paths (replacement, merge, immutability, 403). It omits the recipient/notification parameters and what the response contains, but those are documented in the schema.

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?

With 93% schema coverage the baseline is 3, but the description adds real meaning for the highest-risk parameters: replacement semantics for `details`, merge/append semantics for `options`, future-only `closing_at`, and the `notify_on_open` interaction. The invite/recipient family is left entirely to the schema, so not a 5.

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 ('Edit an OPEN poll by `id_or_key`') and immediately narrows scope to open polls. The list of editable and non-editable fields makes it unmistakable versus create_poll, get_poll, and delete_poll 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.

Usage Guidelines4/5

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

Gives clear operating context: pass only what changes, and what cannot be changed (`poll_type`, `anonymous`, group, tags) with a 403 for closed polls. It stops short of explicitly naming a sibling alternative (e.g. create_poll for new polls), so it is strong but not fully routing guidance.

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