Skip to main content
Glama

AskOne: Live Q&A and Polls

by io.github.phuryn
OverviewDiscussionsAdmin

Add and launch a poll

create_survey

Add a poll, quiz, rating or word cloud to a room and launch it so the audience answers on their phones (launching needs an open room); launch=false saves a draft instead. Use it during a session to ask the audience something. type=poll takes 2-8 options (allow_multiple for several choices), quiz takes options plus correct_option (zero-based), rating takes scale 5 or 10, word_cloud takes no options. Results are shown to the audience by default; show_results=false keeps them private. Returns the survey with its id and the request_id; keep that request_id, because calling again with the same survey fields, that request_id and launch=true is how a saved draft is launched once the room is open. Read answers with get_survey_results and end a live survey with close_survey. Needs rooms:write; pass a request_id UUID and resend the same one to retry safely.

Input Schema

NameRequiredDescriptionDefault
codeYesThe room's six-character code (letters and digits, any case), from list_rooms or create_room.
typeYespoll: people pick from options. quiz: options with one correct answer. rating: a score on a 1-5 or 1-10 scale. word_cloud: short free-text answers shown as a cloud.
scaleNoRating only: 5 or 10 points. Default 5.
launchNotrue (default) launches the survey at once, which needs an open room; false saves a draft. To launch a saved draft later, call again with the same survey fields, its request_id and launch=true.
optionsNoRequired for poll and quiz: 2 to 8 distinct answer options. Leave it out for rating and word_cloud.
questionYesThe question the audience answers; plain text, 1 to 200 characters.
low_labelNoRating only: optional label for the lowest score, up to 80 characters.
high_labelNoRating only: optional label for the highest score, up to 80 characters.
request_idNoA UUID you generate; resend the same one to retry safely without creating a second survey. If omitted, the server generates one and returns it.
room_titleNoPlugin-compatible new-room title; unused because code selects an existing room.
show_resultsNoWhether the audience may see results. Default true, as in the console; false keeps them private. Screens show only the live surveys or the latest closed batch; close_survey can change this later.
allow_multipleNoPoll only: true lets each person pick more than one option. Default false.
correct_optionNoQuiz only, and required for a quiz: the zero-based index in options of the correct answer.

Output Schema

