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

The description adds significant behavioral context beyond the readOnlyHint=true annotation, including that it is a single check without polling, details about missing attributes returning null, and that a missing element is a precondition failure (not a retry). It also specifies all error types and constraints on regex flags. No contradiction with 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?

The description is well-structured and information-dense, starting with the core purpose, then detailing targeting, matching, return value, and errors. Every sentence adds value, though it could be slightly trimmed without losing clarity. It is appropriately front-loaded.

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 tool has 8 parameters, no output schema, and no nested objects, the description compensates thoroughly: it explains targeting, matching options, flags, return fields, and all error types. It is complete enough for an agent to select and invoke 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 the schema already provides descriptions for all 8 parameters (100% coverage), the tool description adds meaningful semantics: explaining that exactly one predicate must be provided, the effect of the attribute parameter on the value read, and the constraints on regex flags (g and y rejected as stateful). This goes beyond 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?

The description clearly states the tool's purpose: 'Validate, in a single check (no polling), that an element's text or a named attribute matches a pattern.' It specifies the verb (validate) and resource (element text/attribute) and distinguishes it from sibling tools like electron_expect_text or electron_get_text by emphasizing the single-shot nature and pattern matching.

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 provides clear instructions on how to target elements (by ref or selector), how to choose between text and attribute validation, and the requirement to provide exactly one of equals/contains/matches_regex. However, it does not explicitly mention when this tool should be used over alternatives or when not to use it, such as when polling is needed.

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

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

Goes well past the readOnlyHint=false / openWorldHint=false annotations: it documents the loopback restriction, that a dropped session reconnects on its next call, that pid enables stop to escalate to SIGKILL, the unsupported iframe/webview surface targeting, and the full error taxonomy with retryability. This is unusually rich operational context.

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 purpose, then selector rules, then capabilities/limits, then returns and errors—a sensible order. The prose is dense and packs several clauses per sentence (returns plus five error codes in one paragraph), which is efficient but slightly heavy for a description.

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, and the description supplies the return shape (ok, session_id, transport, windows, capabilities) as well as the error cases. Combined with the disclosed capability limits, an agent has everything needed to call and interpret 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 coverage is 100%, so the baseline is 3, but the description adds genuinely new semantics: pid is not a standalone attach selector and only affects stop escalation, and port/host versus cdpUrl are alternative selectors with a loopback-only constraint enforced as BAD_ARGUMENT. That meaning is not derivable 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?

States a specific verb and resource ('Attach to an already-running Electron app exposing a CDP debug endpoint') and immediately distinguishes itself from the launch path and from electron_discover_running. An agent can tell exactly what this 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?

Explicitly routes the agent to electron_discover_running for finding a target and to --remote-debugging-port for starting one, and warns that pid alone is not attachable over CDP. Alternatives and preconditions are named, not implied.

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 description discloses behavioral traits: no-op if already checked, and lists error types including retryable ones. Annotations confirm mutation, no contradiction.

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 two sentences plus a concise list of options and errors, front-loaded with the main action. No wasted words.

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 5 parameters, no output schema, the description covers the main action, return format, and errors. Could explain the 'target' field in return, but adequate.

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 adds value by specifying return format, error types, and the no-op condition, going beyond 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?

The title and description clearly state the tool checks a checkbox/radio, with explicit mention of no-op if already checked. It distinguishes from sibling tools like electron_uncheck.

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 implies usage for checkbox/radio elements and mentions no-op behavior, but does not explicitly state when to use this over alternatives like electron_click or electron_uncheck.

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 indicate readOnlyHint=false, aligning with the mutation behavior. The description adds details about options (force bypasses actionability checks), return structure, and specific error types with retryability hints, going beyond what annotations provide.

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 plus compact lists of options, returns, and errors. Every element is essential and informative with no redundancy.

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

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

Covers core action, identification options, options, return shape, and errors. Does not mention event firing or mutual exclusivity of ref/selector explicitly, but the schema covers the latter. Sufficient for a clear-input 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 coverage is 100%, so baseline is 3. The description summarizes parameters (ref/selector, force, timeoutMs) and lists errors, but adds little new meaning beyond the 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?

The description clearly states the verb-resource pair: 'Clear the value of the input/textarea' and distinguishes it from sibling tools like electron_type or electron_get_value.

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 provides clear context that the tool clears an input to empty, but does not explicitly contrast with alternatives like electron_type ' ' or electron_press_sequence. The context is sufficient for an agent to infer usage.

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

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

Annotations only declare readOnlyHint=false and openWorldHint=false, so the description carries most of the burden — and it delivers: force is disclosed as bypassing actionability checks, timeoutMs is clamped, and each error code is labeled retryable or not with the specific remedy and extra payload (similar_refs on REF_NOT_FOUND). POINTER_NOT_DELIVERED explaining that a click 'landed on another element or frame' is exactly the kind of failure semantics an agent cannot get from annotations.

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

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

Front-loads what the tool does, then options, then return shape, then error taxonomy — a logical order with no filler sentences. The error list is long but every entry carries distinct retry/remediation information, though the single dense paragraph could be broken into clearer segments.

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

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

With no output schema, the description correctly supplies the return shape ({ ok, session_id, target }) and a complete error contract including retryability. Together with the fully documented 7-parameter schema and the mutation annotation, an agent has everything needed to invoke 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 schema already documents ref, selector, force, button, clickCount, timeoutMs, and sessionId in comparable detail. The description largely restates that information (clickCount 2 = double-click, force bypasses actionability) rather than adding syntax or format knowledge beyond it — the correct baseline when the schema does the heavy lifting.

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

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

States a concrete verb and resource — 'Click the element identified by ref (from a snapshot) or selector' — and immediately names the two targeting mechanisms. The verb is unambiguous next to siblings like electron_hover, electron_drag, and electron_type, so an agent can select it without reading any other tool.

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 strong operational context: ref vs selector targeting, default values for every option, and per-error remediation ('re-snapshot' for REF_NOT_FOUND, retryable vs not retryable for each failure). It never names an alternative sibling (e.g. when to prefer hover or press_sequence instead), so it stops short of explicit 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?

Annotations already indicate readOnlyHint=true. Description adds value by detailing ordering, overflow behavior, error conditions (NOT_RUNNING, BAD_ARGUMENT). This goes beyond what annotations provide, making behavior fully transparent.

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?

Description is concise yet comprehensive, using parentheses and bullet-like structure. It front-loads the purpose, then lists filters and returns. Every sentence adds value without redundancy.

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

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

Despite no output schema, description fully details return structure (entries with fields, count, overflowed) and lists errors. For a tool with 5 optional parameters and filtering logic, this is complete and covers all relevant context.

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. Description adds extra context: 'ANDed' for filters, 'epoch ms' for since, 'most recent are kept' for limit. This enhances understanding beyond raw 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?

Description states 'Read the captured renderer console output for the session' with a specific verb and resource. It also clarifies ordering ('newest-relevant entries last'), distinguishing it from sibling tools that perform different actions like clicking or waiting.

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?

Description explains all optional filters and their effects (ANDed, regex, epoch ms, limit). It implies usage for reading logs, but doesn't explicitly state when not to use or compare with alternatives. However, the context is clear enough for most use cases.

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

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

Annotations only give readOnlyHint=false and openWorldHint=false, so the description carries the real burden and does so: it discloses that launch-owned transports cannot detach, enumerates the error codes with retryability (TRANSPORT_UNSUPPORTED not retryable), and specifies the success payload. That is far more than the annotations supply.

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?

Ordered as purpose, constraint, alternative, return shape, then error taxonomy. It is dense but every sentence carries a distinct piece of decision-relevant information, with the exclusion front-loaded before the alternative.

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

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

