Reado

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), and the description adds traits they cannot express: an empty list vs null distinction for no-animations vs no-match, a ~6 s failure timeout with its error message, and an auth gate that blocks credential pages until user consent. These are exactly the operational behaviors an agent needs before calling.

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 ordered by importance: purpose and return payload first, empty/null semantics second, prerequisites and failure modes last. No filler; every clause carries distinct information.

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 correctly compensates by enumerating the returned fields and the two empty-result variants. Combined with the documented failure and permission paths, an agent has everything needed to call this 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 selector parameter is fully documented there, including the 'first matching element / document.querySelector' semantics. The description adds the phrase 'one element of the preview' but no further syntax or matching detail, so this is the baseline case where the schema does the heavy lifting.

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 the animations running on one element of the preview') plus the exact return shape (name, keyframes, computed timing), which clearly separates it from siblings like browser_dom or browser_eval. An agent can identify both what it does and what it returns without opening the 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 concrete preconditions: Reado's browser preview must be open with agent access, otherwise the call fails after ~6 s with a specific error string, and credential-bearing pages are refused pending user grant. It does not, however, name an alternative (e.g., that browser_eval could inspect animations differently) or state explicit when-not-to-use cases beyond the environment prerequisites.

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 annotations by disclosing return values ('clicked' / 'not found'), the no-wait semantics, the ~6s failure mode with the exact error string, and a credential-based authorization gate. Annotations only cover the non-readOnly, non-idempotent, non-destructive profile; the description adds the operational detail 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?

Front-loads the action and mechanics, then return values, then the alternative tools, then the failure/auth caveats. Every sentence carries distinct, non-redundant information.

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 correctly supplies return values and failure behavior, and it covers prerequisites and the no-wait contract. Nothing essential for correct invocation 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 documents that selector is a CSS selector using document.querySelector with the first match. The description adds only a light implicit note ('nothing matches') without new syntax or format guidance, so 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?

States a specific verb (click) on a specific resource (an element in the preview) and describes the mechanics: scroll to viewport center then fire a DOM click(). This clearly distinguishes it from siblings like browser_hover, browser_type, and browser_eval.

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 it does not wait for the click's effects and routes the agent to browser_dom, browser_errors, or browser_frame to check outcomes. It also names prerequisites: preview must be open with agent access, and credential pages require user consent.

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 readOnly/idempotent/non-destructive, so the safety burden is covered. The description adds genuinely useful behavior beyond that: it reads captured data 'without touching the page' and returns a 'none is running' answer when no preview is open, covering a key edge case. It stops short of covering volume/pagination or truncation 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?

Two tight sentences, front-loaded with the core action and immediately followed by the routing rule and edge-case behavior. Every clause earns its place with no 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 a no-param, read-only diagnostic tool with no output schema, the description supplies the return format, the sibling routing rule, the no-side-effect guarantee, and the no-preview edge case. Nothing an agent needs to invoke it 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?

The tool takes zero parameters, so there is no parameter semantics to document; baseline 4 applies. The description appropriately focuses on output shape instead of inventing param detail.

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 everything the preview page logged') and describes the return shape (level, message, source, stack). It explicitly distinguishes itself from the sibling browser_errors, so an agent can route correctly 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?

Names the alternative and the condition that selects it: 'Use it to follow what the app is doing; for only what broke, browser_errors is shorter.' This is an explicit when-to-use-this vs when-to-use-other 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 readOnly, idempotent, non-destructive and non-open-world, yet the description still adds real value: a null result when nothing matches, a ~6 s timeout failure when no preview pane runs, and a refusal-plus-user-grant flow on credential pages. It does not state whether the DOM snapshot is a point-in-time copy or whether the 2000-character truncation is signalled in the payload, so it stops just short of 5.

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 return payload, then usage routing, then prerequisites and failure modes, all in three tight sentences with no filler. Every clause carries information an agent needs before calling.

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 carries the full burden of describing return values — and it does: field list, truncation limit, coordinate space (CSS px, viewport-relative), and the null case. Combined with the auth and failure-mode notes, an agent has everything required to call this 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 'selector' parameter is fully documented as a CSS selector resolved via document.querySelector with first-match semantics. The description restates the same first-match behaviour and adds nothing parameter-specific, 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 and resource ('Inspect one element of the preview') and enumerates exactly what is returned: tag, outerHTML, box, computed styles, as JSON. It also names the sibling boundaries (browser_frame for pictures, browser_eval for anything else), so an agent can distinguish it 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?