NameRequiredDescriptionDefault
roomYes
surveyYes
host_urlYes
join_urlYes
request_idYes
projector_urlYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed13 schema fields changed
    • addedInput schema / properties / allow_multiple / description
      Added value: +"Poll only: true lets each person pick more than one option. Default false."
    • addedInput schema / properties / code / description
      Added value: +"The room's six-character code (letters and digits, any case), from list_rooms or create_room."
    • addedInput schema / properties / correct_option / description
      Added value: +"Quiz only, and required for a quiz: the zero-based index in options of the correct answer."
    • addedInput schema / properties / high_label / description
      Added value: +"Rating only: optional label for the highest score, up to 80 characters."
    • addedInput schema / properties / launch / description
      Added value: +"true (default) launches the survey at once, which needs an open room; false saves a draft. To launch a saved draft later, call again with the same survey fields, its request_id and launch=true."
    • addedInput schema / properties / low_label / description
      Added value: +"Rating only: optional label for the lowest score, up to 80 characters."
    • addedInput schema / properties / options / description
      Added value: +"Required for poll and quiz: 2 to 8 distinct answer options. Leave it out for rating and word_cloud."
    • addedInput schema / properties / options / items / description
      Added value: +"One answer option, 1 to 80 characters."
    • addedInput schema / properties / question / description
      Added value: +"The question the audience answers; plain text, 1 to 200 characters."
    • addedInput schema / properties / request_id / description
      Added value: +"A UUID you generate; resend the same one to retry safely without creating a second survey. If omitted, the server generates one and returns it."
    • addedInput schema / properties / scale / description
      Added value: +"Rating only: 5 or 10 points. Default 5."
    • addedInput schema / properties / type / description
      Added value: +"poll: people pick from options. quiz: options with one correct answer. rating: a score on a 1-5 or 1-10 scale. word_cloud: short free-text answers shown as a cloud."
    • changedOutput schema / (root)
      Previous value: -nullNew value: +{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "properties": {
+    "host_url": {
+      "type": "string"
+    },
+    "join_url": {
+      "type": "string"
+    },
+    "projector_url": {
+      "type": "string"
+    },
+    "request_id": {
+      "type": "string"
+    },
+    "room": {
+      "properties": {
+        "closed_at": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "code": {
+          "type": "string"
+        },
+        "counts": {
+          "properties": {
+            "active": {
+              "minimum": 0,
+              "type": "integer"
+            },
+            "answered": {
+              "description": "Included in questions.",
+              "minimum": 0,
+              "type": "integer"
+            },
+            "participants": {
+              "minimum": 0,
+              "type": "integer"
+            },
+            "pending": {
+              "minimum": 0,
+              "type": "integer"
+            },
+            "questions": {
+              "description": "Approved and answered questions.",
+              "minimum": 0,
+              "type": "integer"
+            }
+          },
+          "required": [
+            "questions",
+            "pending",
+            "answered",
+            "participants",
+            "active"
+          ],
+          "type": "object"
+        },
+        "created_at": {
+          "type": "string"
+        },
+        "description": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "name": {
+          "type": "string"
+        },
+        "opened_at": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "status": {
+          "description": "prepared: not joinable yet; open: live; closed: not joinable, content stays readable.",
+          "enum": [
+            "prepared",
+            "open",
+            "closed"
+          ],
+          "type": "string"
+        }
+      },
+      "required": [
+        "code",
+        "name",
+        "status",
+        "description",
+        "created_at",
+        "opened_at",
+        "closed_at",
+        "counts"
+      ],
+      "type": "object"
+    },
+    "survey": {
+      "properties": {
+        "average": {
+          "anyOf": [
+            {
+              "type": "number"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "correct_option_id": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "id": {
+          "type": "string"
+        },
+        "kind": {
+          "enum": [
+            "choice",
+            "rating",
+            "word_cloud"
+          ],
+          "type": "string"
+        },
+        "max_label": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "min_label": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "mode": {
+          "anyOf": [
+            {
+              "enum": [
+                "single",
+                "multiple"
+              ],
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "options": {
+          "items": {
+            "properties": {
+              "count": {
+                "anyOf": [
+                  {
+                    "minimum": 0,
+                    "type": "integer"
+                  },
+                  {
+                    "type": "null"
+                  }
+                ]
+              },
+              "id": {
+                "type": "string"
+              },
+              "label": {
+                "type": "string"
+              },
+              "position": {
+                "type": "integer"
+              },
+              "score": {
+                "type": "integer"
+              }
+            },
+            "required": [
+              "id",
+              "label",
+              "position",
+              "count"
+            ],
+            "type": "object"
+          },
+          "type": "array"
+        },
+        "position": {
+          "type": "integer"
+        },
+        "question": {
+          "type": "string"
+        },
+        "respondents": {
+          "anyOf": [
+            {
+              "minimum": 0,
+              "type": "integer"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "results_public": {
+          "type": "boolean"
+        },
+        "status": {
+          "description": "draft: not launched; live: taking answers; closed: no longer taking answers.",
+          "enum": [
+            "draft",
+            "live",
+            "closed"
+          ],
+          "type": "string"
+        },
+        "words": {
+          "items": {
+            "properties": {
+              "count": {
+                "minimum": 0,
+                "type": "integer"
+              },
+              "word": {
+                "type": "string"
+              }
+            },
+            "required": [
+              "word",
+              "count"
+            ],
+            "type": "object"
+          },
+          "type": "array"
+        }
+      },
+      "required": [
+        "id",
+        "kind",
+        "question",
+        "status",
+        "position",
+        "mode",
+        "results_public",
+        "respondents",
+        "options"
+      ],
+      "type": "object"
+    }
+  },
+  "required": [
+    "room",
+    "survey",
+    "join_url",
+    "projector_url",
+    "host_url",
+    "request_id"
+  ],
+  "type": "object"
+}
  2. Changed1 schema field changed
    • changedInput schema / properties / show_results / description
      Previous value: -"Whether the audience sees results (after answering, and on screens once closed). Default true, as in the console; false keeps them private. A closed survey can be removed from screens later with close_survey."New value: +"Whether the audience may see results. Default true, as in the console; false keeps them private. Screens show only the live surveys or the latest closed batch; close_survey can change this later."
  3. Added

TDQS

A4.8/5.0
Behavior5/5

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

Annotations cover the safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=true, idempotentHint=false), and the description adds genuinely new operational context: rooms:write is required, launching needs an open room, show_results defaults to audience-visible, and re-sending the same request_id makes retries safe despite the non-idempotent hint. That idempotency nuance reconciles the non-idempotent annotation with the retry instruction, which is exactly the kind of context annotations cannot convey.

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?

The description is dense but front-loaded, with the core action first and the mode-specific rules, results visibility, retry guidance and sibling pointers following. It is longer than minimal and could be trimmed, but nearly every clause carries information the agent needs, so little is wasted.

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 tool with a rich output schema and full schema coverage, the description supplies the lifecycle context (draft vs launch, how to launch a draft later, retry with request_id), permissions, and the sibling tools for the follow-up steps. 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 description coverage is 100%, so the baseline would be 3, but the description adds conditional semantics the schema cannot express per-field: poll takes 2-8 options, quiz additionally needs correct_option (zero-based), rating takes scale 5 or 10, word_cloud takes no options. The cross-parameter dependency between type and options/correct_option/scale is the key added value.

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 description opens with a specific verb and resource — 'Add a poll, quiz, rating or word cloud to a room and launch it' — covering all four modes and the launch/save-draft distinction. It names the sibling tools that handle the adjacent lifecycle steps (get_survey_results, close_survey), so the agent can separate it from them 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 Guidelines5/5

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

It gives explicit when-to-use ('during a session to ask the audience something'), the launch=false draft path with the launch-time requirement of an open room, and the alternative tools for reading answers and closing the survey. The when/when-not branches are all present with the condition that selects each.

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

All AskOne: Live Q&A and Polls toolsInspect
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