Although there is no output schema, the description supplies the return shape ({ ok, session_id, detached: true }) and the full error set, plus the operational constraint that determines success. Nothing an agent needs to call this correctly or interpret failure is missing.

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

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

Schema description coverage is 100%, and the schema already explains sessionId including the 'omit when a single session is running' rule, so baseline is 3. The description only indirectly touches the parameter via the BAD_ARGUMENT (multiple sessions) error, adding a little disambiguation but no format or syntax detail.

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

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

States a precise verb and object ('Disconnect from an attached or injected app') and adds the non-obvious qualifier 'without stopping it', which immediately separates it from the kill/stop family. An agent can distinguish it from electron_stop and electron_force_kill without opening a schema.

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

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

Explicitly names the when-not case (launch-owned sessions, including Playwright development launches and packaged CDP launches) and routes the agent to the correct alternative, electron_stop. This is exactly the when/when-not/alternative guidance the dimension asks for.

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 description fully discloses behavior: dialogs block the renderer, policy is applied automatically, default is dismiss to prevent hangs, overflow behavior, and error conditions (NOT_RUNNING, BAD_ARGUMENT). It does not contradict annotations (readOnlyHint=false).

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

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

The description is well-structured with a clear separation of arming and reading arguments. It is fairly long but every sentence adds value, explaining modes, defaults, and edge cases. Slightly verbose but efficient for the 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?

Despite no output schema, the description fully documents the return object (ok, session_id, policy, entries, count, overflowed). It covers all modes, parameter interactions, and errors. Given the tool's complexity (two modes, 9 params), the description is 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 100%, but the description adds essential context: action is the default, perType overrides, promptText requires accepting prompt, oneShot is for next dialog then revert, limit defaults/max, clear flushes whole buffer, overflowed counts across full buffer. This goes far beyond schema.

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

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

The description clearly states the tool's dual function: arming an auto-responder for native dialogs and reading fired dialogs. It distinguishes between the two modes and explains the default policy. No sibling tool handles dialogs, so it is distinct.

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 when to use arming vs. reading (e.g., 'With NO arming args the call is inspect-only'). It mentions that dialogs block the renderer and why the default policy is dismiss. It does not explicitly exclude alternatives, but no siblings exist for this purpose.

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

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

Annotations already declare readOnlyHint=true, indicating safe read. The description adds detailed behavior: scans specified ports, returns diagnostic structure, reports errors (BAD_ARGUMENT for invalid inputs), and clarifies that a failed probe is simply 'no target'. No contradictions.

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 compact (3-4 sentences) and front-loaded: purpose first, then return format, error types, and failure behavior. Every sentence adds value, no fluff.

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?

Despite no output schema, the description fully specifies the return structure (ok, targets, count, scanned with subfields) and error cases. Given 0 required parameters and clear defaults, the agent can use this tool without ambiguity.

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%, but the description adds extra constraints: default values (9222-9225, 127.0.0.1, 300ms), maximum port count (64), maximum timeout (5000ms), and host enum restriction to loopback. This adds meaningful context beyond the schema.

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

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

The description clearly states the verb 'Scan' and the resource 'already-running, debuggable Electron apps', specifying the scope 'on loopback only' and default port range. This distinguishes it from sibling tools like electron_launch or electron_attach.

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 indicates this tool requires no session, implying it's a preliminary diagnostic step. It mentions error types and failure behavior, but does not explicitly compare to alternatives or state when not to use it. The context is clear enough.

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?

Describes tool as non-mutating, which aligns with readOnlyHint annotation. Additionally details what checks are performed and the return structure (including runtime facts and native-addon inventory), going well beyond the annotation.

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

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

Four sentences with high information density: purpose, checks, return value, usage guidance, and error handling. No redundant words; every sentence serves a clear function.

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 diagnostic tool, the description fully explains the checks performed, the return structure, usage context, and error behavior. There is no missing information needed for correct invocation or interpretation.

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 has zero parameters with 100% coverage. Description adds no parameter info but doesn't need to; baseline of 4 is appropriate as the description cannot add value over an 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?

Description clearly states it runs non-mutating preflight checks for the Electron Stagewright environment, listing specific resources checked (Node, Playwright, Electron, etc.). This distinctively separates it from siblings that perform actions like launching, clicking, or attaching.

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 advises to inspect results before electron_launch, providing clear temporal guidance. While it doesn't name alternatives, the sibling list includes electron_launch and other tools, making the pre-launch use case unambiguous.

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

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

Annotations only declare readOnlyHint=false and openWorldHint=false, so the description carries the rest and does so well: it documents the return shape, enumerates error codes, and flags which errors are retryable (ELEMENT_NOT_VISIBLE, POINTER_NOT_DELIVERED) versus terminal. It also explains that BAD_ARGUMENT fires when a side is missing or both ref+selector are supplied.

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

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

Front-loads the action and argument contract in one dense sentence, then appends a compact returns/errors block. Nearly every clause earns its place, though the error list is terse enough to feel telegraphic.

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

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

With no output schema, the description still supplies the return fields and a full error taxonomy with retryability, plus argument exclusivity rules. For a 7-parameter mutation tool, an agent has everything needed 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 description coverage is 100%, so the schema already documents every parameter including defaults, clamps, and the ref-OR-selector rule. The description merely lists 'force, timeoutMs' by name without adding format or behavior meaning beyond the schema, so the baseline 3 applies.

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

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

States a specific verb (drag) plus both the source and target resources, and names the exact argument pairs (ref/selector, targetRef/targetSelector). It is clearly distinguishable from siblings like electron_click or electron_hover.

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 'using the real mouse API' implies when this differs from synthetic-event siblings, but there is no explicit when-to-use guidance, no exclusions, and no routing to alternatives such as electron_drop_file for file drops. Usage is only implied.

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

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

Annotations only indicate readOnlyHint=false, but the description extensively covers behavior: dispatches dragenter/dragover/drop events with a real DataTransfer, explains default_prevented meaning, details file size and path restrictions, and lists possible errors. This goes well beyond the annotations.

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

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

The description is well-structured with the core purpose first, followed by mechanism, constraints, and error enumeration. It is comprehensive but slightly lengthy; some redundancy exists (e.g., file counts repeated). Still, it earns its 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?

Despite having no output schema, the description fully documents the return object fields (ok, session_id, target, files, default_prevented) and all error types. It also clarifies edge cases (default_prevented false). For a complex tool, this provides complete guidance.

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 input schema has 100% description coverage, but the description adds critical constraints not in the schema: absolute paths required, max 10 files, 5242880 bytes each. It also explains the mimeType override behavior and clarifies that ref and selector are mutually exclusive. This adds significant value.

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?

Description clearly states the tool simulates dropping OS files onto an element identified by ref or selector. It distinguishes itself from sibling tools by detailing the DataTransfer mechanism and contrasting with apps needing native IPC paths. The verb 'simulate dropping' and the resource 'OS files onto an element' are specific and unambiguous.

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 explicitly states when to use (simulate file drops) and when not to (apps requiring native OS paths via IPC). It also provides constraints like absolute paths, file limits, and timeout. However, it does not directly compare to sibling tools like electron_drag or electron_set_files, so some implicit guidance is missing.

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 description goes beyond the readOnlyHint annotation by detailing the truncation behavior, default/max limit, error types, and return structure. This provides sufficient behavioral transparency for a read-only listing tool without adding contradictions.

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 concise (4 sentences), front-loaded with the main purpose, and contains no extraneous information. Each sentence adds essential detail (return shape, limit, truncation, errors).

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 tool has 3 parameters, readOnlyHint annotation, and no output schema, the description fully explains the return value structure, error conditions, and query parameter semantics. It is self-contained for an agent to understand and invoke 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?