Explicit routing: use this to check structure and layout, use browser_frame for a picture, browser_eval for anything else. It also states the prerequisite (preview open with agent access), the failure symptom and timing ('fails after about 6 s with no preview pane running'), and the credential-gated refusal path.

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 cover the safety profile (readOnly, idempotent, non-destructive), but the description adds real behavior: the exact empty-result sentinel ('No errors captured.'), that it never touches the page, and the no-preview-open case. That is useful state disclosure beyond the structured fields, though return shape/pagination detail is absent.

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 core scope and three tight sentences that each carry information. It loses a point for the awkward, opaque 'Reads what Reado captured' clause, which adds syllables without adding meaning.

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 zero-parameter, read-only tool with no output schema, the description covers everything an agent needs: what subset is returned, the format, the empty case, and the no-preview case. Nothing material 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?

Zero parameters, so the baseline of 4 applies. The description correctly implies the tool takes no filtering input — scoping is baked in — and nothing about parameters is misstated.

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 only ... error-level console entries — errors and unhandled rejections — as JSON') and explicitly positions itself as 'the part of browser_console that answers "what broke?"', which distinguishes it from its closest sibling 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?

The framing as a filtered subset of browser_console implies the selection rule: use this for error triage, use browser_console for the full log. No explicit 'when not to use' or named alternative is spelled out, so it stops short of 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?

Goes well beyond the annotations: it discloses synchronous evaluation (Promises are not awaited), that it can mutate the page, that a missing preview pane fails after ~6 s with the literal error 'no preview pane running', and that credential-holding pages are refused until the user grants access. The destructiveHint=true annotation is consistent with 'it can change the page'.

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-loads the core action and return format, then usage guidance, then behavioral caveats and prerequisites. Every sentence carries distinct, non-redundant information with no 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?

