> ## Documentation Index > Fetch the complete documentation index at: https://dev.polltheroom.com/llms.txt > Use this file to discover all available pages before exploring further. # Tools > Every tool the MCP server offers, with its arguments. Generated from the server's own tools/list. This page is generated from the server's `tools/list` at `https://test.polltheroom.com/api/mcp` by `scripts/developers-sync.mjs`. The full input schema of every tool, including every widget, travels with the tool itself. The tools are the API's verbs under the same names. A tool needs the scope its verb needs; a tool that cannot do what was asked answers with a result marked `isError` and a sentence saying what to fix. ## Decks A deck is a document the editor and the API both read and write. | tool | does | | ---------------- | ------------------------------------------- | | `list_decks` | List decks | | `create_deck` | Create a deck | | `get_deck` | Get a deck | | `update_deck` | Change a deck | | `delete_deck` | Bin a deck | | `add_step` | Add a step | | `replace_step` | Replace a step | | `remove_step` | Remove a step | | `add_overlay` | Put a poll on a slide | | `get_outline` | Outline a deck | | `get_step` | Read one step | | `update_overlay` | Change a card | | `remove_overlay` | Take a card off a slide | | `add_element` | Put text, a shape or a picture on a slide | | `update_element` | Change text, a shape or a picture | | `remove_element` | Take text, a shape or a picture off a slide | | `duplicate_step` | Copy a step | | `move_step` | Move a step | | `get_screenshot` | Screenshot a step | | `list_fonts` | List the fonts | | `attach_pdf` | Attach the slides as a PDF | ### `list_decks` The decks this key may see: its maker's own plus the team's shared ones. The bin is left out. Needs the "decks:read" scope. Takes no arguments. ### `create_deck` This is the verb an agent starts from. Send a whole document, or nothing for a blank deck that opens with the join screen and one empty slide. A deck can be saved half-finished; presenting needs every poll to pass the readiness check. Needs the "decks:write" scope. | argument | required | meaning | | ---------- | -------- | ------------------------------------------------------------ | | `title` | no | The deck's name | | `document` | no | The deck document (see DeckDocument). Omit for a blank deck. | ### `get_deck` The whole document, the same shape the editor holds. Needs the "decks:read" scope. | argument | required | meaning | | -------- | -------- | ------------- | | `id` | yes | The deck's id | ### `update_deck` Rename, star, or replace the whole document. A replace, never a merge: send the document as you want it to be. To change one step, use the step verbs instead. Needs the "decks:write" scope. | argument | required | meaning | | ---------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `id` | yes | The deck's id | | `title` | no | The deck's name | | `document` | no | The whole document, replaced | | `starred` | no | | | `revision` | no | The deck's revision you read (from get\_deck or the last write). Sent, the write lands only if nobody changed the deck since; left out, it goes through regardless | ### `delete_deck` Into the bin, the same as the app. Thirty days later it is gone for good. Needs the "decks:write" scope. | argument | required | meaning | | -------- | -------- | ------------- | | `id` | yes | The deck's id | ### `add_step` Append a slide or a poll step, or insert it before a given index, without resending the document. The join screen is step 0 and there is only one. Needs the "decks:write" scope. | argument | required | meaning | | ---------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `id` | yes | The deck's id | | `step` | yes | A step, exactly as in the document; ids may be left out | | `at` | no | Insert before this index. Left out, the step goes at the end | | `revision` | no | The deck's revision you read (from get\_deck or the last write). Sent, the write lands only if nobody changed the deck since; left out, it goes through regardless | ### `replace_step` Put a new slide or poll step where one is now. Needs the "decks:write" scope. | argument | required | meaning | | ---------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `id` | yes | The deck's id | | `index` | yes | The step's index. 0 is the join screen and stays put | | `step` | yes | A step, exactly as in the document; ids may be left out | | `revision` | no | The deck's revision you read (from get\_deck or the last write). Sent, the write lands only if nobody changed the deck since; left out, it goes through regardless | ### `remove_step` Take a slide or poll step out. The join screen stays. Needs the "decks:write" scope. | argument | required | meaning | | ---------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `id` | yes | The deck's id | | `index` | yes | The step's index. 0 is the join screen and stays put | | `revision` | no | The deck's revision you read (from get\_deck or the last write). Sent, the write lands only if nobody changed the deck since; left out, it goes through regardless | ### `add_overlay` Drop a poll onto a slide as a floating card, the way the editor does: send the poll, and optionally where (rect) and how it is drawn (style); what you leave out gets the house default. The slide's other content is untouched. For a poll that fills the screen, use add\_step instead. Needs the "decks:write" scope. | argument | required | meaning | | ---------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `id` | yes | The deck's id | | `index` | yes | The slide step's index | | `poll` | yes | The poll, as in the document | | `rect` | no | Where the card sits; left out, the bottom-right quarter | | `style` | no | How the card is drawn; anything left out is the house default | | `revision` | no | The deck's revision you read (from get\_deck or the last write). Sent, the write lands only if nobody changed the deck since; left out, it goes through regardless | ### `get_outline` Every step in a line: kind, page, notes, and for a slide every element's rect and label, which elements cover each other, and its warnings, without the pictures' bytes. Read this first to find your way around a deck, the way Paper's get\_tree\_summary reads a file; get\_deck returns the whole document, images included. Needs the "decks:read" scope. | argument | required | meaning | | -------- | -------- | ------------- | | `id` | yes | The deck's id | ### `get_step` One step exactly as it is in the document, with its layout: every element's rect and which elements cover each other. Cheaper than get\_deck when you work on one slide, and where you read a card's index before update\_overlay or remove\_overlay. Needs the "decks:read" scope. | argument | required | meaning | | -------- | -------- | -------------------------------------- | | `id` | yes | The deck's id | | `index` | yes | The step's index; 0 is the join screen | ### `update_overlay` Change one card on a slide without resending the slide: the poll, where it sits (rect) or how it is drawn (style), each merged over what is there; what you leave out stays. Read the card's index with get\_step. The way Paper's update\_styles and move\_nodes act on one node. Needs the "decks:write" scope. | argument | required | meaning | | ---------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `id` | yes | The deck's id | | `index` | yes | The slide step's index | | `card` | yes | The card's index on the slide, counting from 0; read it with get\_step | | `poll` | no | Poll properties to change; the rest stay | | `rect` | no | Where the card sits now | | `style` | no | Style properties to change; the rest stay | | `revision` | no | The deck's revision you read (from get\_deck or the last write). Sent, the write lands only if nobody changed the deck since; left out, it goes through regardless | ### `remove_overlay` Remove one card from a slide; everything else on the slide stays. Read the card's index with get\_step. Needs the "decks:write" scope. | argument | required | meaning | | ---------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `id` | yes | The deck's id | | `index` | yes | The slide step's index | | `card` | yes | The card's index on the slide, counting from 0; read it with get\_step | | `revision` | no | The deck's revision you read (from get\_deck or the last write). Sent, the write lands only if nobody changed the deck since; left out, it goes through regardless | ### `add_element` Add one text box, shape or image to a slide without resending it: send exactly one of text, shape or image, as in the document. A card is added with add\_overlay. Like a text box, a picture is placed by its rect; the slide clips what runs past it. Needs the "decks:write" scope. | argument | required | meaning | | ---------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `id` | yes | The deck's id | | `index` | yes | The slide step's index | | `text` | no | | | `shape` | no | | | `image` | no | | | `revision` | no | The deck's revision you read (from get\_deck or the last write). Sent, the write lands only if nobody changed the deck since; left out, it goes through regardless | ### `update_element` Change one text box, shape or image on a slide: send the properties to change under text, shape or image (matching the kind in the path); they are merged over what is there, style included, and what you leave out stays. Read the element's index with get\_step. Needs the "decks:write" scope. | argument | required | meaning | | ---------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `id` | yes | The deck's id | | `index` | yes | The slide step's index | | `kind` | yes | | | `element` | yes | The element's index in its list, counting from 0 | | `text` | no | For a text box: the properties to change | | `shape` | no | For a shape: the properties to change | | `image` | no | For an image: the properties to change | | `revision` | no | The deck's revision you read (from get\_deck or the last write). Sent, the write lands only if nobody changed the deck since; left out, it goes through regardless | ### `remove_element` Remove one text box, shape or image from a slide; everything else stays. Read the element's index with get\_step. Needs the "decks:write" scope. | argument | required | meaning | | ---------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `id` | yes | The deck's id | | `index` | yes | The slide step's index | | `kind` | yes | | | `element` | yes | The element's index in its list, counting from 0 | | `revision` | no | The deck's revision you read (from get\_deck or the last write). Sent, the write lands only if nobody changed the deck since; left out, it goes through regardless | ### `duplicate_step` Insert a copy of a step right after it, with fresh ids for the step and everything on it, the way Paper's duplicate\_nodes clones a node. The join screen cannot be copied. Needs the "decks:write" scope. | argument | required | meaning | | ---------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `id` | yes | The deck's id | | `index` | yes | The step's index. 0 is the join screen and stays put | | `revision` | no | The deck's revision you read (from get\_deck or the last write). Sent, the write lands only if nobody changed the deck since; left out, it goes through regardless | ### `move_step` Move a step to another position; the steps in between shift by one. The join screen stays at 0 and nothing lands before it. Ids do not change. Needs the "decks:write" scope. | argument | required | meaning | | ---------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `id` | yes | The deck's id | | `index` | yes | The step's index. 0 is the join screen and stays put | | `to` | yes | The index to land on | | `revision` | no | The deck's revision you read (from get\_deck or the last write). Sent, the write lands only if nobody changed the deck since; left out, it goes through regardless | ### `get_screenshot` A PNG of one step as the room will see it: the slide's page with its cards, text, shapes and images on it, or the full-screen poll the way the audience screen draws it. Beside the picture come the numbers: every element's rect, the pairs that overlap, `warnings` for a card too small to read or over another card or text box, `coversPageText`, the PDF page's own words a card or text box hides, and `measured`, each card and text box as the drawing measured it: cut off by its box, and how high its biggest answer text is drawn. Send `annotate` to have every element's box and name drawn on the picture, the clashing ones in red and the hidden words tinted; `element` to crop to one element, the way Paper screenshots one node; `scale` 2 for twice the pixels. Rendered on the server in a real browser, so the first look takes a few seconds; the same step at the same revision comes straight back. Through MCP the image arrives as an image; over HTTP, read `png` as a data URL or send `Accept: image/png` for the bytes. Needs the "decks:read" scope. | argument | required | meaning | | ---------- | -------- | ------------------------------------------------------------------ | | `id` | yes | The deck's id | | `index` | yes | The step's index; the join screen (0) has no picture | | `scale` | no | 1 (the default) for 1600 pixels wide, 2 for 3200 | | `element` | no | Crop to this element, as get\_step names it: "overlay 0", "text 1" | | `annotate` | no | Draw every element's box and name on the picture, clashes in red | ### `list_fonts` The font keys a text box's `font` and a card's `textFont` take, with the family each one draws. Send `deck` to add the fonts that deck uploaded, which are named by their family. What Paper's get\_font\_family\_info answers for a design file. Needs the "decks:read" scope. | argument | required | meaning | | -------- | -------- | ----------------------------------------- | | `deck` | no | A deck's id, to add the fonts it uploaded | ### `attach_pdf` Put the presenter's own slides behind the deck. The editor renders the pages when the deck is opened, so polls can float on the real slides. With `pages`, and while no slide has a page yet, the blank slides are replaced by one slide per page, in order, after the join screen; polls and paged slides already there are kept. PDF only for now. Needs the "decks:write" scope. | argument | required | meaning | | ---------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `id` | yes | The deck's id | | `pdf` | yes | The PDF file, base64 encoded (24 MB at most) | | `pages` | no | How many pages the PDF has; makes one slide step per page when the deck has none yet | | `revision` | no | The deck's revision you read (from get\_deck or the last write). Sent, the write lands only if nobody changed the deck since; left out, it goes through regardless | ## Rooms A room is one live session of a deck. | tool | does | | -------------- | ---------------- | | `list_rooms` | List rooms | | `start_room` | Start a room | | `room_action` | Drive a room | | `room_results` | Read the results | ### `list_rooms` The team's rooms, newest first, fifty at most. Send deckId for the sessions one deck has run, each with the name it was started under, so the same deck used for five classes lists five sessions. Needs the "rooms:read" scope. | argument | required | meaning | | -------- | -------- | ---------------------------------------- | | `deckId` | no | Only the sessions started from this deck | ### `start_room` Open a room for a deck: a six-digit code the audience joins with, and a presenter link that carries the host's key. The room waits in the lobby until the presenter (or `room_action` with `start`) begins. A deck with slide pages starts here too: the server draws every page of its PDF first, the way the editor does, which adds a few seconds. Needs the "rooms:start" scope. | argument | required | meaning | | -------- | -------- | --------------------------------------------------------------------------------------------------------- | | `deckId` | yes | The deck's id | | `label` | no | A name for this session, such as "Class 3B, Tuesday", so a deck used for several classes lists them apart | ### `room_action` What the presenter's buttons do: start the session, walk to the next or previous step, close the live poll and reveal, or stop the session; spin the wheel on screen, show or hide the join code in the corner of the audience screen (chip), or switch live reactions on or off. Needs the "rooms:start" scope. | argument | required | meaning | | -------- | -------- | ------------------------------------------------------- | | `code` | yes | The room's six-digit code | | `action` | yes | start, next, prev, close, stop, spin, chip or reactions | ### `room_results` Every poll's results so far, as JSON and as a markdown summary. Works while the room is live and after it ended; once the app no longer holds the room, the results saved when its last poll closed or it ended come back instead. Needs the "results:read" scope. | argument | required | meaning | | -------- | -------- | ------------------------- | | `code` | yes | The room's six-digit code |