Since the schema documentation covers 100% of parameters, the description adds marginal value. It restates the limit default and max, which are already in the schema. No new meaning is added beyond what the schema provides.

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

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

The description clearly states it returns every element matching a CSS selector, specifying the output fields (ref, role, name, bbox). It distinguishes from siblings like 'electron_find' which likely returns a single element, and other list tools by emphasizing 'every' element.

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 does not explicitly provide guidance on when to use this tool versus alternatives such as 'electron_exists' or 'electron_find'. The context of use is implied by the purpose (listing all matching elements), but no when-to-use or when-not-to-use instructions are given.

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 readOnlyHint=true, description reveals that no-match is a normal result (exists: false) not an error, and enumerates all error types. This provides significant behavioral clarity.

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

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

Three front-loaded sentences: purpose, key behavior (no-match non-error), then returns/errors. Every sentence adds value.

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 no output schema, description fully covers return format, error types, and use case (polling). With annotations and high schema coverage, no 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 coverage is 100%, so baseline is 3. Description mentions 'ref OR selector' but schema already specifies this. No additional semantic detail beyond 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?

Clearly states the verb 'return' and resource 'whether element exists'. Distinguishes from siblings like electron_find (which returns element data) and visibility checks. No-match clarification clarifies 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?

Explicitly suggests polling use case for appearance/disappearance. Lists error conditions but omits when not to use (e.g., when needing visibility or text).

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 description discloses polling behavior, timeout clamping, error types (EXPECTATION_FAILED with details, retryable), and the return structure. This adds significant behavioral context beyond the readOnlyHint annotation, which only indicates read-only nature.

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 efficiently structured: first sentence states core functionality, then explains modes, then requirements, then returns and errors. No redundant sentences, all information is necessary and front-loaded.

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 (12 parameters, no output schema), the description covers purpose, parameter usage, return values, and error scenarios. It provides enough context for an agent to invoke the tool correctly without additional documentation.

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 coverage, baseline is 3. The description adds meaning by grouping parameters into selector vs role modes, clarifying visible behavior (counts visible only or hidden only), and explaining count predicates. This adds value beyond the 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?

The description clearly states the tool's purpose: 'Assert how many elements match, polling until the count satisfies the predicate or timeoutMs elapses.' It specifies the verb (assert), resource (element count), and distinguishes from sibling tools like electron_expect_state and electron_expect_text by focusing on count assertions.

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 the two modes (by selector or role/name) and requires at least one of equals, min, or max. It does not explicitly exclude cases or mention alternatives, but the context is clear enough for an agent to decide when to use this tool over others.

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 readOnlyHint=true, and the description adds significant behavioral details: atomic polling, timeout mechanism, error types (EXPECTATION_FAILED, REF_NOT_FOUND), and return format. No contradictions with 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?

The description is comprehensive but slightly verbose with error details. It is well-structured, starting with the core action and then listing errors. Could be slightly trimmed without losing value.

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 fully explains the return format and all error types. It covers the complex nested state parameter, multiple identification methods, and timeout behavior, making it complete for an agent to use 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 80%, and the description compensates by explaining the state flags and mutual exclusivity of ref/selector. While schema describes most parameters, the description adds clarity on state flag usage and error conditions.

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

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

The description clearly states the tool asserts element state flags, identifies the element via ref/selector, and polls until timeout. It distinguishes from siblings like electron_expect_visible by supporting multiple state flags atomically.

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 the polling behavior and error conditions but lacks explicit guidance on when to use this tool versus alternatives for single state checks. It implies usage for multi-flag assertions but does not provide exclusion criteria.

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 provide readOnlyHint=true and openWorldHint=false, indicating a read-only side-effect-free operation. The description adds extensive behavioral context: polling semantics, timeout clamping, exact predicate matching, rejection of stateful regex flags (g, y), and detailed error payloads (similar_refs for stale refs, expected+actual for assertion failure). No contradiction with 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?

The description is efficiently structured: front-loaded with core purpose and polling behavior, then a clear bullet of predicate options, followed by flags and error categories. Each sentence serves a distinct purpose without redundancy. Length is justified by the parameter count and error 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?

Despite no output schema, the description fully documents the return object ({ ok, session_id, matched, actual }) and all possible errors with sufficient detail for an agent to handle failures. It covers polling timeout, predicate constraints, and the ref/selector duality. For a tool with 10 parameters, this is comprehensive.

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 is 3. However, the description adds critical semantic constraints beyond the schema: the mutual exclusivity of predicates ('exactly one'), the relationship between 'flags' and 'regex', and the behavior of timeoutMs (0 = check once). This enriches the agent's understanding of parameter interactions.

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

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

The description clearly states the tool's purpose: asserting text of an element via ref/selector with polling. It identifies the specific verb ('Assert'), resource ('text of the element'), and mechanism ('polling until it holds or timeoutMs elapses'). This distinguishes it from siblings like electron_get_text (retrieval without assertion) and other expect_ tools (e.g., expect_url, expect_state) which target different resources.

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 provides explicit selection constraints: 'Provide exactly one of: equals, contains, regex, not_equals, not_contains' and clarifies flags applicability only to regex. It also details error types (EXPECTATION_FAILED, REF_NOT_FOUND, etc.) and their retryability. However, it does not explicitly contrast with alternatives like electron_get_text for cases where the agent might want to fetch text without assertion, though the sibling list implies differentiation.

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 indicate readOnlyHint=true and openWorldHint=false, and the description adds polling behavior, timeout clamping, and detailed error types including retryability of EXPECTATION_FAILED. No contradictions.

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 two sentences covering purpose, predicates, flags, returns, and errors—every sentence carries essential information with no redundancy or fluff.

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?

Despite no output schema, the description explicitly lists return fields and error types. For a polling assertion tool, this provides complete context for an agent.

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%, but the description adds important usage semantics like mutually exclusive predicates, flag restrictions ('g and y are rejected'), and meaning of timeoutMs = 0. This goes beyond the 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?

The description clearly states the tool 'asserts the active window's URL satisfies a predicate' and specifies the supported predicates (contains, matches) and flags. This differentiates it from sibling tools that operate on other aspects like text, state, or count.

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 explicitly requires providing exactly one of 'contains' or 'matches' and explains optional flags and timeout behavior. While it doesn't explicitly compare with alternatives, the purpose is specific enough for an agent to infer appropriate usage.

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

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

Annotations already declare readOnlyHint=true, and the description adds rich behavioral details: polling until timeout, the exact error types (EXPECTATION_FAILED, REF_NOT_FOUND, etc.) with their semantics and retryability, and timeout clamping. No contradiction with 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?

The description is a single dense paragraph but front-loaded with the primary purpose. It could be slightly more structured (e.g., bullet points for predicates and errors), but every sentence adds value and there is no redundancy. Slightly lower for readability.

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 tool's complexity (10 parameters, no output schema), the description sufficiently covers return values (ok, session_id, matched, actual), all error types with conditions, and predicate rules. It is complete enough for an agent to use correctly without additional context.

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. However, the description adds significant value beyond the schema: it explains mutual exclusivity of predicates, valid regex flags (rejecting stateful ones), the meaning of timeoutMs=0, and the return format. This is excellent parameter-level guidance.

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

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

The description clearly states the tool asserts the value of an element against a predicate, with polling. It uses specific verbs ('assert') and resource ('form control value'), and distinguishes well from sibling tools like electron_expect_text or electron_expect_state which handle different checks.

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 specifies that exactly one predicate from a list must be provided, and explains flags for regex. However, it does not explicitly contrast with alternatives like electron_expect_text for text content, leaving some ambiguity about when to use this vs similar tools.

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 description explains polling behavior, timeout clamping, return structure, and error conditions. It adds significant behavioral context beyond the annotations, which only state readOnlyHint=true.

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 concise (4 sentences) with a clear front-loaded main action, followed by definition, return, and errors. Every sentence serves a purpose.

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 4 parameters and no output schema, the description adequately covers purpose, behavior, return fields, and all possible errors. No critical information is missing.

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

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

