ClawdCursor

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

Goes well past the annotations by naming exactly which actions mutate state ("`invoke`, `set_value`, `toggle` and `select` change the app") and adding a safety rule that annotations cannot express: destructive target names (Send, Delete, Pay) require user confirmation. It also discloses output shape and paging. Not a full 5 because return/error behavior for the mutating actions themselves (what invoke or state returns, what happens on element-not-found) is left unstated.

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 "START HERE" and the action list before the preference rule and output semantics, which is the right ordering for a 24-param multi-action tool. It is dense and occasionally stacks three ideas into one sentence (aliases + coordinates + paging), but no sentence is 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 correctly carries the burden of explaining what `read_tree`/`find`/`compile_ui` return and how to chain results. For a 24-param tool the gaps are in the less-used params and the responses of non-read actions, which are secondary but not negligible.

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 earns above it: it explains the `read_tree`/`find` line format, that coordinates are SCREEN space to be clicked with `computer click space:"screen"`, that offset pages past "+N more", and that `find_button`/`find_field` yield an {element_id, snapshot_id} pair to feed into `invoke`/`set_value`. It does not touch roughly half the params (timeout, max_cost, expect, limit, controlType, automationId, mode), so 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?

Opens with an explicit verb+resource framing ("see and drive a window: the OS accessibility tree") and enumerates the concrete capabilities (read names, find by name/role, invoke, toggle, set value, select, query state). It distinguishes itself from the sibling `computer` tool by name and function, so an agent can pick it 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 a hard routing rule: "Always preferred over `computer.click(x,y)` when the target has a name" and names the reason (DPI, resize, layout shifts). It also carves out the fallback path for sparse/ambiguous UIs via `compile_ui`/`find_button`/`find_field` and their coordinate-free {element_id, snapshot_id} handoff. Both when-to-use and when-to-use-something-else are 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 declare destructive/openWorld/non-idempotent, and the description adds substantial context beyond them: the batch HALTS on the first failed precondition, safety stop, or step error and returns a per-step trace; every step passes the same safety gate as a direct call; allowConfirm only works if the daemon was started with CLAWD_BATCH_ALLOW_CONFIRM=1 and never bypasses block-tier. These are exactly the operational traits an agent needs and none are in 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?

Purpose is front-loaded and every sentence carries information about halting, safety gating, or parameter aliases. It is dense and parenthetical-heavy, which slightly hurts scanability, but there is 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?

For a complex, no-output-schema meta-tool this is thorough: it covers step structure, aliases, precondition semantics, halt conditions, the safety gate, dryRun, and confirm-tier gating. An agent has everything needed to construct and reason about a batch without opening the schema.

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: `expect` is a precondition re-checked by re-perceiving before the step runs, `args` is an alias of `arguments`, and `arguments` may carry an `expect` assertion array verified post-step. The allowConfirm env-var gating and dryRun pre-scan behavior also go beyond the schema text.

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 opening sentence names a specific verb and resource ('Run an ORDERED LIST of tool calls in one shot') and explains the mechanism ('collapses many round-trips into one'). It also clarifies its relationship to the sibling tools by describing each step as 'a normal tool call (compound like computer/window or a granular tool)', so an agent can distinguish this meta-tool from the single-capability 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?

It gives concrete usage guidance: use `expect` to 'guarantee you act on the right window/element instead of guessing', and set dryRun:true to pre-scan safety tiers without executing. It also states the halt semantics that govern when a batch is viable. It stops short of an explicit 'prefer batch over sequential calls when X' rule, so 4 rather than 5.

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

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

Annotations already declare destructiveHint=true, openWorldHint=true and idempotentHint=false, so the safety profile is covered. The description adds genuine operational context — that the browser may be launched on demand or attached to an existing debug port. It does not mention that `evaluate` runs arbitrary JavaScript in the page or that actions mutate page state, which is the main residual risk left to 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 the tool's operating model, then the entry-point rule, then the action list. Efficient overall, though the trailing action enumeration duplicates the enum already in the schema and could be trimmed.

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 selection and the critical bootstrap sequence for a 13-parameter open-world tool. There is no output schema, and the description says nothing about what actions return (e.g. `page_context` yielding a structured interactive-element list, `evaluate` returning a value) or about the DEVIATION semantics of `expect`, which are left to the schema prose.

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%, including a per-action required-parameter map in the `action` enum description. The description's action list is a restatement of that enum and adds no per-action parameter semantics beyond it, 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 mechanism (Chrome DevTools Protocol control) and a distinguishing operating model (DOM elements by CSS selector rather than screen pixels), which immediately separates it from the pixel-based `computer` tool. An agent can tell what this tool does 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 an explicit entry sequence — start with `navigate` (launches) or `connect` (attaches to an existing debug port), then operate on that page — and recommends this over `computer` for web automation. It lacks the inverse guidance (when to fall back to `computer`, e.g. non-browser or canvas-only UI).

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 readOnlyHint=false, so the safety profile is covered. The description adds non-obvious behavior the annotations cannot: default coordinate space, the shot-id freshness rule ('Refused when it is not the latest screenshot'), and the expect post-condition contract that returns a DEVIATION the agent must adapt to. It doesn't warn about irreversible click consequences, but the annotations carry that.

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 purpose, then routing, then coordinate semantics — a sensible order with no filler. The long inline action list partially duplicates the schema enum, which is the only waste.

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 24-parameter, no-output-schema tool this covers the essentials: action selection, coordinate spaces, screenshot lifecycle, and verification via expect. Return shapes are only partly implied (the 's3' screenshot id is mentioned in-schema rather than the description), leaving 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%, so baseline is 3; the description still adds value by explaining that coordinates default to image-space of the latest screenshot and that space:"screen" is for positions reported by accessibility (unscaled). That cross-tool coordinate contract is not obvious from the schema alone.

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?

