Skip to main content
Glama

Make a Polemia quiz

create_quiz

Make a new live multiple-choice quiz on Polemia about any topic, ready to play on phones with a join code. Use it when the user wants a quiz, trivia game or icebreaker for a class, party, family, team or pub quiz. Takes 10 to 60 seconds. Returns join_url and code (for the players), host_url (for the person running the game: opening it makes that browser the host, and it works once), qr_url (a QR code image of the join link) and how_it_works, a short explanation of the game. Always give the user both host_url and join_url. "facts" quizzes have right answers; "opinions" quizzes are scored by what the majority picks. Topics that target people, politics, war or adult material are refused.

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": {
      "topic": "<topic>"
    },
    "name": "create_quiz"
  }
}

Input Schema

NameRequiredDescriptionDefault
kindNo"facts": questions with a right answer. "opinions": fun questions where the most popular answer scores.facts
topicYesWhat the quiz is about, e.g. "volcanoes", "Harry Potter", "the human body for 9 year olds".
languageNoWrite the quiz in this language (BCP-47, e.g. "es", "de", "pt-BR"). Leave out to use the language the topic is written in.
questionsNoHow many questions, 1 to 25.
for_children_underNoMake every question suitable for children under this age.

Output Schema

NameRequiredDescriptionDefault
codeYesThe join code players type at polemia.ai.
kindYes
topicYes
qr_urlYes
host_urlYes
join_urlYes
languageYes
questionsYes
how_it_worksYes
host_link_expires_atYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed3 schema fields changed
    • addedOutput schema / properties / how_it_works
      Added value: +{
      +  "type": "string"
      +}
    • removedOutput schema / properties / instructions
      Removed value: -{
      -  "type": "string"
      -}
    • changedOutput schema / required
      Previous value: -[
      -  "code",
      -  "join_url",
      -  "host_url",
      -  "qr_url",
      -  "questions",
      -  "kind",
      -  "language",
      -  "topic",
      -  "host_link_expires_at",
      -  "instructions"
      -]New value: +[
      +  "code",
      +  "join_url",
      +  "host_url",
      +  "qr_url",
      +  "questions",
      +  "kind",
      +  "language",
      +  "topic",
      +  "host_link_expires_at",
      +  "how_it_works"
      +]
  2. First observed

TDQS

A4.3/5.0
Behavior5/5

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

Goes well beyond the annotations: discloses generation latency ('10 to 60 seconds'), explains that host_url 'works once' (reinforcing idempotentHint=false), and states the content-refusal policy for people/politics/war/adult topics. These are exactly the behavioral facts an agent cannot infer from the structured fields.

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?

Front-loads purpose, then triggers, then cost, then return values, then hard constraints. Each sentence adds a distinct piece of information with no repetition, even across five sentences.

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?

Despite an output schema existing, it usefully summarizes the key returns (join_url, code, host_url, qr_url) and, crucially, advises 'Always give the user both host_url and join_url' — a usage rule not encoded anywhere else. Content policy and latency complete the picture for a one-call generative tool.

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

Parameters3/5

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

Schema coverage is 100%, so all five parameters are already documented. The description restates the facts/opinions distinction the schema already carries and adds nothing about questions, language, or for_children_under, so the schema does the heavy lifting — baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource ('Make a new live multiple-choice quiz on Polemia') with clear scope ('about any topic', 'ready to play on phones with a join code'). The creation intent implicitly contrasts with retrieval siblings like find_quizzes, but it never names an alternative explicitly to lock down the distinction.

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?

Enumerates concrete trigger conditions — 'when the user wants a quiz, trivia game or icebreaker for a class, party, family, team or pub quiz' — so an agent can match intent reliably. It gives no explicit when-not-to-use or pointer to a sibling, which keeps it just short of a 5.

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.

Resources