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

With no annotations, the description carries the burden: it usefully establishes the mental model that side effects are identical to pressing the UI button/menu item, which tells the agent this is a mutating, state-changing call. It omits failure behavior for unknown keys, whether the action is synchronous, and what is returned, so significant gaps remain for an unannotated mutation tool.

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

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

A single front-loaded sentence with no filler; the operation, mechanism, and behavioral analogy are all packed into one clause with nothing wasted.

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 and no annotations mean the description must do more: it never says what happens on an invalid key, whether the UI must be idle, what the call returns, or how to enumerate action keys. For a two-parameter trigger tool with an undocumented required parameter, this is insufficient.

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 only 50%: settle_ms is documented in the schema, but 'key' has no schema description and the description does not explain its format or how to discover valid values (e.g., via the list_actions sibling). 'By key' only loosely links to the parameter without adding usable syntax.

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: trigger a Cascadeur action identified by key via ActionManager.call_action. That identifies the operation precisely and implicitly separates it from raw UI tools like ui_click/ui_invoke, but the description never names those siblings to make the distinction explicit.

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?

'Exactly like its toolbar button or menu item' implies a semantic-level alternative to clicking through the UI, but there is no explicit when-to-use guidance against siblings such as ui_invoke, ui_click, or run_python, and no prerequisites or exclusions 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?

With no annotations the description carries the full burden. It usefully discloses scope ('visible' only) and return shape ('texts and buttons as refs'), but says nothing about whether the call blocks, what happens when no dialog is present, or how the refs relate to the ui_* action tools.

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?

A single front-loaded sentence with no filler; the resource type and the returned payload are stated immediately.

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 listing tool with no output schema, the description covers what is returned and that only visible dialogs are included. A note on ref usability with ui_click/ui_type would make it 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?

The tool takes zero parameters, so the baseline is 4. Nothing in the description contradicts or adds burden to the empty 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 (list) and a specific resource type (visible dialogs/popups/secondary windows) plus what is returned (texts and buttons as refs). It implicitly distinguishes itself from generic siblings like ui_tree or screenshot by narrowing to modal/secondary windows, though it never names them explicitly.

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?

No explicit when-to-use or when-not guidance. The intent (find dialog buttons and their refs so they can be clicked) is inferable but left to the agent, and there is no statement about alternatives such as ui_tree or ui_click.

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 annotations, the description carries the full burden and does well: it discloses the crash consequence of skipping it and that execution runs on the scene idle event. It does not cover idempotency, return behavior, or whether re-entry is safe, keeping it below 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?

Two dense sentences with the purpose front-loaded and the prerequisite/crash rationale following immediately. The final sentence about the idle event is slightly implementation-flavored but still informative.

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-required-param mode switch with no annotations or output schema, the description covers purpose, prerequisites, entry-point variants, and failure mode. Only return/verification behavior is unaddressed.

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

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

Only one optional parameter (color) and schema coverage is 100%, so the schema already documents format and default. The description adds nothing about color, so the baseline of 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 ('Enter Cascadeur's Rig mode') and names the exact entry points used (rig_mode.on, run_after_import). None of the siblings (call_action, run_python, ui_*) do mode switching, so the tool is clearly distinguishable.

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 guidance: it is required before Quick Rigging's Add rig elements / Generate rig, and run_after_import is specified for a freshly imported model. No explicit 'when not to use' is given, but there are no real alternatives among the siblings.

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

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

With no annotations, the description still makes clear this is a read ('Read the tail'), which is the main safety signal. It adds genuinely useful context about what the file contains, but omits default line count, maximum size, and whether reading has side effects or permission requirements.

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?

One sentence, front-loaded with the action and resource, and the parenthetical is informative rather than filler. Nothing extraneous, though it is arguably too terse given the unannotated parameters.

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 the bar is low and there's no output schema to explain, but the missing parameter semantics (default line count, filter behavior) leave real gaps that the description should have closed given zero schema coverage and zero annotations.

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 0%, so the description must carry the parameter burden and it largely doesn't: 'optionally filtered' only gestures at the `contains` parameter without saying it's a substring match, and `lines` is never mentioned at all (no default, no cap). An agent would have to guess both semantics.

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 tail of Cascadeur's log file') and adds what kind of content lands there (errors and Python tracebacks), which tells an agent this is the diagnostic output channel. It doesn't need sibling differentiation because no other tool in the list touches logs, so a 4 rather than 5.

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 parenthetical about errors and tracebacks implies the use case (debugging a failed script or inspecting runtime errors), but the description never states when to reach for this over run_python or get_scene_info, nor any preconditions. Usage is inferable rather than 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?

