ClawdCursor

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

Annotations declare destructiveHint=true but not which actions are destructive; the description fills that gap by naming the mutating actions ('invoke, set_value, toggle and select change the app') and explaining that destructive target names require user confirmation. It also documents aliases, the coordinate space of returned elements, and pagination via '+N more'/offset.

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 highest-value guidance ('START HERE', the preferred-over-computer rule) before the long action list. It is dense and long, but for a 24-action tool nearly every sentence carries routing or safety information, so the length is largely justified.

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 does the required work of describing return shapes ('one line per element — [Role] "name" @x,y w×h ... plus value=') and pagination. A few actions (state, list_children, wait_for, smart_read/smart_type) get no explanation, but the core read/act path is fully covered.

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 every parameter and a 3 is the baseline. The description adds real value beyond it: alias mapping (click/set-value/get-value), the fact that read_tree/find use SCREEN coordinates clickable via `computer click` space:"screen", and the element_id+snapshot_id handoff flow.

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 ('see and drive a window: the OS accessibility tree') and enumerates the concrete capabilities (read names, find by name/role, invoke, toggle, expand/collapse, set value, select, query state). It cleanly distinguishes itself from sibling `computer` by describing a name-based accessibility approach versus coordinate clicking.

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 precedence: 'Always preferred over computer.click(x,y) when the target has a name', with the reasons (DPI, resize, layout shifts). It also routes to alternatives for hard cases: use compile_ui / find_button / find_field for 'sparse/ambiguous UIs'.

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, non-idempotent and non-readOnly, so the safety profile is covered. The description adds genuinely useful lifecycle context the annotations don't carry: it may launch a browser, it attaches via debug port, and it acts on DOM selectors rather than pixels. It stops short of noting auth needs or per-action side effects, so it isn't 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?

Front-loaded with the core concept, then workflow, then alternatives — a sensible ordering. The trailing enumeration of the 12 actions partially duplicates the schema enum, which is slightly wasteful, but it does help an agent pick an action. Two dense sentences plus a list, 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 12-action multiplexer with no output schema, the description covers the setup sequence and the primary interactions well. It does not describe what individual lower-traffic actions do (evaluate, list_tabs, wait_for) or what any action returns or errors on, which is a real gap for a tool this broad. Still substantially complete for the main path.

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

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

Schema description coverage is 100%, so all 12 parameters are already documented in the schema (timeout, maxLength, amount, selector, etc.). The description adds only an implicit hint about selector/text usage via the DOM-vs-pixels framing and the action list; it gives no format or constraint detail beyond 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?

