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

With no annotations to rely on, the description carries full behavioral burden and succeeds richly. It discloses auto-guards (tab readyState/identity), 'never guesses' ambiguity behavior, modal-blocking stop codes, delivery verification semantics, and the reserved-only BrowserClickNotDelivered status. These are genuine behavioral traits well beyond 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?

The description is long but densely informative, with major concepts front-loaded (targeting modes, ambiguity handling, modal blocking) and caveats/verification details following. Every sentence serves a purpose, though the delivery-verification section is quite dense and could overwhelm an agent scanning for quick facts. Still, it is appropriately sized for the tool's complexity.

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

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

Despite no output schema, the description covers what the agent needs to handle outcomes: error codes (BrowserAmbiguousTarget, BrowserNoActionableTarget, BrowserModalBlocking), verification status values, reasons, and observed signals. It also handles edge cases like iframe_context_mismatch and modal-vs-navigation-drawer distinction. Nothing critical is left unexplained.

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 substantial meaning beyond parameter names: selector vs. by-axis exclusivity, role as an AND-filter, scope narrowing, tabId+port auto-guards, lensId purpose, scrollIntoView workflow implications, and include/narrate envelope behavior. This is far more than a restatement of 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 opens with 'Click a DOM element in Chrome/Edge' and immediately defines two distinct targeting modes (selector and by-axis), explicitly referencing siblings browser_locate and mouse_click. This gives a specific verb, resource, and clear differentiation from related 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?

It provides explicit when-to-use guidance: selector for stable CSS-based targeting, by-axis for dynamic-class SPAs. It also gives actionable exclusions and workarounds, such as using browser_eval to scroll elements into view, and instructs to retry after dismissing a modal dialog. It clearly states 'Provide EITHER selector OR by+pattern (not both).'

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?

Since no annotations are provided, the description fully discloses behaviors: actions, truncation, withPerception wrapping, readyState checks, error codes (BrowserNotConnected, AutoGuardBlocked), serialization limitations, and execution timeout. 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 well-structured with clear sections (Purpose, Details, Prefer, Caveats, Examples) and front-loads the purpose. It is slightly verbose but 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 the complexity (12 parameters, 3 actions), the description covers all aspects, including return structures, error types, and recommended usage patterns. Examples illustrate typical calls. No output schema exists, but the description adequately hints at return shapes.

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 significant context beyond the schema, such as the purpose of each action, the effect of withPerception, and the use of selectors for appState. It provides examples that clarify parameter usage.

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: 'Inspect or operate on a browser tab via 3 actions'. It specifies each action (js, dom, appState) and differentiates from sibling tools by focusing on evaluation/scripting rather than navigation, clicks, etc.

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 'Prefer:' section explicitly tells when to use each action, e.g., 'Use action='appState' BEFORE 'dom' or 'js' on SPAs'. The 'Caveats' section specifies when not to use this tool (e.g., for controlled inputs) and provides error handling guidance.

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

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

With no annotations, the description carries the full burden and does so thoroughly. It discloses CDP dependency, that it stops with specific error codes on ambiguous or non-actionable targets, that it never guesses, that actual value is verified and authoritative, that masked fields suppress echoing, and even the false-positive controlled-input transform case with subReason hints. No contradiction with structured fields.

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

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

While long, every sentence earns its place. The structure is logical: purpose and use-case first, then targeting methods, then caveats and error handling. It front-loads the core intent and flows from selection to verification. No redundancy; the density is justified by the tool's complexity.

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

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

For a tool with 11 parameters, no output schema, and no annotations, the description is remarkably complete. It covers targeting options, disambiguation, error codes and hints, verification via 'actual' and 'valueWithheld', and the CDP prerequisite. The only minor omission is a full enumeration of all response fields, but the description highlights the critical ones. This is sufficient for an agent to invoke 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?

Although schema coverage is 100%, the description adds substantial semantic depth beyond the schema: it explains the behavior of the 'by' axis resolution, the semantics of 'pattern' paired with 'by', the role and scope filters, and the error scenarios tied to parameters. For instance, it clarifies that 'by' must be paired with 'pattern' and that 'selector' is an exclusive alternative. This enriches understanding beyond field descriptions.

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

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

The description states the exact action ('Fill a form input with a value via CDP') and explicitly differentiates from siblings by noting it works on controlled inputs that reject browser_eval assignment, and names browser_eval and browser_locate as alternatives. It also enumerates two distinct targeting methods, making its purpose unmistakable.

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

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