With no annotations at all, the description carries the full burden. It does disclose one real behavioral trait — that name matching can be partial, not just exact — and that results include behaviours and their property names. It never states that this is a safe read operation, nor what happens when a partial name matches many objects.

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?

A single front-loaded sentence with no filler; the match-mode detail appears early. The phrase 'behaviours with their property names' is slightly compressed to the point of ambiguity but the 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 small read-style tool with no annotations and no output schema, the description covers the return content reasonably well. It leaves out the truncation behavior implied by 'max_properties' and what happens on ambiguous partial matches, which an agent would need before calling it reliably.

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 0%, so the description must compensate. It adds real meaning for 'name' (exact or partial matching) but says nothing about 'max_properties', which is undocumented in both the schema and the description — a significant gap for a 2-parameter 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+resource ('Describe objects by exact or partial name') and enumerates what comes back (type, id, behaviours with property names), which clearly distinguishes it from the UI/action/log siblings. It falls short of 5 only because 'describe' versus 'get info' is slightly ambiguous about whether it returns a schema-like summary or runtime values.

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?

There is no when-to-use or when-not-to-use guidance, and no named alternative — yet siblings such as get_scene_info plausibly overlap for object introspection. The only implicit usage signal is the mention of exact or partial name matching; an agent must infer the rest.

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?

No annotations are provided, so the description carries the full burden. It does disclose the return content areas (frames, counts, selection, rig/animation, license), which is valuable, but says nothing about cost, permissions, truncation, or how large scenes are handled.

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?

A single dense sentence with the resource stated first and the payload contents front-loaded. 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 and no annotations, the description does well to enumerate the returned sections, but it leaves the one parameter and any behavioral bounds (scene size limits, response size) unexplained, which matters for a scene-wide scan 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 0% and the single parameter max_objects is never mentioned in the description. Whether it caps the object list, truncates counts, or has any default is completely undocumented.

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 (summarize) plus resource (current scene) with an enumerated content list: name/path, frames, object counts, selection, rig/animation, license flags. It is clearly a whole-scene overview, which implicitly separates it from get_object_info, but no sibling is named explicitly.

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?

There is no explicit when-to-use, when-not, or alternative named. An agent must infer from 'summarize the current scene' that this is the broad orientation call versus get_object_info or get_log — the description never states that 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?