Schema coverage is 100%, so baseline 3 is appropriate. The description adds no new information beyond the schema's property descriptions, though it does restate the ref/selector exclusivity.

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

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

The description clearly states the tool asserts an element's visibility, defines 'visible' precisely, and distinguishes it from other expect tools like expect_text or expect_state. The verb 'assert' and resource 'element visibility' are specific.

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 covers the tool's behavior but does not explicitly guide when to use it versus siblings like electron_exists or other expect tools. Usage is implied through the definition of visibility.

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

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

Annotations only cover readOnlyHint and openWorldHint; the description adds substantial behavioral detail beyond that — limit truncation semantics with count still reporting the true total, the truncated flag, null refs for non-interactive landmarks, and the exact zero-match hint payload (similar_names, without_state_filters, other_roles, roles_present, text_matches). It also names the two error codes, marks NOT_RUNNING non-retryable, and explains multi-session BAD_ARGUMENT.

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 constraint in the first clause, and every later sentence carries non-redundant payload (returns shape, null refs, hint keys, errors). It is dense and slightly run-on — the long parenthetical enumerating hint fields is heavy — but nothing 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 carries the return contract itself and does so fully: the result envelope, matches shape, count/truncated relationship, and the optional zero-match hints object. Error behavior and recovery paths are also covered, leaving nothing material an agent needs before calling it.

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

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

Schema description coverage is 100% and each parameter is already documented, so the baseline is 3. The description's filter list largely restates schema fields (role exact, name_contains, name_exact, visible, enabled, interactive, limit) and omits sessionId from that list, adding little semantic weight beyond what the schema provides.

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 ("Find elements in the renderer by accessibility role + name + state") and immediately draws the boundary against the CSS-selector approach used by siblings like electron_wait_for_selector and electron_exists. An agent can distinguish this from electron_elements_list or electron_snapshot 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?

"No CSS selectors" plus the NOT_RUNNING remediation ("call electron_launch first") give clear entry conditions and steer away from selector-based siblings. However, it never names a concrete alternative for state-polling cases (electron_wait_for_state, electron_expect_visible) or says when a cheaper tool suffices, so alternatives are implied 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?

Beyond the readOnlyHint annotation, the description discloses the return format, null case (body only focus), and possible error types (TRANSPORT_UNSUPPORTED, NOT_RUNNING, BAD_ARGUMENT). No contradictions with annotations.

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

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

Three concise sentences with no redundancy. Information is front-loaded and every sentence adds value.

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 read-only tool with one optional parameter, the description covers purpose, return format, edge case (null focus), and errors. No output schema exists, but the description sufficiently explains the response structure.

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 already covers the single parameter (sessionId) with a clear description. The tool description adds minimal extra meaning about parameter usage, but mentions a BAD_ARGUMENT error for multiple sessions, providing slight context beyond the schema.

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

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

The description clearly states the verb 'Return' and the resource 'element that currently has focus', specifying the output format as { ref, role, name }. It distinguishes itself from sibling tools by its specific focus-retrieval purpose.

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?

Provides explicit usage context: 'Useful after a Tab press or to confirm focus moved.' This helps the agent know when to apply. However, it does not mention when not to use or provide alternatives.

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 indicate destructive nature. Description adds specific details: uses SIGKILL, returns {ok, session_id, killed: true}, lists error types. No contradiction.

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: first captures purpose and use case, second covers return and errors. Every word earns its place; no redundancy.

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

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

For a simple destructive tool with one parameter, the description covers purpose, usage, return format, and error handling. Annotations handle safety profile. Complete for agent decision-making.

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?

Single parameter 'sessionId' with 100% schema coverage. Description adds value by explaining that omission works when single session is active and that errors include BAD_ARGUMENT for multiple sessions without sessionId.

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?

Describes a specific verb ('force kill'), resource ('session'), and context ('escape hatch when stop hangs'). Clearly distinguishes from sibling 'electron_stop' by stating it's the hard kill option.

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 to use ('when stop hangs') and lists error conditions (NOT_RUNNING, BAD_ARGUMENT). Could be improved by explicitly stating when NOT to use (e.g., prefer stop first).

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 indicate readOnlyHint=true and openWorldHint=false. The description adds behavioral detail beyond annotations: returns null for absent attribute (not an error), lists specific error types, and describes the return format. This provides helpful context for safe operation.

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

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

The description is relatively concise with core purpose upfront. It includes error list and return format in a single paragraph. A bit dense but not overly verbose. Could be slightly more structured, but overall effective.

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 tool's complexity (4 parameters, no output schema, no nested objects), the description covers return values, error types, null behavior, and the element identification methods. It does not mention the mutual exclusivity of ref and selector, which is in the schema, but still provides sufficient context for correct usage.

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 input schema covers all 4 parameters with descriptions (100% coverage). The description itself does not add new parameter-level information beyond what the schema provides. Baseline 3 is appropriate as schema does the heavy lifting.

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

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

The description clearly states the tool returns the value of an attribute on an element, distinguishing it from sibling tools like get_text or get_value. It specifies the verb (return), resource (attribute on element), and handles the null case for absent attributes.

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 how to use it (by ref or selector) and mentions null behavior, but does not provide explicit guidance on when to use this tool over alternatives or when not to use it. Sibling tools are not referenced.

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 readOnlyHint=true, and the description adds detailed error types and return format, going beyond the annotation. It provides context about the operation's safety and possible failures.

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 efficiently convey purpose, return format, and errors. No unnecessary information; front-loaded with the core action.

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 no output schema, the description fully specifies the return object and all possible error types. For a simple read operation, this is complete and sufficient for agent 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 100%, so the schema already fully describes parameters. The description adds little beyond noting 'ref OR selector' and a brief mention of sessionId, but this is already covered in 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?

The description clearly states it returns the bounding box in CSS pixels for an element identified by ref or selector, which is a specific verb and resource. This distinguishes it from sibling tools like electron_get_attribute or electron_get_state.

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 implies use when needing bounding box geometry but does not explicitly state when to prefer this over alternatives like electron_get_state or electron_get_computed_style. No exclusions or when-not guidance are provided.

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

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

Annotations already declare readOnlyHint=true, and the description adds behavioral details: it only returns requested properties (never full style), returns a structured object with ok, session_id, style, and enumerates specific error types. No contradiction with 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?

The description is a single, well-structured paragraph. It front-loads the core action, then details constraints and output format, followed by error types. Every sentence adds information without redundancy.

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

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

Given no output schema, the description fully explains the return format and error scenarios. With 4 parameters (all documented) and the complexity of getting computed styles, the description leaves no ambiguity for an AI agent.

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 has 100% parameter coverage, but the description adds value by explaining kebab-case for properties, mutual exclusion of ref/selector, and maximum items of 50. This goes beyond the schema's basic 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 description clearly states the tool's purpose: 'Return the computed value of each requested CSS property' for an element identified by ref or selector. It specifies kebab-case notation and a max of 50 properties, distinguishing it from sibling tools like electron_get_attribute or electron_get_state.

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 implicitly indicates when to use (when needing computed CSS values) and provides guidance on providing ref OR selector. It lists possible errors that help an agent decide if it's the right tool, though explicit comparison to alternatives is absent.

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

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

Annotations already declare readOnlyHint=true, so the description adds value by detailing the return shape (list of states, role, name) and listing possible errors (REF_NOT_FOUND, etc.). No contradictions.

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 highly concise: three sentences that front-load the main purpose, then list states and error types. Every sentence adds value with no redundancy.

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

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

