Skip to main content
Glama

Create Poll

create_poll

Make a live poll people vote on from a link, with results you can read back. Use it whenever your user asks for a poll, a vote or a quick survey, instead of writing one out in the chat, which cannot collect votes; never make one they did not ask for or agree to. Give a question and 2 to 6 options; type is "pick_one" (default), "pick_several" (with optional min_picks and max_picks) or "ranked" (voters put the options in order; the Borda count decides). write_in: true lets voters add their own answer that others can then pick (pick_one and pick_several only, never on a public document). Optional: when it closes (closes_at as an ISO time, or closes_in of 1h, 1d, 3d or 1w), close_after_votes, and who sees results before it closes (results_visibility: always, after_vote (default), after_close, owner_only). Leave document out and Gryz makes a short private document that holds the poll. Pass document (the slug of a Markdown or HTML document your user owns) to add the poll to it: for a Markdown document the result gives a small block to put where the question sits, with the document edit tools, and people cannot vote until it is there. For an HTML document the poll shows after the page at once, and the result also gives markup you can restyle and put in the page so the poll sits where the question is: a click on an option opens a Gryz vote box where the person confirms. A ranked poll has no markup and always shows after the page. A poll is as private as its document: whoever can open the document can vote. You never vote, and there is no tool that does. The question and options you send are shown to people as written. With projects on, add project (a project id from list_projects) to put the new short document in one of your user's projects.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "create_poll"
  }
}

Input Schema

NameRequiredDescriptionDefault
typeNo"pick_one" (default), "pick_several" or "ranked" (voters put the options in order)
optionsNo2 to 6 options, 1 to 80 characters each, no links, no repeats
projectNoA project id from list_projects: the new short document goes in that project. Not together with document.
documentNoSlug of a Markdown or HTML document your user owns. Leave out for a new short private document.
questionNoThe question, 1 to 200 characters. Neutral wording.
templateNoA starting point when you leave out the question or the options: pick_one, go_no_go, prioritize, confidence, retro_pulse, quick_vote, pick_a_date
write_inNoLet voters add their own answer, which others can then pick. pick_one and pick_several only, never on a public document. Default false.
closes_atNoWhen it closes, as an ISO 8601 time. Not together with closes_in.
closes_inNoHow long until it closes: 1h, 1d, 3d, 1w. Not together with closes_at.
max_picksNopick_several only: the most options a voter picks (default all)
min_picksNopick_several only: the fewest options a voter picks (default 1)
close_after_votesNoClose when this many people have voted (2 to 10000)
results_visibilityNoWho sees counts before it closes: always, after_vote (default), after_close, owner_only

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observed

TDQS

A4.8/5.0
Behavior5/5

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

Beyond the annotations (readOnlyHint=false, openWorldHint=true), the description discloses the privacy model ('a poll is as private as its document'), that Markdown documents require the returned block to be inserted before voting works, that HTML polls appear immediately and support markup, that ranked polls have no markup, and that the agent itself can never vote.

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 usage rules before the mechanics, which is the right order for a 13-parameter tool. It is dense with long sentences and repeats a few schema facts (the closes_in values, the type enum), but nearly every clause carries operational 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?

For a 13-parameter, zero-required, no-output-schema creation tool, the description covers creation, visibility, closing rules, document attachment behavior, and post-creation steps (inserting the block or markup). Nothing an agent needs to call this correctly is missing.

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 100%, so the baseline is 3, but the description adds real meaning: why 'ranked' matters (Borda count decides), the interaction constraint that write_in is invalid on public documents, how document/project interact, and that closes_in accepts only 1h/1d/3d/1w. Some of this duplicates schema text, keeping it short of 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?

The first sentence states a specific verb and resource ('Make a live poll people vote on from a link') plus the outcome ('results you can read back'), which distinguishes it cleanly from get_poll and close_poll. An agent knows exactly what this creates without opening the 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?

It gives explicit positive guidance ('use it whenever your user asks for a poll, a vote or a quick survey, instead of writing one out in the chat, which cannot collect votes') and an explicit exclusion ('never make one they did not ask for or agree to'). It also routes the document vs. no-document decision and points at list_projects for the project parameter.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.