No annotations are provided, so the description carries the full burden, yet it only discloses that keys are 'found in the UI' and come 'with labels'. It says nothing about whether the result is exhaustive or scoped, whether hidden actions are omitted by default (only implied by the schema's include_hidden), or whether this requires a live Cascadeur UI session.

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?

A single front-loaded sentence with the resource named first and the example format appended where it is most useful. No filler, no restatement of the tool 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 annotations, no output schema, and 0% parameter coverage, the description needs to do more: it never characterizes the two filter parameters or the shape of returned entries (actionId + label is only hinted at). For a discovery tool meant to feed call_action, the missing linkage and filter semantics are real gaps.

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 0%, so both parameters ('query' and 'include_hidden') are undocumented anywhere. The description never explains what the query string matches against (key path, human label, or both) nor what counts as a hidden action, leaving the agent to guess at filtering 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?

States a specific verb and resource ('List Cascadeur action keys (actionId)') and even supplies a concrete example value ('Commands.Rig mode.On') plus the presence of labels, so the agent knows exactly what comes back. It does not explicitly contrast with the sibling call_action, but the 'list vs. call' distinction is inferable from the name and example format.

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?

There is no statement of when to use this tool, when to prefer a different sibling (e.g. calling an action directly via call_action), or what prerequisites exist for the UI to be present. The pairing with call_action is left entirely to inference from the tool name.

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 annotations, the description carries the full burden, and it does add real context: projection depends on the viewport camera and a 30-degree vertical FOV verified for Cascadeur 2026.2.3. However, it says nothing about the return shape (which is critical since there is no output schema), what happens for missing/occluded objects, or whether the 3D viewport must be active.

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

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

Two compact clauses, front-loaded with the core action, followed by the coordinate consumer and the camera/FOV caveat. No filler 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 tool with zero annotations, no output schema, and 0% parameter coverage, the description should explain the returned coordinate structure and failure behavior. It covers the projection model well but leaves those gaps, so an agent cannot fully predict the response.

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 0%, so the description must compensate. It does clarify that 'names' refers to scene object names and implies 'fov_deg' defaults to the 30-degree vertical FOV, but it leaves the expected name format (short name vs. path) and override semantics of fov_deg ambiguous.

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 ('project scene objects ... to main-window coordinates in the 3D viewport') and names the downstream consumers (ui_click/ui_drag x/y). An agent can tell immediately that this converts object names into clickable screen coordinates, distinct from coordinate-free siblings like ui_tree or get_scene_info.

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 phrase 'for ui_click/ui_drag x/y' gives a clear use context: call this first when you know an object name but need pixel coordinates. It does not state exclusions (e.g. objects off-screen or behind the camera) or name alternatives, so it stops short of full 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.

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

With no annotations, the description carries the full burden and discloses important behavior: execution on the GUI thread, available scope objects, return of stdout and an expression/result variable, and the caveat that scene.modify*/edit return False on callback failure. It omits broader side-effect or permission considerations, but the runtime and failure semantics are unusually well covered.

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 tightly packed sentences with no filler. The execution environment and scope are front-loaded, followed by return and failure behavior, so every clause earns its place.

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

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

For a two-parameter tool with no output schema and no annotations, the description covers execution context, scope, return values, and a key failure mode. The main remaining gap is usage routing versus siblings, but the core invocation semantics are adequately 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 50%; the timeout parameter is documented in the schema, while the required code parameter has no schema description. The description compensates by explaining what is in scope for the code and how results are returned, but it does not explicitly discuss timeout behavior or parameter-level semantics.

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 environment: 'Run Python inside Cascadeur on the GUI thread.' It also names the variables in scope, making the tool's purpose unambiguous. However, it does not explicitly differentiate itself from siblings like call_action or the ui_* tools, so it falls short of a 5.

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

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

The description explains what the tool does but gives no guidance on when to choose it over call_action, ui_invoke, or other siblings. There are no when-not conditions or alternative routing hints, leaving usage selection entirely 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?

No annotations exist, so the description carries the burden. It usefully discloses the pixel-to-window coordinate conversion returned with the image, which is real behavioral context beyond the schema. However it says nothing about whether restore mutates window state, cost/latency, or what the payload actually looks like, leaving mutation-side effects to the schema.

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 and load-bearing: the first defines what is captured, the second gives the coordinate-mapping fact needed to act on the result. 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 does the important work of hinting at the return payload (image plus window_units_per_pixel). It stops short of confirming the image encoding or how element refs are surfaced, but nothing essential for calling the tool 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 80%, so the schema already documents ref, window, restore and max_width; the description only echoes the ref-based element capture. It also names window_units_per_pixel, which is not in the input schema at all, so the agent could mistake it for a parameter rather than an output field.

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

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

States a specific verb+resource ("Capture a Cascadeur window ... as an image") and covers both scope variants: whole window or a single element by ref. That clearly separates it from the UI-driving siblings such as ui_click or ui_tree, which read/inspect rather than render pixels.

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?

Implicitly routes the agent into the screenshot-then-click workflow by explaining that window_units_per_pixel converts image pixels to the coordinates ui_click expects. There is no competing screenshot sibling, so no explicit exclusion is needed, but it never states plainly when to reach for this tool (e.g. after ui_tree fails to identify an element).

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 annotations, the description carries the full burden. It usefully discloses that events are synthesized to mimic a real user and that the call blocks for settle_ms before returning, but says nothing about failure behavior (element not found, ambiguous query match), foreground/focus requirements, or what side effects a click may trigger.

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

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

Two compact sentences, front-loaded with the core action and targeting modes, then the optional variations. No filler and no repetition of the tool 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?

For an 11-parameter, zero-required, mutation-style tool with no annotations and no output schema, the description covers the primary targeting intent but omits precedence rules when multiple selectors are supplied and omits any return/error semantics. Adequate but clearly short of 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 64%, so the schema documents most parameters itself. The description adds the meaningful conceptual grouping (target by ref, by query, or by raw coordinates) and flags the button/double/modifier variations, but adds nothing for force, index, window, or settle_ms 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 concrete verb ('Click') plus the three targeting modes (ref, query, x/y coordinates) and the supported variations (button, double, modifiers). It clearly separates itself from ui_drag and ui_hover by naming the interaction type, but never contrasts with ui_invoke, the sibling most likely to be confused with a click.

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

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

Usage is implied by 'Click like a real user (synthesized mouse events)', suggesting it belongs when real input events are needed rather than a programmatic action. There is no explicit when-to-use/when-not and no named alternative such as ui_invoke, so the agent must infer the boundary.

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 annotations, the description carries the burden well: it discloses the press/move/release sequence, that each step runs separately for UI updates, the qtest-vs-event input path distinction, and that it returns actual start/end points. It omits any risk, permission, or focus-change caveats.

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?

Dense and front-loaded: the drag mechanics come first, then start/end targeting, then rationale for per-step execution, then return value. Every sentence carries information, though the start/end enumeration is slightly terse.

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

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

For an 18-parameter, no-annotation, no-output-schema tool, the description covers the essential drag lifecycle, targeting options, and return values. Some timing/modifier parameters remain only in the schema, and there is no note on failure or focus 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?

At 61% schema coverage, the description adds real value by defining the start (object/ref/query/window x/y) and end (to_x/to_y or offset dx/dy) coordinate schemes, which the schema alone does not explain. Remaining params (steps, hold_ms, settle_ms, modifiers) are left to schema descriptions.

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

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

States a specific verb (drag) with the exact mechanics: press at start, move in steps, release at end. It is clearly distinguishable from siblings ui_click, ui_hover, and ui_key by describing the multi-step held-button gesture.

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 use-case (AutoPosing while dragging a control point) and explains why steps run separately so Cascadeur updates between moves. It lacks explicit when-not-to-use guidance or a direct alternative comparison, keeping it below 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?

No annotations are provided, so the description carries the full behavioral burden. It discloses the visible effect of hovering (tooltips, menus), which is useful, but it omits whether the action is safe/non-destructive, how coordinates are interpreted, whether it returns revealed content, and what happens if no element is found.

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 a single front-loaded sentence with zero waste. It states the action immediately and appends the effect parenthetically.

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 six-parameter UI interaction tool with no annotations and no output schema, the description is too thin. It does not cover coordinate semantics, failure behavior, or what the agent should expect after settling, leaving significant gaps for correct invocation.

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 67%, with ref, query, window, and settle_ms already described. The description adds a useful mapping by saying "element or point," corresponding to ref/query versus x/y, but it does not explain coordinate units or origin, and x/y remain undocumented in both schema and 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 states a specific verb and resource: "Move the mouse over an element or point." The parenthetical clarifies the effect (tooltips, hover menus), making it distinct from siblings like ui_click and ui_drag, though it doesn't explicitly name those alternatives.

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

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

Usage is implied by the parenthetical "shows tooltips, hover menus," which indicates when hovering is useful. However, the description does not state when to prefer this over ui_click, ui_drag, or ui_invoke, nor does it mention prerequisites such as needing a visible window.

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 annotations, the description carries the full burden. It usefully discloses the key behavioral constraint that the target method must take no arguments, but says nothing about side effects of invoking a signal, what happens if the method name doesn't exist, whether the ref must be fresh, or what is returned.

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

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

Two short sentences: capability first, usage condition second. No filler, and the examples are embedded efficiently.

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, no-output-schema tool this is nearly sufficient: what it does, examples, and when to reach for it. The remaining gap is failure semantics – invalid refs or missing method names – which an agent would need to handle.

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 50% – 'ref' is documented in the schema while 'method' is a bare string. The description compensates for that gap by giving example method values and stating the no-argument restriction, adding real meaning beyond the schema.

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

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

States a specific verb and resource ('invoke a no-argument QML method or signal on an element') and gives concrete examples of methods ('clicked', 'toggle', 'open', 'close'). It distinguishes itself from ui_click via the 'cannot be clicked on screen' clause, though it never contrasts with the sibling call_action, which sounds adjacent.

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 triggering condition: use it when an element cannot be clicked on screen. It offers no explicit exclusions or guidance on when ui_click, ui_key, or call_action would be preferred instead, so it stops short of full routing guidance.

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

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

No annotations are provided, so the description carries the full burden. It conveys input syntax but not where the keystrokes go, whether window focus changes, whether arbitrary/destructive sequences (the 'ctrl+a Delete' example implies they are possible) have side effects, or what is returned; the tool's degree of control over the OS/UI is never 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?

A single front-loaded sentence with three illustrative examples, each earning its place by teaching the combo syntax. Nothing is wasted, though it is a sentence fragment and omits any hint of targeting behavior.

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

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

For a simple three-parameter input tool with no annotations or output schema, the description covers the essential calling convention but leaves the agent guessing about focus targeting, side effects, and what the call returns or confirms.

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 67% and the undocumented parameter is 'keys' itself; the description compensates by explaining that combos are space-separated and giving literal example strings, which the schema does not. The other two parameters (window, settle_ms) are already documented in the schema, so no further detail is needed.

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

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

The description states a specific verb and resource ('Press keys or shortcuts') and illustrates the exact input syntax with three concrete examples, so an agent knows precisely what the tool does. It does not explicitly distinguish itself from siblings like ui_type or ui_click, which keeps it short of a 5.

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

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

Usage is only implied: the examples ('ctrl+s', 'Escape', 'ctrl+a Delete') suggest when keystroke input is appropriate, but there is no statement of when to prefer this over ui_type, ui_click, or ui_invoke, and no prerequisites or exclusions are named.

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 annotations, the description carries the full behavioral burden. It does disclose one genuinely important trait — that this mutates state without dispatching input events — which an agent could not infer from the schema. However, it says nothing about persistence, whether bindings/signals fire, required element visibility, or failure behavior, leaving the mutation profile largely undisclosed.

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

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

Two compact sentences, zero filler. The core operation and its examples come first, and the usage caveat follows in the strongest possible position for a reader scanning the tail.

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 3-required-parameter mutation tool with no annotations and no output schema, the description covers purpose, the key behavioral caveat, and an alternative. It still omits value-type expectations, error/return behavior, and how to obtain a valid `ref` beyond the schema hint, so an agent may need to probe to call it correctly.

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

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

Schema coverage is only 33%: `ref` is documented in the schema, while `name` and `value` are bare. The description partially compensates by giving example property names, which clarifies `name`, but `value` is an untyped `{}` with no explanation of how its type must match the target property — a real gap.

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 a specific verb and resource ("Set a QML property on an element") and enumerates concrete example properties (checked, value, text, currentIndex), so an agent knows exactly what operation it performs. It doesn't explicitly contrast with sibling setters, but the examples pin down the domain well enough to distinguish it from ui_click/ui_type.

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 explicitly names an alternative and a selection rule: "prefer ui_click when possible," plus the reason (this bypasses input handlers). It stops short of stating hard exclusions or prerequisites (e.g. element must be present in the latest ui_tree), so it's clear guidance rather than complete guidance.

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

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

With no annotations, the description carries the full burden; 'List' signals a read operation and the enumeration of returned fields tells the agent what to expect. It does not disclose cost/latency of walking a UI tree, whether hidden elements are included by default, or that results are truncated by a default limit. Adequate but leaves real gaps for an unannotated tool.

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

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

A single dense sentence with the resource front-loaded and the interoperability note trailing. Every clause carries information; 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?

With no output schema, the enumeration of returned fields (text, tooltip, actionId, type, rect, flags) usefully stands in for a return-value spec, and the ref-for-siblings note completes the workflow picture. The only gap is the undocumented include_hidden parameter and the default-limit 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?

Schema description coverage is 80%, so the schema already documents limit, query, window, and interactive_only; the description adds nothing parameter-specific beyond naming searchable fields in the return list. The undocumented include_hidden parameter is not compensated for in the description either.

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 (List) and two concrete resources (open windows, on-screen UI elements), then enumerates the element attributes returned. The closing clause 'with refs for the other ui_* tools' distinguishes it from the action-taking siblings like ui_click and ui_invoke, which consume those refs.

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?

'with refs for the other ui_* tools' implicitly positions this as the discovery step before ui_click/ui_hover/ui_type, which is clear workflow context. However, it never explicitly says when to use this versus screenshot or get_scene_info, and gives no exclusions or 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?

With no annotations, the description carries the full behavioral burden. It discloses that replace clears the field and submit presses Enter, but leaves unclear whether default typing appends, inserts at the cursor, or replaces text, and it does not cover failure behavior or return effects.

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 definition is two tight sentences with no wasted language, and the core action is front-loaded before the behavioral modifiers.

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

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

For an 8-parameter UI automation tool with no annotations and no output schema, the description covers the main action and two key modifiers but is thin on failure handling, default typing behavior, and what is returned after the interaction.

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 63%, and the description usefully adds meaning for replace and submit, which lack schema descriptions. It does not further explain window, settle_ms, or release_focus beyond the schema, so it adds only partial semantic value across the 8 parameters.

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

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

The description states a specific verb and resource: typing text into the focused element, with an explicit option to focus by ref or query first. It is clearly distinguishable from sibling UI tools such as ui_key or ui_click.

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 explains that ref/query can be used to focus an element first and clarifies replace/submit behavior, but it does not say when to prefer this tool over ui_key, ui_click, or other UI interaction siblings. Usage is implied rather than explicitly bounded.

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