Annotated-screenshot reviews and ready-made product studies your AI agent can read, run, and share.
Scored across 12 tools
Most tools target a distinct resource and action (create_review, add_note, add_screenshot, replace_screenshot, check_inbox, create_inbox). The one real overlap is fetch vs get_review: both accept a review slug/URL, and only the descriptions clarify that fetch returns text and get_review returns images. The append-vs-replace distinction is explicitly called out, which keeps the rest clean.
Nearly every tool follows a snake_case verb_noun pattern (add_note, create_review, check_inbox, update_review, replace_screenshot). The deviations are the bare verbs `fetch` and `search`, which drop the noun and are less self-describing than their siblings. Still readable and highly predictable overall.
12 tools is squarely in the well-scoped range, and each tool maps to a concrete step: set up a review, append content, share/export it, plus research helpers (search, fetch, get_playbook) and an inbox pair for signup testing. Nothing looks redundant or padded.
The review lifecycle is largely covered: create, update title/summary, append screenshots and notes, replace a screenshot, read back text and images, and email it. The notable gap is deletion — there is no way to remove a note, remove a screenshot, or delete a review, so a mistaken append is a dead end. No item reordering or note editing either, though those are less critical.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| text | Yes | The note text (plain text or markdown). | |
| review | Yes | The review slug or URL from create_review. | |
| claim_token | Yes | 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. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false, destructiveHint=false, and openWorldHint=true, so the safety profile is known. The description adds value by clarifying that notes are appended (additive, non-destructive) and that the target review must originate from create_review; it does not cover editability or persistence limits of a note.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two compact sentences with no filler; the core action and scope constraint are front-loaded before the usage examples.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple append tool with full schema coverage, no output schema, and safety annotations present, the description supplies enough context to invoke it correctly. Return behavior and whether notes are editable remain unstated, but those are minor for an additive note tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and the schema documents all three parameters in detail, including the claim_token authorization and the saved-review token alternative. The description adds only the link between 'review' and create_review, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (append) and resource (free-standing text note), and scopes it precisely with 'not tied to a screenshot ... to a review created by create_review'. This distinguishes it cleanly from the add_screenshot sibling.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says when to use it ('for context, steps taken, or a summary of findings between screenshots') and the parenthetical 'not tied to a screenshot' implicitly routes the alternative case to add_screenshot. No explicit when-not or named alternative, so it stops short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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).
| Name | Required | Description | Default |
|---|---|---|---|
| image | No | 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. | |
| title | No | Optional short caption for the screenshot. | |
| review | Yes | The review slug or URL from create_review. | |
| comment | No | Optional note describing what this screen shows or what's wrong with it. | |
| page_url | No | 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. | |
| viewport | No | With page_url: 'desktop' (1280x800, default) or 'mobile' (390x844 phone, 2x, touch). | |
| full_page | No | 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. | |
| image_url | No | 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. | |
| source_url | No | Optional URL of the page the screenshot was taken on. | |
| claim_token | Yes | 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. | |
| hide_selectors | No | 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. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only cover the safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=true); the description adds a great deal on top: append-only semantics, a 10-30 second render latency for page_url, the failure mode of sites blocking headless browsers, automatic cookie-banner hiding, and that page_url becomes source_url unless overridden. That is exactly the behavioral context an agent needs before invoking.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The purpose and the append-vs-replace distinction are front-loaded, and the middle sentence is a dense but well-organized enumeration of the three input methods. It runs long with nested parentheticals, but nearly every clause carries operational information rather than filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For an 11-parameter mutation tool with no output schema, the description covers authorization (claim_token), input modes, latency, and error behavior, and even notes that page_url returns the rendered image. What it does not describe is the shape of the success response (item id, position in the review), which leaves a small gap given there is no output schema to fall back on.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3, but the description adds genuine cross-parameter meaning the schema lacks: which three parameters are alternative image sources, that page_url populates source_url unless one is passed, and that claim_token can be either the create_review token or the human's exported agent token for a saved review.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The first sentence gives a precise verb+resource+effect: append one screenshot to the end of a review. It then explicitly distinguishes itself from replace_screenshot ('This tool only appends; it never changes an existing item'), so an agent can route between the two without opening either schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It enumerates the three mutually alternative supply paths (page_url, image_url, image) with the conditions that select each, and names the sibling to use for the modify case. It also states when-not: login-gated pages can't be rendered, external image URLs are refused, and oversized base64 images should be uploaded instead.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read mail delivered to an inbox from create_inbox, newest first, for example a verification code or confirmation link from the signup email of the product being tested. Requires the inbox_token, so only whoever created the inbox can read it. 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.
| Name | Required | Description | Default |
|---|---|---|---|
| format | No | "text" (default) returns each message flattened to readable text, with link targets kept. "html" returns the raw HTML part. | |
| address | Yes | The inbox address from create_inbox. | |
| inbox_token | Yes | The inbox_token from create_inbox (authorizes reading). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only declare readOnly/openWorld/non-destructive; the description adds real behavioral context beyond them: the inbox_token requirement means only the creator can read, the call returns immediately rather than blocking, mail typically lands within seconds, and an empty result is safe to retry shortly. That auth + latency/retry disclosure is exactly the kind of value annotations cannot carry.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Four compact sentences with the core purpose and ordering front-loaded, then auth, then timing, then the format option. Every sentence carries information; it runs slightly long but no clause is wasted.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There is no output schema, so the description must convey returns, and it does: newest-first messages, plain-text flattening with link targets by default, or raw HTML when format="html". Retry behavior on empty results is covered; pagination or message-count limits are not mentioned, keeping it just under fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all three parameters including the format enum are already documented in the schema. The description's format="html" note largely restates the schema wording, adding no syntax or format detail the schema lacks — baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ("Read mail delivered to an inbox"), names the originating sibling (create_inbox), and specifies ordering ("newest first"). An agent can distinguish this from create_inbox or the review tools without opening any schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives a concrete motivating scenario (verification code or confirmation link from a signup email) and the format="html" case for design review, so the agent knows the typical context. It never states an explicit when-not-to-use or an alternative to pick instead, so it stops short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a temporary email inbox for testing the signup or email flow of a product the user owns or is authorised to test, within that product's terms. Returns an address to enter in the product's form and an inbox_token for reading it with check_inbox. Each inbox expires 24 hours after it is created, receives mail only (it cannot send), and accepts mail only while it exists. Up to 20 inboxes can be created per hour from one IP address.
| Name | Required | Description | Default |
|---|---|---|---|
| review | No | Optional review slug this inbox belongs to — a label for your own bookkeeping. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations cover only the safety profile (not read-only, non-destructive, open-world), while the description adds substantive behaviour: 24-hour expiry, receive-only, valid only while it exists, and a rate limit of 20 inboxes per hour per IP. That is exactly the context annotations cannot express.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The purpose and return values are front-loaded, and every clause carries information. Slightly dense with four separate operational facts packed in, but nothing is redundant with the schema or annotations.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description still describes what is returned (an address and an inbox_token) and how to consume it. Combined with the lifecycle and rate-limit details, an agent has everything needed to call and use this tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and the single optional 'review' parameter is fully documented in the schema, so the baseline of 3 applies. The description adds no extra meaning about the parameter, but none is needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Create a temporary email inbox') and immediately narrows scope to testing signup or email flows for products the user owns or may test. It also names the sibling check_inbox as the reader tool, so an agent can distinguish it from siblings without opening a schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives a clear use context (testing the signup/email flow of an owned or authorised product, within terms) and routes reading to check_inbox. It stops short of explicit when-not-to-use guidance or naming other alternatives among the eleven siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| title | Yes | Title of the review, e.g. 'Onboarding walkthrough — Jupiter Invoice'. | |
| summary | No | Optional overview shown at the top of the review (plain text or markdown). Good place for the overall task, outcome, and headline findings. | |
| product_url | No | Optional URL of the product/site under review. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare a non-read-only, open-world, non-destructive creation, and the description goes well beyond that: it discloses the returned slug + claim_token handshake required by add_screenshot/add_note, the save_url flow requiring a signed-in human, and the 30-day anonymous auto-deletion policy. That is exactly the behavioral context annotations cannot carry.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the action and its handle, then the use cases, then the return contract and lifecycle caveat. Slightly dense with multiple clauses and em-dashes, but every sentence (including the 30-day expiry) earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There is no output schema, so the description must carry the return contract — and it names review slug, claim_token, review_url, and save_url along with how each is used. Combined with the retention rule, an agent has everything needed to create, fill, and hand off the review.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so title, summary, and product_url are already fully documented in the schema; the description adds no per-parameter syntax or format guidance. Baseline 3 applies because the structured field does the heavy lifting here.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource — 'Start a new Cobalt Capture review and get a handle for filling it in' — and contrasts the tool against the add_screenshot/add_note siblings that consume its output. An agent can distinguish this creation tool from update_review, get_review, and the append tools without opening a schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly frames the when: compile findings from a usability pass, pricing teardown, positioning audit, or QA run into one report. It also routes the agent around a real constraint — 'with no browser, add_screenshot(page_url=...) renders the pages for you' — naming the sibling to use in that situation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| Yes | The human's Cobalt account email. Must belong to a verified account, or the send is refused. | ||
| review | Yes | The review slug or URL from create_review. | |
| claim_token | Yes | 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). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already disclose side-effect behavior via readOnlyHint=false, destructiveHint=true, and openWorldHint=true. The description adds useful behavioral constraints beyond annotations: only verified Cobalt addresses are accepted, unverified addresses are refused, and the email contains only the review link with no caller-supplied text.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three tight sentences and is front-loaded with the core action. Each sentence earns its place by covering purpose, recipient restriction, and payload limitation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a three-parameter side-effecting tool with no output schema, the description covers the essential behavior: recipient requirements, refusal of unverified addresses, and the limited email content. It could say a bit more about success/failure outcomes, but the key invocation context is present.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents review, claim_token, and email. The description reinforces that email must be a verified Cobalt account address but does not add new syntax or format semantics beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: email a link to a review. It also names the intended recipient as the person who ran the study, which distinguishes it from sibling review tools such as get_review or create_review.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied: use this tool when you need to send a review link to the study owner. The description does not explicitly say when not to use it or name alternative tools for related tasks, so guidance remains minimal.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch the full text of a Cobalt study by the id search returned, or of any Cobalt review by its URL (/r/) 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.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | An id from search (e.g. 'teardown:canva'), or a review URL or slug. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the safety profile (readOnlyHint=true, destructiveHint=false, openWorldHint=false), so the bar is lowered. The description adds real value by enumerating what comes back — findings, prices, comparison matrix, and review notes with screenshot links — plus a text-vs-image limitation versus get_review.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no waste. Acceptable inputs are front-loaded and the alternative-tool guidance closes it, with every clause earning its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists, so the description compensates by describing the returned text contents. Combined with the annotations and full schema coverage, an agent has everything needed to invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and there is only one parameter, so the schema already documents that id accepts a search id, URL, or slug. The description restates the same formats without adding syntax or edge-case detail beyond the schema, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (fetch) and resource (Cobalt study or review) plus the two accepted identifier forms (search id, review URL/slug). It explicitly names the sibling it replaces in one use case, so an agent can distinguish it from get_review without opening schemas.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives explicit routing guidance: 'Use get_review instead when you need to see the screenshots as images.' The when-to-use is also implied by the id-source note ('the id search returned'), giving the agent a clear selection rule.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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: a new user signs up and tries to get real jobs done, judged as a whole experience; needs a browser); 'flow_pass' (one specific flow the user names, such as checkout or inviting a teammate, walked step by step 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); 'design_pass' (what the product looks like across nine phone, tablet and desktop sizes with menus, dialogs and forms opened: uneven padding, near-miss alignment, cut-off or colliding text, and a few hard fundamentals, nominated by a script in the page; needs a browser). The public-page studies work without a browser because add_screenshot(page_url) renders pages server-side. The same methods are offered as MCP prompts, and every playbook's full text is published at https://cobaltcapture.com/developers#playbooks. Each one tells the user its plan before acting, and the ones that sign up or use a product stop for the user's approval first.
| Name | Required | Description | Default |
|---|---|---|---|
| url | No | The site to run it against, if you already know it. | |
| name | Yes | Playbook name, e.g. 'usability_pass'. | |
| companion_of | No | design_pass only: the URL of the usability or scenario review this pass accompanies. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover safety (readOnlyHint=true, destructiveHint=false, openWorldHint=false), and the description adds real behavioral detail beyond them: every playbook announces its plan before acting, sign-up/product-use steps pause for user approval, and public-page studies avoid a browser because add_screenshot renders server-side. It does not describe return format or size, but the added workflow behavior is substantive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Purpose is front-loaded and every sentence carries information, though the single dense paragraph with embedded semicolons and parentheticals is heavy to parse. The trailing note about the public playbook URL is the weakest line but still aids the agent.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only fetch tool with no output schema, the definition supplies the valid inputs, per-input prerequisites, and the user-approval workflow. Nothing an agent needs to call it correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% so the baseline would be 3, but the description compensates for the missing enum on the required 'name' parameter by enumerating every valid playbook name and flagging 'positioning_pass' as an alias. It also clarifies that browser-needing playbooks are a property of the chosen name, which the schema does not convey.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Return the full text of a Cobalt study playbook') and immediately defines what a playbook is. It is unambiguously distinct from siblings like get_review or create_review.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description effectively routes selection by describing what each playbook is for (e.g. 'can a buyer tell what they would pay and which tier fits') and its preconditions ('needs a browser', 'public pages only'). It also notes alternatives exist ('offered as MCP prompts') but never explicitly states when to call this tool versus those alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| review | Yes | A Cobalt review URL (https://cobaltcapture.com/r/<slug> or /s/<slug>) or just the slug. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so safety is covered. The description adds real value beyond that by disclosing the return shape: reviewer notes as text plus each annotated screenshot as an image, which matters because no output schema exists.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two tight sentences with zero filler, front-loading the action and identifier before the payoff of what you get back.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only single-parameter tool, the description covers the action, the input form, and the return composition (text notes + annotated images), which compensates for the absent output schema. Only minor gaps remain, such as failure behavior for invalid links.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With a single parameter at 100% schema description coverage, the schema already documents the accepted URL formats and bare slug. The description's 'share link or slug' adds no syntax or format detail beyond that, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb (Fetch) and resource (a Cobalt Capture review), and specifies the identifier type (share link or slug). It is clearly distinct from write-oriented siblings like create_review and update_review, though it never names an alternative reader.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
'Fetch ... by its share link or slug' implies the retrieval use case, and the closing clause hints at the goal (see what was marked and what to change). However, there is no explicit when-to-use/when-not guidance and no mention of alternatives such as search or fetch.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| item | Yes | The 1-based number of the existing screenshot item to overwrite (as it appears in the review, counting notes). | |
| image | No | 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. | |
| title | No | Optional short caption for the screenshot. | |
| review | Yes | The review slug or URL from create_review. | |
| comment | No | Optional note describing what this screen shows or what's wrong with it. | |
| page_url | No | 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. | |
| viewport | No | With page_url: 'desktop' (1280x800, default) or 'mobile' (390x844 phone, 2x, touch). | |
| full_page | No | 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. | |
| image_url | No | 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. | |
| source_url | No | Optional URL of the page the screenshot was taken on. | |
| claim_token | Yes | 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. | |
| hide_selectors | No | 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. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare destructiveHint=true, but the description goes further: the old image plus any pins or annotations are removed and 'cannot be recovered,' and title/comment change only if new values are passed. That is exactly the kind of consequence detail annotations cannot encode, and it is the highest-value information for a destructive operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three tight sentences, front-loaded with what the tool does and the destructive consequence, then the scope restriction, then the argument relationship. No filler and nothing buried.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive 12-parameter mutation with no output schema, the description covers the irreversibility, the item-indexing convention, the selective field overwrite, and the scope boundary, while the 100%-covered schema handles argument syntax. Nothing an agent needs before invoking this safely is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% so the baseline is 3, but the description adds semantics beyond the schema: the exact meaning of `item` (1-based position counting notes) and the conditional behavior that title/comment are only overwritten when new values are supplied. It also frames the remaining arguments as identical to add_screenshot, reducing the need to re-read them.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a precise verb and resource ('Overwrite one existing screenshot in a review with a new capture, in the same position') and immediately distinguishes itself from siblings by declaring 'Works on screenshots only, not notes.' An agent can separate this from add_screenshot or add_note without opening any schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives clear context — replacing an existing item in place rather than appending — and routes the agent to add_screenshot for the shared capture arguments. It does not explicitly state the inverse condition ('use add_screenshot when you want a new item'), so the when-to-choose guidance is implied rather than spelled out.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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).
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | What to look for, e.g. 'canva pricing' or 'spotify'. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, openWorldHint=false, and destructiveHint=false, so safety behavior is covered. The description adds genuine scope context beyond that: it discloses the corpus boundary (published studies only, closed-world) and the return shape {id, title, url} plus the id-to-full-text escalation path. It does not discuss ranking, result limits, or empty-result behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, front-loaded with purpose and scope, then return shape, then exclusion. Every clause earns its place: examples clarify content type, and the negative scope prevents a likely misuse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists, so the description usefully supplies the return shape ({id, title, url}) and how to turn a result into full text. For a one-parameter read-only search, nothing an agent needs to call it correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and there is a single required parameter, so the schema already carries the parameter burden. The description's examples ('Canva pricing', 'Spotify vs Apple Music') reinforce query intent without adding new syntactic guidance beyond the schema's own example.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb ('Search') and a precisely scoped resource ('the studies Cobalt Capture has published'), naming the content types (pricing teardowns, positioning audits, head-to-head comparisons) with examples. An agent can distinguish it from siblings like get_review and fetch without consulting their schemas.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states what the tool does NOT cover ('It does NOT search private reviews, which are reachable only by their link') and names the alternatives (get_review, or fetch with the review URL). This is a clear when/when-not plus routing to the correct sibling.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| title | No | Optional replacement title. | |
| review | Yes | The review slug or URL from create_review. | |
| summary | No | The overview shown at the top of the review. Replaces any existing summary. | |
| claim_token | Yes | 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. | |
| compared_to | No | Optional: when this run repeats an earlier study, the earlier review's slug or URL. Recorded so re-runs can be compared over time. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and idempotentHint=true, so the overwrite risk is largely covered. The description reinforces this with 'Replaces any existing summary or title,' but adds little else about permissions or side effects beyond what the schema's claim_token note covers.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short sentences, front-loaded with the action, and the replacement warning is stated directly. No filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with no output schema, the description plus annotations and the fully documented schema give enough to call it correctly. Only permission/authorization nuance and confirmation behavior are left implicit.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all five parameters are documented in the schema itself. The description echoes the summary semantics ('shown at the top... above every screenshot and note') but adds no new syntax or format detail, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (set/replace) and resource (a review's summary and/or title), so the agent can tell what the tool does. It does not, however, explicitly contrast with create_review or the note/screenshot siblings, so differentiation is left to the agent.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied by 'Set or replace' and the note that existing values are replaced, which suggests using it after a review exists. There is no explicit when-not guidance or mention of alternatives such as add_note for appending content.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
get_playbook1 field changedInput schema / properties / companion_ofAdded value: +{
+ "description": "design_pass only: the URL of the usability or scenario review this pass accompanies.",
+ "type": "string"
+}add_screenshot6 fields changedInput schema / properties / full_page / descriptionPrevious value: -"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."New value: +"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."Input schema / properties / hide_selectors / descriptionPrevious value: -"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."New value: +"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."Input schema / properties / image / descriptionPrevious value: -"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."New value: +"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."Input schema / properties / image_url / descriptionPrevious value: -"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."New value: +"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."Input schema / properties / page_url / descriptionPrevious value: -"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."New value: +"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."Input schema / properties / viewport / descriptionPrevious value: -"With page_url: 'desktop' (1280x800, default) or 'mobile' (390x844 phone, 2x, touch) — the way to test the phone fold."New value: +"With page_url: 'desktop' (1280x800, default) or 'mobile' (390x844 phone, 2x, touch)."check_inbox1 field changedInput schema / properties / format / descriptionPrevious value: -"\"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."New value: +"\"text\" (default) returns each message flattened to readable text, with link targets kept. \"html\" returns the raw HTML part."replace_screenshot6 fields changedInput schema / properties / full_page / descriptionPrevious value: -"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."New value: +"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."Input schema / properties / hide_selectors / descriptionPrevious value: -"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."New value: +"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."Input schema / properties / image / descriptionPrevious value: -"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."New value: +"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."Input schema / properties / image_url / descriptionPrevious value: -"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."New value: +"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."Input schema / properties / page_url / descriptionPrevious value: -"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."New value: +"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."Input schema / properties / viewport / descriptionPrevious value: -"With page_url: 'desktop' (1280x800, default) or 'mobile' (390x844 phone, 2x, touch) — the way to test the phone fold."New value: +"With page_url: 'desktop' (1280x800, default) or 'mobile' (390x844 phone, 2x, touch)."update_review2 fields changedInput schema / properties / compared_to / descriptionPrevious value: -"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."New value: +"Optional: when this run repeats an earlier study, the earlier review's slug or URL. Recorded so re-runs can be compared over time."Input schema / properties / summary / descriptionPrevious value: -"The overview shown at the top of the review — put the headline findings and outcome here. Replaces any existing summary."New value: +"The overview shown at the top of the review. Replaces any existing summary."add_screenshot1 field changedInput schema / properties / replace_itemRemoved value: -{
- "description": "RETAKE: the 1-based number of an existing screenshot item to overwrite in place with this capture (same position, pins cleared, title/comment replaced only if given). Use it when the image that came back wasn't the shot. Not for notes.",
- "minimum": 1,
- "type": "integer"
-}replace_screenshotfetchsearchadd_noteadd_screenshotcheck_inboxcreate_inboxcreate_reviewemail_reviewget_playbookget_reviewupdate_reviewCreate, launch, and analyze user research studies, AI interviews, and AI tests from your AI agent.
Captured web interfaces, screenshots, flows and structured evidence for AI coding agents.
Loom for agents: AI agents record narrated product demos, plus transcripts, summaries, and search.
Prototypes made of HTML screens and the review notes designers dictate, ready for your AI to apply.
Add one secure layer between your agents and this server.
