get_delivery_status
ChatGPTUse this when the user asks whether a screen you published is showing yet ("is it showing?", "did it work?"). Pass the job_id publish_screen returned. Returns status: ready (waiting for the frame's next check-in, about a minute), displayed, superseded (a newer screen replaced it), held (another screen is held up until later), offline (the frame hasn't checked in: it shows the screen when it reconnects; pass on message and hint) or failed with an error. No job_id in this chat? list_frames shows whether the frame is online. Read-only.
get_design_guide
ChatGPTUse this once per conversation before designing your first screen, or when the user asks how to make screens look good. Returns Mantel's full guide: when to draw, how the 1-bit panel renders, type sizes, layout, photo cards, which tool to use for each kind of photo, routines and the setup playbook. Read-only.
list_frames
ChatGPTUse this whenever you need a frame_id or routine_id, or when the user asks which frames they have, who can draw on one, what's scheduled, or whether a frame is online. Returns their own frames (role owner) and frames shared with them (role guest) with display_name, owner_name, online, paused and web_url; on their own frames also guests (first name, masked email) and routines. Rules: people say "Nick's frame", "Josephina's frame" or a room: match display_name, owner_name or name. now_showing says who put the current screen up ("you", a first name, "Mantel") and when. connection has Wi-Fi signal and restarts; if connection.hint is set, tell the user. Drawings for an offline frame wait and show when it reconnects. If setup_needed is true, first do what the user asked, then offer once: "Want me to set up your Mantel?". On guest frames never offer setup or routines. Read-only.
list_photos
ChatGPTUse this when the user mentions a photo already saved to Mantel ("show my beach photo", "use the dog picture"). Returns their Mantel photo library, newest first, with names. Pick the best name match and pass its photo_id to publish_screen (or place it in an SVG as href="photo:<photo_id>"). For a photo attached in this chat, use manage_photos upload_link (Claude) or image_file (ChatGPT) instead. Read-only.
manage_frame
ChatGPTUse this to rename a frame, pause or resume it ("freeze the kitchen frame"), share it ("let Ada draw on my frame"), remove a guest ("stop sharing with Ada") or leave a frame shared with you. share returns a single-use invite link (7 days) and a ready-to-send message; list_invites shows unused links (created, expires) and revoke_invite (invite_id) cancels one. Rules: share only when the user explicitly asks in this chat; confirm who it's for first; show the link only to the user, never send it anywhere else. Only the owner can rename, share, list_invites, revoke_invite, remove_person, pause or resume. person: a guest's first name or masked email from list_frames. Releasing a frame isn't a tool: give the user web_url.
manage_photos
ChatGPTUse this when the user attaches a photo for the frame and you can run shell commands (Claude with code execution, Claude Code), or asks to rename or delete a saved photo. upload_link returns a single-use upload_url (10 minutes) and a curl command: replace FILE with the original file's path and run it; it prints JSON with photo_id, then call publish_screen with it. If the command fails (the sandbox can't reach Mantel), don't ask the user to change settings: send a small image_base64 instead. In ChatGPT use image_file. rename and delete take photo_id from list_photos; delete only when the user asks.
publish_screen
ChatGPTUse this when the user asks to show, draw, display or put anything on their Mantel ("show me…", "put the weather on my frame", "show my beach photo", "leave a note on Nick's frame"), and for the welcome screen and routines (run_routine says what to draw). Draw right away; don't ask first. Works on the user's frames and frames shared with them. It replaces what the frame shows; the frame updates within about a minute. Call get_design_guide once before your first screen in a conversation. Send exactly one source: svg (preferred, 800x480); photo_id (a Mantel library photo, see list_photos; inside an SVG use <image href="photo:pho_..." preserveAspectRatio="xMidYMid slice"/>); image_file (ChatGPT: a photo the user attached); image_url (https photo on the web); image_base64 (last resort). A photo attached in Claude: call manage_photos with action upload_link first, then pass its photo_id. Never threshold, dither, darken or crop photos yourself and leave mode unset: Mantel does that. If the reply says the screen is mostly black, redo it on white. The canvas is 800 x 480 pixels, pure black and white, viewed from across a room. E-ink rules: draw <rect width="800" height="480" fill="#fff"/> first. Only #000 and #fff: light gray vanishes, darker gray turns solid black. No dark or "dark mode" backgrounds: keep black under ~30% of the screen (black fills only for one header bar up to 80 px tall, or small badges); if over 1/3 would be black, invert the design. Bold (700) for anything read from afar: key number or headline 96-160 px, headings 56-72 px, body 36 px or more, nothing under 28 px; at most 6 lines, about 40 words. Strokes 4 px or more, dividers 6 px or more, no hairlines. Margins 40 px or more; group with white space, not filled boxes. Charts: schematic, bars and lines 8 px or more, at most 5 labels. Photos: pass photo_id or <image href="photo:pho_..."> and let Mantel brighten and dither it; never threshold, dither or darken it yourself. Photo cards: photo at least 280 px wide, text beside it (not on it), at most 2 photos. Pick bright, high-contrast photos with large faces; avoid night or busy shots. Full-bleed photo: caption on a solid black bar up to 72 px tall, white bold text 36 px or more. SVG filters are ignored; keep text under 5,000 characters and images under 4 megapixels.
run_routine
ChatGPTRead a saved Mantel routine when the user requests a refresh or an authorized scheduled task runs. Returns the routine configuration, enabled status, frame and rendering guidance. This tool does not fetch data from other services or publish a screen. Any later data access or screen update requires the user's existing authorization and the relevant tool's permissions. If the routine is disabled, report that status without updating the frame. No paid plan required for manual refresh. Say 'refresh my Mantel' any time. Owner only. Read-only in Mantel.
save_routine
ChatGPTUse this to create or change a recurring screen (a routine), and when the setup card saves: "every weekday at 6:45 show my brief", "add the Warriors", "move it to 7:30", "turn off my morning screen", "delete game nights". Send routine_id (or frame_id + name) and only what changes; frame_id, time and timezone create one. enabled: false pauses it; delete: true removes it. Returns routine, task_prompt, needs_task_update. Rules: if needs_task_update, create the scheduled task in this app with exactly task_prompt (update the existing one, never duplicate); else the task still works. No paid plan or no scheduled tasks: say so in one line, draw it now (run_routine), offer a longer-lasting version (a this-week screen, hold_until if useful) and say "Say 'refresh my Mantel' any time." Owner only; draws nothing.
set_up_mantel
ChatGPTUse this when the user says "set up my Mantel", "set up my frame", "help me get started" or "redo my setup", or has just connected Mantel. Safe to re-run. Before calling, guess from what you know and pass it: time, days, timezone, city, items, topics, quote_style and up to 3 ideas made for their life; leave out what you can't guess. In apps that show cards this opens a setup card for their "Morning brief" routine, pre-filled (a saved routine plus your guesses); tapping Save calls save_routine. Returns their frames with routines, the card's values and the playbook: follow it. Without a card, confirm in one line, then call save_routine. Only the user's own frames: a guest gets guest mode (no card, nothing saved). Draws nothing.