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

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

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

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

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

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

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

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

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

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

Although schema coverage is 100%, the description adds substantial meaning beyond parameter names: selector vs. by-axis exclusivity, role as an AND-filter, scope narrowing, tabId+port auto-guards, lensId purpose, scrollIntoView workflow implications, and include/narrate envelope behavior. This is far more than a restatement of the schema.

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

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

The description opens with 'Click a DOM element in Chrome/Edge' and immediately defines two distinct targeting modes (selector and by-axis), explicitly referencing siblings browser_locate and mouse_click. This gives a specific verb, resource, and clear differentiation from related tools.

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

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

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

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

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

Since no annotations are provided, the description fully discloses behaviors: actions, truncation, withPerception wrapping, readyState checks, error codes (BrowserNotConnected, AutoGuardBlocked), serialization limitations, and execution timeout. No contradictions.

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

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

The description is well-structured with clear sections (Purpose, Details, Prefer, Caveats, Examples) and front-loads the purpose. It is slightly verbose but every sentence adds value.

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

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

Given the complexity (12 parameters, 3 actions), the description covers all aspects, including return structures, error types, and recommended usage patterns. Examples illustrate typical calls. No output schema exists, but the description adequately hints at return shapes.

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

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

Schema coverage is 100%, but the description adds significant context beyond the schema, such as the purpose of each action, the effect of withPerception, and the use of selectors for appState. It provides examples that clarify parameter usage.

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

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

The description clearly states the tool's purpose: 'Inspect or operate on a browser tab via 3 actions'. It specifies each action (js, dom, appState) and differentiates from sibling tools by focusing on evaluation/scripting rather than navigation, clicks, etc.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value beyond the schema by explaining the semantics of includeHidden (why default false: to avoid CSRF-token clutter), the output shape (masking details), and the container concept for selector. However, it does not elaborate on port, tabId, or include's envelope behavior, though those are already well described in the schema. The added context justifies a 4.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

No output schema, but description states return of physical screen coordinates. More detail on return format (e.g., object with x,y) would improve completeness, but error types and compatibility hints are good.

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

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

Schema description coverage is 100%, baseline 3. Description adds little beyond schema for parameters, but mentions coordinate compatibility with mouse_click, which is helpful context.

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

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

Description clearly states action (find DOM element) and output (physical screen coordinates), explicitly distinguishing from sibling tools browser_click and browser_overview.

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

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

Explicitly suggests using browser_click for find+click in one step and browser_overview to discover selectors. Also includes caveat about stale coordinates after page reflow.

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

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

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

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

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

The description is front-loaded and information-dense, with a clear caveat label and a structured error taxonomy. It is slightly overstuffed—repeated wait_until advice and internal CDP jargon (frameStoppedLoading/loaderId) could be trimmed—but overall every sentence earns its place.

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

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

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

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

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

Schema coverage is 100%, so the baseline is 3. The description adds useful context for tabId/port (auto-guard) and lensId (pinned-tab workflows), but it does not compensate for the waitForLoad inconsistency nor add semantics for include/narrate beyond what the schema already describes.

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

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

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

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

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

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

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

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

Despite no annotations, the description fully discloses behavior: returns tabs array with specific fields, idempotent launch, error codes, killExisting warning data loss, and CDP connection per-process. No contradictions.

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

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

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

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

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

Covers all necessary aspects: prerequisite, input/output, errors, edge cases (browser restart, existing session, unreachable endpoint). References sibling tools. Complete for a setup tool with no output schema.

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

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

Schema already describes all parameters, but description adds context: explains launch parameter purpose, default behavior, example usage, and caveats for killExisting. Adds value beyond schema.

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

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

The description clearly states the tool connects to a debug-mode browser and returns open tab IDs, and it distinguishes from siblings by being the prerequisite for all other browser_* tools.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Schema coverage is 100%, so the baseline is 3. The description adds materially beyond the schema by explaining the non-matching scope selector behavior (silent fallback to the full document) and by clarifying input-text semantics as they relate to output. Most other parameter details are already well-documented in the schema, so the added value is meaningful but not exhaustive.

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

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

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

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

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

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

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

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

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

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

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

Compact and well-structured: purpose, axes, result usage, pagination, caveats, then error codes. Every sentence serves a purpose with no redundancy.

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

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

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

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

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

