Cobalt Capture

Fetch a Cobalt Capture review by its share link or slug. Returns the reviewer's notes as text AND each annotated screenshot as an image, so you can see exactly what was marked and what to change.

{
  "type": "object",
  "properties": {
    "review": {
      "description": "A Cobalt review URL (https://cobaltcapture.com/r/<slug> or /s/<slug>) or just the slug.",
      "type": "string"
    }
  },
  "required": [
    "review"
  ]
}

Start a new Cobalt Capture review and get a handle for filling it in. Use this to compile the findings of any site study — a usability pass, a pricing teardown, a positioning audit, a QA run — into one shareable, durable report with real screenshots. Works from any client, chat assistants included: with no browser, add_screenshot(page_url=...) renders the pages for you. Returns a `review` slug and a `claim_token` — pass BOTH back to add_screenshot / add_note to append content. Also returns a `review_url` to share and a `save_url` the human opens (while signed in) to save the review to their account permanently. The review is anonymous and auto-deletes after 30 days unless saved.

{
  "type": "object",
  "properties": {
    "product_url": {
      "description": "Optional URL of the product/site under review.",
      "type": "string"
    },
    "summary": {
      "description": "Optional overview shown at the top of the review (plain text or markdown). Good place for the overall task, outcome, and headline findings.",
      "type": "string"
    },
    "title": {
      "description": "Title of the review, e.g. 'Onboarding walkthrough — Jupiter Invoice'.",
      "type": "string"
    }
  },
  "required": [
    "title"
  ]
}

Append a screenshot (with an optional note) to a review created by create_review. The image is stored durably in Cobalt — this is the way to persist screenshots that would otherwise be lost when they only pass through a browser tool. Call once per screen as you go. NO BROWSER? Pass `page_url` and Cobalt renders the page for you (Cloudflare headless Chrome): `viewport` 'desktop' (1280px) or 'mobile' (390px phone, 2x), `full_page` true for the whole scroll. Use it for every screen you would otherwise only describe in text — a review without screenshots is a reduced deliverable, and the mobile viewport is how you test the phone fold without a device. The result includes the rendered image: LOOK AT IT before moving on. Cookie walls and modal veils are stripped automatically, but if what came back is still not the shot (an overlay, a blank, the wrong page), retake it in place with replace_screenshot(item=<that item's number>), adding `hide_selectors` for anything you can name — never leave a useless capture in the review and never append a second copy after it. This tool only ever appends; it never changes an existing item. Otherwise the input is `image_url`: POST the image to https://cobaltcapture.com/api/upload (multipart field `file`, no auth, returns {url, key}) and pass back the url. If a browser-automation script took the screenshot, do that POST inside the same script (Python `requests.post(...)`, or Playwright's request context) rather than shelling out to curl afterwards — same result, one less permission prompt. The `image` base64 parameter exists for small images only: tool-call arguments are model-generated text, so a real screenshot means emitting tens of thousands of base64 tokens perfectly, and an image you received as an image cannot be transcribed at all.

