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 it does so richly: it discloses the ambiguity/no-actionable-target/modal-blocking stop codes, the ancestor-climb depth and occlusion hit-testing, the auto-guard behavior for tabId+port, and the precise verifyDelivery semantics including why activeElementChanged is deliberately not a delivery signal. This is far beyond what any annotation could 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 purpose and targeting modes are correctly front-loaded, and the error-code content earns its place, but the description is heavily overloaded — the BrowserClickNotDelivered reserved-note, the CDP '2 values only' aside, and cross-tool hwnd/UIA commentary add length without helping an agent call this tool. Several clauses duplicate schema text verbatim.

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

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

With no output schema, the description assumes responsibility for return-shape disclosure and does it thoroughly: post.perception.status, hints.verifyDelivery with its status enum and reason values, and the observedSignals fields. For a 13-parameter mutation tool with zero annotations, nothing an agent needs to invoke it correctly or interpret the result is missing.

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

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

Schema description coverage is 100%, so the schema already documents all 13 parameters, and much of the description's parameter content (by-axis behavior, ancestor climb) merely restates the schema text. It adds some value by tying parameters together (role as an AND-filter, scope as narrowing, the one-of selector/by constraint) but does not introduce syntax or formats the schema lacks. 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?

States a specific verb+resource ('Click a DOM element in Chrome/Edge') and immediately disambiguates against siblings by naming browser_locate and mouse_click and explaining how selector mode combines them. An agent can distinguish this from click_element, mouse_click, and browser_locate 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?

Spells out the two targeting modes and when each applies ('stable across repaints' vs 'dynamic-class SPAs'), the mutual-exclusion rule ('Provide EITHER selector OR by+pattern (not both)'), the modal-blocking fallback (dismiss then retry), and the out-of-viewport workaround via browser_eval. These are explicit when/when-not conditions with named 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 carries the full burden and discharges it: circular-ref serialization, controlled-input restrictions, strict readyState checking, and two typed errors (BrowserNotConnected, AutoGuardBlocked) with their recovery paths. It also notes the ~15s CDP eval bound and that polling loops belong in wait_until.

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?

Labeled sections (Purpose / Details / Prefer / Caveats / Examples) are well front-loaded and skimmable. The Examples block re-states call shapes already implied by the schema, which is mild redundancy, but overall every section contributes.

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

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

For a 12-parameter, no-annotation, no-output-schema tool this covers actions, error taxonomy, alternatives, and caveats thoroughly. The one gap is that return shapes per action are shown only by example rather than described, though withPerception and includeContext hints partially bridge it.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real value: it ties parameters to actions (selector/maxLength belong to 'dom', selectors to 'appState'), explains withPerception's {ok, result, post} wrapping, and notes that per-action required fields are enforced at call time despite the flat schema. That last point is a genuine clarification of a schema quirk.

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 ('Inspect or operate on a browser tab') and immediately enumerates the three actions (js/dom/appState) with a one-line gloss of each. This distinguishes it from siblings like browser_navigate, browser_click, and browser_locate without opening a schema.

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

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

The 'Prefer' block gives explicit routing rules: appState before dom/js on SPAs, dom when appState is empty, js as the escape hatch, and keyboard/browser_fill instead of value-setting on controlled inputs. Alternatives and exclusions are stated, not implied.

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

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

With no annotations provided, the description carries the full burden and does so: it discloses ambiguity handling (stops with BrowserAmbiguousTarget plus candidates[]/next[] hints), non-fillable targets (BrowserNoActionableTarget), never guessing, the BrowserFillNotDelivered error, the controlled_input_transform false positive, masked-field behavior (valueWithheld:'masked'), and the CDP/browser_open requirement.

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 is front-loaded in the first clause and nearly every sentence carries non-redundant operational detail (errors, caveats, verification). It is a dense wall of nested parentheticals, though, and would scan better as bullets — the length is earned but the structure is heavy.

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

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

For an 11-parameter, no-annotation, no-output-schema mutation tool, the description supplies what the structured fields lack: error taxonomy, verification semantics, masking caveat, and prerequisite. Nothing an agent needs to invoke it 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 already 100%, so the baseline is 3; the description adds cross-parameter meaning by restating the selector-vs-by+pattern mutual exclusion and explaining what the by-axis resolution does to a match. It stops short of adding syntax or format detail beyond the schema's own enum and pattern documentation.

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

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

States a specific verb+resource ('Fill a form input with a value via CDP') and immediately scopes the capability to React/Vue/Svelte controlled inputs that reject JS value assignment. An agent can distinguish it from browser_eval, browser_click, and browser_form 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 names the alternative and the selecting condition: 'Use this over browser_eval when setting a controlled input's value via JS does not update framework state.' It also routes to browser_overview/browser_locate for selector discovery, states the EITHER selector OR by+pattern exclusivity, and notes the browser_open prerequisite.

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 delivers: masking semantics (value null, valueWithheld 'masked', hasValue), label resolution precedence (for[id] > ancestor LABEL > aria-labelledby > aria-label), hidden inputs excluded by default with an opt-in, and 200-char value truncation.

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 the action and return shape, then usage, then caveats — every sentence earns its place. It is long, but the length is justified by the return-field enumeration and required by the absence of an output 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?

For a 7-parameter read tool with no annotations and no output schema, the description fully covers what is returned, the masking/truncation edge cases, the dependency, and the workflow position. Nothing needed to invoke it 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; the description nonetheless adds value beyond the schema by explaining the masking fields and truncation behavior tied to the value output, plus the rationale for includeHidden. It does not extend the meaning of port, tabId, include, or maxResults.

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 (inspect) and resource (form fields: input, select, textarea, button) scoped to a CSS-selector container, and enumerates the returned attributes. An agent can distinguish it from browser_fill, browser_locate, or browser_search without opening the schema.

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

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