Schema coverage is 100%, baseline 3. Description adds value beyond schema by explaining search axes with examples (literal substring, CSS), result chaining, and parameter adjustments implied in error codes (e.g., 'broaden the by:text substring').

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

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

The description clearly states this is a 'Grep-like element search' with specific axes (text, regex, role, ariaLabel, selector) and explains result usage ('pass results[0].selector to browser_click'). It distinguishes from sibling browser_overview for broad discovery.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value beyond schema by explaining the intent of fixId ('re-target after window identity drift') and lensId ('advanced pinned-lens use'), and mentions that include and narrate affect response shape. While the schema already documents each parameter, these contextual clarifications improve agent comprehension.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Schema coverage is 100%, but the description adds critical semantics beyond it: the exact meaning of each action, the 8MB read limit, 12000-char fallback limit, and the delivery-verification process. It also explains the 'include' parameter's effect indirectly through response shape context, though not named.

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

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

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

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

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

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

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

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

With no annotations, the description carries full burden and exceeds expectations. It discloses extensive caveats: non-UIA element detection limits, hasModal only seeing UIA dialogs, CDP fallback behavior, masked-field handling with road-specific details, and the 'attention' signal interpretation. It also explains why focusedElement.value may be absent and the meaning of hints. This level of transparency is exemplary and far beyond typical tool descriptions.

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

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

The description is long but well-structured with Purpose, Details, Prefer, and Caveats sections. Every sentence carries substantive information, and the critical guidance (attention='ok' and prefer-after-action) is front-loaded. It is appropriately detailed for a complex tool with 7 optional parameters, though it could be tightened slightly without losing value.

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

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

Given the tool's complexity (7 optional params, no required, no output schema, many edge cases), the description is remarkably complete. It covers all return fields, optional inclusions, failure modes (browser_open requirement, non-Chromium, masked fields), and even hints for troubleshooting. An agent has everything needed to invoke and interpret the tool correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value beyond the schema: includeCursor is described as 'richer than cursorPos', includeDocument explains silent omission on non-Chromium, and includeSessionContext includes ADR-017 context and a heuristic explanation for 'locked' state. These are meaningful additions that help an agent decide when to enable flags.

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

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

The description opens with a precise purpose: 'Read-only observation of the current desktop state.' It lists exactly what is returned (focused window, element, cursor, modal flag, etc.) and clearly distinguishes itself from desktop_discover by noting it does not enumerate descendants. The verb 'observe' and resource 'desktop state' are specific and unambiguous.

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

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

Explicit guidance says 'Use after each action to confirm state' and notes it is the cheapest observation tool compared to screenshots. It explains when to enable each include* flag and warns that includeDocument requires browser_open. It also compares itself to desktop_discover for actionable entity lists, giving clear when-to-use vs when-not-to-use context.

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

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

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

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

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

The description is well-structured with clear sections (Purpose, Details, Prefer, Caveats, Examples). It is comprehensive but each sentence adds necessary information, avoiding redundancy. Front-loading the purpose and distinction aids quick understanding.

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

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

Given the tool's complexity (VBA execution, COM, permissions), the description covers all essential aspects: purpose, setup requirements, prevalidation, caveats about naming and blocking, and complete examples with return values. No gaps remain despite the lack of an output schema.

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

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

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

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

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

The description clearly states the purpose: author and run VBA macros against Excel via COM late binding. It distinguishes from 'Claude for Excel' which writes formulas but cannot run VBA. The two actions run_vba and check_access_vbom are explicitly defined, making the tool's functionality unambiguous.

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

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

The description provides direct guidance: 'Prefer: Run check_access_vbom first when a workflow depends on macro execution'. It explains the preflight check and remediation for failures. Examples illustrate correct usage for both actions, clarifying when to use each.

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

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

No annotations provided, so description carries full burden. It discloses case-insensitivity, partial match, CDP availability (silently skipped), focus stealing, Win11 foreground refusal with specific error code, and recovery options. No contradictions.

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

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

Description is relatively long but every sentence adds value. Front-loaded with core purpose. Well-structured, no redundancy. Concisely covers all necessary aspects.

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

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

Given complexity (5 params, no output schema), description covers usage, alternatives, failure modes, caveats, and error recovery. Complete for an AI agent to select and invoke correctly.

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

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

Schema description coverage is 100%. Description adds context beyond schema: explains when to use chromeTabUrlContains ('when the target is a Chrome tab that is not currently active'), details forceFocus behavior (auto-escalation), and include parameter options. Adds meaning beyond schema.

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

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

