cobalt

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already signal a non-readonly, non-destructive write operation. The description adds useful behavioral context: the operation appends rather than overwrites, produces a free-standing note rather than a screenshot-bound annotation, and depends on an existing review from create_review. This goes beyond the annotation hints.

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 two sentences with no filler. The first sentence states the operation and key distinction; the second gives practical use cases. Every clause 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?

For a three-parameter tool with no output schema, the description gives enough context to call it correctly: it identifies the parent resource, the write authorization requirement via claim_token, and the intended use cases. It does not describe the return behavior, but that is not essential here.

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 baseline is 3. The description itself does not add parameter-level detail, but the schema already documents review, claim_token, and text well, including the special saved-review token case.

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 clearly states the operation: append a free-standing text note to a review. It also explicitly distinguishes itself from add_screenshot by saying the note is not tied to a screenshot, leaving no ambiguity about what tool to pick.

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 provides practical use cases: context, steps taken, or a summary of findings between screenshots. It implies when add_note is appropriate and contrasts with screenshot-based additions, though it does not explicitly list exclusions or name alternative tools.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations carry only readOnlyHint=false and destructiveHint=false, so the description shoulders the transparency burden, and it delivers in detail: it discloses persistence ('stored durably in Cobalt'), rendering behavior (Cloudflare headless Chrome, bot checks waited through, 10-30s), stripping of cookie walls and modal veils, the requirement to inspect the result before moving on, and failure modes (overlay, blank, wrong page) with the replace_item remediation. This goes well beyond the annotations and tells the agent exactly what to expect side-effect-wise.

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 long, but this is a 12-parameter tool with multiple modes (browser-retake, server-side render, image-url upload, base64 edge case) and every sentence earns its place by disambiguating a decision an agent must make. It front-loads the core purpose, then the no-browser path, then retake behavior, then the upload flow, then the base64 caution. The only cost is density; an agent must read carefully, but the structure follows the natural call flow and is not padded.

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 12-parameter tool with two required params and no output schema, the description is unusually complete: it covers all three capture modes, authentication via claim_token, retake semantics, selector hiding, upload mechanics, timing, failure handling, and what to do after the result returns ('LOOK AT IT before moving on'). There is no material decision an agent faces that the description leaves unaddressed.

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 already 3, but the description still adds meaning beyond the schema. It clarifies that page_url is the no-browser path, that image_url must be on Cobalt's own host and is obtained via the upload endpoint (schema already says this, but description ties the flow together: POST then pass back the url), that image base64 is for small inputs only and not for screenshots, and that claim_token has a different route for saved reviews. The description integrates the parameters into workflows instead of just listing 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?

The description opens with a specific verb and resource: 'Append a screenshot (with an optional note) to a review created by create_review.' It immediately distinguishes itself from siblings like add_note (screenshots vs notes) and create_review (append to existing vs create), and the title restates it cleanly. The purpose is unambiguous and action-oriented.

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 gives explicit when-to-use guidance: 'Call once per screen as you go,' 'Use it for every screen you would otherwise only describe in text,' and 'a review without screenshots is a reduced deliverable.' It names the browser-tool alternative and routes around it: 'NO BROWSER? Pass page_url.' It also gives explicit retake guidance ('retake it in place with replace_item') and what not to do ('never append a second copy after it'). That is thorough, decision-ready guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description richly discloses behavior beyond the readOnlyHint and openWorldHint annotations: there is no blocking wait, responses can be empty and should be retried, results are newest-first, and text mode flattens layout while HTML mode preserves it. This gives the agent accurate expectations for a sluggish, poll-for-mail tool.

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 front-loaded with the core purpose, followed by operational advice and format guidance. Every sentence earns its place, and the prose is dense but not bloated. It efficiently communicates a non-obvious retry behavior and the auditing use case without 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?