{
  "type": "object",
  "properties": {
    "claim_token": {
      "description": "The claim_token from create_review (authorizes the write). For a review the human has SAVED to their account, pass the agent token they generated on the review page (Export & more → Hand to your agent) here instead.",
      "type": "string"
    },
    "comment": {
      "description": "Optional note describing what this screen shows or what's wrong with it.",
      "type": "string"
    },
    "full_page": {
      "description": "With page_url: capture the entire scrollable page instead of the first viewport. Default false. Prefer the fold first; use full_page for one overview shot. Sites that scroll inside an inner container (some app-style marketing pages) come back fold-sized regardless — if that happens, say so rather than retrying.",
      "type": "boolean"
    },
    "hide_selectors": {
      "description": "With page_url: extra CSS selectors to hide before the shot (e.g. ['#newsletter-modal', '.chat-widget']) when the returned image shows something still covering the page. Common cookie/consent banners are already removed on every render.",
      "items": {
        "type": "string"
      },
      "maxItems": 10,
      "type": "array"
    },
    "image": {
      "description": "For SMALL images only (< ~100 KB) that you already hold as base64 text: a base64-encoded PNG/JPEG/WebP (data: URL prefix accepted). Not the path for screenshots — emitting one as tool-call text is slow and error-prone, and an image you received as an image cannot be transcribed. Upload it and pass image_url instead.",
      "type": "string"
    },
    "image_url": {
      "description": "The image URL returned by Cobalt's own upload: POST the file as multipart field `file` to https://cobaltcapture.com/api/upload (returns {url, key}) — ideally from inside the script that captured it — or use the browser hook window.cobaltGrab(). Must be on Cobalt's own image host; external URLs are refused.",
      "type": "string"
    },
    "page_url": {
      "description": "A public http(s) page for Cobalt to render and screenshot server-side — the path when you have no browser or screenshot tool of your own (chat clients, text-only agents). Public pages only: nothing behind a login you signed into in your own session. Becomes the item's source_url unless you pass one. Takes 10–30 s (bot checks are waited through); a site that hard-blocks automated browsers returns a clear error — report that as a coverage gap, don't retry.",
      "type": "string"
    },
    "review": {
      "description": "The review slug or URL from create_review.",
      "type": "string"
    },
    "source_url": {
      "description": "Optional URL of the page the screenshot was taken on.",
      "type": "string"
    },
    "title": {
      "description": "Optional short caption for the screenshot.",
      "type": "string"
    },
    "viewport": {
      "description": "With page_url: 'desktop' (1280x800, default) or 'mobile' (390x844 phone, 2x, touch) — the way to test the phone fold.",
      "enum": [
        "desktop",
        "mobile"
      ],
      "type": "string"
    }
  },
  "required": [
    "review",
    "claim_token"
  ]
}

Overwrite one existing screenshot in a review with a new capture, in the same position. Use it when the image add_screenshot returned is not the shot (a cookie wall or overlay, a blank, the wrong page): retaking in place keeps the review clean instead of leaving a useless capture and a second copy after it. DESTRUCTIVE: the old image and any pins or annotations on it are removed and cannot be recovered; the title and comment are replaced only if you pass new ones. Screenshots only, never notes. Takes the same capture arguments as add_screenshot, plus `item`, the 1-based number of the screenshot to replace.

{
  "type": "object",
  "properties": {
    "claim_token": {
      "description": "The claim_token from create_review (authorizes the write). For a review the human has SAVED to their account, pass the agent token they generated on the review page (Export & more → Hand to your agent) here instead.",
      "type": "string"
    },
    "comment": {
      "description": "Optional note describing what this screen shows or what's wrong with it.",
      "type": "string"
    },
    "full_page": {
      "description": "With page_url: capture the entire scrollable page instead of the first viewport. Default false. Prefer the fold first; use full_page for one overview shot. Sites that scroll inside an inner container (some app-style marketing pages) come back fold-sized regardless — if that happens, say so rather than retrying.",
      "type": "boolean"
    },
    "hide_selectors": {
      "description": "With page_url: extra CSS selectors to hide before the shot (e.g. ['#newsletter-modal', '.chat-widget']) when the returned image shows something still covering the page. Common cookie/consent banners are already removed on every render.",
      "items": {
        "type": "string"
      },
      "maxItems": 10,
      "type": "array"
    },
    "image": {
      "description": "For SMALL images only (< ~100 KB) that you already hold as base64 text: a base64-encoded PNG/JPEG/WebP (data: URL prefix accepted). Not the path for screenshots — emitting one as tool-call text is slow and error-prone, and an image you received as an image cannot be transcribed. Upload it and pass image_url instead.",
      "type": "string"
    },
    "image_url": {
      "description": "The image URL returned by Cobalt's own upload: POST the file as multipart field `file` to https://cobaltcapture.com/api/upload (returns {url, key}) — ideally from inside the script that captured it — or use the browser hook window.cobaltGrab(). Must be on Cobalt's own image host; external URLs are refused.",
      "type": "string"
    },
    "item": {
      "description": "The 1-based number of the existing screenshot item to overwrite (as it appears in the review, counting notes).",
      "minimum": 1,
      "type": "integer"
    },
    "page_url": {
      "description": "A public http(s) page for Cobalt to render and screenshot server-side — the path when you have no browser or screenshot tool of your own (chat clients, text-only agents). Public pages only: nothing behind a login you signed into in your own session. Becomes the item's source_url unless you pass one. Takes 10–30 s (bot checks are waited through); a site that hard-blocks automated browsers returns a clear error — report that as a coverage gap, don't retry.",
      "type": "string"
    },
    "review": {
      "description": "The review slug or URL from create_review.",
      "type": "string"
    },
    "source_url": {
      "description": "Optional URL of the page the screenshot was taken on.",
      "type": "string"
    },
    "title": {
      "description": "Optional short caption for the screenshot.",
      "type": "string"
    },
    "viewport": {
      "description": "With page_url: 'desktop' (1280x800, default) or 'mobile' (390x844 phone, 2x, touch) — the way to test the phone fold.",
      "enum": [
        "desktop",
        "mobile"
      ],
      "type": "string"
    }
  },
  "required": [
    "review",
    "claim_token",
    "item"
  ]
}