Explicitly says to use it before browser_fill to discover exact field selectors and to avoid targeting the wrong input (naming a concrete failure mode, a global search bar). It also states the hard prerequisite (browser_open / CDP active).

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 well: it discloses the staleness caveat (coords captured at call time, may go stale after reflow), the prerequisite (call browser_open on BrowserNotConnected), and two typed error codes with recovery paths. This is exactly the behavioral context a caller needs.

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

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

Front-loaded with purpose and output, then alternatives, then caveats, then error codes. Every sentence carries actionable information; no filler.

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

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

With no output schema and no annotations, the description still covers return shape (screen coordinates usable by mouse_click), prerequisites, failure modes, and recovery steps. Nothing needed to invoke it correctly is missing.

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

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

Schema description coverage is 100% and the schema already documents all five parameters thoroughly (port default, tabId sourcing, include envelope/raw semantics, includeContext token-saving). The description adds no parameter-level detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource ('Find a DOM element by CSS selector') plus the exact output ('physical screen coordinates'). It also names the sibling relationships (compatible with mouse_click), so an agent can distinguish it from browser_click and browser_eval without opening schemas.

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

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

Explicitly routes to alternatives: 'Prefer browser_click to find+click in one step' and 'Prefer browser_overview to discover selectors.' Both the general case and the discovery case are covered, with the selecting condition stated.

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

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

With no annotations the description carries the full behavioral burden, and it does disclose a lot: auto-guard behavior, a typed error taxonomy (NavigateFailed, BrowserNotConnected, AutoGuardBlocked), and the guard's recommended next step. However, the headline caveat 'Does not block until page load completes' conflicts with the schema's waitForLoad default of true, which does block on readyState 'complete' — the description appears to describe only the waitForLoad:false path. That stale claim can push an agent into redundant wait_until polling, a real transparency defect rather than a mere omission.

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

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

It is front-loaded correctly (verb/resource first, then caveats, then errors), but it is dense and several clauses do not earn their place: the parenthetical about frameStoppedLoading / loaderId being 'internal' adds no actionable guidance, and 'lensId is optional for advanced pinned-tab workflows' is undefined shorthand. The error taxonomy is worth its length, but the stale non-blocking caveat consumes space while actively misinforming.

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

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

For an 8-parameter tool with no annotations and no output schema, the description is unusually complete: it names the returned field (post.perception.status), enumerates failure modes with recovery steps, and warns about the auto-guard. The main remaining gap is that it never explains the default (waitForLoad=true) behavior, leaving the sync/async contract ambiguous against the contradicting caveat.

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 baseline is 3, but the description adds meaning the schema does not: tabId+port together trigger the server-side auto-guard (readyState verification) and post.perception.status is returned on success. That auto-guard semantics is genuinely new information rather than a restatement of the parameter docs.

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 clause names a specific verb and resource ('Navigate a browser tab to a URL via CDP Page.navigate') and immediately positions it against an alternative ('more reliable than clicking the address bar'). An agent can separate it from browser_open, browser_click, and browser_eval without opening any schema. The CDP mechanism and the tab-scoped nature are both stated up front.

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

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

It gives concrete sequencing guidance (follow with wait_until({condition:'ready_state'}) or browser_eval polling for slow pages) and routes the BrowserNotConnected case to browser_open for re-attach. It also explains what tabId+port and lensId are for in practice. It stops short of an explicit 'use this instead of X / do not use when Y' comparison against siblings such as browser_open or browser_click.

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

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

No annotations exist, so the description carries the full burden and does so: it discloses the per-process CDP lifetime, that restarts invalidate tab IDs, that a non-debug session cannot be taken over, idempotency of launch, and the concrete failure codes (BrowserNotConnected vs ToolError) with recovery steps. This is behavior far beyond what the schema declares.

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

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

Purpose and prerequisite are front-loaded in the first sentence, and the caveat/error material is grouped at the end. It is dense and somewhat long, and portions of the launch-idempotency wording repeat the schema, but the length is largely justified by the missing annotations.

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 supplies the return shape (tabs[] with id/url/title/active), the failure shape (ok:false with code), and the lifecycle caveats. An agent has everything needed to call this correctly and to recover from an unreachable endpoint.

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 structured fields already document port, launch sub-fields and include; baseline is 3. The description adds useful framing beyond that by explaining which launch mode is preferred when an endpoint is live and that omitting launch means pure connect, but it does not extend meaning much further than the schema already provides.

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

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

States a specific verb and resource ('Connect to Chrome/Edge running with --remote-debugging-port and return open tab IDs') and immediately distinguishes itself from siblings by declaring it is the prerequisite for all other browser_* tools. An agent can identify its role without opening the schema.

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

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

Explicitly states when to use it ('required before all other browser_* tools'), when to pass launch ({}) vs omit it (pure connect), and what to do in the failure path (re-call with launch:{} or start Chrome manually). The alternative-recovery guidance is unusually complete.

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: it discloses that selectors are CDP snapshots needing re-call after navigation, that input text is the field name and never the typed value, that the modal section is always present and drawers are not modals, that a non-matching scope silently falls back to the full document, and the typed error BrowserNotConnected with its remedy.

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

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

Purpose is front-loaded and every sentence carries operational information (alternative routing, caveats, error handling). It is a dense single-paragraph wall of text that would scan better with structure, but there is little filler to remove.

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 8 parameters, the description compensates by describing return content in detail: per-element CSS selectors, text, viewport status, ARIA state, and the always-present modal section with isModal, blocker, and the signals it was judged on. Nothing needed to call it correctly appears 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 semantic value on top: it explains scope limits enumeration to a CSS subsection and warns that a non-matching scope selector silently falls back to the full document rather than erroring. It does not add much on port, tabId, maxResults, or include beyond the schema.

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

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