Given no output schema, the description fully explains the return value structure and all possible errors. For a simple read-only tool, this is 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 100%, so the description does not need to add much. It reiterates that ref or selector should be provided, not both, which is already implied by the schema descriptions. Baseline 3 is appropriate.

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

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

The description explicitly states the tool returns the full state envelope of an element, listing all boolean properties plus role and name. It clearly distinguishes from sibling tools like electron_expect_state or electron_get_attribute by being a comprehensive state query.

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

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

The description gives a strong usage hint: 'One call answers is this clickable / checked / focused'. It implies use when multiple state properties are needed. However, it does not explicitly contrast with siblings like electron_expect_state (which asserts a state) or electron_exists, leaving some ambiguity about when to prefer this over alternatives.

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 description adds substantial behavioral context beyond annotations: it explains the fallback logic (trimmed textContent then accessible label), enumerates all error types, and confirms the tool is read-only, consistent with annotations. No contradiction.

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 compact but includes necessary details (behavior, errors, return shape). It is front-loaded with the core action. Minor redundancy in error listing but still efficient.

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 no output schema, the description covers return format and errors. Parameters are fully explained via schema. Sibling tools are many but the tool's purpose is distinct. Completeness is high for a read-only text retrieval 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 coverage is 100%, so parameters are already documented. The description reiterates the 'ref OR selector' constraint but does not add new semantics beyond what the schema provides. Baseline 3 is appropriate.

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

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

The description clearly states 'Return the text of the element identified by ref or selector' with a specific verb and resource. It distinguishes from siblings like electron_get_value and electron_get_attribute by focusing on text content and accessible labels.

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 when to use (to get text content, especially for find-by-name chains) but does not explicitly exclude scenarios or mention alternatives among the many sibling tools. However, the context is clear enough for most agents.

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

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

Discloses return format ({ ok, session_id, value }), null handling, and specific error types (REF_NOT_FOUND, SELECTOR_NO_MATCH, etc.). Annotations (readOnlyHint=true) are consistent.

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?

Very concise: one sentence with essential details front-loaded, followed by return and error notes. No wasted words.

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?

Explanation of usage, return format, errors, and optional sessionId is sufficient for a simple getter. No output schema needed.

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% with descriptions, but the description adds behavioral context (element types, null return). Minor gap: no clarification on value type (string? number?).

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

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

The description clearly states it returns the .value of form controls (input/textarea/select) by ref or selector. It distinguishes from siblings like electron_get_attribute or electron_get_text.

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 implies usage for form control values, but doesn't explicitly contrast with alternative getters. It clearly explains the ref/selector choice and sessionId optionality.

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

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

Annotations only declare readOnlyHint=false and openWorldHint=false; the description adds substantial value beyond that by enumerating error codes with retryable semantics (ELEMENT_NOT_VISIBLE, POINTER_NOT_DELIVERED) and a return shape. It omits any note on auth/permissions, but for a non-destructive UI interaction the error and return disclosure is meaningful.

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 options, returns, and errors in compact labeled segments. The error list is dense but every entry earns its place; nothing is redundant padding.

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

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

No output schema exists, and the description compensates by giving the return shape and the full error taxonomy, which is what an agent needs to handle this interaction tool. Coverage is strong, with only minor omissions like permission requirements.

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

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

Schema description coverage is 100%, so the schema already documents all five parameters (including sessionId, which the description omits). The description's 'Options: force, timeoutMs' merely echoes a subset of what the schema fully specifies, adding little. Baseline 3 applies.

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

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

States a specific verb (Hover) and target (element identified by ref or selector), and adds the motivation ('e.g. to reveal a tooltip or menu') that distinguishes it from click/press siblings. An agent can tell exactly what this 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 a clear usage context (reveal a tooltip or menu) that orients the agent toward when hovering is appropriate rather than clicking. It stops short of naming alternatives or explicit when-not conditions, but the context is unambiguous.

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

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

Annotations only declare readOnlyHint and openWorldHint, but the description adds substantial undisclosed behavior: signature status semantics per packaging and OS, null returns for versions/app under CDP transports, and error codes with explicit retryability. This is exactly the kind of context structured fields cannot convey.

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

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

One dense but well-ordered paragraph: purpose first, then enumeration, then the targeting rule, then return shape, then errors. No filler sentences, and every clause carries information an agent would otherwise have to probe for.

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

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

With no output schema, the description supplies the return object shape and the error taxonomy itself, plus the null-field caveats for CDP sessions. For a read-only diagnostic tool, nothing an agent needs to call it correctly or interpret the result is missing.

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

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

Schema coverage is 100%, so the single sessionId parameter is already documented; the description still adds meaning by tying omission to the single-session case and by naming the BAD_ARGUMENT failure when multiple sessions are live. Marginal but genuine added value above 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?

States a specific verb ('Report') and resource ('running Electron app environment') and then enumerates exactly what is reported: versions, app identity/paths, packaged flag, code-signature status, transport, and capability matrix. An agent can distinguish this from sibling probes like electron_status or electron_discover_running from the content list alone.

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 conditional ('Pass sessionId to target a specific session when several are running') and routes the NOT_RUNNING case to electron_launch first. It stops short of naming a sibling as the preferred alternative for, say, a quick liveness check, so it is clear context rather than full when/when-not 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?

Annotations only give readOnlyHint=false and openWorldHint=false; the description goes well beyond by disclosing the return shape ({ ok, session_id, transport, windows, capabilities }) and three named error conditions with retryability and a remediation path. This is exactly the extra context annotations cannot supply for an injection/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?

Front-loads the key precondition and mechanism in the first clause, then compresses return shape and errors into a tight list. Dense but every element earns its place; slightly runs together as one long block without visual separation.

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 still names the return fields and enumerates failure modes with retry guidance, so an agent knows both what comes back and how to recover. Nothing needed to invoke this tool correctly is missing.

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

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

Schema description coverage is 100% and both params (pid, timeoutMs) are already documented there. The description only restates 'Provide pid', adding no format, range, or default detail beyond the schema. Baseline 3 applies when the schema does the heavy lifting.

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

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

States a specific verb (attach), the resource (a running Electron process), and the decisive precondition (NOT started with a debug flag) plus the mechanism (injecting the Node inspector). This immediately distinguishes it from the sibling electron_attach, which targets apps already exposing a debug endpoint.

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

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

Explicitly frames the selection condition (app lacks a debug flag) and routes to the alternative in the error guidance: 'try electron_attach when the app already exposes a debug endpoint'. Both the when and the when-not are stated, along with the retryable nature of INJECT_FAILED.

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

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

Annotations only declare readOnly=false and openWorld=false, so the description carries the real burden and does: it discloses the return shape { ok, session_id, key, focused }, enumerates failure modes (SELECTOR_NO_MATCH/REF_NOT_FOUND with similar_refs, ELEMENT_NOT_VISIBLE retryable, NO_FOCUSED_EDITABLE, NOT_RUNNING, BAD_ARGUMENT), and explains focus/force behavior. It stops short of stating whether the key press is dispatched as down+up or how modifiers 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?

Front-loaded with the action and examples, then scoping rule, then editor caveat, then returns and errors. Dense but every clause carries usable information; the only filler is the short options enumeration.

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, no-output-schema tool, the description supplies the missing pieces: return object keys, error taxonomy, and target-resolution rules. An agent can call it and interpret failures without further documentation.

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 earns above that by explaining the ref-vs-selector precedence ('Focuses ref/selector first when given') and the intent behind force:true rather than merely restating its definition. The 'Options:' list itself is redundant with 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?