The tool has no output schema, so the description must carry return-behavior information. It covers ordering, emptiness, retry semantics, and the difference between text and HTML output. It doesn't specify the exact response envelope or fields, but it gives enough for an agent to call, read, extract, and continue.

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 already 100%, so the baseline is 3. The description adds meaningful guidance on the format parameter, explaining exactly why to choose text (code/link extraction) vs html (auditing layout, typography, branding). Address and inbox_token are adequately covered by the schema and referenced contextually.

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 opens with a specific verb and resource: 'Read mail delivered to an inbox from create_inbox.' It also gives concrete use cases (pulling a verification code or confirmation link) and a key behavioral trait ('Returns newest-first'), making its purpose unambiguous and distinct from related tools like create_inbox.

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 tool gives clear context: use it to read inbox mail, retry after a few seconds if empty, and switch to format="html" when auditing instead of extracting a code. It does not explicitly name a sibling alternative or state when not to use the tool, 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.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already signal readOnlyHint=false, and the description does not contradict that. It adds useful behavioral context: inboxes are temporary, and the returned address/token enable later reading, which arouses the agent to treat the inbox as disposable.

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 concise sentences each carry weight: what the tool does, what it returns, and when/how to use it. No filler or repetition of annotation data.

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?

Even without an output schema, the description explicitly names the returned values (address and inbox_token). Combined with the sibling check_inbox and the simple single-parameter schema, the agent has enough context to call and use the 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?

There is only one optional parameter and the schema already provides a full description for it, so schema coverage is 100%. The tool description adds no parameter-specific details, so a baseline 3 is appropriate.

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 action — "Create a disposable email inbox" — and names the resource and its purpose (monitoring signup emails). It also distinguishes itself from sibling tools like check_inbox and 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?

Explicitly says when to use it: instead of asking the human for an email account or a third-party inbox API key, with no setup needed. It also advises creating a fresh inbox per test persona, giving clear routing and lifecycle guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Goes well beyond the readOnlyHint/destructiveHint annotations, disclosing that the review is anonymous, auto-deletes after 30 days unless saved, returns two tokens that must both be passed back, and provides a save_url for permanent storage. This is exactly the kind of behavioral context an agent needs.

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?

Every sentence carries distinct information: purpose, supported use cases, no-browser rendering, token mechanics, share/save URLs, and 30-day lifecycle. Content is front-loaded with the primary purpose and handle.

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?

Since there is no output schema, the description fully documents all return values and their roles, including the requirement to pass both slug and claim_token back. It also covers the save flow and retention policy, so an agent has everything needed to invoke and follow up 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?

All parameters are already documented in the schema (100% coverage), so the description doesn't need to restate them. It adds value by explaining how the returned slug/claim_token wire into later calls, but no extra parameter-level meaning 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?

States a specific action ('Start a new Cobalt Capture review') and resource, and clarifies it produces a handle for later appending. It also names the kinds of studies it supports, distinguishing it from sibling tools like get_review/update_review that operate on an existing 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?

Explicitly says when to use: to compile findings from a site study into a shareable report. It also addresses the no-browser case by pointing to add_screenshot for rendering, but it doesn't explicitly say when not to use it or mention alternatives like update_review.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description discloses critical behaviors beyond the annotations: only verified Cobalt account addresses are accepted, the call is refused otherwise, the email contains only a link and no custom text, and the agent should ask the human for the account email and pass it verbatim. This is rich, honest behavioral context.

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 is front-loaded, usage instructions are direct, and the important verification warning is clearly separated. A little rationale is included, but it serves the agent's decision-making rather than padding.

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?

The description covers purpose, inputs, eligibility, refusal behavior, and content limitations. It doesn't describe what a successful call returns, but with no output schema and a straightforward send action, this is a minor gap.

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 already 100%, and the description adds useful nuance: review is a slug or URL from create_review; claim_token proves ownership or can be the saved-review agent token; email must be the verified Cobalt account address passed verbatim. This goes beyond the schema descriptions.

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 finished review to the human who started the run.' It clearly identifies the action, the object, and the recipient, and it is readily distinguishable from sibling tools like create_review and check_inbox.

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 gives clear usage context ('useful at the end of a long unattended study') and tells the agent exactly what to pass: the review, its claim_token, and the human's email. It doesn't explicitly name alternative tools or state when not to use this one, but it does explain when calls will be refused, which is strong practical guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Beyond the readOnlyHint annotation, the description reveals important runtime behavior: which playbooks work from chat without a browser, which require a controlled browser, and how add_screenshot compensates for lack of browser access. It does not describe error conditions or exact return format, but the added environment and dependency context is valuable.

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 long but information-dense; nearly every sentence earns its place, especially the playbook-by-playbook breakdown and the explicit fallback instruction. It could be slightly more scannable, but the structure is logical and front-loaded with the core action.

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?