Append a free-standing text note (not tied to a screenshot) to a review created by create_review. Use for context, steps taken, or a summary of findings between screenshots.

{
  "type": "object",
  "properties": {
    "claim_token": {
      "description": "The claim_token from create_review (authorizes the write). For a review the human has SAVED to their account, pass the agent token they generated on the review page (Export & more → Hand to your agent) here instead.",
      "type": "string"
    },
    "review": {
      "description": "The review slug or URL from create_review.",
      "type": "string"
    },
    "text": {
      "description": "The note text (plain text or markdown).",
      "type": "string"
    }
  },
  "required": [
    "review",
    "claim_token",
    "text"
  ]
}

Update a review's summary and/or title after the fact. Use this at the END of a run to land the verdict at the TOP of the review: the headline findings don't exist until the work is done, but readers (and agents ingesting the review) want them before scrolling past every intermediate screenshot. Prefer this over burying conclusions in a closing note.

{
  "type": "object",
  "properties": {
    "claim_token": {
      "description": "The claim_token from create_review (authorizes the write). For a review the human has SAVED to their account, pass the agent token they generated on the review page (Export & more → Hand to your agent) here instead.",
      "type": "string"
    },
    "compared_to": {
      "description": "Optional: if this run RE-RAN an earlier study (compare mode), the prior review's slug or URL you compared against. Set it when finalizing a re-run so the improvement-over-time is recorded.",
      "type": "string"
    },
    "review": {
      "description": "The review slug or URL from create_review.",
      "type": "string"
    },
    "summary": {
      "description": "The overview shown at the top of the review — put the headline findings and outcome here. Replaces any existing summary.",
      "type": "string"
    },
    "title": {
      "description": "Optional replacement title.",
      "type": "string"
    }
  },
  "required": [
    "review",
    "claim_token"
  ]
}

Fetch a Cobalt study playbook by name and follow it exactly. Works from ANY client — a coding agent driving a browser, or a chat assistant with no browser (Claude chat, Cowork, ChatGPT): the public-page studies run in full from chat, because add_screenshot(page_url=...) renders the pages for you. Use this when the user asks for any kind of site review, audit, teardown, or test and you don't already have the playbook text. Available: 'pricing_teardown' — can a buyer tell what they'd pay and which tier is theirs (public pages: runs anywhere); 'website_teardown' — visual website teardown: what each key page puts first and what it says, judged cold and then through the site's likely visitors; 'positioning_pass' is its old name (public pages: runs anywhere); 'comparison_study' — two or three products compared for one buying decision, with a sourced matrix and an overall lean (public pages plus web search: runs anywhere); 'usability_pass' — first-time-user usability audit: signs up with a disposable inbox, drives the product, finds friction (needs a browser you control); 'flow_pass' — walks a specific flow the user names, signup/checkout/invite, including any email it sends (needs a browser you control); 'investigation_pass' — the general product investigator for an app you OWN, run in its own environment (needs a browser and usually the repo). All deliver a shareable Cobalt review. If the user's study is NONE of these, do not bend it into the nearest one — its lenses and severity labels will mislabel the findings; run the generic method in the server instructions instead. Prefer this over fetching the playbook from a URL: it comes through the protocol complete, whereas web fetchers summarize it and a summarized playbook silently drops the instructions that make the run work.

