Skip to main content
Glama

vote_poll

Idempotent

Cast or change a vote on an open Signal poll in a DM or group by creator phone and poll timestamp, passing option indices; each call replaces your previous vote.

Instructions

Cast or change your vote on an open Signal poll in a DM or group; the vote is visible to participants. Use create_poll to start a poll, terminate_poll to close your own. A poll has no separate id: identify it by target_author (E.164 number of the poll's creator) + target_timestamp (ms timestamp of the poll message, from create_poll or get_conversation). votes: 0-based indices into the poll's options — exactly one for a single-choice poll, all chosen indices at once for multi-select (each call replaces your previous vote). Give recipient (E.164) for a DM poll or group_id for a group poll; neither is an error. Voting on a terminated poll fails. Contacts Signal's servers; a local per-poll counter is incremented so re-votes supersede earlier ones. Returns {status: 'vote sent'}.

Input Schema

NameRequiredDescriptionDefault
votesYesOption indices to vote for (0-based). Single item for single-choice polls.
group_idNoGroup ID for a group poll — provide this OR recipient
recipientNoPhone number for a DM poll — provide this OR group_id
target_authorYesPhone number of the poll creator (E.164)
target_timestampYesTimestamp of the poll message (from get_conversation)

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed2 schema fields changedv1.36.0
    • removedInput schema / properties / poll_id
      Removed value: -{
      -  "description": "Poll ID from the poll message data",
      -  "type": "integer"
      -}
    • changedInput schema / required
      Previous value: -[
      -  "target_author",
      -  "target_timestamp",
      -  "poll_id",
      -  "votes"
      -]New value: +[
      +  "target_author",
      +  "target_timestamp",
      +  "votes"
      +]
  2. Changed6 schema fields changedv0.1.2
    • changedInput schema / properties / group_id / description
      Previous value: -"Group ID for a group poll"New value: +"Group ID for a group poll — provide this OR recipient"
    • changedInput schema / properties / poll_id / description
      Previous value: -"Poll ID from the original poll message"New value: +"Poll ID from the poll message data"
    • changedInput schema / properties / recipient / description
      Previous value: -"Phone number for a DM poll"New value: +"Phone number for a DM poll — provide this OR group_id"
    • changedInput schema / properties / target_author / description
      Previous value: -"Phone number of the poll creator"New value: +"Phone number of the poll creator (E.164)"
    • changedInput schema / properties / target_timestamp / description
      Previous value: -"Timestamp of the poll message"New value: +"Timestamp of the poll message (from get_conversation)"
    • changedInput schema / properties / votes / description
      Previous value: -"List of option indices to vote for (0-based)"New value: +"Option indices to vote for (0-based). Single item for single-choice polls."
  3. First observedv0.1.0

TDQS

A4.9/5.0
Behavior5/5

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

Annotations already cover safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=true, openWorldHint=true). Description adds substantial context: vote visibility to participants, replacement semantics for re-votes, server contact, local per-poll counter, and return value. Aligns with annotations (idempotentHint matches re-vote superseding).

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 purpose and alternatives, but dense with multiple clauses in later sentences. Every sentence earns its place, though the description could be slightly trimmed without losing critical information.

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

Completeness5/5

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

No output schema exists, but the description provides the return value. Covers identification, parameter usage, failure conditions, and server interaction. Complete for a voting tool of this complexity.

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

Parameters5/5

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

Schema description coverage is 100%, so baseline is 3. However, the description adds meaning beyond schema: identification via target_author + target_timestamp, votes semantics (0-based indices, single-choice vs multi-select, each call replaces previous vote), and DM vs group parameter selection. This significantly enriches parameter understanding.

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+resource: 'Cast or change your vote on an open Signal poll in a DM or group.' Clearly distinguishes from siblings create_poll and terminate_poll, which are named as alternatives.

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?

Explicitly names create_poll and terminate_poll as alternative tools and their use cases. Also details how to identify the poll, which parameters to provide for DM vs group, and the failure condition (voting on a terminated poll fails).

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