Description states 'Bring a window to the foreground by partial title match (case-insensitive)', which is a specific verb and resource. It distinguishes from siblings by mentioning when to use focus_window vs chromeTabUrlContains and other tools like desktop_act.

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

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

Explicit guidance: 'Use when a tool does not accept a windowTitle param, or when you need to switch focus before a sequence of actions.' Also details when to use chromeTabUrlContains and provides alternatives for recovery from ForegroundRestricted (desktop_act, click_element, keyboard).

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 full weight and delivers: auto-clipboard behavior for non-ASCII, IME composition failure mode, focus-leash chunking with FocusLostDuringType, terminal-class BG auto-engagement, WM_CHAR verification via UIA read-back, sequence atomicity, blocked Windows key combos, and IME-bridge forceImeOff. It even exposes failure contract differences between sequence and press. This is far beyond a minimal safety note.

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

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

The description is dense and front-loaded with a clear Purpose line, then Details, Prefer, Caveats, and Examples. However, it is very long and mixes many distinct concerns (blocked combos, return contracts, env vars, issue references, read-back details) into a single prose block. The Examples section helps, but the Caveats section in particular is a wall of text that would benefit from segmentation; every sentence earns its place, but not every sentence earns its position.

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 params, no output schema, and no annotations, the description covers the missing pieces: return hints (hints.clipboard, verifyDelivery status, context.typed/remaining), failure modes (FocusLostDuringType, BackgroundInputNotDelivered, ForegroundRestricted, MenuFocusLostMidSequence), and per-action verification contracts. It loses the 5th point because it omits a few edge states like the exact shape of the raw response and the interaction between include:['envelope'] and the narrated/rich post state, though the schema's include/narrate descriptions partially cover that.

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% and the schema descriptions are already rich (e.g., steps, use_clipboard, forceImeOff, abortOnFocusLoss cover their semantics thoroughly). The tool description adds cross-cutting semantics like action-specific validation, clipboard backend reporting, and the relationship between sequence and focus_only, but the per-parameter meaning is already fully carried by the schema. Base is 3; the description's additions are contextual rather than per-field.

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

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

The description opens with a precise verb–resource pair ('Send keyboard input to a window') and enumerates the three action modes ('type', 'press', 'sequence') with their distinct purposes. It differentiates from sibling tools by naming the intended alternatives (desktop_act setValue, click_element) rather than overlapping with browser/keyboard-free siblings.

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

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

Explicit guidance is given for when to use each action, when to prefer setValue for UIA fields, and when to switch to desktop_act/click_element for non-terminal windows. It also states the exact destination requirements (windowTitle or hwnd REQUIRED, @active for foreground targeting) and the env-var downgrade path. The Prefer section and Caveats cover both positive and negative selection criteria.

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

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

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

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

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

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

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

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

Given the tool's complexity (6 actions, credential security, terminal integration, Windows-specific behavior), the description is remarkably complete. It covers prerequisites (known_hosts for ssh saves), failure modes (KeyLockerWtUnavailable), security boundaries (secrets never shown), and the exact workflow with terminal. The examples show realistic input/output pairs. Nothing an agent needs to call this tool correctly is missing.

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

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

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

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

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

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

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

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

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

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

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

With no annotations provided, the description carries the full burden and excels. It discloses auto-guard behavior, the post.perception status, the conversion of origin+scale, double/triple-click precedence, the suggestedFix mechanism with 15s expiry, the verifyDelivery status signals, Win11 foreground refusal handling with a specific error code, and the reserved-only MouseClickNotDelivered. Every notable behavioral trait is explicitly documented.

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

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

The description is long but each sentence carries unique information. It is front-loaded with the core action and examples, then adds caveats and error recovery. The structure is logical, though the density could be slightly intimidating; however, there is no redundancy or filler, making it appropriately sized for the tool's complexity.

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

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

Given 21 parameters, nested objects, and no output schema, the description is remarkably complete. It explains return shapes (post.perception.status, hints.verifyDelivery), error recovery (fixId, ForegroundRestricted), parameter interactions, and even the rationale behind reserved error codes. An agent has everything needed to call this tool correctly and handle failure modes.

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 value by explaining the interplay of origin+scale with conversion math, the semantics of verifyDelivery statuses ('delivered'|'focus_only'|'unverifiable' and the three signals), the one-shot fixId expiry, and the precedence of tripleClick over doubleClick. It does not rehash every parameter but focuses on the non-obvious ones, elevating it above 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 description opens with a specific verb+resource: 'Click at screen coordinates.' It immediately distinguishes from siblings by naming alternatives ('Prefer click_element (UIA) for native apps, prefer browser_click for Chrome') and clarifies scope. This gives an agent a clear, unambiguous purpose and differentiates it from similar tools.

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

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

