annotate_screenshot
ChatGPTUse this when the user wants to point something out on a screenshot: circle or highlight a button, add an arrow or a numbered callout, or blur personal data. Do not use for changing the website itself, for cropping, or for images that are not in ScreenshotAgent. Mark up a screenshot: circle, highlight or point an arrow at an element, add a numbered callout, blur sensitive data, or wrap it in a browser frame. A vision model finds the element and ScreenshotAgent draws the marks on top of the original capture, so the screenshot's own pixels are never changed. The result is saved as a new version; the original capture is kept. Name the element in instructions, e.g. presets ["hand_drawn_circle"] with instructions "the Approve button". Without presets you get a hand-drawn circle; without instructions the most important call to action is marked. It works on the stored image only and does not visit the screenshot's URL. Uses one AI annotation from the team's monthly allowance (separate from captures; a browser frame alone is free) and fails without charging when the allowance is used up or the element can't be found. Each call queues another annotation and another new version, so do not repeat a call that is still running. Returns an annotation uuid; poll get_annotation_status every 5-10 seconds until done is true. It marks the latest capture unless version_id is given: the version_id of an entry in get_screenshot's recent_versions, not its version_number.
approve_version
ChatGPTUse this when the user wants a new capture to go live, wants to go back to an older version, or wants to dismiss a capture. Do not use for making a private screenshot public (that is done in the dashboard), or without the user's go-ahead. Decide on a version of a screenshot. action "approve" (default) makes the version the one embeds show, replacing the image that is live on every page embedding it: approve a waiting capture, or pass an older version to revert to it. Confirm with the user before reverting. Approving anything other than the newest capture switches the screenshot to "Needs approval" so the next capture does not replace it (switched_to_approval is true). action "dismiss" stops asking about a waiting version without making it live; embeds keep showing the live version. Needs a token with the manage scope, created by a teammate who can approve screenshots. Returns the version beside the live one after the change.
create_screenshot
ChatGPTCreate a new, persistent screenshot of a web page and queue its first capture. ScreenshotAgent's capture agent opens the URL in a sandboxed browser, follows your instructions, and saves a versioned PNG image. Instructions can make the agent act on the target site, for example clicking tabs, closing pop-ups, or filling in a form field with a value you name; it only clicks buttons that create, change, submit or delete something when the instructions explicitly ask for that action. The saved instructions are replayed on every later recapture. To capture just one section, describe it in part_of_page. The URL must be reachable from the internet (no localhost or private network hosts). Pages behind a login work when you pass the project_id of a project whose site login is set up in the ScreenshotAgent dashboard; the capture signs in with that saved login. Never ask the user for passwords in chat. The new screenshot is private: it has no public embed URL until the user makes it public in the ScreenshotAgent dashboard. The response includes dashboard_url, a link to the screenshot in the dashboard; share it with the user when they want to publish or embed the image. By default the page is captured once, at desktop_1440 in the site's own color scheme. Pass sizes to capture exact browser sizes instead (one picture per size), and color_scheme "both" to capture each size once in light and once in dark. Each extra size or scheme is a variant of the same screenshot with its own image URL, listed under embed.variants in get_screenshot. Every image bills as one capture from the team's plan: 3 sizes in light and dark is 6 images, so 6 captures per run, on the first capture and on every recapture. The response reports this as captures_per_run. The call fails without creating anything when captures are paused, a daily limit was hit, or the plan has fewer captures left than the images it would produce. Each call creates another screenshot, so do not call it twice for the same page. Optionally pass frame to present the public image in a frame: padding on a background, rounded corners, a drop shadow, a 1px border and browser chrome. The frame is drawn on the served image only; captures stay raw, the frame can be changed later without recapturing, and adding ?frame=0 to an image URL serves it unframed. Without frame the screenshot follows its project's default frame, if any. Returns the new screenshot's id; its first capture is already queued, so do not call recapture for it. Poll get_capture_status with the id every 15-30 seconds until done is true.
get_annotation_status
ChatGPTUse this when the user wants to see the marked-up screenshot from annotate_screenshot, or to know whether it is ready. Do not use for checking a capture (use get_capture_status). Check an AI annotation queued by annotate_screenshot. Poll every 10-20 seconds. annotation.status is pending or processing while in progress, completed when the annotated version is saved, failed on error (see annotation.error; failed annotations are not charged). annotation.done is true once completed or failed, so check annotation.status before reporting success. When completed, annotated_version has the new version's details and URLs; pass its version_id to get_version_diff or approve_version. annotation.explanation says in one line what was marked (e.g. Blurred: profile photo (image next to "Dave Kiss")); annotation.marked lists each target with resolved_by, confidence, box and element, so you can check it landed on the right thing. needs_review is true when a recapture could not find a rule's remembered target with confidence: the capture is held for review instead of going live. In ChatGPT, Claude and other MCP Apps hosts the marked-up image shows to the user inline once the annotation is completed; don't also post it as a Markdown image.
get_capture_status
ChatGPTUse this when the user wants to know whether a screenshot they just asked for is ready, or to see it once it is. Do not use for showing a screenshot that was not just captured (use get_screenshot). Check the progress of a capture queued by recapture or create_screenshot. Captures usually take a minute or two. Pass wait_seconds (up to 15) to wait for the capture to finish before answering, so the image can show in the same reply; call again while done is false, and if it is still running, tell the user and offer to check again. busy is true when the server could not wait right now; then follow retry_hint and ask again in about 10 seconds rather than at once. status is pending or capturing while in progress, ready when done, failed on error (see error_message). done is true once the status is ready or failed, so check status before reporting success; when it failed, report error_message and do not present an earlier version as the new capture. phase is queued, capturing, ready or failed; it is not_captured when a queued capture never started, so recapture it instead of polling further. When ready, latest_version has the new version's details and URLs (a public pinned_url and embed URLs only if the screenshot is public). In ChatGPT, Claude and other MCP Apps hosts the finished image shows to the user inline once status is ready, so there's no need to call get_screenshot just to show it, and don't post it as a Markdown image.
get_screenshot
ChatGPTUse this when the user wants to see one screenshot, its versions, or the link to embed it in their docs. Do not use for taking a new screenshot, or for finding one by what is on it (use search_screenshots first). Get full detail for one screenshot by id: settings, tags, project, the last capture's status and error, and the 10 most recent versions. For public screenshots, embed contains the page URL, the always-latest image URL (use this in docs so the image updates itself), a Markdown snippet, a thumbnail URL, per-variant image URLs, and a template for pinning a specific version (replace {version} with a version_number). Each version has a version_id to pass to annotate_screenshot, get_version_diff and approve_version, its variant_key, is_live (embeds show it) and review_state (live, waiting_for_approval, held_for_review with review_reason, dismissed, or not_live). frame describes how the public image URLs present the capture (padding, background, radius, shadow, border, browser chrome) and where it comes from (screenshot, page, project or default). The embed URLs serve the framed image; raw_image_url (the image URL with ?frame=0) serves the capture as is. version file_url links are always raw. A version's pinned_url is set only while that version is the one published at the public URLs. Each version's file_url is a signed link to the raw file that expires after an hour (at file_url_expires_at); never paste it into docs. When one has expired, call get_screenshot again for a fresh link instead of recapturing. In ChatGPT, Claude and other MCP Apps hosts this tool shows the image to the user inline; don't also post it as a Markdown image.
get_version_diff
ChatGPTUse this when the user wants to see what changed between a new capture and the one that is live. Do not use for comparing two different pages, or images that are not in ScreenshotAgent. Compare one version of a screenshot with the live version its embeds show. Returns both versions with short-lived image_url links (open them to see the difference), is_live, waiting (and reason), and change_from_previous_percent: how much of the image changed since the capture before it.
list_projects
ChatGPTUse this when the user wants to see their projects or sites in ScreenshotAgent, or names a project to work in. Do not use for finding a screenshot (use search_screenshots) or for taking a new one. List the team's ScreenshotAgent projects. A project groups the screenshots of one site or app under a base URL. Returns each project's id (use it as project_id in list_screenshots, recapture and create_screenshot), name, base URL, screenshot count, capture schedule and has_login. has_login is true when the project has a site login saved in the dashboard: screenshots in that project capture signed in, so pass its id as project_id to capture pages behind the login. To list or filter screenshots (for example failed ones), call list_screenshots directly; it needs no project_id.
list_screenshots
ChatGPTUse this when the user wants to see all their screenshots, the newest ones, or the ones that failed or have a tag. Do not use for finding a screenshot by what is on it (use search_screenshots) or for taking a new one. List the team's screenshots, newest first, with optional filters. All filters combine with AND. Each item has the screenshot id (use it with get_screenshot, recapture and get_capture_status), uuid, name, target URL, status (pending, capturing, ready, failed), visibility, the time of the latest version, and public embed URLs when the screenshot is public (embed is null for private screenshots). Results are paginated: when has_more is true, call again with page + 1.
list_waiting_versions
ChatGPTUse this when the user wants to know what is waiting for their approval or review before it goes live. Do not use for listing all screenshots (use list_screenshots). List captures that are waiting for someone to approve them before embeds change, newest first. A capture waits when its screenshot's Updates setting is "Needs approval", or when it was held for review (reason says why, e.g. a blur could not be re-applied). Each item has the waiting version and the live version embeds show in its place, both with a version_id and short-lived image_url links to compare, plus change_from_previous_percent. Approve or dismiss with approve_version, passing the screenshot_id and version.version_id.
recapture
ChatGPTQueue fresh captures of existing screenshots, for example after a deploy changed the UI. Pick screenshots by screenshot_ids, tags, project_id, or all: true. Filters are combined as a union (OR): a screenshot matching any one of them is queued, so passing tags and project_id together selects more screenshots, not fewer. To recapture only the screenshots that match several conditions (for example one tag within one project), call list_screenshots with those filters, which combine with AND, and pass the ids it returns as screenshot_ids. Do not call it for a screenshot create_screenshot just made: its first capture is already queued. Finding, showing or linking a screenshot never needs a recapture. Each capture opens the screenshot's URL in ScreenshotAgent's sandboxed browser and follows its saved capture instructions, which may include clicks or form fills on that site. The new capture is saved as a new version; unless the screenshot needs approval, it becomes the image its embeds show. Capturing a page also queues captures of its saved views (child screenshots), which use captures too. Every image bills as one capture from the team's plan: a screenshot captured at several sizes, or in light and dark, uses one capture per image (3 sizes in light and dark is 6 captures). Only recapture what changed. The call fails without queueing anything when captures are paused or the plan has fewer captures left than the selection's images. When the team's daily capture budget runs out partway, only part of the selection is queued; the rest is reported under skipped_reasons.daily_cap_exceeded and can be retried tomorrow. Returns queued and skipped counts, captures_used (the images the queued screenshots produce, one capture each), skip reasons (already_capturing, daily_cap_exceeded, not_found), and queued_ids. After calling, poll get_capture_status with each queued id every 15-30 seconds until done is true.
search_screenshots
ChatGPTUse this when the user wants to find or see a screenshot they already have, described by what is on it, like "the pricing page" or "the settings screen in dark mode". Do not use for taking a new screenshot or for searching the web. Find screenshots by what they show. Searches each screenshot's name, tags, project, target URL and what the capture agent saw on the latest capture: page title, headings, a short description of the layout and notable elements, UI element labels (e.g. "Upgrade button", "Invoices table") and visible text. Use it for requests like "the billing settings page in dark mode", "the pricing table" or "the onboarding screenshots". Search matches by meaning as well as by keyword, so describe the screen in plain words ("change password" finds "Update credentials"); exact words from the page rank highest. Quoted phrases, OR and -exclusions keep exact keyword semantics. It searches recorded text and descriptions, not image pixels. Results are best match first and include pages and views. Each has the screenshot id (use it with get_screenshot, recapture and get_capture_status), uuid, name, score, matched_by ("keyword", with matching words in bold in the snippet, or "meaning", with the snippet taken from the closest field), page title, description, UI elements, the time of the latest version, and public embed URLs when the screenshot is public (embed is null for private screenshots). preview_url is a signed thumbnail link that expires after an hour; never paste it into docs. In ChatGPT, Claude and other MCP Apps hosts this tool shows the results to the user inline as a grid of thumbnails; don't also post them as Markdown images. Call get_screenshot when the user wants one result's full detail. Screenshots captured before search launched may only match on their name, tags and URL until they are recaptured.