States a specific verb and resource ('List all interactive elements... on the current page') and enumerates the returned fields (CSS selectors, visible text, viewport status, ARIA state). It directly distinguishes itself from siblings by naming browser_click, screenshot, browser_form, and browser_eval as different tools for different jobs.

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 is given ('use before browser_click to discover stable selectors') plus a named alternative and the condition that selects it ('prefer this over screenshot when verifying button/toggle state after submission'). It also routes value-reads to browser_form and scope-verification to browser_eval.

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 result ordering ('sorted by confidence descending'), the chaining contract ('pass results[0].selector to browser_click'), pagination behavior, and a catalog of typed error codes with remediation. This is behavior an agent could not infer from the schema alone.

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

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

Front-loaded with the core purpose and the distinguishing sibling comparison, then moves to output shape, pagination, and error handling. It is dense and mostly earns its length, though the error-code enumeration is long enough to risk burying the primary usage rule.

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 characterize the return value — and it does ('results[] sorted by confidence descending', results[0].selector). For an 11-parameter tool, it covers purpose, alternatives, chaining, pagination, and failure modes without leaving gaps.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds meaning beyond it — explaining the 'by' axes inline, the offset/maxResults pagination pair, and how results feed into browser_click. It does not add much detail on visibleOnly or caseSensitive beyond what the schema already 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: 'Grep-like element search across the current page', immediately conveying the operation and its scope. It explicitly positions itself against sibling browser_overview, so an agent can distinguish the two 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?

States the selection rule directly: 'Use browser_overview for broad discovery; use browser_search when you know specific text or role to target.' It also prescribes fallback behavior per error (broaden substring, relax regex, switch to browser_overview to enumerate selectors), giving explicit when-to-use and when-to-switch guidance.

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

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

No annotations are provided, so the description carries the full burden — and it does disclose meaningful behavior: auto-guarding on windowTitle (identity/foreground/modal), the perception envelope return, and typed error codes with recovery paths. However, it omits the return shape beyond post.perception.status and never states permission or side-effect profile beyond 'invoke', leaving some behavioral burden unmet for a no-annotation 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 and routing in the first two sentences, with caveats last. It is long, but nearly every clause is actionable (error codes, recovery choice, fallback), so little is filler.

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

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

With no output schema, the description compensates by describing the perception envelope and post.rich diff behavior, plus typed errors and recovery steps. For a 9-parameter invocation tool with no annotations, this is complete enough to call correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds genuine meaning beyond the schema: windowTitle triggers identity/foreground/modal guarding, fixId re-targets after window-identity drift, and lensId is scoped to advanced pinned-lens use. This is more than the raw schema conveys.

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 (invoke) and resource (UI element by name or automationId) with the mechanism (UIA InvokePattern) and the constraint (no screen coordinates). It explicitly distinguishes itself from mouse_click, so an agent can route between them without opening either schema.

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

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

Gives explicit when-to-use (buttons, menu items, links in native Windows apps) and when-not ('Prefer over mouse_click'), plus a workflow prerequisite ('Use desktop_discover first to discover automationIds') and a fallback rule for unsupported controls.

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 entire behavioral burden and does so thoroughly: byte-level (UTF-16LE) write verification, 4s/5s timeouts and why retrying is futile, indeterminate vs known-failed write states, distinct error codes, non-text payload behavior, and the backend-specific 12000-char fallback cap. This is exactly the context an agent needs to interpret results and avoid blind retries.

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 first two sentences are well front-loaded, but the body becomes a very long run-on covering diagnostics like sequenceAfterWrite, postCloseChecked, and inSessionReadable that are closer to release notes than call guidance. For a 2-action, 3-parameter tool this is over-sized even though most individual clauses are substantive.

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

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