The description covers tool selection, environment compatibility, available values, fallback behavior, and why the protocol route is preferable. Since there is no output schema, it could have said a bit more about what the returned playbook contains, but overall it gives an agent enough context to invoke the 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%, so the baseline is 3. The description adds meaningful value by explaining each playbook name's purpose and runtime requirements, which the schema alone does not convey. The url parameter is only lightly touched, but the name parameter semantics are substantially enriched.

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 opens with a specific verb and resource: 'Fetch a Cobalt study playbook by name and follow it exactly.' It also enumerates the available playbook variants with concrete purposes, making it easy to distinguish this fetch operation from sibling review/note tools.

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 explicitly states when to use this tool: 'when the user asks for any kind of site review, audit, teardown, or test and you don't already have the playbook text.' It also gives exclusions ('If the user's study is NONE of these, do not bend it into the nearest one') and even advises preferring this over fetching from a URL.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already mark this as readOnlyHint=true, so the safety profile is covered. The description adds valuable behavioral details beyond annotations: it returns the reviewer's notes as text and annotated screenshots as images, and it explains the purpose ('see exactly what was marked and what to change'), which is not derivable from the schema or annotations.

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: the first states what the tool fetches and how to identify the review; the second states what it returns and why that matters. Every sentence earns its place, no fluff, and the key action is front-loaded.

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 one-parameter tool with readOnlyHint coverage and no output schema, the description fully explains the return content (notes and annotated screenshots), which is exactly what an agent would need to know to invoke it correctly and interpret results. Nothing critical 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% and the schema already describes the accepted formats (URL or slug). The description repeats this idea but does not add new parameter semantics beyond what the schema provides, so the baseline of 3 is appropriate.

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 uses a specific verb ('Fetch'), identifies the resource ('Cobalt Capture review'), and specifies the input form ('share link or slug'). It clearly differs from siblings like create_review, update_review, and email_review by being a pure read operation, and from get_playbook by targeting reviews instead.

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 context is clear: use this when you need to retrieve a review and see reviewer notes plus annotated screenshots. The description does not explicitly name alternatives or when-not conditions, but the read-only nature and resource specificity make the intended usage obvious in contrast to the siblings.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already cover the key behavioral traits (readOnlyHint=false, idempotentHint=true, destructiveHint=false), so the bar is lower. The description adds usage context about placing the verdict at the top of the review, but it does not disclose additional behavioral details such as authorization nuances, side effects beyond the summary/title replacement, or error behavior. This is adequate but not rich.

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 compact: the first sentence states the action, the second gives the key timing rationale, and the third gives a preference. Every sentence earns its place, and the most important information is front-loaded.

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?

Given the rich parameter schema and annotations, the description adds the crucial usage context (end-of-run finalization, top-of-review placement) that an agent needs. There is no output schema, but for an idempotent, non-destructive update tool, the description and schema together are sufficient. A minor gap is that the description does not explicitly mention the claim_token authorization requirement, but the schema covers it.

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 fully documents all five parameters, including the special claim_token behavior. The description reinforces that summary and title are the primary mutable fields, but it does not add meaning beyond the schema. A baseline 3 is appropriate.

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: 'Update a review's summary and/or title after the fact.' It clearly identifies the affected fields and the timing, distinguishing it from create_review (which creates) and add_note/screenshot (which add content) by emphasizing that this is for landing the final verdict at the top of the 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 explicitly says when to use the tool: 'Use this at the END of a run' and gives a specific preference over an alternative: 'Prefer this over burying conclusions in a closing note.' This gives an agent direct routing guidance between update_review and the note-adding pathway.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.