Specific verb+resource with concrete key/chord examples ('Control+A', 'ArrowDown'). It does not explicitly name the sibling it displaces (electron_type, electron_type_into_editor, electron_press_sequence), so an agent must infer that boundary from the editor hint rather than from an explicit routing statement.

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

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

Gives clear operating context: focuses ref/selector first when provided, otherwise targets the active element; for editors, click the visible content area first; reserve force:true for offscreen inputs that truly accept focus. Clear when-to-use guidance, but no explicit when-not or named alternative for multi-key sequences.

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

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

Annotations only declare readOnlyHint=false/openWorldHint=false, so the description carries the real burden and does: it explains focus behavior with and without a target, the force bypass semantics, the TYPE_NO_EFFECT failure mode, retryability of ELEMENT_NOT_VISIBLE, and enumerates error codes. It even documents the return payload shape despite no output schema existing.

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 verb/mechanism contrast in the first sentence, and every subsequent sentence carries actionable information (alternative tool, focus behavior, force caveat, return shape, errors). It is a dense single block with a long error enumeration that is slightly over-packed for readability, but nothing is truly 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?

For an 8-parameter interaction tool with no output schema, the description covers focus resolution, actionability/force semantics, failure modes with remediation hints, and the exact return shape including the focused element descriptor. An agent has everything needed to call it and interpret the result.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds genuine meaning beyond the schema for force (focuses offscreen/aria-hidden inputs, keystroke may be swallowed) and explains the no-target focus path governed by waitForFocusMs. It only lists timeoutMs and requireEditable by name without adding semantics, so it stops short of full coverage.

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

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

States a specific verb and mechanism ('type text as real per-character keystrokes') and immediately distinguishes it from the sibling electron_type ('sets the value directly'). The distinction from electron_type_into_editor for editors is also spelled out, so an agent can pick the right tool 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?

Explicit routing: use electron_type for value-setting, use this for real keystrokes, use electron_type_into_editor for Monaco/EditContext, and an explicit 'do NOT target the hidden textarea' exclusion. The force caveat ('swallowed keystroke returns TYPE_NO_EFFECT') adds a when-not condition.

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 far beyond the readOnlyHint:false / openWorldHint:false annotations: it discloses which transport is used per launch mode (Playwright vs loopback CDP), how runtime resolution and fallback work, the single-instance refusal default, side effects of the credential store mock flags on macOS/Linux, and what renderer_ready:false actually means. Error taxonomy with retryability flags gives the agent a recovery plan.

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?