No output schema exists, yet the description fully specifies return shapes, per-response fields (backend, postCloseChecked, sequenceAfterWrite), and error codes, plus caveats and recovery. Nothing an agent needs to call this correctly or interpret its result is missing.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds semantics the schema does not: what action='read' actually returns (empty string for non-text/oversize), that write replaces existing content, and that effective text limits differ by backend (12000 chars on powershell vs the schema's nominal 100000 maxLength). That extra meaning lifts it above baseline.

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

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

Opens with a specific verb+resource: 'Read or write the Windows clipboard,' then immediately disambiguates the two modes by their observable effect (read returns text, write replaces and verifies). An agent can distinguish this from the keyboard sibling purely from the description.

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 recovery routing — retry the write or fall back to keyboard(action='type', use_clipboard=false) for short text — and specifies when reads of oversize text are refused. It is strong on failure-path guidance, though it never states the general condition for preferring clipboard over other input methods in the first place.

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 declares the read-only safety profile, discloses relative cost, and details caveats (cannot detect non-UIA elements, hasModal is a title-based heuristic, includeDocument requires browser_open). The masked-field/value-absence discussion openly flags a security-relevant limitation rather than hiding 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?

Front-loaded with labeled sections (Purpose / Details / Prefer / Caveats) and leads with the core statement, so it is skimmable. It is nonetheless very long, and the extended masked-field passage is repetitive enough to dilute the section's value.

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

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

For a complex hub tool with no output schema and no annotations, the description fully compensates: it enumerates always-present and opt-in return fields, explains the Chromium/UIA perception paths and hints, and lists caveats. An agent has everything needed to call it and interpret results.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description adds meaning beyond the schema: it explains the cost of each include* flag ('each adds one syscall or CDP round-trip') and the fallback behavior for includeDocument. Most flag semantics are, however, repeated from the schema rather than extended.

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

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

States a specific verb+resource ('Read-only observation of the current desktop state') and enumerates the exact return surface (focusedWindow, focusedElement, cursorPos, hasModal, pageState, attention, visibleWindows). It also explicitly distinguishes itself from siblings: 'Does NOT enumerate descendants — use desktop_discover for actionable entity list and window list.'

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

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

'Prefer: Use after each action to confirm state. Cheapest observation tool — cheaper than any screenshot' gives explicit when-to-use guidance. It also names the alternative (desktop_discover) for enumeration and states when to set the include* flags ('only when you need the extra data'), covering when-not to use the optional paths.

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 delivers: prerequisites (HKCU AccessVBOM=1, VBAWarnings=1, registered Trusted Location, restart-after-CLI), the STA serialization caveat that long macros block subsequent excel() calls, the VbaMacroNotFound failure mode, and the UI-bypass behavior. This is unusually rich behavioral disclosure.

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

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

Front-loaded with 'Purpose:' followed by Details, Prefer, Caveats, and Examples — a predictable structure. It is dense and long, but nearly every line carries non-redundant information, so the length is justified rather than padding.

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

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

For a complex COM/VBA tool with no output schema, the description supplies enough: return-shape examples (trusted/scope, ok/workbookPath), preconditions, and failure modes. Nothing an agent needs to invoke it 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 baseline is 3, but the description adds real meaning: macroName must appear as `Sub <name>(...)` in code (else VbaMacroNotFound), and the three worked examples show how action/code/macroName/visible combine. The cross-parameter constraint between code and macroName is the key added 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?

States a specific verb and resource ('Author and run VBA macros against Excel via COM late binding') and clearly enumerates the two actions, run_vba and check_access_vbom. It differentiates against an external product ('Claude for Excel') but never distinguishes from the sibling tool run_macro, which an agent must otherwise infer is different.

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

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

Gives an explicit ordering rule — run check_access_vbom first when a workflow depends on macro execution — and explains the remediation motivation. It stops short of stating when NOT to use this tool versus siblings like run_macro, so exclusion guidance is missing.

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

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

No annotations exist, so the description carries the full burden and does so thoroughly: it discloses silent CDP skipping and where to check (response.hints.warnings), the WindowNotFound error and desktop_discover recovery, focus-stealing caveats, and the Win11 foreground refusal contract (code:'ForegroundRestricted' ok:false instead of silent success).

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

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

Front-loaded with the core verb+resource before any caveats, and nearly every sentence adds operational value. It is dense and long, bordering on caveat overload for a single tool, which keeps it out of the top band.

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 still covers error codes, silent-skip semantics, recovery paths, and caveats an agent needs to call this correctly. Nothing material 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: chromeTabUrlContains activation semantics and why only the active tab's title is visible, plus forceFocus's auto-escalation behavior on Win11. It slightly exceeds what the schema already documents.

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

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

States a specific verb+resource and matching semantics (foreground a window by case-insensitive partial title). Explicitly contrasts with sibling tools: browser_* target by tabId/selector, not windowTitle, and it names desktop_act/click_element as foreground-free 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?

Gives explicit when-to-use conditions ('when a tool does not accept a windowTitle param', 'before a sequence of actions') plus a pre-condition for the Chrome tab path. Also names concrete alternatives and their selection criteria (UIA InvokePattern, keyboard BG path for terminals only).

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 behavioral burden and does so extensively: blocked key combos, IME composition behavior, background versus foreground routing, focus-leash abort behavior, atomic sequence locking, destructive side effects like clipboard replacement, and specific error codes. This is far beyond what structured fields 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 front-loaded with purpose, action modes, required destination, and alternatives, then follows with caveats and examples. It is dense and very long, but the complexity of the tool and the absence of annotations justify most of the detail; some schema-level repetition could be trimmed.

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

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

Given 19 parameters, no annotations, no output schema, and a complex windowing/input domain, the description is remarkably complete. It explains destination requirements, failure modes, recovery context, IME handling, focus behavior, and action-specific verification limits, leaving little an agent would need to infer.

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 meaningful semantics beyond the schema by explaining action-specific required fields, when windowTitle versus hwnd matters, why '@active' is special, and how method routing interacts with each action. It does not need to re-document every parameter, but it usefully frames their behavior.

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

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

The description names the specific verb ('Send keyboard input') and resource ('to a window'), then immediately distinguishes the three action modes type, press, and sequence. It also routes the agent away from sibling tools by referencing desktop_act({action:'setValue'}) and click_element where appropriate, so the tool's identity is 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 gives explicit when-to-use guidance for each action mode: type for text, press for key combos, sequence for atomic multi-step menu navigation. It also names alternatives for specialized cases, such as desktop_act for UIA ValuePattern fields, use_clipboard for IME-safe text, and click_element for non-terminal foreground refusal.

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: secrets are never shown to the assistant or sent to the tool, stored via Windows DPAPI for the current user, first save triggers a one-time consent confirmation, enabling grants autofill AND pane-launch capability, disabling via DESKTOP_TOUCH_DISABLE_KEY_LOCKER=1, Windows-only, and ssh saves need the host key already in known_hosts.

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?

Long, but organized into Purpose/Details/Prefer/Caveats/Examples with the scoping and safety constraint front-loaded and worked examples at the end. Dense for a single description, though nearly every clause maps to a real invocation decision, so little is expendable.

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

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

No output schema exists, yet the description supplies per-action return shapes and worked call/response examples (including the paneId flow into terminal), covering consent state, bindingCount, and captured/paneId returns. For a 9-parameter, seven-action tool this is complete enough to invoke correctly.

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

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

Schema description coverage is 100% (baseline 3), but the description adds real meaning: it explains per-action required fields ('enforced at call time (see the tool description); this flat schema lists every action's fields as optional'), ties paneId to launch_console output, and warns never to put a secret in `reason`.

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

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

States a specific verb+resource ('Manage credentials the terminal autofills for you') and enumerates each action's effect (save pre-seeds a binding, list shows metadata, forget deletes, fill_once types once). It clearly distinguishes itself from the terminal and browser_fill siblings by scoping to SSH/sudo/login credential prompts in a locker-owned pane.

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 gives explicit routing: autofill is automatic for bound commands, fill_once is for prompts autofill can't handle (nested ssh, unsaved logins), and it names the sibling call to compose with ('then run the ssh / sudo command with terminal({action:'run'|'send', paneId})'). It also states the hard precondition that only launch_console panes can be filled.

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 richly: auto-guarding semantics, post.perception.status values, hints.verifyDelivery status derivation from three signals, ForegroundRestricted recovery path, WindowOnOtherDesktop non-action, and the deliberate suppression of a MouseClickNotDelivered typed code. This is far more behavioral context than any structured field 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?

Front-loaded with the core action and the primary guidance, and nearly every sentence carries information (errors, recovery, verification). However it is a single dense block with many interleaved caveats, which taxes scanability for a click 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?

For a 21-parameter, enum-heavy tool with nested objects and no output schema, the description covers error codes, recovery alternatives, verification signalling, and guard behavior. An agent has everything needed to call it correctly and interpret failures.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds cross-parameter meaning the schema states only in isolation: origin+scale are meaningful ONLY with dotByDot=true responses and are converted to screen coords before guarding, and fixId is a one-shot 15s approval token. It adds real semantics beyond per-parameter docs.

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 distinguishes itself from siblings by naming click_element (UIA native apps) and browser_click (Chrome) as preferred alternatives in their domains. An agent can place this tool vs. its neighbors without opening any schema.

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

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

Explicit when-to-use rules: normally pass windowTitle so the click is guarded, omit lensId for normal use, use doubleClick/tripleClick flags for multi-clicks. It even names the exclusions (prefer click_element for native apps, browser_click for Chrome) and gives concrete guarded vs. unguarded examples.

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: left-button-only, both endpoints guarded, cross-window/desktop blocked by default, tab-strip drags blocked, plus specific error codes (CrossWindowDragBlocked, TabDragBlocked, ForegroundRestricted, WindowOnOtherDesktop) and the verifyDelivery status semantics. It also discloses that a window on another virtual desktop sends nothing rather than switching desktops.

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

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

Front-loaded with the core action, endpoint semantics, and use cases before diving into caveats, which is the right order. It is dense but most sentences earn their place; the niche 'MouseDragNotDelivered is SUGGESTS-registered but reserved-only' aside is the main place where trimming would help.

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

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

No output schema exists, so the description must carry return semantics, and it covers them: post.perception, hints.verifyDelivery statuses, and the error-code taxonomy for blocked or refused drags. It is nearly complete for a 14-parameter mutation tool, with only minor gaps around the untouched params.

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%, and the description adds genuine meaning beyond the schema for several parameters: windowTitle 'auto-guards the start coordinate and returns post.perception', lensId is scoped as advanced-only, and the two guard flags are framed by intent. It leaves some params (speed, homing, include, narrate, hwnd) entirely to the schema, so it does not fully compensate.

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

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

States a specific verb+resource with both endpoints ('Click and drag from (startX, startY) to (endX, endY)') and enumerates concrete use cases (sliders, drag-and-drop, canvas drawing, window resizing). It implicitly and explicitly distinguishes itself from the sibling mouse_click by referencing the shared verifyDelivery shape and by its distinct drag semantics.

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

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

Gives clear when-to-use context via the use-case list and a worked example, plus explicit conditions for the advanced flags (pass allowCrossWindowDrag:true to confirm cross-window intent; allowTabDrag:true for tearing off tabs). It does not, however, explicitly route the agent to mouse_click or scroll as alternatives, so it stops short of full when-not guidance.

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

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

With no annotations present, the description carries the full burden and does so richly: it discloses that user-visible delivery is fundamentally unobservable, that Focus Assist / notifications-off / consent-UI suppression cannot be detected from the tool, and that every successful response includes hints.verifyDelivery with status="unverifiable", reason, and channel. This pre-empts the exact behavioral trap an agent would otherwise fall into.

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

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

Purpose and usage are correctly front-loaded, but the caveat block mixes English with Japanese and cites opaque internal references ("matrix §3.1 line 158 規範整合"), which slows an English-language agent parsing the key constraint. The double-quoted JSON literal detail is useful but the surrounding prose is dense and non-uniform in language.

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 or annotations exist, and the description compensates by specifying the shape of the delivery-verification hint on success. Parameters are fully covered by the schema. It stops short of 5 because the include/envelope return-shape options are left entirely to the schema and no failure-mode behavior is described.

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 title, body, and include are already documented with constraints (maxLength 200/500) and the envelope/raw opt-in semantics. The description adds no parameter-level meaning, so the baseline 3 applies.

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

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

States a specific verb ("Show") and resource ("a Windows system tray balloon notification") with the mechanism named (System.Windows.Forms). An agent can identify the capability immediately, and no sibling tool overlaps with desktop notification delivery.

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 trigger: "Use at the end of a long-running task so the user knows it finished without watching the screen." It also advises the caller to indirectly observe delivery via wait_until(focus_changes), which is actionable routing. It lacks an explicit when-not, so it falls short of 5.

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

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

No annotations are provided, so the description carries the full burden and does so well: it discloses the max 50 steps, stop_on_error default, 10000ms sleep cap, that intermediate results cannot be inspected mid-run, the token cost of embedded screenshots, and which sibling tools are never valid steps. It does not describe the success/failure return shape (e.g. per-step error reporting), which is the main remaining gap for a tool with no output 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?

Long but well-front-loaded with Purpose/Details/Prefer/Caveats/Examples labels, and the two worked examples remove ambiguity. There is minor redundancy — the config-dependent tool pairs are explained twice — and the volume exceeds what most agents need, but almost every sentence carries specific operational guidance.

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 batch-execution tool with no annotations and no output schema, the description covers all decision-critical constraints an agent needs: valid step set, step limits, error-handling behavior, latency/cost implications, and when to avoid it. Nothing required to invoke it 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 genuine meaning beyond the schema: the special 'sleep' pseudo-step with its max duration, the config-dependent validity of desktop_discover/desktop_act vs get_windows/get_ui_elements/set_element_value, and the note that the tool field's own description is authoritative for the dispatched set. The include parameter is left to the schema.

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

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

States a specific verb and resource ('Execute multiple tools sequentially in one MCP call') and immediately names the benefit and its distinguishing scope versus any single sibling tool. An agent can tell this is the macro/batch aggregator, not one of the ~30 individual action 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 'Prefer' section names the use case (predictable fixed sequences like focus → sleep → type → screenshot) and the explicit exclusion (do not use for conditional logic — return to the LLM between branches). It also advises splitting the macro where a step may fail conditionally, giving a concrete when-not rule.

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 disclosure burden, and it does so extensively: scaling formula caveat (maxDimension=768 means pixels != screen pixels), diffMode requiring a prior baseline or returning a full frame cold, background mode requiring windowTitle/hwnd and only composing with {image, meta}, ocr cold-start ~1s plus language pack requirement, and confirmImage not needed for background mode. This is well beyond what annotations would supply.

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

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

It is long, but that length is justified by 19 parameters and five detail modes. The Purpose/Details/Prefer/Caveats/Examples structure is front-loaded and scannable, and each section earns its place. There is minor duplication with the already-exhaustive schema descriptions, 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?

With no output schema and no annotations, the description must explain return shapes, and it does: meta returns titles+positions, text returns UIA elements with clickAt, som/ocr return elements plus by-ref resource_link, and confirmImage controls inlining. Combined with the caveat coverage of mode/detail compatibility, an agent has enough to call this complex 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%, so the schema already documents each parameter, making 3 the baseline. The description nevertheless adds cross-parameter meaning the schema does not: worked examples, the grayscale/dotByDotMaxDimension/windowTitle+region reduction recipes, and the screen-coordinate computation with origin and scale. That is genuine value over the per-parameter text.

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

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

The opening sentence names a specific verb (Capture) and its resource scope (desktop, window, region) and enumerates the orthogonal axes it operates on (detail levels, capture modes). It separates itself from siblings directly by routing Chrome work to browser_* and element discovery to desktop_discover. An agent can tell what this tool does and does not do 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?

The 'Prefer:' block gives explicit when-to-use rules: meta to orient, text before clicking, som for UIA-blind native apps/games, ocr to force OCR unconditionally, background when the window must stay hidden, diffMode after actions to confirm state, and browser_* for Chrome. Exclusions and alternatives are stated rather than implied.

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

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

With no annotations supplied, the description carries the full behavioral burden and discharges it: it discloses the destructive safety gate (dual-flag), what a dry run returns (candidate captures plus orphan count/size), that includeOrphans reclaims files with no index entry, that the newest capture survives count/byte caps, and the hard scope guarantee that only files inside the screenshot cache are ever touched.

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

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

Dense but well front-loaded: the default-safe dry run and the deletion gate come first, then retention caps, then scoping. It repeats the dryRun/confirm pairing and re-explains orphan reclaiming that the schema also covers, so a little trimming is possible.

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

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

For an 8-parameter, annotation-free mutation tool with no output schema, this is close to complete: deletion semantics, safety gating, defaults, scoping, and even the dry-run return shape are all covered. Only permission/auth requirements are left 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 already 100%, so the baseline is 3, but the description adds genuine meaning beyond the schema: the concrete env defaults (newest 200 / 256 MiB) applied when no caps are given, the interplay of dryRun and confirm, and that maxAgeMs can clear even the newest capture. It does not explain the `include` response-shape parameter at all.

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 and resource: 'Reclaim disk space from cached screenshots by retention policy.' It is unmistakably distinct from the read-oriented siblings (screenshot, screenshot_query) and the browser_* family, and the retention-policy scope further narrows what it does.

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

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

Gives explicit when/when-not rules: the call is a dry run by DEFAULT and deletes nothing, and real deletion requires BOTH dryRun:false AND confirm:true. It also states the fallback behavior when no retention caps are passed (env defaults of newest 200 / 256 MiB) and the tag-scoping 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 delivers: the by-ref link return convention (screenshot://by-ref/{captureId}), the fact that reading bytes costs tokens, newest-first ordering, whole-cache totals in the response, and that results never include a filesystem path. It does not cover auth/rate limits, but the behavioral profile is unusually complete.

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

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

Front-loaded with the core purpose, then the response shape, then filtering/paging, then the ordering guarantee. Dense with many parentheticals, but each sentence carries information an agent needs. Slightly overpacked but not wasteful.

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

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

No output schema exists, so the description compensates by enumerating the returned fields (captureId + by-ref uri, dimensions, size in bytes, timestamp, tag/window) and the totals (totalCaptures/totalBytes), plus ordering. Nothing an agent needs to call 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 baseline is 3. The description adds real meaning beyond the schema: it groups the filters (tag/windowUuid/since/until), states the paging defaults (limit default 50, offset), and clarifies that results are newest-first and offset skips 'from the newest end', which disambiguates the offset direction the schema leaves implicit.

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

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

States a specific verb and resource ('List screenshots already saved in the disk-cache') and sharpens it with a distinguishing constraint ('WITHOUT re-reading any pixels'). It also implicitly separates this from sibling `screenshot` (which captures) and names `screenshot_gc` as the space-reclaim alternative, so an agent can tell the tools apart without opening schemas.

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

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

Explicitly gives the two motivating use cases ('find and re-open a specific earlier capture, or check how much the cache holds before reclaiming space with screenshot_gc') and names the alternative tool for space reclamation. It also adds an exclusion-style warning: open a by-ref link only when you actually need the pixels.

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 delivers strongly: it discloses typed errors, OCR imperfection, pixel-coordinate mismatch after downscaling, visibility/UIA/CDP prerequisites, boundary-success semantics, per-action caveats, and ADR-backed verification hints. This is unusually complete behavioral disclosure for a tool with zero structured safety information.

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 with Purpose, then Details, Prefer, Caveats, and Examples. Its length is justified by five actions and 32 parameters, and each section helps an agent select or correctly invoke the tool rather than padding the text.

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

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

For a 32-parameter, five-action tool with no annotations and no output schema, the description supplies routing guidance, action behavior, error recovery, caveats, and examples that cover what an agent needs to call it correctly. Return-shape details are partial but sufficient given the action-specific outputs described.

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 meaningful action-level semantics and examples beyond the flat schema, especially by defining what each action does and implying per-action required fields. However, much parameter detail still lives in the schema, and some amount-scale language is duplicated rather than adding new meaning.

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 ('Scroll a window or page') and immediately enumerates five distinct action strategies, making it easy to distinguish from sibling browser_* and desktop_* tools. The agent can tell what the tool does and which strategy family applies 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?

The 'Prefer:' block gives explicit routing: use to_element/smart for out-of-viewport click recovery, capture for reading long pages as images, read for OCR text extraction where copy-paste is unavailable, and raw for simple scrolling. It also names alternatives (focus_window, desktop_discover, browser_eval, browser_overview) and the conditions that select them.

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

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

With no annotations, the description carries the full burden, and it does so substantially: it discloses that engine values are stable for the process lifetime while nativeUiaEvidence and health change per call, that health counters reset in a new process, and that the tool is a diagnostic read. It stops short of stating the safety profile (no side effects / auth) explicitly, keeping it from a 5.

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

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

The purpose is front-loaded in one short sentence, but the remaining ~300 words are an unstructured run-on dumping every internal field's semantics, including details the description itself says not to surface unless asked. Sized and structured poorly for tool selection, even if the individual facts are accurate.

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 high-complexity diagnostic tool with no output schema, the description exhaustively documents the returned fields (engine, nativeUia/nativeUiaEvidence, imageDiff, health) and their stability semantics, so an agent can interpret the response. The only real omission is the `include` response-shape option, which is covered in the schema.

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

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

The schema has 100% description coverage for the single `include` parameter (envelope vs raw shape), so the schema already does the heavy lifting. The description never mentions `include` or the envelope/raw response-shape choice, adding nothing beyond the baseline.

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

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

The first sentence gives a specific verb+resource ('Return MCP server status') that an agent can act on immediately. It is clearly distinguishable from the action-oriented siblings (browser_*, click_element, etc.) by being diagnostic in nature, though the description never explicitly says so. The purpose is clear but buried under heavy field-level detail.

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 offers scattered timing guidance ('read it after the act it should cover') and output guidance ('do not surface unless the user asks about performance/troubleshooting'), which is useful. However, it never states when to call server_status versus the sibling tools or what question it answers, so invocation guidance is only implied.

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

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

With no annotations, the description carries the full burden and does so: it enumerates completion reasons (quiet | pattern_matched | exited | timeout | window_closed | window_not_found | send_failed), documents outputIntegrity:'baseline_lost' and the forced empty output plus readError.code, the FileLockCollision warning, clipboard replacement by preferClipboard, the Windows Terminal exclusion from the BG path, and the foreground-refusal/other-desktop failure modes. Side effects (clipboard replaced, foreground stolen) and auth/routing constraints are surfaced up front.

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 and cleanly sectioned with Purpose/Details/Prefer/Caveats/Examples, and the examples are useful. However, it is extremely dense and repeats material already carried by the 96%-coverage schema (paneId behavior is restated three times in the schema and again here, as is the clipboard-replacement caveat), so several sentences do not earn their place relative to structured fields.

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, yet the description documents the response surface directly — completion={reason, elapsedMs}, outputIntegrity, warnings, hints (verifyDelivery.unverifiable, hints.clipboard, hints.terminalMarker.previousMatched) — along with recovery actions for each. For a 25-parameter, three-mode, multi-failure-mode tool, nothing operationally necessary 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 96%, so the baseline is 3, but the description adds genuinely non-redundant semantics: it explains the paneId-vs-windowTitle precedence ('pass the paneId field, NOT windowTitle'), the deprecated `command` alias for `input`, and when to choose pattern vs exit mode. It stops short of a full walkthrough of secondary parameters (settleMs, chunkSize, focusFirst), which the schema already covers.

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 concrete verb+resource+scope: 'Interact with a terminal window: read output, send input, or run+wait+read in one call,' then splits the three action modes explicitly and notes that read/send absorb formerly-standalone tools. An agent can distinguish this from siblings like screenshot, keyboard, and window_dock without opening the schema.

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

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

Gives explicit routing: prefer action='run' for execution+result, switch to until:{mode:'pattern'} for long-running builds/test runners because quiet mode can complete prematurely, and use read/send only for fine-grained interleaving. It also names the alternative to avoid ('Do not screenshot the terminal — action='read' is cheaper and structured'), which is exactly the when-not guidance the dimension asks for.

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

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

With no annotations, the description carries the full burden and does so: it discloses the success shape ({ok, elapsedMs, observed}), the four error codes (WaitTimeout, ToolError, BrowserNotConnected, WindowExcluded) and how to branch on them, the CDP connection prerequisite, and that element_appears/value_changes spawn a UIA process per poll. It even warns that suggest[] may open with a poll-earned line and that the lastLook baseline can surface masked credentials.

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

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

Purpose/Details/Prefer/Caveats/Examples headers front-load the key information and the length is defensible for a nine-branch condition poller. Some caveat clauses are packed densely (the suggest-indexing and masked-value asides) and could be trimmed without losing call correctness.

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

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

No output schema and no annotations exist, yet the description still documents return values, timeout semantics, all failure codes, prerequisites, and per-condition target requirements. An agent has everything needed to select a condition, supply the right target fields, and handle 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% but the nested target object's fields carry no per-field descriptions in the schema, so the description's per-condition requirement mapping (which conditions need windowTitle, elementName, pattern, regex, by) is genuinely additive. It stops short of explaining by's role/ariaLabel values, port, tabId, or elementSelector, so a few nested fields remain unglossed.

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

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

States a specific verb+resource ('server-side poll for an observable condition') and immediately positions itself against the screenshot-polling pattern agents typically fall back on. The nine condition branches make the scope unambiguous, and an agent can tell it apart from run_macro/screenshot siblings without opening any schema.

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

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

Explicitly says 'Use instead of run_macro({sleep:N}) + screenshot loops' and then routes by scenario (terminal_output_contains for CLI completion, element_matches for DOM readiness, url_matches for SPA routing/redirect cascades). Both when-to-use and the named alternatives are present, so nothing is left to inference.

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

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

With no annotations, the description carries the full burden and does so richly: pin survives minimize/restore and requires explicit unpin, minimized windows are auto-restored before docking, hidden windows are skipped, dock fails on elevated processes, and dock overrides existing Win+Arrow snap. These are exactly the side effects 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?

Labeled sections (Purpose / Details / Prefer / Caveats / Examples) front-load the core purpose and keep each sentence earning its place. The three examples demonstrate distinct actions compactly.

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 mutation tool the coverage is strong: actions, defaults, and edge-case failure modes are all addressed. The only gap is that the response-shape opt-in (include/envelope) is left entirely to the schema.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds essential per-action semantics the flat schema omits — the schema itself defers 'per-action required fields' to the description, and the Details section maps action to behavior (dock defaults 480×360 bottom-right, pin:false to skip topmost). It stops short of covering the include/response-shape opt-in.

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 states a specific verb and resource ('Decorate a window: pin, unpin, or dock') and immediately disambiguates each action. It distinguishes itself from siblings by naming focus_window as the tool to use first for hidden windows, so an agent can route correctly without opening schemas.

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

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

The 'Prefer' block gives explicit when-to-use guidance: dock for terminal/CLI auto-positioning at session start, pin alone when only always-on-top is needed. It also names the alternative (focus_window) and the condition ('hidden one ... is not docked') 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 carries the full burden and delivers: polling cadence, null-window semantics, single-instance no-new-HWND behavior, minimized and <50x50 exclusion, the title-change fallback, and the fact that pid may differ from the launched process. This is exactly the behavioral context an agent needs.

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

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

Front-loaded with Purpose then Details, and organized under Prefer/Caveats/Examples headers so an agent can scan it. It is on the long side and the caveat list is dense, but nearly every sentence encodes a distinct behavior rather than padding.

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

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

Although there is no output schema, the description fully specifies the return object ({launched, args, windowTitle, hwnd, pid, region, foundWindow}) and notes the foundWindow/windowTitle alias and the 'hint' field. Nothing needed to call or interpret the result is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning beyond the schema: waitMs:0 returns immediately with null window fields, command resolves well-known names and App Paths entries to a full path, and localized titles are handled via HWND-based detection.

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 states a specific verb and resource—launch an application and wait for its window—and enumerates the return fields (title, HWND, PID). It clearly distinguishes itself from siblings like run_macro and desktop_discover by naming what it replaces.

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 the agent to use this instead of run_macro({exec, sleep, desktop_discover}) combos, and prescribes follow-up calls (desktop_discover with the returned hwnd, or focus_window). Both the condition and the alternatives are stated.

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

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

No annotations exist, so the description carries the full burden and does so well: it discloses internal parallelism, latency characteristics (≈ max single screenshot), scaled-not-1:1 thumbnails, and a significant side effect (resetting the screenshot diff baseline/identity tracker). It even flags that the reset isn't reflected in causal memory, which is rare and useful context.

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

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

Well front-loaded with labeled sections (Purpose, Details, Prefer, Caveats) that let an agent scan quickly. However, it is verbose and the diff-baseline reset is stated twice (once as 'resets the diffMode buffer', again as 'resets the screenshot diff baseline'), and jargon like 'ADR-010 §11 OQ carry-over' adds length without actionable value.

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

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

With no output schema, the description correctly explains the return shape (layouts, thumbnails, actionable element lists with coords) and covers the side effects and caveats an agent needs before calling. Nothing material is missing for a zero-required-parameter orientation tool.

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

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

Schema description coverage is 100%, so the three input parameters (include, includeUiSummary, thumbnailMaxDimension) are already fully documented in the schema. The description adds no input-parameter semantics beyond that; its detailed field talk (clickAt, actionable[]) describes response content, not inputs. Baseline 3 applies.

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

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

The opening line states a specific verb ('Orient fully') and enumerates exactly what is returned: display layouts, WebP thumbnails, and per-window actionable element lists with clickAt coords. It is clearly distinguishable from screenshot siblings by naming the alternatives (screenshot(detail='meta'), screenshot(detail='text')) and contrasting their scope.

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

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

Explicitly says when to use it ('session start or after major workspace changes') and routes each alternative case to the correct sibling tool ('screenshot(detail=meta)' for cheap re-orientation, 'screenshot(detail=text, windowTitle=X)' for a single window). This is textbook when/when-not/alternative guidance.

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