The description names the mechanism precisely (Chrome DevTools Protocol control) and the operating model (DOM elements via CSS selector rather than screen pixels), then enumerates the full action set. It explicitly distinguishes itself from the `computer` sibling, so an agent can route between them 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 an explicit workflow: start with `navigate` or `connect`, then `page_context`/`click`/`type` on that page. It also distinguishes when to use `navigate` (agent's own CDP browser, launching if needed) vs `connect` (attach to a browser already on the debug port), and names `computer` as the less reliable alternative for web automation.

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, readOnlyHint=false, and non-idempotent, so the safety profile is partly covered. The description adds genuine behavioral context: coordinates default to image-space pixels and are scaled to the screen, space:"screen" uses unscaled reported positions (with a macOS point-vs-pixel caveat), and the expect parameter returns a DEVIATION on failed post-conditions requiring adaptation. It does not restate the destructive nature, but the added coordinate and verification semantics are substantive.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the core purpose, then the action enum, then routing guidance, so the most important selection signal (prefer accessibility) lands early. The long action enumeration is dense but earns its place by defining the dispatch surface. Minor redundancy in restating the enum, but no wasted prose.

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 23-parameter, multi-action tool with no output schema, the description covers dispatch, coordinate spaces, sibling routing, and post-condition verification. Annotations carry the safety profile. The one gap is that individual action-to-parameter mappings (which params apply to which of the 23 actions) rely entirely on the schema, but the overall behavioral envelope is well specified.

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 cross-cutting meaning the schema alone does not: the default coordinate space is image-space scaled from the latest screenshot, and pass space:"screen" to click positions reported by accessibility. This resolves the ambiguity of how x/y map between capture and screen, which is the highest-risk semantic in the tool.

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 family and resource ('Direct mouse/keyboard/screenshot control') and enumerates the full set of sub-actions, so an agent knows exactly what capability this covers. It explicitly differentiates itself from siblings by naming accessibility and system as the preferred alternatives for named targets and text. No other sibling tool overlaps this pixel-level control scope.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives explicit when-to-use and when-not-to-use guidance: screenshot is the LAST RESORT, first try accessibility read_tree/find/compile_ui or system copy_all_text, prefer accessibility for named targets, and use computer only for pixel-level control. It names the alternative siblings and the condition that selects each, leaving nothing 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?

Beyond the annotations (destructiveHint=true, openWorldHint=true), the description discloses the concrete destructive consequences: relaunch_with_cdp 'CLOSES the app and restarts it with a debug port — unsaved work can be lost, so it needs the user's confirmation', and clipboard_write 'overwrites the user's clipboard'. It also documents control-flow behavior unique to this tool (pause_for_user's waiting receipt and re-call pattern, report sends nothing, build_uri has no side effects) and the untrusted-content wrapping.

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?

It is front-loaded with the scope statement and sibling routing, and with 19 sub-actions nearly every clause carries necessary routing information, so length is justified. The cost is a single dense paragraph with no line breaks, which makes it harder to scan than a bulleted action list would be.

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 19-action multiplexer with no output schema, the description covers the high-risk paths (destructive relaunch, clipboard overwrite, user-pause protocol) and return framing ('Returns text; screen-derived text is wrapped in <untrusted-screen-content>'). A few low-risk actions (system_time, undo, system_prompt) have only brief mentions, leaving minor gaps in return expectations.

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: timeout 'waits up to timeout s, then returns {status:"waiting"}' plus the clamped range, scope semantics for ocr, context = the app for shortcuts_run, and scheme+path/query feeding build_uri then open_uri. It maps parameters to actions rather than merely restating field descriptions.

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

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

The opening sentence names the specific domain (screen text, clipboard, shortcuts, user hand-off, URI launching) and immediately draws the boundary against siblings: 'For elements use accessibility; for raw clicks and keys computer; for windows window.' An agent can classify a task to this tool versus the four siblings 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?

Every sub-action carries a when-to-use clause plus alternatives: 'read through accessibility with no keystrokes where possible; prefer it to OCR' for copy_all_text, 'for when the accessibility tree is empty' for ocr, 'the same as on window' for the open_* actions, and detect_webview/relaunch_with_cdp routed to browser for sparse Electron/WebView2 trees. Exclusions and prerequisites are stated explicitly rather than inferred.

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 the hard prerequisite (daemon on 127.0.0.1:3847 with an LLM configured), the bounded-sync wait semantics and its default, that a timed-out task continues in the background rather than restarting, and that roadblocks (sign-in, 2FA, CAPTCHA) cause a pause with `waitingFor`. These are exactly the 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?

Front-loads the daemon prerequisite, then purpose, then protocol, using bold caps to mark the load-bearing clauses. It is long, but every sentence carries distinct operational information; the density is warranted by the tool's complexity.

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 compensates by naming the return shapes ({status:"running"} with progress, {status:"paused", waitingFor}) and the daemon-error path. Combined with the protocol for continuing, polling, and aborting, an agent has everything required to call and recover from this tool.

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

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

Schema description coverage is 100%, so the enum actions, timeout bound, and instruction requirement are already documented. The description reinforces the same facts (default 45s, clamp, ignored for status/abort) but adds no syntax or semantics beyond the schema, making the baseline 3 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+resource: hand a whole natural-language task to clawdcursor's internal agent loop, which decomposes it and picks the cheapest execution path. It explicitly contrasts with the step-level `computer`/`accessibility`/`window`/`system`/`browser` siblings, so an agent can route without opening any schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives an explicit when-to-use trigger ("when you don't want to micromanage every primitive") and names the alternatives plus their role (step-level control). It also spells out the operating protocol under failure: re-call with the same instruction to keep waiting, poll with status, abort, or resume.

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

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

The annotations already flag this as non-read-only, open-world, non-idempotent, and potentially destructive, but the description adds important specifics: `close` may trigger save prompts and lose unsaved work, requires user confirmation through a safety gate, and failures explain why. It also discloses that `open_file` executes executables and that `open_app` reports when no window has appeared yet.

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 dense but front-loaded and appropriately sized for a 15-action tool. Each sentence carries necessary routing or behavioral information, and the read-only / arrange / open grouping gives the agent a usable structure without 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?

There is no output schema, but the description explains the return format as text: a window list or a one-line result, with failure reasons such as no matching window or safety-gate refusal. Combined with the annotations and parameter coverage, it contains everything an agent needs 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?

Although schema coverage is high at 93%, the description adds substantial semantic detail beyond the schema: window targeting works via `processName`, `processId`, or a `title` substring, and defaults to the foreground window when none is supplied. It also clarifies resize coordinates and units, the `space:"image"` alternative, omitted-field preservation, and the 1-9 tab index / next-previous direction behavior.

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 precise verb-and-resource statement: OS-level windows, apps, and displays, with find/open/focus/arrange operations. It explicitly distinguishes this tool from `accessibility` (inside a window) and `browser` (web DOM), so an agent can select it confidently against its 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 explicit alternatives and boundaries: use `accessibility` for what is inside a window, and `browser` for a web page's DOM. It also routes the agent through the sub-actions with their intended use cases, including targeting rules for arranging and the distinction between `open_url`, `navigate`, and `switch_tab`.

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