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 one screenshot, with an optional title and note, to the end of a review. The image is stored in Cobalt and shown in the review. Three ways to supply it: `page_url`, a public page that Cobalt renders in a headless browser (`viewport` 'desktop' at 1280px or 'mobile' at 390px, `full_page` for the whole scroll, `hide_selectors` for elements to hide; common cookie banners are hidden automatically), which also returns the rendered image; `image_url`, an image already uploaded to https://cobaltcapture.com/api/upload; or `image`, a small base64 image. This tool only appends; it never changes an existing item (replace_screenshot does that).

{
  "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. Pages that scroll inside an inner container come back viewport-sized.",
      "type": "boolean"
    },
    "hide_selectors": {
      "description": "With page_url: extra CSS selectors to hide before the shot, e.g. ['#newsletter-modal', '.chat-widget']. Common cookie and consent banners are hidden on every render.",
      "items": {
        "type": "string"
      },
      "maxItems": 10,
      "type": "array"
    },
    "image": {
      "description": "A small base64-encoded PNG, JPEG or WebP (data: URL prefix accepted). Intended for images under about 100 KB; larger screenshots are better uploaded and passed as image_url.",
      "type": "string"
    },
    "image_url": {
      "description": "An image URL on Cobalt's own image host, as returned by https://cobaltcapture.com/api/upload (multipart field `file`, returns {url, key}) or by the editor's window.cobaltGrab(). External URLs are refused.",
      "type": "string"
    },
    "page_url": {
      "description": "A public http(s) page for Cobalt to render and screenshot server-side. Pages behind a login can't be rendered. Becomes the item's source_url unless one is passed. Takes 10 to 30 seconds; a site that blocks automated browsers returns an error.",
      "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).",
      "enum": [
        "desktop",
        "mobile"
      ],
      "type": "string"
    }
  },
  "required": [
    "review",
    "claim_token"
  ]
}

Overwrite one existing screenshot in a review with a new capture, in the same position. Destructive: the old image and any pins or annotations on it are removed and cannot be recovered; the title and comment change only if new ones are passed. Works on screenshots only, not 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. Pages that scroll inside an inner container come back viewport-sized.",
      "type": "boolean"
    },
    "hide_selectors": {
      "description": "With page_url: extra CSS selectors to hide before the shot, e.g. ['#newsletter-modal', '.chat-widget']. Common cookie and consent banners are hidden on every render.",
      "items": {
        "type": "string"
      },
      "maxItems": 10,
      "type": "array"
    },
    "image": {
      "description": "A small base64-encoded PNG, JPEG or WebP (data: URL prefix accepted). Intended for images under about 100 KB; larger screenshots are better uploaded and passed as image_url.",
      "type": "string"
    },
    "image_url": {
      "description": "An image URL on Cobalt's own image host, as returned by https://cobaltcapture.com/api/upload (multipart field `file`, returns {url, key}) or by the editor's window.cobaltGrab(). 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. Pages behind a login can't be rendered. Becomes the item's source_url unless one is passed. Takes 10 to 30 seconds; a site that blocks automated browsers returns an error.",
      "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).",
      "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"
  ]
}

Set or replace a review's summary and/or title. The summary is shown at the top of the review, above every screenshot and note. Replaces any existing summary or title.

{
  "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: when this run repeats an earlier study, the earlier review's slug or URL. Recorded so re-runs can be compared over time.",
      "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. Replaces any existing summary.",
      "type": "string"
    },
    "title": {
      "description": "Optional replacement title.",
      "type": "string"
    }
  },
  "required": [
    "review",
    "claim_token"
  ]
}

Return the full text of a Cobalt study playbook: a step-by-step method for a kind of product review that ends in a shareable Cobalt review. Available: 'pricing_teardown' (can a buyer tell what they would pay and which tier fits; public pages only); 'website_teardown' (what each key page leads with and says, judged as a first-time visitor; public pages only; 'positioning_pass' is its old name); 'comparison_study' (two or three products compared for one buying decision, with a sourced matrix; public pages plus web search); 'usability_pass' (a first-time-user audit that signs up and uses the product; needs a browser); 'flow_pass' (one named flow such as signup or checkout, including its emails; needs a browser); 'investigation_pass' (a product investigation of an app the user owns, run in its own environment; needs a browser and usually the code). The public-page studies work without a browser because add_screenshot(page_url) renders pages server-side.

{
  "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 temporary email inbox for signing up to a product under test. Returns an `address` to enter in the signup form and an `inbox_token` for reading it with check_inbox. Inboxes expire after a day.

{
  "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, newest first, for example a verification code or confirmation link from a signup email. Returns immediately; mail usually arrives within seconds, so an empty result can be checked again shortly. format="html" returns each message's HTML for reviewing the email's design.

{
  "type": "object",
  "properties": {
    "address": {
      "description": "The inbox address from create_inbox.",
      "type": "string"
    },
    "format": {
      "description": "\"text\" (default) returns each message flattened to readable text, with link targets kept. \"html\" returns the raw HTML part.",
      "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 review to the person who ran the study. Sends only to an address that belongs to a verified Cobalt account (other addresses are refused, which keeps the tool from being used to send unsolicited mail). The email contains only the review link, never text supplied in the call.

{
  "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"
  ]
}