Explicitly states when to use this tool vs alternatives ('Prefer click_element (UIA)... prefer browser_click...'), when to pass windowTitle for guarded clicks, and when lensId is appropriate ('only for advanced pinned-target workflows'). It also explains the unguarded fallback and how to recover from guard failures via fixId. Usage context is fully specified.

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

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

With no annotations, the description fully discloses behavioral traits: left-button only, both start and endpoint guarded, cross-window and tab drags blocked by default with specific error codes, verification status reporting, homing correction, and Win11 foreground restrictions. It also explains that MouseDragNotDelivered is reserved-only, showing deep transparency.

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

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

The description is dense and information-rich, front-loaded with purpose and examples, followed by caveats. It is longer than ideal but every sentence adds critical operational detail. The structure flows from core action to edge cases, making it usable despite the length.

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 14 parameters, no output schema, and no annotations, the description covers all essential behavioral aspects: error codes, verification, guards, exceptions, and even server-specific refusal conditions. It leaves no critical operational gap for an agent 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 71%, so the description compensates for missing schema descriptions on startX/startY/endX/endY by illustrating them in the example. It adds meaning to verifyDelivery (3-value shape) and clarifies the purpose of windowTitle, allowCrossWindowDrag, and allowTabDrag. Minor gap: no explicit description of the coordinate semantics beyond the example, but it's sufficient.

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

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

The description clearly states the action (click and drag), the resource (mouse coordinates), and specific use cases (sliders, drag-and-drop, canvas drawing, window resizing). It differentiates from mouse_click by specifying the drag behavior and includes an explicit example with parameter names.

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

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

The description provides explicit guidance on when to use the tool (e.g., for drag operations) and when to use specific flags (allowCrossWindowDrag, allowTabDrag) to override default blocks. It also mentions advanced lensId workflows, giving clear context for parameter choices.

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

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

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

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

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

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

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

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

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

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

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

Schema coverage is 100%, so the baseline is 3. The description does not add significant new meaning beyond what the schema already provides for the title, body, and include parameters. The description focuses on behavioral aspects rather than parameter details.

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

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

The description clearly states 'Show a Windows system tray balloon notification to alert the user', providing a specific verb and resource. It distinguishes from sibling tools which are focused on browser interactions, desktop actions, and data processing, making the purpose unambiguous.

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

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

The description explicitly says 'Use at the end of a long-running task so the user knows it finished without watching the screen', providing clear context for when to use. It also includes caveats about delivery verification and suggests indirect observation via wait_until, but does not mention alternative tools or explicitly state when not to use.

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

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

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

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

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

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

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

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

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

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

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

Schema coverage is 100%, but the description adds substantial meaning beyond the schema: it defines the structure of steps[] with {tool, params}, explains the special sleep pseudo-step, enumerates which tools are invalid as steps, and clarifies the include/stop_on_error parameters. This goes well beyond the baseline for high schema coverage.

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

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

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

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

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

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

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

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

Despite no annotations, the description thoroughly discloses behavioral traits: default scaling, diffMode cold-start behavior, background capture constraints, OCR fallback logic, and coordinate computation. No contradictions.

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

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

Long but well-structured with sections for purpose, details, prefer, caveats, and examples. Front-loaded with key info. Could be slightly more concise, but justified by tool complexity.

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

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