It provides explicit guidance on when to use this tool over browser_eval ('Use this over browser_eval when setting a controlled input's value via JS does not update framework state'), and when to choose selector vs. by-axis ('by-axis resolves to a SINGLE fillable element...'), with a direct constraint: 'Provide EITHER selector OR by+pattern (not both).' It also warns about the CDP prerequisite (browser_open).

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

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

With no annotations provided, the description carries full responsibility for behavioral disclosure. It discloses the CDP prerequisite, the default exclusion of hidden inputs, the 200-char truncation, and the masking behavior (value null, valueWithheld 'masked', hasValue) with the exact resolution order for labels. This is thorough and leaves no critical behavior unexplained.

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 longer than minimal but every sentence adds essential context. It front-loads the core purpose and output details, then covers caveats. The structure flows logically from what the tool does, to how to use it, to behavioral notes. It could be slightly tightened (e.g., combining some caveats), but it is efficient and well-organized.

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 (7 parameters, no output schema), the description provides a complete picture: it explains the returned data structure (including edge cases like masked fields), the prerequisite, the default behavior for hidden inputs, and the label resolution order. An agent has everything needed to invoke it correctly and interpret results. No output schema exists, so the description's coverage of the response is essential and fully supplied.

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 adds value beyond the schema by explaining the semantics of includeHidden (why default false: to avoid CSRF-token clutter), the output shape (masking details), and the container concept for selector. However, it does not elaborate on port, tabId, or include's envelope behavior, though those are already well described in the schema. The added context justifies a 4.

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

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

The description states a precise verb ('Inspect'), a specific resource ('all form fields within a CSS-selector-specified container'), and enumerates the exact attributes returned. It also names the sibling tool it supports ('browser_fill') and the risk it mitigates (targeting the wrong input), making its purpose unambiguous and distinct from other browser 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?

The description explicitly says 'Use this before browser_fill' and explains why (to discover exact field selectors and avoid accidental targeting). It also provides caveats: requires browser_open (CDP active), hidden inputs are excluded by default, and when to set includeHidden:true. This gives clear when-to-use guidance and a precondition, though it does not name alternatives beyond browser_fill.

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

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

No annotations provided, so description carries full burden. It discloses capture-time coordinates, staleness risk, and typed errors. Could mention more about response shape, but sufficient for safe use.

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

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

Three sentences, front-loaded with purpose, zero wasted words. Caveats and error patterns are clearly separated.

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, but description states return of physical screen coordinates. More detail on return format (e.g., object with x,y) would improve completeness, but error types and compatibility hints are good.

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%, baseline 3. Description adds little beyond schema for parameters, but mentions coordinate compatibility with mouse_click, which is helpful context.

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 action (find DOM element) and output (physical screen coordinates), explicitly distinguishing from sibling tools browser_click and browser_overview.

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 using browser_click for find+click in one step and browser_overview to discover selectors. Also includes caveat about stale coordinates after page reflow.

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 several valuable non-obvious traits: ack semantics, auto-guard behavior, post.perception.status, and three typed errors with remediation. However, it asserts 'Does not block until page load completes' while the schema's waitForLoad defaults to true and waits for readyState 'complete', a conflict that can mislead agents about default behavior. Since no annotations exist, the description carries the full burden, making this inconsistency more damaging.

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

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

The description is front-loaded and information-dense, with a clear caveat label and a structured error taxonomy. It is slightly overstuffed—repeated wait_until advice and internal CDP jargon (frameStoppedLoading/loaderId) could be trimmed—but overall 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?

Despite having no output schema or annotations, the description covers return perception status, error codes, auto-guard refusal, and recommended follow-ups for an 8-parameter CDP tool. The only serious omission is the waitForLoad/loadTimeoutMs behavior, which is contradicted by the caveat and leaves slow-page guidance incomplete.

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 adds useful context for tabId/port (auto-guard) and lensId (pinned-tab workflows), but it does not compensate for the waitForLoad inconsistency nor add semantics for include/narrate beyond what the schema already describes.

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

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

The opening sentence names a specific verb (navigate), resource (browser tab to URL), and mechanism (CDP Page.navigate), and explicitly contrasts with clicking the address bar, which separates it from sibling browser tools. The lensId and perception-status details further clarify its 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?

The description explicitly directs follow-up with wait_until or browser_eval polling for slow pages, and names browser_open for reconnection after BrowserNotConnected. It also frames the tool as more reliable than the address-bar alternative, giving an agent enough context to choose among siblings.

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

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

Despite no annotations, the description fully discloses behavior: returns tabs array with specific fields, idempotent launch, error codes, killExisting warning data loss, and CDP connection per-process. 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?

Single paragraph but well-structured with clear logical flow. Slightly redundant on 'idempotent' but overall concise given the information density.

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 all necessary aspects: prerequisite, input/output, errors, edge cases (browser restart, existing session, unreachable endpoint). References sibling tools. Complete for a setup 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 already describes all parameters, but description adds context: explains launch parameter purpose, default behavior, example usage, and caveats for killExisting. Adds value 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 connects to a debug-mode browser and returns open tab IDs, and it distinguishes from siblings by being the prerequisite for all other browser_* 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?

Explicit instructions on when to use (required before other browser tools), when to use launch:{} vs pure connect, and caveats (Chrome restart, cannot take over existing session without debug port). Also gives error handling guidance.

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

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

With no annotations, the description carries the full burden of behavioral disclosure, and it does so richly. It discloses that selectors are CDP-generated snapshots requiring re-calls after navigation or re-render, that input text is always the name and never the typed value, that browser_form withholds masked-password values, that a non-matching scope silently falls back to the full document, and it names the BrowserNotConnected error condition. No annotation contradiction exists.

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

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

The description is dense but every clause earns its place: main purpose is front-loaded, usage guidance follows, and caveats are grouped and clearly labeled. Though lengthy, the complexity of the tool (8 parameters, modal behavior, error conditions, scope fallback) justifies the length. There is no filler or redundant restating of the schema.

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

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

Given the absence of an output schema, the description does a strong job of explaining what the agent will receive: ARIA state values, the always-present modal section with isModal and blocker details, and structured output. It also covers error conditions, scope fallback, and masked input behavior. The definition is complete enough for correct invocation and expectation-setting.

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 adds materially beyond the schema by explaining the non-matching scope selector behavior (silent fallback to the full document) and by clarifying input-text semantics as they relate to output. Most other parameter details are already well-documented in the schema, so the added value is meaningful but not exhaustive.

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

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

The description opens with a specific verb-resource pair: 'List all interactive elements (links, buttons, inputs, ARIA controls) on the current page' and enumerates the returned data (CSS selectors, visible text, viewport status). It also explicitly distinguishes the tool from browser_click and screenshot, so an agent can immediately tell what it does and why it exists.

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 explicit when-to-use guidance: 'use before browser_click to discover stable selectors' and 'prefer this over screenshot when verifying button/toggle state after submission'. It also routes value reading to browser_form and suggests browser_eval for verifying a scope selector, providing clear context and alternatives without leaving inference to the agent.

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

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

With no annotations, the description is transparent about result sorting ('confidence descending'), pagination, and options like visibleOnly and inViewportOnly with behavior notes. It mentions error codes and conditions. Lacks an explicit statement of non-destructiveness but implies it.

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?

Compact and well-structured: purpose, axes, result usage, pagination, caveats, then error codes. Every sentence serves a purpose 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?

For a complex tool with 11 parameters and no output schema, the description covers core functionality, error handling, and usage context. Could include a sample result structure but sufficient given the chaining hint.

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%, baseline 3. Description adds value beyond schema by explaining search axes with examples (literal substring, CSS), result chaining, and parameter adjustments implied in error codes (e.g., 'broaden the by:text substring').

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 this is a 'Grep-like element search' with specific axes (text, regex, role, ariaLabel, selector) and explains result usage ('pass results[0].selector to browser_click'). It distinguishes from sibling browser_overview for broad discovery.

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 when to use this tool ('when you know specific text or role to target') vs browser_overview for broad discovery. Also provides detailed error code remedies, guiding the agent on corrective actions (e.g., broaden substring, reduce maxResults).

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

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

With no annotations, the description bears full behavioral disclosure burden. It goes beyond basics: explains server-side guarding using windowTitle, the return of post.perception.status, and enumerates typed error codes with precise recovery actions (InvokePatternNotSupported, ElementDisabled, GuardFailed). It also discloses limitations of custom controls. This is exceptional 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?

The description is detailed but tightly structured: purpose, usage guidance, then error handling caveats. Every sentence earns its place—no filler or redundancy. Despite its length, it remains front-loaded with the core purpose and immediately actionable guidance, making it efficient for an agent to parse.

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 9 parameters, no annotations, and no output schema, the description covers all essential contextual aspects: purpose, prerequisites (desktop_discover), selection criteria, error recovery, and limitations. It omits nothing an agent needs to call it correctly. The schema handles parameter details, and the description handles decision-making and error handling comprehensively.

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 adds value beyond schema by explaining the intent of fixId ('re-target after window identity drift') and lensId ('advanced pinned-lens use'), and mentions that include and narrate affect response shape. While the schema already documents each parameter, these contextual clarifications improve agent comprehension.

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

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

The description states a specific verb and resource: 'Invoke a UI element by name or automationId via UIA InvokePattern — no screen coordinates needed.' It clearly differentiates from siblings like mouse_click and browser_click by identifying the use case (native Windows UI controls) and explicitly naming alternative tools. This is a precise, actionable 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?

The description provides explicit when-to-use guidance: 'Prefer over mouse_click for buttons, menu items, and links in native Windows apps.' It also instructs to 'Use desktop_discover first to discover automationIds' and explains when to pass fixId. It even describes fallback cases, e.g., 'fall back to mouse_click' when InvokePattern is unsupported. No ambiguity remains about selecting this tool vs 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?

With no annotations, the description must reveal all behavioral traits. It discloses timeouts (4s/5s), failure codes (ClipboardWriteNotDelivered), indeterminate state after a timed-out write, backend differences (native vs powershell), delivery verification, and diagnostic fields. This is exemplary 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?

Despite its length, the description is front-loaded with the core purpose and uses clear sections (Caveats, Recovery, Diagnostics) to structure dense information. Every sentence adds actionable detail, so the length is justified rather than 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?

Given no output schema, the description thoroughly covers return behavior (empty string for non-text), error conditions, environment variations, and diagnostics. It anticipates edge cases like clipboard managers and RDP transcoding, and offers recovery steps. No significant gaps remain.

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 critical semantics beyond it: the exact meaning of each action, the 8MB read limit, 12000-char fallback limit, and the delivery-verification process. It also explains the 'include' parameter's effect indirectly through response shape context, though not named.

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

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

The description opens with 'Read or write the Windows clipboard,' clearly specifying the verb and resource. It further distinguishes the two actions ('read' returns text; 'write' replaces and verifies) and avoids confusion with sibling tools like keyboard by focusing on clipboard interaction.

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 alternative guidance for failed writes: 'fall back to keyboard(action="type", use_clipboard=false) for short text.' It also warns when retrying is futile (unresponsive clipboard owner) and when reading non-text payloads yields empty strings, effectively defining when-not-to-use.

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

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

No annotations exist, so the description carries the full burden, and it does so extensively: UIA limitations ('cannot detect non-UIA elements'), the modal-detection gap ('browser alert/confirm dialogs may not appear here'), the CDP dependency and its silent-failure behavior, the hints.* diagnostic fields, and the masked-value handling on both the CDP and UIA roads. This is far more than a restatement of the name.

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 a clear Purpose/Details/Prefer/Caveats structure, and the long return-field enumeration is justified because no output schema exists. However, the masked-value passage is rambling and re-explanatory ('nothing here distinguishes from its real value... nothing here distinguishes from its real value' paraphrased across several sentences), which costs some density.

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

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

With no annotations, no output schema, and 7 parameters, the description must be self-sufficient, and it is: it documents the always-returned fields, the opt-in fields, the hints diagnostic vocabulary, the CDP prerequisite, and the platform caveats. Nothing an agent needs to call this correctly appears to be missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds value the schema does not: each include* flag 'adds one syscall or CDP round-trip', flags are 'default off', and port fallback semantics are clarified. Minor inconsistency: the description offers include:['sessionContext'] as an alias, while the schema's `include` description documents only 'envelope' and 'raw'.

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

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

States a specific verb and resource ('Read-only observation of the current desktop state') and enumerates the exact return surface. It also explicitly bounds the tool against a sibling: 'Does NOT enumerate descendants — use desktop_discover for actionable entity list and window list.' An agent can distinguish this from desktop_discover without opening either schema.

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

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

Gives a concrete usage rule ('Use after each action to confirm state'), a cost comparison ('cheapest observation tool — cheaper than any screenshot'), a decision gate ('attention='ok' means safe to proceed; other values require recovery'), and a conditional rule for the include* flags ('Set include* flags only when you need the extra data'). The alternative (desktop_discover) is named with the condition that selects 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?

With no annotations, the description fully discloses behavioral traits: required registry keys (AccessVBOM=1, VBAWarnings=1), Trusted Location setup, need for Excel restart, COM STA serialization causing blocking, and the requirement that macroName must match the Sub name in code. Failure modes (HRESULT 0x800a03ec) are also noted.

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 clear sections (Purpose, Details, Prefer, Caveats, Examples). It is comprehensive but each sentence adds necessary information, avoiding redundancy. Front-loading the purpose and distinction aids quick understanding.

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 (VBA execution, COM, permissions), the description covers all essential aspects: purpose, setup requirements, prevalidation, caveats about naming and blocking, and complete examples with return values. No gaps remain despite the lack of an 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?

The input schema is empty with additionalProperties: true, so it provides no parameter definitions. The description compensates by defining the key parameters (action, code, macroName, visible) and their meanings, including constraints like macroName must match Sub name. Examples show expected parameter combinations and their effects.

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 purpose: author and run VBA macros against Excel via COM late binding. It distinguishes from 'Claude for Excel' which writes formulas but cannot run VBA. The two actions run_vba and check_access_vbom are explicitly defined, making the tool's functionality 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 direct guidance: 'Prefer: Run check_access_vbom first when a workflow depends on macro execution'. It explains the preflight check and remediation for failures. Examples illustrate correct usage for both actions, clarifying when to use each.

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

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

No annotations, so the description carries the full burden, and it discloses a lot: silent skip of chromeTabUrlContains when CDP is unavailable (with hints.warnings), WindowNotFound semantics, and the ForegroundRestricted failure mode with its UIPI/admin/background-process causes. It stops short of describing the return payload shape or the exact ok/windowChanged contract on success, which is a minor residual gap.

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

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

The purpose and alternatives are front-loaded in the opening sentences, and the caveats/recovery guidance is dense but earns its place for a tool with this many failure modes. It is on the long side, with a fair amount of cross-tool referencing that could be trimmed, but nothing is decorative.

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 naming the error codes (WindowNotFound, ForegroundRestricted), the hints.warnings channel, and concrete recovery tools. For a 5-parameter foreground-transfer tool with several silent-failure traps, an agent has everything needed to call it and to interpret failure.

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 genuine value: it explains the sequencing relationship between chromeTabUrlContains and title (activate the tab first, since only the active tab's title is visible), and the escalation behavior of forceFocus including the DESKTOP_TOUCH_FORCE_FOCUS env override. That is semantics beyond the field-level text.

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

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

States a specific verb and resource (bring a window to the foreground by partial title match, case-insensitive) and immediately differentiates itself from browser_* (tabId/selector targeting) and desktop_act/click_element (no foreground needed). An agent can identify exactly what this does and what it is not 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?

Explicit when-to-use ('when a tool does not accept a windowTitle param', 'need to switch focus before a sequence of actions') and explicit alternatives with selection conditions (chromeTabUrlContains for non-active Chrome tabs, desktop_act/click_element/keyboard BG path when foreground transfer is refused). Routing is fully specified.

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

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

With zero annotations the description carries the full burden, and it delivers: blocked combos (win+r/x/s/l), IME composition failure modes, auto-clipboard promotion and restore behavior, background WM_CHAR auto-engagement and read-back verification, the foreground focus leash, and named failure codes (FocusLostDuringType, BackgroundInputNotDelivered, MenuFocusLostMidSequence, WindowOnOtherDesktop). It even discloses the config flags that change behavior (DTM_BG_AUTO, DESKTOP_TOUCH_REQUIRE_DESTINATION).

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

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

It is well front-loaded with labeled sections (Purpose, Details, Prefer, Caveats, Examples), so key routing info comes first. But the Caveats block is a dense run-on packed with internal error codes and env-var names that pushes the size far past what an agent needs to select and invoke the tool correctly.

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

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

For a 19-parameter, no-annotation, no-output-schema tool, this is essentially complete: it states prerequisites, blocked inputs, alternative tools, environment overrides, and the shape of post-action hint fields (hints.clipboard, hints.verifyDelivery) that would otherwise appear undocumented. Nothing material is missing for correct invocation.

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

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

Schema coverage is 100%, so the baseline is 3, and the description earns above that by adding cross-cutting semantics the flat schema cannot express: precedence of hwnd over windowTitle, that '@active' targets the foreground deliberately, and the per-action required-field enforcement that explains why the schema lists everything as optional. It adds context beyond the per-field text without fully re-documenting every one of the 19 fields.

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

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

Opens with a precise verb+resource ('Send keyboard input to a window') and immediately disambiguates the three action modes with concrete semantics for each ('type' inserts text, 'press' sends combos, 'sequence' runs atomic multi-step chords). It also distinguishes itself from siblings by naming desktop_act({action:'setValue'}) and click_element as the correct tools for UIA value fields and non-terminal refusal 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?

Gives explicit when-to-use guidance per action, including the non-obvious case for 'sequence' (Alt+letter mnemonic chains whose intermediate calls would close the menu). It names alternatives with conditions ('Use desktop_act({action:'setValue'}) for UIA ValuePattern text fields', 'non-terminal switch to desktop_act / click_element'), states the hard prerequisite (windowTitle or hwnd REQUIRED) and the '@active' escape hatch.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure, and it does so thoroughly. It discloses that secrets are never shown to the assistant, that the first save shows a one-time enable confirmation, that autofill only works in an active tab, that enabling grants both credential autofill and pane-launch ability, that Windows-only, and that API-token/env-var credentials are not supported. It also explains the retry path for KeyLockerWtUnavailable. This is exemplary 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?

The description is long but every section earns its place: Purpose, Details, Prefer, Caveats, and Examples. It is front-loaded with the core purpose and action list, then workflow guidance, then caveats, then concrete examples. It could be slightly tightened (e.g., the parenthetical about host:'classic' appears twice), but the structure is logical and scannable.

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 actions, credential security, terminal integration, Windows-specific behavior), the description is remarkably complete. It covers prerequisites (known_hosts for ssh saves), failure modes (KeyLockerWtUnavailable), security boundaries (secrets never shown), and the exact workflow with terminal. The examples show realistic input/output pairs. Nothing an agent needs to call 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?

The input schema is empty with additionalProperties: true, so the description must document the action parameter and its values, which it does extensively. It explains each action (save, list, forget, set_policy, status, launch_console) and the uri format for save (ssh://user@host:22, sudo://host/root, https-cred://host:443, sshkey:SHA256:…). It also documents host:'classic' and fresh:false. The only minor gap is that it doesn't enumerate every possible property in the schema, but with 0 params and 100% schema coverage, the description compensates well.

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

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

The description opens with a specific verb and resource: 'Manage credentials the terminal autofills for you (SSH key passphrases, sudo / login passwords).' It clearly distinguishes this from sibling tools like terminal, clipboard, and run_macro by focusing on credential storage and autofill. The action list (save, list, forget, set_policy, status, launch_console) further disambiguates the tool's 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?

The 'Prefer' section explicitly states when to use this tool vs alternatives: autofill is automatic, but only fires in a pane opened by launch_console, and the agent must pass paneId, not windowTitle. It also gives a concrete workflow: 'to autofill, first launch_console, then run the ssh / sudo command with terminal({action:'run'|'send', paneId}).' This is explicit when-to-use guidance with no ambiguity.

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

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

With no annotations, the description carries the full burden and does so unusually well: it discloses the guard's verification steps, unguarded vs guarded post.perception.status values, the three verifyDelivery signals and the 'unverifiable' degradation path, ForegroundRestricted and WindowOnOtherDesktop failure modes with recovery, and that MouseClickNotDelivered is deliberately never emitted. Nothing material about behavior is left undisclosed.

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

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

Very long, but front-loaded with the core action and then ordered into guard behavior, alternatives, examples, fix flow, and caveats, so each block earns its place for a 21-parameter tool. Slightly dense and mixes examples with caveat prose in a way that could be tightened, so not a 5.

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

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

Given 21 parameters, nested origin, no output schema, and no annotations, the description covers the call shape, guard semantics, failure codes and their recovery paths, and return hints. An agent has everything needed to call this correctly 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 real meaning beyond the schema: origin+scale are only meaningful with dotByDot=true screenshots, fixId is one-shot and server-revalidated, lensId is optional/advanced and should be omitted normally, and hints.verifyDelivery.status is explained. It does not restate many of the 21 params (settleMs, homing, speed, button), which keeps it from a 5.

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

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

Opens with a specific verb+resource ('Click at screen coordinates') and immediately differentiates itself from siblings by naming click_element for native apps and browser_click for Chrome. An agent can pick this tool over the alternatives without opening any schema.

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

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

Explicitly states the preferred call shape (pass windowTitle for guarded, omit for unguarded), names the alternative tools for other contexts, and describes the fixId recovery path with its one-shot/15s expiration. When-to-use and when-to-prefer-siblings guidance is fully present.

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

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

With no annotations, the description carries the full burden and does an unusually thorough job: it discloses left-button-only, both endpoints guarded, default blocking of cross-window/tab drags, and typed refusals (CrossWindowDragBlocked, TabDragBlocked, ForegroundRestricted, WindowOnOtherDesktop). It also flags MouseDragNotDelivered as reserved-only and explains the verifyDelivery status shape. This is rich behavioral context, but some of it (guard flags) is duplicated from the schema rather than adding net-new behavior, keeping it just shy of top marks.

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 action and use cases are front-loaded, then caveats and error codes follow in a dense but well-organized block. It is long, and the caveat sentences restate the allowCrossWindowDrag/allowTabDrag schema text, which is mildly redundant, but given the operational complexity most 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?

There is no output schema, so the description must explain returns, and it does: post.perception, the hints.verifyDelivery 3-value shape, and the include envelope opt-in. For a 14-parameter tool this is fairly complete, though the required verifyDelivery input parameter's purpose is never explained in the description or 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 71%, so the schema already documents most parameters including the guard flags. The description adds real meaning for windowTitle (auto-guards the start coordinate) and lensId ('same as mouse_click'), which is genuine added value, but it does not clarify the required verifyDelivery input param, whose schema description is a non-informative placeholder.

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 first sentence states a precise verb+resource+coordinates ('Click and drag from (startX, startY) to (endX, endY) holding the left mouse button') and enumerates concrete use cases (sliders, drag-and-drop, canvas drawing, window resizing). It clearly distinguishes this from the sibling mouse_click by being the drag variant.

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 when-to-use scenarios are given, plus an inline example call. It names when to set the guard flags (allowCrossWindowDrag:true 'to confirm intent', allowTabDrag:true 'when tearing off or rearranging a tab is intended') and scopes lensId as 'only for advanced pinned-target workflows', so alternatives and exclusions are covered.

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

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

With no annotations provided, the description carries the full burden. It discloses that the successful response always includes a hints.verifyDelivery object with status 'unverifiable' and explains the reasons (Focus Assist, DND, consent UI). It also mentions the underlying technology (System.Windows.Forms) and that no external modules are needed. However, it does not clarify if the tool is blocking or asynchronous.

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 moderately concise but includes Japanese text and a JSON literal that may hinder readability. The first sentence is clear, followed by technical caveats that are all relevant but could be more structured. Every sentence serves a purpose, but the mix of languages and technical jargon reduces conciseness.

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 that the tool has only 3 parameters, no output schema, and no nested objects, the description covers the key aspects: purpose, usage context, delivery verification behavior, and a suggested indirect observation method. It is complete enough for an agent to use correctly, though it does not cover behavior for multiple rapid calls or notification click handling.

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 does not add significant new meaning beyond what the schema already provides for the title, body, and include parameters. The description focuses on behavioral aspects rather than parameter details.

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 'Show a Windows system tray balloon notification to alert the user', providing a specific verb and resource. It distinguishes from sibling tools which are focused on browser interactions, desktop actions, and data processing, 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 explicitly says 'Use at the end of a long-running task so the user knows it finished without watching the screen', providing clear context for when to use. It also includes caveats about delivery verification and suggests indirect observation via wait_until, but does not mention alternative tools or explicitly state when not to use.

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

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

With no annotations, the description carries the full burden and does so excellently. It discloses which tools are never valid steps, that sleep is a pseudo-step, the max 50-step limit, stop_on_error behavior, that intermediate results cannot be inspected, and the token cost of screenshots. This is rich behavioral context well beyond what the schema provides.

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

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

The description is long but every section earns its place: purpose, details, usage preference, caveats, and two concrete examples. It is well-structured with clear headers and front-loads the core purpose. The length is justified by the complexity of the tool.

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 is highly complete for a complex tool: it explains step validity, execution flow, failure behavior, and examples. The only minor gap is that it doesn't explicitly describe the shape of the returned results (e.g., an array of per-step outputs), though it does note that output is only returned after all steps complete or an error occurs.

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 substantial meaning beyond the schema: it defines the structure of steps[] with {tool, params}, explains the special sleep pseudo-step, enumerates which tools are invalid as steps, and clarifies the include/stop_on_error parameters. This goes well beyond the baseline for high schema 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?

The description clearly states the tool's specific purpose: 'Execute multiple tools sequentially in one MCP call.' It distinguishes itself from sibling tools by emphasizing batching and latency elimination, making it easy for an agent to understand this is a meta-orchestration tool rather than a single-action 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?

Explicit guidance is provided: 'Prefer: Use for predictable fixed sequences... Do not use for conditional logic — return to the LLM between branches.' It also gives concrete caveats about splitting macros when steps may fail conditionally, which tells the agent exactly when this tool is and isn't appropriate.

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

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

No annotations are provided, so the description carries the full burden and does so richly: the default maxDimension scaling (image px != screen px), the diffMode baseline requirement, the mode='background' + detail combination restriction, the ~1s OCR cold-start and language-pack dependency, and the confirmImage/by-ref default behavior are all disclosed. These are exactly the non-obvious traits an agent needs.

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

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

It is long, but the Purpose/Details/Prefer/Caveats/Examples scaffolding is front-loaded and skimmable, and the length is largely earned by 19 parameters and several orthogonal modes. Points deducted for some repetition (confirmImage and the by-ref resource_link are explained multiple times) that could be tightened.

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

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

With no output schema and no annotations, the description must cover behavior, and it does: capture routes, coordinate math, fallbacks, prerequisites, and worked examples. An agent can call this correctly across detail/mode combinations 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 the schema already documents all 19 parameters and the baseline is 3. The description nonetheless adds cross-parameter semantics the schema cannot express: the mode='background' only composes with detail in {'image','meta'} dispatcher rule, the dotByDot screen-coordinate formula, and the region-with-windowTitle cropping idiom.

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

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

The opening sentence states a specific verb (Capture) and resources (desktop, window, region) and enumerates the dimensions of variation (detail levels, capture modes). It clearly distinguishes this tool from siblings like desktopt_state and the browser_* family, which the 'Prefer' section explicitly routes away from.

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?

An explicit 'Prefer:' block gives when-to-use guidance: meta to orient, text before clicking, som/ocr for UIA-blind targets, background when the window must stay hidden, diffMode after actions, and to use browser_* for Chrome. Alternatives and conditions are named, not inferred.

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

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

No annotations provided, so description fully bears burden. Discloses dry-run default, two-flag safety gate, retention cap behaviors (always keeps newest), and scope limitation to screenshot cache only. Thoroughly covers behavioral traits.

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 dense paragraph, front-loaded with key behavior and safety. Every sentence provides value; however, could benefit from clearer structure (e.g., bullet points for retention caps). Still highly concise.

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 all 8 parameters, defaults, safety, scope, and return value in dry-run (candidates + orphan stats). No output schema, but description adequately explains what the call returns. Complete for a cleanup 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%, but description adds value: explains default retention values (newest 200 / 256 MiB), safety interplay of dryRun/confirm, purpose of include (response shape), and includeOrphans default. Goes 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 'Reclaim disk space from cached screenshots by retention policy', specifying the action (reclaim) and resource (cached screenshots). It distinguishes from sibling tools like screenshot (capture) and screenshot_query (query) by focusing on garbage collection and cache cleanup.

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 explains dry-run default and safety condition (dryRun:false + confirm:true for actual deletion). Provides context on when to use (disk space reclamation) and scope options (tag, includeOrphans, retention caps). Implicitly distinguishes from capture/query 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?

With no annotations, the description fully discloses behavior: non-destructive, lists returned fields (captureId, by-ref uri, dimensions, size, timestamp, tag/window, totals), notes ordering (newest-first), and warns about token costs for reading pixels. Also explains response shape options via 'include' parameter.

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 well-structured sentences: first states core purpose, then elaborates on return content, cost warning, filter/paging options, and ordering. No fluff, front-loaded with the main 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 7 parameters (0 required) and no output schema, the description covers the tool's purpose, return shape (fields and totals), filtering, pagination, ordering, and token-cost warning. It adequately equips an agent to use the tool correctly without needing 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. Description adds extra context: defaults for limit (50), offsets, case-insensitivity for tag, and ordering (newest-first). While some info repeats schema, the description organizes and clarifies usage for pagination and filtering, adding meaningful 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 verb 'List' and resource 'screenshots saved in the disk-cache', emphasizing it is non-destructive and fast. It distinguishes from sibling tools like 'screenshot' and 'screenshot_gc' by describing its specific function.

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 use cases: 'so you can find and re-open a specific earlier capture, or check how much the cache holds before reclaiming space with screenshot_gc.' Also warns against unnecessary token cost when opening by-ref links. Differentiates from siblings and advises on when to use.

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

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

With no annotations provided, the description carries the full burden and delivers extensively: it discloses pixel-vs-screen-coordinate mismatch for capture, the mutating CSS side effect of expandHidden, OCR accuracy limits, the requirement for window visibility in read mode, typed error codes (ScrollNotDelivered, OverflowHiddenAncestor, VirtualScrollExhausted), and the weak-evidence caveat for verifyDelivery pixel_delta_observed. It also explains the wheel-notch semantics and the 1000-notch ceiling rationale.

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 long but densely packed with high-value information, organized into Purpose, Details, Prefer, Caveats, and Examples sections. It front-loads the five strategies and their one-line definitions before diving into per-action details. The length is justified by the tool's complexity (5 modes, 32 parameters), though a few details (e.g., ADR-018 §2.6 reference) are terse to the point of being cryptic for an agent.

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 32-parameter, 5-mode tool with no output schema and no annotations, the description is remarkably complete. It covers per-action semantics, error codes, prerequisites (browser_open for CDP, UIA ScrollItemPattern for native), fallback ordering, and even provides five usage examples covering different actions. The only minor gap is that the return shape for each action is not explicitly described, but the description's examples and caveats largely compensate.

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 adds substantial meaning beyond the schema: it explains the relationship between amount and screenfuls, clarifies that one notch equals one physical wheel detent, gives per-app step sizes, and explains per-action required fields are enforced at call time. It also adds context for parameters like sizeReduced (mentioned in description though not in schema) and virtualIndex/virtualTotal via the VirtualScrollExhausted error. Minor deduction because the description is not exhaustive for every parameter (e.g., homing, scrollKey, verifyWithHash are only in 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 opens with a clear verb and resource ('Scroll a window or page') and immediately enumerates the five action strategies with one-line definitions. It distinguishes itself from siblings like mouse_click, browser_eval, and screenshot by naming its own sub-modes (raw, to_element, smart, capture, read) and their outputs.

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 'Prefer' section explicitly states when to use each action and when not to: use to_element/smart for entity_outside_viewport recovery, use capture for reading long pages as images, use read for OCR text extraction, and use raw for simple scrolling. It also names alternatives (focus_window, desktop_discover, browser_eval, browser_overview) and gives exclusion conditions like 'scrolling only helps when the target scrolled out of its own window'.

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

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

With no annotations, the description carries the full burden. It discloses that results change per call, that health is a process diagnostic snapshot, that nativeUiaEvidence reflects actual engine runs rather than the switch, that shutdown.pending indicates stdin EOF, and that lastRpc only tracks stdio transport. These are exactly the kind of behavioral caveats an agent needs, and they are clearly stated.

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 long but deliberately structured into field groups (engine, nativeUia, imageDiff, health) with terse explanations. The opening sentence states the core purpose, and each section earns its place by defining non-obvious semantics and failure modes. It could be trimmed slightly, but the density is justified by the tool's diagnostic 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 having no output schema, the description thoroughly documents every return value, sub-field, and their dynamic behavior. It explains limitations (HTTP transport not tracked), how to interpret counts (tasksDone vs tasksSent), and why a value might be null. An agent can call this tool and correctly interpret the response with no further information.

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 include parameter is fully documented in the input schema. The description adds nothing about the include parameter beyond what the schema says (envelope/raw), so the baseline of 3 applies. It does not worsen or improve the semantic gap.

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

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

The description opens with 'Return MCP server status', a specific verb+resource pair. It then enumerates the distinct field groups (engine, nativeUia, imageDiff, health, lastRpc) with precise meanings, making it unmistakably different from sibling tools like desktop_state or workspace_snapshot. The resource and scope are fully stated.

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 clear usage context: 'Diagnostic metadata — do not surface unless the user asks about performance/troubleshooting' signals when the tool is appropriate. It also advises 'read it after the act it should cover' because values change per call. It does not name explicit alternatives or exclude any sibling, but it orients the agent well.

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

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

With no annotations, the description carries the full burden and does so: it discloses completion reasons, outputIntegrity:'baseline_lost' semantics, specific error codes, the Windows Terminal WM_CHAR drop exclusion, foreground/background path selection, clipboard replacement by preferClipboard, and FileLockCollision warnings. Side effects, failure modes, and platform caveats are all surfaced.

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

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

It is well-structured with labeled sections (Purpose/Details/Prefer/Caveats/Examples) and front-loads the core behavior, which is a strength. However, it is extremely dense and long, and numerous issue-number citations (#245, #386, #173, #196, #236) and internal error-code asides add noise that an agent selecting a tool does not need.

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 10-parameter tool with nested objects and no output schema, the description covers return shapes (completion, outputIntegrity, warnings), typed errors, and platform-specific routing, so an agent has enough to call it correctly. Nothing critical is missing given the absence of an 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 80%, but the description meaningfully extends the undocumented parameters: it explains the `until` modes (quiet/pattern/exit with shell semantics), the paneId-vs-windowTitle precedence, the deprecated `command` alias, sinceMarker incremental reads, and send/read method options. This goes well beyond what the schema states.

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

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

Opens with a specific verb+resource+scope: 'Interact with a terminal window: read output, send input, or run+wait+read in one call.' It enumerates the three action modes (read/send/run) so an agent can distinguish behaviors without opening the schema, and it clearly separates this from screenshot-style siblings.

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

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

Provides explicit routing: prefer action='run' for execution+result, use until:{mode:'pattern'} for long-running commands, and use action='read'/'send' for fine-grained control. It also names when-not (do not screenshot; the default quiet mode fails on multi-second silent gaps) and gives concrete examples per action.

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

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

With no annotations provided, the description carries the full burden and does so thoroughly: it discloses success/error response shapes, all relevant error codes, browser/CDP prerequisites, per-poll UIA process spawning, the 500ms interval floor, and context.lastLook behavior including masked credentials. This goes far beyond what the schema or annotations convey.

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

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

The description is long but well-structured with Purpose, Details, Prefer, Caveats, and Examples sections, front-loading the most decision-relevant information. Each sentence earns its place given the nine-condition matrix, and the examples cover representative invocation patterns without becoming 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?

Given no annotations and no output schema, the description fully covers return values, error codes, prerequisites, condition-specific target requirements, and example calls. An agent can select and invoke this tool correctly for any of the nine conditions without needing 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?

Although schema coverage is 100%, the description adds critical meaning: per-condition target field requirements, optional regex flags, the internal 500ms interval for terminal_output_contains, the minimum interval for UIA conditions, and URL/SPA matching semantics. The target property in the schema is only described as 'depends on condition', so this text is essential for correct invocation.

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

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

The description opens with a specific verb and resource: 'Server-side poll for an observable condition', and immediately ties the purpose to eliminating screenshot-polling loops. It also differentiates itself from sibling tools such as run_macro and screenshot by explicitly contrasting those alternatives.

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

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

The 'Prefer' section explicitly states when to use this tool instead of run_macro({sleep:N}) + screenshot loops, and maps each condition to its intended use case (terminal completion, DOM readiness, SPA routing, redirects). The caveats further clarify when CDP prerequisites or UIA constraints apply.

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

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

With no annotations, the description carries the full burden and does so thoroughly: pin survives minimize/restore and requires explicit unpin, dock fails on elevated processes, dock overrides existing Win+Arrow snap arrangements, minimized windows are auto-restored, and hidden windows are silently skipped. These are exactly the non-obvious behaviors an agent needs before calling.

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

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

Front-loaded with a one-line purpose, then labeled Details/Prefer/Caveats/Examples sections that make it scannable. It is long and the examples are somewhat redundant with the Details section, but every section carries distinct information.

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

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

For a 10-parameter, no-annotation, no-output-schema tool, the description covers actions, defaults, failure modes, and prerequisites well. It does not describe the success/failure response shape at all (the 'include' envelope opt-in is only in the schema), leaving the return contract unstated.

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 per-action field semantics beyond the flat schema — which fields apply to 'dock' (corner/width/height, default 480x360 bottom-right), that dock pins unless pin:false, and that duration_ms auto-unpins. This compensates for the schema's own note that per-action required fields are enforced at call time and only documented in the description.

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

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

The first sentence states a specific verb set (pin/unpin/dock) and the resource (a window), with 'decorate' framing the scope. It clearly differentiates from siblings like focus_window and desktop_state by describing window decoration rather than querying or focusing.

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 'Prefer:' block explicitly routes between actions: use 'dock' for terminal/CLI auto-positioning at session start, 'pin' alone when only always-on-top is needed. It also names the prerequisite workaround — bring hidden/minimized-on-other-desktop windows back with focus_window first — which is an explicit 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?

With no annotations, the description carries the full burden and does so: polling every 200ms up to waitMs, waitMs:0 semantics, minimized/<50x50 windows excluded, the title-change fallback that may report the wrong app, and pid possibly differing from the launched process. This is unusually rich behavioral disclosure for a mutation/launch 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-loaded with Purpose, then Details, Prefer, Caveats and Examples — every section is labeled and scannable. It is long and carries a minor redundancy (the foundWindow/windowTitle legacy note), keeping it just short of a 5.

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

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

There is no output schema, so the description must explain the return value, and it enumerates every field ({launched, args, windowTitle, hwnd, pid, region, foundWindow}), states when window fields are null, and mentions the explanatory hint. Nothing an agent needs to call or interpret this correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: waitMs default 2000 / max 30000 / 0 returns immediately, and that well-known names and App Paths entries resolve to a full path. The args shell-metacharacter restriction is only in the schema, not elaborated on here.

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 application and wait for its window to appear') plus the exact return payload (title, HWND, PID). It differentiates itself from siblings by naming run_macro combos it replaces and the desktop_discover/focus_window follow-ups.

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 'Prefer' section says to use this instead of run_macro({exec, sleep, desktop_discover}) and to follow with desktop_discover({target:{hwnd}}). Caveats add a when-not condition: single-instance apps that reuse a window should be checked with desktop_discover 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?

No annotations are provided, so the description carries the full burden. It discloses important behavioral traits: parallel execution, resetting the diffMode buffer, side effects on diff baseline and identity tracker. It also warns about thumbnail scaling and recommends tracking the reset point. This is thorough and 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?

The description is well-structured with headings (Purpose, Details, Prefer, Caveats) and each section adds value. However, it is somewhat verbose, especially the caveat referencing ADR-010. It could be slightly more concise without losing information, but it remains 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 has 3 parameters, no output schema, and no annotations, the description is remarkably complete. It explains what is returned, side effects, usage patterns, and caveats. It fully equips the agent to use 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 description coverage is 100% (all three parameters have descriptions in the input schema). The description does not add significant new meaning beyond the schema; it references 'includeUiSummary' indirectly and mentions thumbnail dimensions, but the schema already covers these. 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 the tool's purpose: 'Orient fully in one call' and enumerates what it returns (display layouts, thumbnails, actionable element lists). It is a specific verb+resource combination and distinguishes from sibling tools like screenshot and screenshot variants.

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 usage guidance: 'Use at session start or after major workspace changes.' It also offers alternatives: 'Use screenshot(detail='meta') for cheap re-orientation' and 'screenshot(detail='text', windowTitle=X) for a single-window update.' This helps the agent decide when to use this tool versus others.

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