Tools - Poll the Room

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

​Decks

​list_decks

​create_deck

​get_deck

​update_deck

​delete_deck

​add_step

​replace_step

​remove_step

​add_overlay

​get_outline

​get_step

​update_overlay

​remove_overlay

​add_element

​update_element

​remove_element

​duplicate_step

​move_step

​get_screenshot

​list_fonts

​attach_pdf

​Rooms

​list_rooms

​start_room

​room_action

​room_results

Decks

`list_decks`

`create_deck`

`get_deck`

`update_deck`

`delete_deck`

`add_step`

`replace_step`

`remove_step`

`add_overlay`

`get_outline`

`get_step`

`update_overlay`

`remove_overlay`

`add_element`

`update_element`

`remove_element`

`duplicate_step`

`move_step`

`get_screenshot`

`list_fonts`

`attach_pdf`

Rooms

`list_rooms`

`start_room`

`room_action`

`room_results`