Covers the action, the return format, prerequisite/auth gating, failure timing and error message, and execution semantics for a single-parameter tool with no output schema. Nothing an agent needs to call it correctly appears to be 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%, so the js parameter and the IIFE-wrapping convention are already documented in the schema. The description adds the JSON-serialization of the return value but no further syntax 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 and resource ('Run a JavaScript expression in the preview page') and immediately names its scope against siblings ('the escape hatch for what the other browser_* tools don't cover'). An agent can distinguish it from browser_console/browser_dom 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 gives when-to-use examples (reading app state, calling page functions, scrolling a nested container) and a when-not-to-use rule ('prefer them when they fit'). It also states the prerequisite: a Reado browser preview must be open with agent access on.

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 readOnly/idempotent/non-destructive, but the description adds substantial behavior the annotations cannot express: the Linux unavailability, the prerequisite of an open browser preview with agent access, the ~6 s failure with the specific "no preview pane running" error, and the credential-page refusal pending user consent. This is exactly the preconditions-and-failure-mode 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?

Three sentences, each load-bearing: what it returns, when to use it versus the sibling, and the environment/auth preconditions. The core action is front-loaded and there is no 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 a zero-parameter screenshot tool with no output schema, the description covers the return type (PNG image), the visual-vs-DOM tradeoff, platform limits, and the auth/failure conditions. Nothing needed to invoke 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?

The tool takes zero parameters, so the schema has nothing to document and the baseline of 4 applies. There is no parameter semantics for the description to add or omit.

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 ("Screenshot the preview as it renders right now") plus the returned artifact (PNG image). It explicitly differentiates itself from the sibling browser_dom, so an agent can choose between them 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 concrete when-to-use cases (layout and visual bugs, result of a click) and names the alternative tool with the condition that selects it ("for exact sizes and styles use browser_dom"). It also states an availability exclusion ("Not available on Linux"), so the agent knows when not to call it.

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?

Discloses far more than the annotations: the synthetic-event caveat that CSS :hover styles do not apply, the ~6 s timeout failure message when no preview pane runs, and the credential-page access refusal. These are exactly the behavioral traits an agent needs and cannot derive from structured fields.

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 purpose, then the return values, caveat, and prerequisites. Every sentence carries distinct, load-bearing information with no 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?

With no output schema, the description still communicates return values (hovered / not found), prerequisites (preview open with agent access), the failure mode, and the credential-access constraint. Nothing an agent needs to invoke 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 schema already documents the selector parameter and its first-match semantics. The description adds no additional parameter detail beyond what the schema provides, so 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 (hover) and resource (an element in the preview) and explains the intent — open a menu or tooltip before inspecting it. This clearly separates it from browser_click and browser_dom without needing to open 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 concrete when-to-use condition: to reveal a menu or tooltip ahead of inspection. It does not explicitly name a sibling alternative (e.g. when to prefer browser_click), so it stops short of full routing guidance, but the context is clear.

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?

Adds rich behavioral context beyond annotations: allowlist enforcement and refusal message ('origin not allowed'), timeout behavior (~6s with 'no preview pane running'), credential page gating, and replacement of current page. Annotations declare idempotentHint and non-destructive, but the description provides operational failure modes and preconditions that are essential for correct invocation.

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 the core action, followed by constraints and failure modes. No wasted words, but the sentence about credential access is somewhat abrupt and could be integrated more elegantly.

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 a single-parameter tool with no output schema, the description covers purpose, environment prerequisites, allowlist constraints, failure modes, and special cases (credential pages). An agent has all necessary information to attempt the call and interpret errors. Output schema absence is mitigated by stating what is returned ('Answers the URL loaded').

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 description already explains absolute vs. relative URL formats with examples. The description adds no additional parameter semantics beyond what the schema provides, so 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?

Specific verb+resource: 'Load a URL in the preview, replacing the current page.' Clearly distinguishes from sibling inspection tools like browser_console or browser_dom. An agent can identify this as the navigation tool immediately.

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?

Describes the preconditions—'Needs Reado's browser preview open with agent access on'—and the allowlist conditions. It explains when the call fails but doesn't explicitly suggest alternatives for when navigation is refused. Clear context, no explicit exclusions.

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 read-only/idempotent/non-destructive, so the bar is lower. The description still adds real value by explaining that it reads Reado's captured data without touching the live page and that it reports when no preview is running, both beyond the structured fields.

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 is returned, then usage, then the passive-read caveat. No sentence is redundant.

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 zero-param read tool with annotations covering the safety profile and no output schema, the description fully covers return fields, use case, and the empty-state behavior.

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?

Zero parameters, so the baseline is 4. The description instead documents the response shape it yields, which is useful given no output schema exists.

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 (preview page's network activity) and enumerates the returned payload (method, URL, status, timing, failures flagged). This cleanly differentiates it from network-adjacent siblings like browser_console and browser_errors.

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 when-to-use context: checking API calls, failed fetches, and slow responses. It does not explicitly name a sibling alternative (e.g., browser_console for logs), but the intent is unambiguous enough to select the right tool.

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 idempotency and non-destructiveness, but the description goes well beyond them: it discloses the return token ('scrolled'), the prerequisite (browser preview open with agent access), the concrete failure mode and timing (~6 s, 'no preview pane running'), and an auth gate on credential-bearing pages. Rich behavioral context that annotations do not 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 verb and resource, then the mechanism, then alternatives, then prerequisites and failure behavior. Dense but every clause earns its place; no 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 a two-parameter scroll tool with no output schema, the description covers the action, return value, prerequisites, failure timing, and access restrictions. Nothing needed to invoke 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 both x and y are already fully documented with units, defaults, and minimums. The description only reinforces that the position is absolute rather than relative, adding marginal value over the schema. 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+resource (scroll the preview's window), names the underlying mechanism (window.scrollTo), and specifies absolute positioning. It is immediately distinguishable from browser_click, browser_frame, and browser_eval, all of which it references.

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 routes the agent: use this before browser_frame, browser_click already scrolls its own target, and a nested scroll container requires browser_eval. This is exactly the when-to-use/when-not-to-use guidance that selects among 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 cover safety (readOnlyHint=false, idempotentHint=true, destructiveHint=false), and the description goes well beyond them: no key events are dispatched, Enter-to-submit won't trigger, failure mode and timing (~6 s, 'no preview pane running'), and a credential-page refusal requiring user consent. That is unusually rich behavioral disclosure.

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 tight sentences, front-loaded with the action and its input/change behavior, then caveats, then prerequisites. Every sentence carries actionable information; nothing is 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?

With no output schema, the description still covers the return values ('typed' or 'not found'), the failure mode and latency, the prerequisites, and the auth gate for credential pages. Nothing an agent needs to invoke this 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%, so both `selector` and `text` are already documented in the schema, including the replace-not-append and empty-string-clears semantics. The description restates the replacement behavior but adds no new parameter-level syntax or formatting 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 and resource ('Fill a form field in the preview') and enumerates the exact mechanics: focuses the field, replaces its whole value with `text`, fires input and change. This is clearly separable from siblings like browser_click (which sends real input) and browser_eval (which runs arbitrary code).

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 when this tool is the wrong choice ('No key events are sent, so keydown handlers and Enter-to-submit don't fire — click the submit button instead'), routing the agent to browser_click for submission. It also names the prerequisite (browser preview open with agent access) and the refusing condition for credential pages.

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 the write/non-idempotent profile (readOnlyHint=false, idempotentHint=false), and the description adds real behavior beyond them: the comment is agent-signed, a `task` joins the user's task queue as actionable work, and the call returns the comment's id and state as JSON. It omits auth/permission requirements and whether the anchor must lie within the file's existing line count, so it is strong but not exhaustive.

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 action and anchor semantics, then mode semantics, then routing. No filler and nothing repeated from the schema.

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?

Although there is no output schema, the description states the return payload (id and state as JSON) and provides sibling routing, which covers most of what an agent needs. The remaining gap is disambiguating the two enums (kind vs. type) that both accept "note".

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 a 3 is the baseline; the description goes further by explaining the consequence of `kind`: `task` (default) enters the user's queue as work, `note` only informs. It does not clarify the overlap between the `kind` and `type` enums, both of which include "note".

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 ("Anchor a new comment") plus the anchoring scope (a line range) and the authorship attribute ("signed by the agent"). It also draws a clear boundary against two sibling tools (comment_reply, review_propose_comment), so an agent can select it 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?

Explicitly routes: existing comment -> comment_reply, in-review flow -> review_propose_comment (with the note that a human approves first). It also gives the selection criterion between the two modes of this tool itself (task = work to do, note = informs only).

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=false, destructiveHint=false and idempotentHint=false, so safety is partly covered. The description adds value beyond that by clarifying the write is attributed to the agent ('signed by the agent'), that it does not mutate comment state, and that the response returns the comment's id and state as JSON — important since 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?

Three tightly packed clauses: purpose, negative scoping against siblings, and return shape. Front-loaded and every sentence 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 2-parameter tool with full schema coverage and no output schema, the description supplies the missing pieces: usage triggers, exclusions, and the return value. Nothing an agent needs to invoke it correctly is absent.

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 both parameters (id source, Markdown body) are already documented in the schema. The description adds no syntax or format detail beyond that, 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?

States a specific verb and resource (reply in an existing comment's thread) and immediately delimits its scope against the state-changing siblings task_done, task_fail and task_block. An agent can tell what this does and what it does not do without opening the 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 both positive triggers (to answer a question the user asked, or to explain what you changed) and an explicit when-not with named alternatives for the state-change case. Nothing is left to inference.

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 only the generic profile (not read-only, not idempotent, not destructive, not open-world). The description adds genuinely non-derivable behavior: it interrupts a human and misuse gets the companion disabled, and over-280-character text is refused rather than truncated — a hard failure mode, not a silent clamp.

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 core action, then restraint rules, then a hard limit, then the return shape — every sentence carries information. It is slightly prose-heavy (the chattering-companion rationale could be tightened) and restates the 280-character cap already in the schema.

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 closes the loop by naming the return value (`said: <text>`), and it covers the failure mode and the restraint policy for a tool whose only real risk is overuse. Nothing needed to call this 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 is 3, but the description goes further by giving the `mood` enum semantic weight — `ask` means the agent is actually blocked and waiting on the user, which the schema's 'expression' text does not convey. The 280-character limit is repeated from the schema, which is mild redundancy rather than added meaning.

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 (say one line) and a specific channel (through Reado's mascot, described for an agent that has never seen it), and it implicitly distinguishes itself from the notification-oriented siblings by framing itself as a human-facing interrupt rather than browser instrumentation. An agent can select it correctly without opening the 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 gives an explicit positive trigger (the moment the user must know about while away: what you need, or what just landed) and an explicit negative list (not narration, not progress, not running commentary), plus a routing rule for the `ask` mood: use it only when actually waiting. This is about as unambiguous as usage guidance gets.

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 readOnly, idempotent and non-destructive, so safety is covered. With no output schema, the description usefully discloses the read is and what it contains, which is real added value beyond the 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?

Front-loaded with verb and scope, then the field inventory, and the sibling redirect is held to the end. The field list is a touch long but each item earns its place since no output schema exists.

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 two-parameter read tool with no output schema, the description carries the return-shape burden well by enumerating the JSON payload. Nothing an agent needs to invoke it correctly appears to be 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%, so both 'file' and 'sessionId' (including the newest-session default) are already documented in the schema. The description adds no syntax or format detail beyond that, so 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 ('Read') and resource ('one file's context'), enumerates the returned fields (objective, route entry, state, summary, proposals), and explicitly distinguishes itself from the session_show sibling. An agent can identify the scope as single-file versus session-wide without opening the 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 timing ('before reviewing it') and names the alternative for whole-session needs ('For the whole session use session_show'), which routes the agent correctly. It offers clear context but no explicit when-not-to-use beyond the sibling redirect.

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 cover the mutation profile (readOnlyHint=false, idempotentHint=false), and the description adds genuinely new behavior: the tool is single-shot per session and will be refused if a route exists, and it returns a routed-file count plus the 'uncovered' files the scope contains but the route left out. That post-condition and refusal semantics go beyond the structured fields.

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 core action and timing, then alternatives, then the refusal rule. Dense but every sentence carries information; the inline CLI invocation for the out-of-scope path is the only slightly heavy element.

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, yet the description explains the return shape (routed count and uncovered files), the prerequisites, the single-use constraint, and the remedy when refused. An agent has everything needed to decide whether to call it and what to expect back.

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 'route' and 'sessionId' are already fully documented (including priority ordering, relatedFiles, and suggestedReviewMode). The description contextualizes the route via the uncovered-files concept but adds no parameter-level format or syntax 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 and resource ('Set a guided review's ranked route') and immediately scopes it as 'the planning pass, once per session, before you review any file.' That framing separates it from the sibling review_propose_route_change, which it explicitly names as the change path.

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 the timing ('once per session, before you review any file'), the downstream routing alternatives (review_propose_route_change for files in the route, an out-of-scope declaration for files not), and an explicit exclusion ('Refused if the session already has a route; propose a change instead'). When-to-use, when-not-to-use, and the alternative are all stated.

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 the safety profile (readOnly hint false, destructive false, idempotent false, non-open-world). The description adds behavioral context beyond that: the proposal is adjudicated by a human who 'accepts or discards it,' and the call returns the proposal's id. It does not mention auth requirements, but the workflow outcome is disclosed.

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 kind taxonomy are front-loaded, and the sibling-routing sentence comes last where it is most useful. Slightly dense with em-dash asides, but every clause carries information and none is redundant.

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 5-param, non-destructive write with no output schema, the description covers the required kind/body semantics, the optional file/line scoping, and what the call returns ('answers the proposal's id'). The sessionId inheritance behavior is left to the schema, which is acceptable given the high schema coverage.

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 meaning to the `kind` enum by explaining what each value signifies (a question for the human, a follow-up after review, needs-context when the agent cannot judge). That is genuine semantic value beyond the schema's short enum labels.

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 (propose a guided-review item) and enumerates the three allowed kinds, immediately delimiting it as 'not a finding on the code.' It explicitly names and defers to review_propose_comment for line-level findings, 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 when-to-use for each of the three kinds, including the decision rule 'prefer it to guessing' for needs-context, and routes line-specific findings to review_propose_comment. Both the selection condition and the alternative are stated explicitly.

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 annotations (readOnlyHint=false, destructiveHint=false, idempotentHint=false), the description discloses the key behavioral trait: this only creates a proposal that the human accepts, edits, or discards, and only an accepted one becomes a comment. It also states the return value ('Answers the proposal's id'), which no structured field provides.

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 core action, then the proposal lifecycle, then routing guidance. Every sentence carries distinct information with no restatement of the name or 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?

No output schema exists, yet the description covers the return ('proposal's id') and the essential lifecycle (non-final until accepted). With 100% schema coverage and clear alternatives, nothing an agent needs to call this 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%, so parameters like line/end/file/type are already documented. The description's mention of line-range anchoring and the bug/refactor/performance examples only partially overlaps the enum values; it adds little syntax or format 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 ('Propose a finding') and the anchoring mechanism (line range), with concrete examples of finding types. It names the sibling it is not for (review_propose) and the outside-context alternative (comment_add), so an agent can distinguish it 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?

Explicit routing: 'For a question or missing context rather than a finding use review_propose; outside a guided review, comment_add.' Both the when-to-use and when-to-use-something-else paths are stated with the condition that selects them.

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 past the annotations: nothing takes effect until the human accepts in Reado, the running route is unaffected, a newer proposal replaces a pending one, the call resolves as a confirmation, and it is refused when no reason is supplied. These are exactly the mutation/authority semantics an agent needs and 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?

Front-loads the purpose, then adds behavioral constraints in tight clauses that each carry information (replacement rule, non-blocking behavior, confirmation/refusal). Dense but not padded; only the em-dash example list borders on redundant.

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 covers return behavior ('answers a confirmation'), the human-gated mutation model, and the sessionId fallback via the schema. For a 3-parameter, non-destructive proposal tool this is close to complete, though it never states what a rejection looks like.

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 route, reason, sessionId (including the omit-to-use-newest fallback). The description reinforces that a reason is mandatory ('refused without a reason'), but adds little on the route payload beyond what is structured. 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?

States a specific verb (Propose) plus a specific resource (a new route for a guided review already under way) and enumerates the kinds of changes it covers: adding a found file, reordering, dropping a file. The 'already under way' qualifier implicitly separates it from the sibling review_propose for initial planning.

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 usage context — it applies to a review in progress, and the agent is told to keep working the current file rather than wait. It also notes that a new proposal supersedes a still-pending one. It stops short of explicitly naming alternatives (review_propose, review_plan) or stating when NOT to use it.

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 write/idempotent/non-open-world. The description adds real behavioral facts beyond that: it overwrites the file's earlier summary, it transitions a file with no state to reviewed, and it returns a confirmation. It stops short of permissions or size/rate constraints, hence a 4 rather than 5.

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 core action and four short sentences with no filler; the alternatives clause is deliberately last. 'Answers a confirmation' is slightly awkward phrasing, which keeps it from a 5.

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 2-required-param mutation tool with no output schema, the description covers the trigger, the overwrite semantics, the state change, and a minimal return statement. Return details are thin ('Answers a confirmation') but sufficient for this interaction pattern.

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; the description goes slightly beyond by specifying what the 'text' parameter should contain ('what you checked, the risks you see, what comes next'), which is content guidance the schema's 'a few lines, in Markdown' does not provide.

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?

Specific verb+resource (record a file's mini-summary) inside a clearly scoped context (guided review of a single file). It explicitly distinguishes itself from the sibling session_summarize, and separates a per-file action from the whole-review action.

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?

States the trigger condition plainly: 'when you finish reviewing it in a guided review,' and names the alternative for the other case ('For the whole review use session_summarize'). An agent has an explicit routing rule and does not need to infer it from sibling names.

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 establish this is a non-read-only, non-idempotent action, and the description adds a real behavioral consequence not in the annotations: Reado alerts a user who has walked away, so a premature call 'fetches them back for nothing.' That side effect is the key operational trait. It does not, however, describe any result/confirmation behavior, and the trailing 'Answers an acknowledgement.' is opaque.

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 critical trigger and its exclusion are front-loaded and the sentence count is small. Minor waste and confusion come from the garbled 'Reado' reference and the unfinished 'Answers an acknowledgement.' fragment.

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 and zero required parameters, the description's main job is to nail the invocation trigger, which it does thoroughly, including the anti-pattern case. It is nearly complete; only the vague closing fragment leaves a small 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 100%: both parameters (status enum, summary line) are fully documented in the schema, including the enum values and what the summary becomes. The description adds nothing 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 clearly states the tool signals the end of the turn ('your next act is to wait for the user'). It distinguishes the session-level trigger from intermediate steps, but never names or differentiates itself from the closely related task_done/task_fail/task_block siblings, which an agent will have to disambiguate on its own.

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 gives explicit when-to-call conditions (finished, blocked, need an answer) and an explicit when-NOT ('NOT after a command returns or a step completes... if you will do anything else before stopping, it is too early'), plus the rationale that a premature call needlessly summons the user. This is about as complete as usage guidance gets.

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, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description goes beyond that by itemizing the return payload, which matters because there is no output schema, and by noting any pending route change is surfaced. It stops short of describing size, pagination, or failure behavior when no open session 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 sentences, both front-loaded: the return contract first, then the usage routing. The long middle enumeration is dense but earns its place given the absence of an output schema, and there is no filler or restatement of the name.

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 does so thoroughly across scope, objective, route, per-file state, proposals, and pending changes. Combined with annotations that cover the safety profile, an agent has everything needed to call this correctly on the first try.

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 single sessionId parameter already documents both its origin and the omit-to-use-newest-session fallback, so the schema does the heavy lifting. The description adds no syntax or format detail about the parameter beyond that. Baseline 3 is correct for a fully documented single-parameter 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 verb ('Read') and resource ('a guided-review session in full, as JSON') and then enumerates exactly what the payload covers: scope, objective, route, per-file state, proposals, and pending route change. It also draws the boundary against the sibling review_context ('for a single file, review_context is smaller'), so an agent can distinguish it 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?

Gives two explicit invocation conditions ('call it first on a READO GUIDED REVIEW prompt' and 'to find your place after losing context') plus the negative case that routes the agent to a smaller alternative for a single file. Nothing about when to prefer this over siblings is left to inference.

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 cover mutation and idempotency, and the description adds the important replacement semantic ('It replaces any earlier recap') plus the fact that the call yields a confirmation — neither of which is in the annotations or an output schema. It doesn't state permissions or authoring constraints, keeping it short of a 5.

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, the core action and scope front-loaded, with the sibling pointer last. 'Answers a confirmation' is slightly stilted, but nothing is 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 2-parameter write tool with no output schema, the description covers what is recorded, the replacement behavior, and that a confirmation is returned, which is enough to call it correctly. It omits any error or permission caveats, so not a full 5.

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; the description earns extra by specifying what belongs in the required 'text' payload (findings, prioritized risks, remaining work), which the schema's terse 'The recap, in Markdown' does not convey. It adds little about sessionId beyond what the schema already explains.

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 ('Record a guided review's overall recap') plus the scope of that recap (findings, top risks, what's left). It also explicitly distinguishes itself from review_summarize_file, so an agent can pick the right tool 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?

Gives a clear timing condition ('once the routed files are done') and names the sibling to use for per-file notes. It lacks an explicit when-not case, but the overall-vs-per-file split effectively covers the main routing decision.

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 annotations (non-readOnly, idempotent, non-destructive) by disclosing the full lifecycle: the block persists until the human answers in Reado, answering reopens the task with a fresh attempt count, and blocking again replaces the reason. It also names the returned fields (id, state, reason) where 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?

Three sentences, front-loaded with purpose then lifecycle then return shape, with no filler. Every clause carries distinct information: trigger, persistence/reopen semantics, reason-replacement behavior, and response fields.

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 supplies the return contract (id, state, reason) and the state-transition semantics an agent needs before invoking. Annotations already cover the safety/idempotency profile, so nothing material 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 both parameters are fully documented in the schema itself, including that 'reason' is written for the human answering. The description restates 'your reason' without adding format, length, or content guidance 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 and resource ('Block a task') and pins the exact triggering condition ('you cannot finish without the human — a decision, a credential or context you don't have'). That condition implicitly separates it from task_done and task_fail, though neither sibling is named outright.

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 when-to-use context via three concrete triggers (decision, credential, missing context). It stops short of explicit when-not guidance, e.g. when blocking is inappropriate versus failing the task with task_fail, leaving that boundary to inference.

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 annotations by disclosing what `verify` actually does — runs the command in the project root, exit 0 archives the task, failure or omission leaves it resolved-but-unverified and visible to the human. It also describes the return shape (id, state, resolution as JSON). This is exactly the kind of side-effect context annotations (readOnlyHint/destructiveHint false) cannot convey.

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 primary action and consequence before the fallback routes. No filler; every clause carries either behavior, routing, or return-value information.

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, but the description explicitly states what is returned (id, state, resolution as JSON), and it covers the mutation's side effects, the verify lifecycle, and escalation paths. Nothing an agent needs to call this 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 is 3, but the description adds real meaning the schema does not: the behavioral consequence of `verify` (archival on exit 0 vs. unverified state on failure) and that `diffRef` is surfaced to the reviewer. `id` and `model` are left to the schema, hence not a 5.

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?

Specific verb+resource ('mark a task resolved ... recording how') and it explicitly names the sibling tools it is not (task_fail, task_block), so an agent can route without opening a schema. Clearly differentiated from the browser_* and review_* siblings.

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?

States the trigger (once your change addresses it), the alternatives by name, and the selecting condition for each: task_fail if the attempt didn't work, task_block if you need the human. When/when-not is fully 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?

With no output schema, the description carries return-value burden and does so: 'Answers the task's id, state and attempt count as JSON.' It also discloses non-obvious state machine behavior (returns the task to open; third failure blocks until a human answers), which annotations cannot convey beyond readOnlyHint=false/idempotentHint=false.

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 short sentences, front-loaded with the action, then state consequences, then return format, then routing. Every sentence earns its place with no 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?

Covers action, state transition, retry/blocking threshold, return payload, and the alternative tool. Nothing an agent needs to call this correctly (including the non-idempotent attempt increment) 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 both parameters (id, note) are fully documented inline, so the schema does the heavy lifting. The description adds no syntax or format detail beyond what the schema supplies; baseline 3 is correct.

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+resource ('Record a failed attempt at a task') and immediately distinguishes it from the sibling task_block and, implicitly, task_done. An agent can tell exactly what operation this is 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 names the alternative and the condition selecting it: 'When you already know you need the human, use task_block instead.' The 'if it just didn't work, fail it' path is implied by the whole framing, giving clear when/when-not guidance.

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