Content is nearly all load-bearing, but it is delivered as one dense ~250-word paragraph with no bullets, and several clauses duplicate schema descriptions word-for-word (credentialStore's mock-keychain behavior, the 5000ms readyTimeoutMs default). The error list is valuable but reads as a run-on rather than scannable structure.

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 launch tool with no output schema, the description supplies the return shape ({ ok, session_id, transport, renderer_ready, runtime_source, ... }), the waiting semantics, and a full error catalogue with retryability. Nothing an agent needs to call it correctly or recover from failure is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds genuine meaning: precedence between executablePath and runtime, the default runtime resolution logic, the demo-entry fallback when both are omitted, and the operational consequence of readyTimeoutMs via renderer_ready. Some sentences restate schema text verbatim (credentialStore flags, readyTimeoutMs default), which caps this below 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?

States a specific verb and resource ('Launch an Electron app and start a driving session') and immediately distinguishes the two launch modes (main-based development vs executable-only packaged app). An agent can tell this apart from electron_attach or electron_discover_running 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 explicit conditions for the main choices: when to pass main vs executablePath, when runtime:'project' applies and its requirements, when to use credentialStore:'system', and when to override with allowMultiple. Sibling routing (attach to an already-running app rather than launch) is only implied through the ALREADY_RUNNING error rather than stated as an alternative.

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

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

Annotations only declare not-read-only and closed-world, so the description carries the burden and does so well: it discloses focus behavior, that requireEditable is checked before the first key, the return object shape, and a full error taxonomy including which errors are retryable (ELEMENT_NOT_VISIBLE) and what BAD_ARGUMENT covers (empty keys or ref+selector both).

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

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

Front-loads the core action plus example, then tucks usage cautions, options, returns, and errors into short trailing segments. The 'Options: force, timeoutMs, ...' enumeration largely restates schema property names and is the one slightly wasteful line.

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

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

With no output schema, the description supplies the return shape and the error contract, and it covers focus targeting, editor caveats, and validation for all 8 parameters. An agent needs nothing further to decide to call it and interpret failures.

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 adds value beyond it by clarifying timing semantics ('requireEditable checked before the first key') and the intended role of force as a last resort. It does not add format details for selector/ref beyond the schema's 'ref OR selector' constraint.

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?

Starts with a specific verb and resource ('Press each key in `keys`, in order') and gives a concrete example array, making the sequential semantics unmistakable. It does not name the close siblings electron_key or electron_keyboard_type, so the distinction from a single-key press or a text-typing tool must be inferred from the 'sequence' framing.

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 practical usage conditions: 'For editors, click the visible content area first' and 'reserve force:true for offscreen inputs that truly accept focus', which tells the agent when to escalate to force. It stops short of explicit when-not-to-use this tool versus electron_key/electron_keyboard_type.

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

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

Annotations only mark it non-read-only and closed-world; the description adds the real behavioral payload: prior refs are invalidated by the reload, the page-render wait happens before the selector wait, the default 5000ms budget is shared, and it enumerates the failure modes including which one is retryable (WAIT_TIMEOUT). This is exactly the state-destruction and retry information an agent cannot infer from 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?

Front-loaded with the action, then the timing rule, then the anti-pattern, then the state warning, then the return and error contract — no filler and each clause carries a distinct fact. Dense but never redundant.

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

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

Five optional parameters, no output schema, no enum guidance — yet the description supplies the return shape, the error taxonomy, the invalidation caveat, and the timeout default in prose. Nothing material is missing for an agent to call this correctly on the first attempt.

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

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

Schema coverage is 100%, so the baseline is 3; the description still adds value beyond it by stating that windowId both targets and selects the window (a side effect the schema does not mention) and that readyTimeoutMs is a single shared budget rather than per-phase. It does not explain sessionId disambiguation further, keeping it at 4 rather than 5.

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

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

Specific verb and resource ('Reload the active window ... or windowId') with explicit scope including the readiness wait and optional selector wait. It distinguishes itself from the two nearest siblings by name, noting the wait semantics are 'like electron_launch' and that the pending selector is what electron_wait_for_selector would otherwise handle.

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?

'Use it instead of location.reload() in eval' is an explicit routing rule against a competing approach, and the readyTimeoutMs budget covering both the render wait and waitForSelector tells the agent not to stack an extra wait tool. No explicit when-not-to-use case (e.g. full navigation vs. reload) is given, so it stops short of a 5.

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

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

The description states that the image is written on the server host, that path can be overwritten, and that an existing file may be overwritten; this conflicts with the readOnlyHint=true annotation, which implies no environment modification. The description itself is highly transparent, but it contradicts the structured safety annotation.

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 core purpose and output-model constraint are front-loaded, and the density is justified by the tool's 14 parameters and rich return values. However, the single long paragraph is hard to scan and could be structured more cleanly.

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 screenshot tool with annotations, a full input schema, and an output schema, the description is complete. It covers targeting, output location, waiting behavior, return fields, and common errors, leaving little ambiguity for an agent.

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 100%, the description adds meaningful semantics beyond the schema: window target precedence, default active window, default output locations, path/dir interaction, element-vs-window constraints, and settle/frame waiting behavior. It enhances rather than merely repeats parameter documentation.

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 ("Capture a screenshot") and immediately clarifies the output model: an image file path, not inline bytes. It also distinguishes element captures from window captures and identifies the targeted window precedence, so an agent can tell exactly what the tool does.

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 clear usage conditions: ref/selector captures an element, otherwise a window is targeted, and path/dir/default behavior is explained. It does not explicitly state when not to use the tool or name alternatives, but the context is otherwise unambiguous.

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 are minimal (readOnlyHint=false, openWorldHint=false), so the description carries the burden. It discloses return formats, error types (with similar_refs information), and the timeoutMs parameter for actionability. While it doesn't detail scroll animation or waiting behavior, it provides sufficient context for understanding side 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 description is highly concise: two sentences covering functionality, options, returns, and errors. Information is front-loaded with the primary behavior first. No superfluous content; every sentence earns its place.

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

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

Given 6 parameters, no output schema, and minimal annotations, the description fully covers the two modes, parameter relationships (mutual exclusivity), return objects for each case, and all possible errors. It is complete enough for an agent to understand and invoke 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?

Schema coverage is 100%, so baseline is 3. The description adds value by grouping parameters into modes (element vs wheel), clarifying the purpose of timeoutMs, and indicating when ref/selector are required together or conflicting. This extra context justifies a score above baseline.

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

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

The description clearly states two distinct modes: scrolling an element into view using ref/selector, or dispatching a wheel delta with dx/dy. It also specifies the return format and errors, making the tool's purpose unambiguous. It distinguishes itself from siblings like electron_scroll_into_view by covering both cases.

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 provides clear guidance on when to use ref/selector vs dx/dy, and notes mutual exclusivity of ref and selector. However, it does not explicitly differentiate this tool from the sibling electron_scroll_into_view or provide when-not-to-use advice, which would be helpful given the similar sibling names.

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

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

Annotations provide minimal behavioral cues (readOnlyHint: false). Description discloses common errors (SELECTOR_NO_MATCH, REF_NOT_FOUND) and mentions return format, but does not detail scoping behavior (e.g., scrollable container) or conditions for element actionability.

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?

Extremely concise: two sentences plus a compact error list. Main action is front-loaded. Every element serves a purpose; no fluff.

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 no output schema, description adequately covers return shape and error types. However, it omits details about centering alignment (e.g., top, bottom) and behavior on hidden elements. Still, it is reasonably complete for a scroll 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 coverage is 100%, so descriptions already define parameters well. The tool description adds only a summary ('Options: timeoutMs') and implicitly reinforces the ref/selector mutual exclusivity, but adds no new semantic depth 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?

Clearly states the verb (centre/scroll), resource (element), and action (into viewport). The description distinctively identifies the tool from siblings like electron_scroll and explicitly mentions that it targets elements by ref or selector.

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 guidance on when to use this tool versus alternatives. The description lists options and errors but does not specify scenarios, prerequisites, or compare to other scroll tools like electron_scroll.

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 (readOnlyHint=false) indicate a state-modifying operation, which aligns with the description. The return format and error types are listed, providing transparency beyond annotations. No contradictions.

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 two sentences: first states the core action, second lists options, returns, and errors. It is concise and front-loaded with essential information.

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

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

Despite no output schema, the description specifies return fields and error types. All parameters are documented in the schema, and the tool's purpose is fully covered for its complexity.

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 baseline is 3. The description adds value by summarizing key options (force, timeoutMs) and listing return fields and errors, which supplements the schema.

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

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

The title and first sentence clearly state the tool's action: selecting option(s) in a dropdown by value. It is distinct from sibling tools like electron_click or electron_check because it specifically targets <select> elements.

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 provides constraints such as providing ref or selector (not both) and mentions error conditions like REF_NOT_FOUND and SELECTOR_NO_MATCH. However, it does not explicitly compare to alternative tools or indicate when not to use this tool.

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

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

Annotations indicate mutation (readOnlyHint=false). Description discloses size limits, host requirements, and return structure. Missing explicit statement on whether setting files replaces or appends, but typical behavior is replacement. Good overall transparency.

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 concise sentences followed by a compact error listing. No redundant information; every sentence adds value. Front-loaded with action and constraints.

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 5 parameters (1 required), no output schema, and moderate complexity, the description covers purpose, constraints, options, return format, and errors. Minor gap on whether files are replaced or appended, but technically 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 100% with descriptions. The description adds crucial constraints (absolute paths, max files, size) and explains return/errors, going beyond schema details. Baseline 3, elevated for meaningful additions.

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

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

The description clearly states the verb ('Set files') and the resource ('<input type=file>'), and specifies identification methods ('ref or selector'). It uniquely distinguishes from sibling tools like electron_drop_file which handles drag-and-drop.

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?

Provides explicit constraints (absolute paths, max files/size), options (timeoutMs), and detailed error conditions. While it doesn't name alternative tools, the error list helps agents decide when to use this tool. Could be improved by mentioning electron_drop_file for alternative file actions.

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

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

Adds substantial behavior beyond annotations: waits for settling, reports clamping by app min/max or screen, restores maximized/fullscreen windows first, documents CDP-attach limitations, and lists specific errors. These details are highly relevant for a mutating tool with readOnlyHint=false.

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

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

Front-loaded with the core action and scope, and every clause carries useful information. It is dense and semicolon-packed, especially the return/error section, but not wasteful.

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

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

No output schema exists, so the description supplies the return shape and error cases directly. With annotations sparse and the operation complex, the definition provides enough detail for an agent to call it correctly and interpret results.

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, but the description adds meaningful semantics: width/height may be clamped, area "content" means page viewport in CSS pixels under CDP, and windowId defaults to active. It goes beyond the schema's terse parameter 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 and resource: resize the active window or windowId to width x height, with window vs content-area scope. This is clearly distinguishable from sibling window-management tools such as electron_switch_window or electron_windows_list.

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?

Explains the key usage context: resizing the active window by default or a specific windowId, and choosing area "content" for the web content. It also notes that maximized/fullscreen windows are restored first, but it does not explicitly compare against alternative tools or state when not to use it.

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

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

Adds substantial context beyond the readOnly/openWorld annotations: how refs are tagged on the DOM (data-sw-ref), that renderer_reloaded detects stale refs, that closed shadow roots are opaque unless the app opts in, and precise error codes with retryability. Annotations are consistent with the read semantics.

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

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

Front-loads the core action and return shape, then layers mode-specific detail. It is dense and long, but for an 8-parameter tool with a nested root object and no output schema, nearly every sentence carries operational value; only minor density costs it a point.

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 fully specifies the return object ({ ok, surface_id, kind, snapshot?, diff?, ... truncated }) and enumerates error conditions. Edge cases (stale refs, closed shadow roots, truncation) are all covered, so an agent has everything needed 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 description coverage is already 100%, but the description still enriches semantics: it explains since, format:'text' rendering syntax, diffFormat default/override, and budgetTokens' server-side drop order. It meaningfully exceeds the schema rather than merely restating it.

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

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

States a specific verb and resource ('Capture the selected renderer surface accessibility tree') and enumerates what it returns (role, name, state, bbox, ref). It's clearly distinguishable from siblings like electron_elements_list or electron_screenshot, which an agent can tell apart without opening schemas.

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

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

Gives clear conditional usage for its modes: since:"last" for deltas, interactiveOnly to drop landmarks, format:"text" to save tokens, budgetTokens for truncation. It also names electron_launch as the prerequisite for the NOT_RUNNING case. It stops short of explicitly contrasting against sibling listing tools, so a 4.

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 establish readOnlyHint and openWorldHint, and the description goes well beyond them by listing specific never-returned data (arguments, paths, logs, stack traces, prompt text, plugin payloads), which tells the agent what privacy/safety envelope it operates within. It also discloses error behavior ('Errors: none').

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 what it returns, then the negative spec, then alternatives, then the return shape – a logical order. The long enumerations are dense but each clause carries distinct, useful information; nothing is obviously padding.

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

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

With no output schema, the description carries the burden and provides the return shape explicitly ({ ok, server, active_sessions, sessions }) plus a nested field list. An agent can call and interpret it without further info.

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

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

Zero parameters, so there is nothing to document and the baseline is 4. The description does not need to explain inputs, and it spends its words on the return shape instead.

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 ('Return compact orientation') and resource ('this server'), then enumerates exactly what it returns: version, uptime, session count, per-session transport/readiness/surface/error code. It explicitly distinguishes itself from electron_windows_list, electron_surfaces_list, and plugin tools.

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

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

Names the alternatives explicitly ('Use electron_windows_list, electron_surfaces_list, or the relevant plugin tool for detailed state'), so an agent knows this tool is for a compact overview and those siblings are for detail. Clear when-to-use 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?

Annotations already indicate destructive behavior, but the description adds vital details: auto-escalation to SIGKILL, timeout, response fields, and specific errors, providing thorough behavioral insight.

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 concise, front-loaded with the primary action, and efficiently covers details, return values, and errors in a structured manner.

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?

The description covers all necessary context: usage, parameters, return values, escalation behavior, and errors, making it complete for a stop tool with no output 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 baseline 3. The description adds meaning for 'sessionId' (omit if single session) and 'timeoutMs' (graceful closing budget), raising the score.

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

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

The description clearly states the verb 'stop' and resource 'session', and distinguishes it from siblings like 'electron_force_kill' by emphasizing graceful stop with auto-escalation.

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 provides context for when to use (stop a session) and error conditions (NOT_RUNNING, BAD_ARGUMENT). It could explicitly mention when to use 'electron_force_kill' instead, but the graceful vs force distinction is clear.

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

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

Annotations already indicate readOnlyHint=true and openWorldHint=false. Description adds that opaque ids are stable only while surface is live, need to select with switch_surface, and details return structure. No contradictions.

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?

Five sentences front-loaded with purpose, then usage, return, and errors. Every sentence adds value; no wasted words.

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 one optional parameter and no output schema, description provides return structure, error conditions, and usage guidance. Sufficient for agent to understand invocation and results.

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 covers sessionId with description; description adds 'Omit when a single session is running' and mentions errors for multiple sessions, adding context beyond 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?

Description clearly states verb 'List', resource 'session renderer surfaces', and specifies order and types (BrowserWindow roots, WebContentsViews, etc.). Differentiates from sibling tools by mentioning relationship to electron_switch_surface and existing window tools.

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

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

Explicitly states when to use (before snapshot/find/renderer interactions) and when not to use (window-only flows). Lists error conditions with guidance on retryability and provides context for optional sessionId.

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

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

Discloses that the surface must be from electron_surfaces_list, that old refs from other surfaces are rejected, and lists possible errors. Since annotations only indicate not read-only, the description provides necessary behavioral details.

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?

Concise: three sentences covering purpose, effect, return, and errors. No redundant information, all sentences earn their 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?

Given two parameters, no output schema, and minimal annotations, the description explains the effect on subsequent operations and error conditions well. Some context about state management could be added, but sufficient for the tool's complexity.

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% with descriptions, providing baseline 3. Description adds value by clarifying surfaceId's source and sessionId's optionality, enhancing understanding beyond 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?

Clearly states it selects a live renderer surface using an opaque ID from electron_surfaces_list. Explains that subsequent operations target that surface, distinguishing it from sibling tools like electron_surfaces_list.

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?

Implies when to use by stating that operations like snapshot and interactions target the switched surface. Explicitly notes that references from different surfaces are rejected. Could be more precise about when not to use, but adequate.

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 indicate readOnlyHint=false, and the description adds that it changes the renderer target without promising OS focus. It also lists error types. No contradiction with 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?

Two sentences and an error list, front-loaded with the main purpose. No superfluous text.

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 moderate complexity, the description covers return format, errors, and behavioral nuance. It is nearly complete for agent 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 covers all 4 parameters with descriptions. The tool description adds the precedence order and notes that sessionId can be omitted for single sessions, adding value beyond the schema.

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

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

The description clearly states it selects the active window with a defined precedence order. It distinguishes the tool's action from siblings like electron_switch_surface but does not explicitly differentiate.

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 and does not do (no OS focus guarantee) and lists errors. However, it does not specify when to use this tool vs sibling tools like electron_switch_surface.

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 annotations (readOnlyHint=false), the description adds critical behavioral details: it mentions that the tool 'fires an input event', lists possible error types with their meanings (e.g., TYPE_NO_EFFECT indicates wrong target), and notes that the force option bypasses actionability checks. This significantly helps an agent understand side effects and handling.

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 concise and well-structured: one paragraph that front-loads the main action, then provides alternative usage, options summary, return shape, and error list. Every sentence is informative with no redundancy or fluff.

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 tool's complexity (6 parameters, 1 required, no output schema), the description covers the core behavior, element identification (ref/selector), options (force, timeout), return value, and error cases. It is nearly complete, but it does not explicitly state that the text replaces existing content (implied by 'Set the value') or mention the maximum text length from 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% with each parameter already described. The description adds minimal extra meaning: it groups 'force' and 'timeoutMs' as options and clarifies the ref/selector mutual exclusivity, but does not provide deeper semantics beyond what the schema already offers. Baseline of 3 is appropriate.

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

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

The description clearly states 'Set the value of the input/textarea identified by ref or selector (fires an input event)', specifying the verb ('Set the value') and resource ('input/textarea'). It also explicitly distinguishes from the sibling tool `electron_type_into_editor` for code editors, making the purpose unambiguous.

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 provides explicit instructions: use for standard input/textarea, and for code editors use `electron_type_into_editor` instead. It explains why (setting .value on editor host does not update its model). However, it does not address other potentially confusing siblings like `electron_keyboard_type` or `electron_press_sequence`, so some guidance is missing.

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

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

Discloses behavioral traits beyond annotations: it clicks the content area, types real keystrokes, and for replace mode uses Meta/Control+A for select-all with platform awareness. Covers the auto-pairing caveat where real keystrokes trigger auto-closing of quotes/brackets, causing debris. Describes return structure and error types with details like similar_refs. Annotations only indicate readOnlyHint=false, so description adds significant value.

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 main purpose and mechanism. Each sentence earns its place: purpose, replace behavior, auto-pairing caveat, return/errors. No redundant text. Well-structured with clear sections for different aspects.

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 6 parameters and no output schema, the description covers usage, behavior, caveats, return structure (ok, session_id, target, typed, replaced), and error codes with retryable flags. Addresses edge cases like empty text clearing the editor. Sufficient for an agent to use 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% with descriptions for all 6 parameters. The description adds meaning beyond schema: explains how ref resolves to data-sw-ref attribute, how replace triggers select-all and typing, and how text interacts with auto-pairing. However, timeoutMs and sessionId are standard and not further elaborated. Overall enhances understanding.

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 it types into a code editor (Monaco/EditContext, CodeMirror, contenteditable) the reliable way, distinguishing it from typing into a hidden textarea that fails for modern editors. The verb 'type into' and resource 'code editor' are specific, and it differentiates from siblings like 'electron_type' which likely targets regular inputs.

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

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

Explicitly says to use this instead of typing into an editor's hidden textarea due to the TYPE_NO_EFFECT error. Provides guidance on when to use replace:true (replace contents, clear editor). Implicitly suggests not using this for non-editor inputs, but doesn't name alternatives beyond the hidden textarea distinction.

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

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

Discloses no-op behavior, options (force, timeoutMs), return shape, and error types with retryability hints. Annotations are minimal, so description fully carries behavioral disclosure.

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

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

Single sentence covering purpose, options, returns, and errors. Concise but could benefit from structured sections for clarity.

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