Cobalt Capture

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.

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.

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

Annotations already declare readOnlyHint, openWorldHint and destructiveHint, so safety is covered. The description adds genuinely useful behavior beyond that: it returns immediately, mail typically arrives within seconds, an empty result can be re-checked shortly, and format=html changes what is returned.

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 the core purpose and followed by timing/retry and format behavior. No filler or repetition.

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 carries the burden of describing returns, and it does so partially (newest-first ordering, text vs HTML). The polling/empty-result semantics are covered, though it doesn't detail message fields an agent will encounter.

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 are already documented. The description only restates the format=html behavior that the schema enum already explains, adding marginal value over the structured field.

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 (read) and resource (mail delivered to an inbox from create_inbox), plus ordering (newest first). The example use case (verification code, confirmation link) pins down intent, and it is clearly distinct from sibling create_inbox, which provisions rather than reads.

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 scenario for when to use it (retrieving a signup verification code or confirmation link) and explains the retry condition when the inbox is empty. It does not name an alternative tool or state exclusions, but the single-purpose nature makes that gap minor.

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 safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=true), and the description adds genuinely useful behavior: it returns an address and inbox_token, and inboxes expire after a day. Explicitly disclosing the TTL is valuable context not derivable from 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?

Three short sentences, front-loaded with the action and purpose, then return values, then the expiry caveat. Every sentence carries information an agent needs.

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 compensates by naming the returned fields (address, inbox_token) and the expiry window. For a zero-required-parameter creation tool, nothing essential 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% for the single optional 'review' parameter, so the schema already explains its meaning. The description adds no additional parameter guidance, which is the baseline expectation at high coverage.

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') plus the intent ('for signing up to a product under test'). This clearly distinguishes it from sibling check_inbox, which reads rather than creates.

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 context for when to reach for this tool (product signup flows) and routes the agent to check_inbox for retrieval. It does not state exclusions or prerequisites, so it falls 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 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.

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.

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.

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

Annotations already declare readOnlyHint=true, openWorldHint=false and destructiveHint=false, so the safety profile is covered. The description adds genuinely non-obvious behavioral context: which studies need a browser versus which run server-side via add_screenshot(page_url). It stops short of describing error behavior for an invalid playbook name.

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 opening sentence front-loads the verb, resource, and payload, and the long playbook list is necessary selection data rather than filler. It is dense, but the multi-line semicolon-heavy enumeration is heavier than ideal for a single paragraph.

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 carries the burden of saying what comes back ('the full text') and does so. Browser vs server-side requirements per playbook and the legacy alias ('positioning_pass' is the old name of 'website_teardown') round it out; only failure/edge handling for bad names 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 compensates for the absent enum on 'name' by listing the valid playbook identifiers. It also clarifies the optional 'url' is only needed if the target site is already known, adding meaning beyond the schema's terse 'if you already know it.'

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 then defines what a playbook actually is, distinguishing it from sibling tools like create_review or add_screenshot. The enumeration of playbook names gives the agent an unambiguous picture of what this tool yields.

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?

Each playbook variant is annotated with when it applies ('can a buyer tell what they would pay', 'judged as a first-time visitor', 'two or three products compared for one buying decision'), which effectively routes selection. It does not explicitly say when NOT to call this tool or how it relates to create_review (e.g., fetch then run), leaving that inference to the agent.

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 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.

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.

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.

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.