Opens with a specific verb+resource ('Direct mouse/keyboard/screenshot control') and enumerates the full action set, so the agent knows exactly what surface this tool covers. It explicitly distinguishes itself from the accessibility and system siblings, which neither tool's name alone would convey.

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 when NOT to use it ('screenshot is the LAST RESORT... first try accessibility read_tree/find/compile_ui or system copy_all_text') and when to use it ('only when you need pixel-level control'), naming the concrete alternatives. This is explicit when/when-not/alternative routing.

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?

Although annotations already flag destructive, open-world, and non-idempotent behavior, the description adds substantial context beyond them: `clipboard_write` overwrites the user's clipboard, `relaunch_with_cdp` closes the app and can lose unsaved work, `report` sends nothing, `build_uri` has no side effects, and `pause_for_user` returns running/timeout statuses. It also explains that screen-derived text is wrapped in `<untrusted-screen-content>`, which is a critical safety 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?

The description is front-loaded and every clause carries useful information, but it is a dense run-on paragraph covering 19 actions. It would be easier to scan with bulleted grouping. For a multiplexed tool of this size the length is justified, though the structure could be improved.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the complexity of 21 parameters, 19 sub-actions, no output schema, and destructive/open-world annotations, the description covers all enumerated actions and explains return content at a high level. It warns about destructive behavior and the untrusted-content wrapper, which is complete enough for an agent to call the tool correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 100% schema description coverage, the baseline would be 3, but the description adds value by tying required parameters to their actions: `clipboard_write: text`, `shortcuts_run: intent`, `delegate: task`, `pause_for_user: message`, `relaunch_with_cdp: appName`, `build_uri: scheme`, and so on. It also clarifies the timeout semantics. However, some parameters such as `expect`, `done_when`, and `mode` receive little or no action-specific treatment in the description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a clear scope statement and explicitly distinguishes this tool from its siblings: elements go to `accessibility`, raw clicks and keys to `computer`, windows to `window`. It then names every sub-action with a specific verb/resource, so an agent can identify both the overall capability and individual actions 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 provides explicit when-to-use guidance throughout: prefer `copy_all_text` to OCR, use `ocr` when the accessibility tree is empty, use `pause_for_user` for sign-in/2FA/CAPTCHA, use `relaunch_with_cdp` only for sparse Electron/WebView2 trees, and use the sibling tools for elements, raw clicks, and windows. Alternatives and exclusions are stated directly.

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 it discloses the daemon prerequisite, bounded-sync wait semantics (returns {status:"running"} while continuing), re-attach-not-restart behavior, and the pause-at-roadblock model (sign-in, 2FA, CAPTCHA) with waitingFor. These are substantial operational traits the annotations do not 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?

The daemon prerequisite is front-loaded and every block (usage, bounded-sync, pause handling, sibling contrast) is relevant. It is dense and somewhat long for a description, with minor repetition of the resume/status guidance also present in the schema, but no wasted sentences.

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 complex open-world agent tool with no output schema, it still describes return shapes ({status:"running"}, {status:"paused", waitingFor}) and the failure mode when the daemon is absent. An agent has everything needed to invoke and manage the task lifecycle 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 coverage is 100% and each parameter already has an enum/description, so the schema carries the parameter burden. The description adds the 1–50 clamp context and re-attach semantics, but largely restates what the schema documents, warranting the baseline 3.

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?

It states a specific verb and resource: hand a whole natural-language task to an internal agent loop that decomposes and executes it. It also explicitly distinguishes itself from the sibling compounds (computer/accessibility/window/system/browser) that give step-level control, so an agent can route correctly 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?

It gives explicit when-to-use ("when you don't want to micromanage every primitive") and names the alternative for step-level control. It further spells out the call patterns for each state: re-call to keep waiting, {action:"status"} to poll, {action:"abort"} to stop, {action:"resume"} after user completion.

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: close behaves like the ✕ and can lose unsaved work, gated on user confirmation; focus keeps the window maximized; switch_tab is a keyboard shortcut sent to the focused browser; open_app reports when no window appeared yet; failures explain why (no match, refused by safety gate). This is consistent with destructiveHint/openWorldHint and adds the specifics 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-loaded with purpose and sibling routing, then grouped read-only / arrange / open actions. It is dense and runs long per action, but nearly every clause carries operational detail; a small amount of tightening (e.g. the nested parentheticals in `resize`) would help.

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 15-action dispatcher with no output schema, it explains the return text ('the window list, or one line saying what happened') and failure modes. The only gap is the `expect` post-condition parameter, which is left entirely to the schema; otherwise complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 93%, so the schema carries most parameter docs, but the description adds material semantics the schema does not: target resolution by processName, processId or title substring with foreground as the default when none is given, resize units in screen px vs space:'image' for screenshot pixels, and that omitted resize fields are kept. The schema's `space` description is empty, which the description fills.

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 and resource: OS-level windows, apps and displays, with find/open/focus/arrange. It explicitly draws the boundary against siblings: 'For what is INSIDE a window use `accessibility`; for a web page's DOM use `browser`.' An agent can route correctly 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?

Names alternatives and the conditions that select them (accessibility for window content, browser for DOM, navigate vs open_url, clawdcursor's own browser). Per-action guidance is explicit, including when close requires user confirmation and that open_file executes .exe/.app.

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