{
  "type": "object",
  "properties": {
    "name": {
      "description": "Playbook name, e.g. 'usability_pass'.",
      "type": "string"
    },
    "url": {
      "description": "The site to run it against, if you already know it.",
      "type": "string"
    }
  },
  "required": [
    "name"
  ]
}

Search the studies Cobalt Capture has published on well-known products: pricing teardowns, positioning audits, and head-to-head comparisons (for example Canva pricing, Spotify vs Apple Music). Returns matching studies as {id, title, url}; pass an id to fetch for the full text. It does NOT search private reviews, which are reachable only by their link (use get_review, or fetch with the review URL).

{
  "type": "object",
  "properties": {
    "query": {
      "description": "What to look for, e.g. 'canva pricing' or 'spotify'.",
      "type": "string"
    }
  },
  "required": [
    "query"
  ]
}

Fetch the full text of a Cobalt study by the id search returned, or of any Cobalt review by its URL (/r/<slug>) or slug. Returns text: findings, prices, the comparison matrix, and the underlying review's notes with links to its screenshots. Use get_review instead when you need to see the screenshots as images.

{
  "type": "object",
  "properties": {
    "id": {
      "description": "An id from search (e.g. 'teardown:canva'), or a review URL or slug.",
      "type": "string"
    }
  },
  "required": [
    "id"
  ]
}

Create a disposable email inbox you can monitor, for signing up to the product you're testing. Returns an `address` to type into the signup form and an `inbox_token` to read it with. Use this instead of asking the human for an email account or a third-party inbox API key — no setup needed. Inboxes are temporary; create a fresh one per test persona.

{
  "type": "object",
  "properties": {
    "review": {
      "description": "Optional review slug this inbox belongs to — a label for your own bookkeeping.",
      "type": "string"
    }
  }
}

Read mail delivered to an inbox from create_inbox — e.g. to pull a verification code or confirmation link out of a signup email. Returns newest-first. Mail usually lands within seconds; if the response is empty, wait a few seconds and call again (there is no blocking wait). Extract the code or link yourself and continue the flow in the browser. Pass format="html" when you are AUDITING the email rather than reading a code out of it: the default text view flattens away the layout, typography and branding, which is exactly what an email audit is judging.

{
  "type": "object",
  "properties": {
    "address": {
      "description": "The inbox address from create_inbox.",
      "type": "string"
    },
    "format": {
      "description": "\"text\" (default) flattens each message to readable text — right for pulling a code or link. \"html\" returns the raw HTML part instead, for auditing the email as a rendered artifact: write it to a file, open it in the browser, and screenshot it.",
      "enum": [
        "text",
        "html"
      ],
      "type": "string"
    },
    "inbox_token": {
      "description": "The inbox_token from create_inbox (authorizes reading).",
      "type": "string"
    }
  },
  "required": [
    "address",
    "inbox_token"
  ]
}

Email a link to a finished review to the human who started the run, so they don't have to remember to come back for it — useful at the end of a long unattended study. Pass the review, its claim_token, and the human's email. IMPORTANT: we only send to a VERIFIED COBALT ACCOUNT address (this prevents the tool being used to send spam); if the address isn't a Cobalt account, the call is refused with a message telling the human to create a free account at cobaltcapture.com with that address first. The email contains only a link to the review — no text you provide — so ask the human for their account email and pass it verbatim.

{
  "type": "object",
  "properties": {
    "claim_token": {
      "description": "The claim_token from create_review (proves you created this review), or, for a saved review, the agent token its owner generated on the review page (Export & more → Hand to your agent).",
      "type": "string"
    },
    "email": {
      "description": "The human's Cobalt account email. Must belong to a verified account, or the send is refused.",
      "type": "string"
    },
    "review": {
      "description": "The review slug or URL from create_review.",
      "type": "string"
    }
  },
  "required": [
    "review",
    "claim_token",
    "email"
  ]
}