No output schema, but description covers return types (resource_link, inline image, elements) and important notes like the need for a baseline for diffMode. Addresses all key aspects for a complex tool.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value with examples, inter-parameter dependencies (e.g., region with windowTitle), and business logic (e.g., confirmImage 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 explicitly states the tool captures desktop, window, or region with multiple detail levels and capture modes. It distinguishes from sibling tools like browser_* and screenshot_gc, and provides clear usage boundaries.

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?

Extensive guidance on when to use each detail level, mode, and combination. Includes a 'Prefer' section with explicit recommendations and a 'Caveats' section detailing restrictions and prerequisites.

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

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

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

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

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

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

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

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

Covers all 8 parameters, defaults, safety, scope, and return value in dry-run (candidates + orphan stats). No output schema, but description adequately explains what the call returns. Complete for a cleanup tool.

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

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

Schema coverage is 100%, but description adds value: explains default retention values (newest 200 / 256 MiB), safety interplay of dryRun/confirm, purpose of include (response shape), and includeOrphans default. Goes beyond schema.

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

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

Description clearly states 'Reclaim disk space from cached screenshots by retention policy', specifying the action (reclaim) and resource (cached screenshots). It distinguishes from sibling tools like screenshot (capture) and screenshot_query (query) by focusing on garbage collection and cache cleanup.

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

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

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

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

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

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

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

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

Five well-structured sentences: first states core purpose, then elaborates on return content, cost warning, filter/paging options, and ordering. No fluff, front-loaded with the main action.

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

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

Given 7 parameters (0 required) and no output schema, the description covers the tool's purpose, return shape (fields and totals), filtering, pagination, ordering, and token-cost warning. It adequately equips an agent to use the tool correctly without needing additional context.

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

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

Schema coverage is 100%, so baseline is 3. Description adds extra context: defaults for limit (50), offsets, case-insensitivity for tag, and ordering (newest-first). While some info repeats schema, the description organizes and clarifies usage for pagination and filtering, adding meaningful value.

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

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

Description clearly states the verb 'List' and resource 'screenshots saved in the disk-cache', emphasizing it is non-destructive and fast. It distinguishes from sibling tools like 'screenshot' and 'screenshot_gc' by describing its specific function.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Schema coverage is 100%, so the baseline is 3. The description adds substantial meaning beyond the schema: it explains the relationship between amount and screenfuls, clarifies that one notch equals one physical wheel detent, gives per-app step sizes, and explains per-action required fields are enforced at call time. It also adds context for parameters like sizeReduced (mentioned in description though not in schema) and virtualIndex/virtualTotal via the VirtualScrollExhausted error. Minor deduction because the description is not exhaustive for every parameter (e.g., homing, scrollKey, verifyWithHash are only in schema).

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

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

The description opens with a clear verb and resource ('Scroll a window or page') and immediately enumerates the five action strategies with one-line definitions. It distinguishes itself from siblings like mouse_click, browser_eval, and screenshot by naming its own sub-modes (raw, to_element, smart, capture, read) and their outputs.

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

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

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

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

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

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

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

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

The description is long but deliberately structured into field groups (engine, nativeUia, imageDiff, health) with terse explanations. The opening sentence states the core purpose, and each section earns its place by defining non-obvious semantics and failure modes. It could be trimmed slightly, but the density is justified by the tool's diagnostic complexity.

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

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

Despite having no output schema, the description thoroughly documents every return value, sub-field, and their dynamic behavior. It explains limitations (HTTP transport not tracked), how to interpret counts (tasksDone vs tasksSent), and why a value might be null. An agent can call this tool and correctly interpret the response with no further information.

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

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

Schema description coverage is 100%, so the include parameter is fully documented in the input schema. The description adds nothing about the include parameter beyond what the schema says (envelope/raw), so the baseline of 3 applies. It does not worsen or improve the semantic gap.

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

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

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

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

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

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

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

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

No annotations are present, so the description carries full burden. It richly discloses behavioral traits: completion reasons (quiet, pattern_matched, exited, timeout, etc.), outputIntegrity values, baseline_lost behavior, file-lock warnings, default quietMs, platform-specific nuances (Windows Terminal vs conhost, FG/BG paths), and hidden-input prompt handling. This transparency far exceeds typical tool descriptions.

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 extremely long but well-structured with clear sections (Purpose, Details, Prefer, Caveats, Examples) and front-loaded purpose. While every sentence is information-dense, some redundancy exists (e.g., command alias mentioned multiple times, multiple issue references). Still, for a tool with this complexity, the length is largely justified, though a trim would improve conciseness.

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

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

Given no output schema, the description thoroughly explains return values (completion={reason, elapsedMs}, outputIntegrity, error codes), behavioral details, and edge cases. Examples cover run/read/send with various options. The description is complete enough for an agent to select and invoke the tool correctly across diverse scenarios, including Windows Terminal limitations and error handling.

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

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

Schema coverage is 80%, but the description adds substantial meaning: it explains the deprecated `command` alias, clarifies paneId vs windowTitle precedence, details until modes (pattern/exit/quiet) with examples, and describes readOptions/sendOptions forwarding. It also gives concrete input examples that map parameters to usage scenarios, going well beyond the schema's field-level descriptions.

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

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

The description opens with a specific verb+resource: "Interact with a terminal window: read output, send input, or run+wait+read in one call." It clearly distinguishes three actions (read/send/run) and explicitly notes that this tool absorbs the formerly-standalone read/send tools, making its scope unambiguous.

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

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

The description provides explicit guidance: "Prefer: action='run' for command execution + result" and "Use action='read'/'send' for fine-grained control or when you need to interleave other actions." It also instructs users to avoid screenshots of the terminal, directing them to read instead, and explains when to use pattern mode for long-running commands.

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

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

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

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

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

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

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

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

Given no annotations and no output schema, the description fully covers return values, error codes, prerequisites, condition-specific target requirements, and example calls. An agent can select and invoke this tool correctly for any of the nine conditions without needing additional documentation.

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

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

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

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

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

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

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

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

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

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

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

With no annotations provided, the description fully bears the burden of behavioral disclosure. It explains pin survival across minimize/restore, need for explicit unpin, dock failure on elevated processes, override of Windows snap, and auto-restoration of minimized windows before docking.

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

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

The description is well-structured with labeled sections (Purpose, Details, Prefer, Caveats, Examples), front-loads the purpose, and every sentence adds value. It is concise yet comprehensive, fitting all necessary information into a manageable length.

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

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

Given the tool's complexity (10 parameters, 3 actions) and lack of output schema, the description provides thorough coverage of usage and behavior, including examples. However, it does not describe the return value or error handling, which would improve completeness.

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%, and the description adds value beyond the schema by explaining defaults (480×360 bottom-right), the relationship between action and required fields, and the interplay between pin and duration_ms. However, the schema itself is already clear, so the description only slightly enhances understanding.

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

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

The description clearly states the tool's purpose with specific verbs (decorate, pin, unpin, dock) and resources (window), distinguishing it from sibling tools like focus_window. The three actions are explicitly listed and explained.

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

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

The description provides explicit 'Prefer' section advising when to use action='dock' versus action='pin' alone, and includes caveats about elevated processes and overriding snap arrangements, giving clear guidance on appropriate usage.

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

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

With no annotations provided, the description carries the full burden and richly discloses behavior: HWND-based detection, polling mechanism, localized title handling, and detach effects. It explains the snapshot-then-poll logic and default timeout, leaving no ambiguity.

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

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

The description is well-structured with clear sections (Purpose, Details, Prefer, Caveats, Examples). It is front-loaded with the main purpose and every sentence adds value without redundancy. Efficient use of space.

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

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

Given no output schema, the description fully explains the return shape and edge cases. It covers localization, single-instance apps, and detach behavior, making it complete for an AI agent to understand invocation and outcomes.

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

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

Schema has 100% coverage, but the description adds valuable context: explains command and args restrictions, default timeout (though slightly inconsistent with schema's waitMs), and includes examples. However, the minor discrepancy in default value (timeoutMs vs waitMs) prevents a perfect score.

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

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

The description clearly states the tool's purpose: 'Launch an application and wait for its new window to appear, returning title, HWND, and PID.' It specifies the verb (launch), resource (application), and return values, distinguishing from sibling tools like run_macro.

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

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

The description explicitly recommends using this tool instead of run_macro combos and provides follow-up actions like focus_window. It also includes caveats for single-instance apps and detach behavior, offering clear when-to-use and when-not-to-use guidance.

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

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

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

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

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

The description is well-structured with headings (Purpose, Details, Prefer, Caveats) and each section adds value. However, it is somewhat verbose, especially the caveat referencing ADR-010. It could be slightly more concise without losing information, but it remains effective.

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

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

Given the tool has 3 parameters, no output schema, and no annotations, the description is remarkably complete. It explains what is returned, side effects, usage patterns, and caveats. It fully equips the agent to use the tool correctly.

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

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

Schema description coverage is 100% (all three parameters have descriptions in the input schema). The description does not add significant new meaning beyond the schema; it references 'includeUiSummary' indirectly and mentions thumbnail dimensions, but the schema already covers these. Baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'Orient fully in one call' and enumerates what it returns (display layouts, thumbnails, actionable element lists). It is a specific verb+resource combination and distinguishes from sibling tools like screenshot and screenshot variants.

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

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

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

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