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

Annotations already declare readOnlyHint=true, so description adds the X11 and text-layer context. However, it does not disclose behavior for empty or non-text clipboard contents, nor platform dependence beyond X11.

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

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

Single sentence with direct verb+object. No wasted words, front-loaded with purpose.

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

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

For a simple 0-parameter read tool with readOnlyHint, the description fully covers what the tool does and its data source. No output schema needed for a text return.

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?

No parameters in schema, so description does not need to explain them. The baseline for 0 parameters is 4; description is concise and clear.

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

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

Description clearly states it reads the X11 CLIPBOARD selection as text, which is a specific verb+resource. It distinguishes from clipboard_set, which writes.

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

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

No explicit guidance on when to use this tool versus alternatives like screenshot_text or type_text. Simple read operation but lacks context on prerequisites or 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?

Annotations indicate destructiveHint: true, so the tool is marked as destructive. The description adds minimal behavioral information beyond stating it writes to the clipboard. It could mention that it overwrites existing clipboard content or is X11-specific, but it does not. With annotations covering the destructive nature, a score of 3 is appropriate.

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

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

The description is a single, front-loaded sentence that conveys everything necessary. No wasted words; every word earns its place.

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

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

Given the low complexity (1 param, no output schema, annotations present), the description is mostly complete. It mentions the specific X11 selection, which is useful context. However, it could clarify that it overrides clipboard content and is limited to X11 environments. Still, it is sufficient for an agent to use correctly.

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

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

The input schema has one parameter 'text' with no description (0% coverage). The description implicitly identifies it by saying 'Write a string', which matches the schema type. However, it does not add additional meaning such as format constraints, max length, or encoding. It adds marginal value over the schema alone.

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

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

The description clearly states the action ('Write a string') and the resource ('to the X11 CLIPBOARD selection'), distinguishing it from sibling tools like clipboard_get. It is specific and unambiguous.

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

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

The description does not explicitly state when to use or not use this tool versus alternatives. However, given the sibling tool clipboard_get, the purpose is implicitly clear. No exclusions or alternative suggestions are provided, making it adequate but not thorough.

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

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

The description adds behavioral context beyond the annotations by mentioning 'gracefully' and 'via the WM close hint'. However, it does not fully disclose potential consequences (e.g., unsaved changes) or clarify that it is a destructive action beyond the annotation.

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

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

The description is a single, concise sentence with no extraneous words. It is front-loaded with the action and efficiently conveys the necessary information.

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

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

For a simple tool with one parameter and no output schema, the description covers the core functionality and parameter meaning. It is complete enough for an agent to use the tool correctly, though additional context about failure modes or preconditions would be helpful.

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

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

With schema coverage at 0%, the description adds essential meaning: it specifies that the parameter is a 'title pattern' used for matching, not an exact title. This clarifies usage but could provide examples or pattern syntax.

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

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

The description clearly states the tool's purpose: to request closing a window matching a given title pattern. It uses a specific verb ('close') and resource ('window'), and differentiates from siblings like 'focus_window' and 'list_windows'.

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

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

No guidance on when to use this tool versus alternatives. The description implies graceful closing but does not provide explicit conditions or when-not-to-use scenarios.

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

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

The description explains the matching behavior (substring, case-insensitive) beyond the annotation's destructiveHint. It adds value by detailing how the pattern is matched. No contradiction with annotations, though destructiveHint seems misaligned.

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

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

The description is a single sentence that is front-loaded with the key action and resource. No wasted words; every part is necessary.

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

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

For a simple tool with one parameter and no output schema, the description is fully complete. It covers the purpose, matching behavior, and implicitly the effect. No 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?

The input schema provides no description for 'title_pattern' (0% coverage). The description compensates by clarifying that it is a substring, case-insensitive pattern. This is essential information 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 clearly states the action (bring to foreground) and the resource (window matching title pattern), and specifies matching semantics (substring, case-insensitive). This distinguishes it from sibling tools like close_window or move_window.

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

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

The description implies usage for focusing an existing window but does not explicitly state when to use this tool versus alternatives like list_windows or move_window. No exclusion criteria or prerequisites are provided.

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

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

Annotations already set destructiveHint=true, so the description does not need to emphasize destructiveness. It adds value by specifying the notation (xdotool's keysym) but could disclose side effects like focus changes or system-level impact. With annotations covering the safety profile, a 3 is appropriate.

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 very concise: two sentences with no wasted words. It front-loads the action and notation, then immediately provides examples. 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?

For a simple tool with one parameter and no output schema, the description is fairly complete. It covers the action, notation, and examples. Minor omission: it doesn't state that the press is instantaneous or that it simulates press and release. Still, it's sufficient given the tool's simplicity.

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 for the 'combo' parameter is 0%, so the description must compensate. It does so by providing examples and explicitly mentioning 'xdotool's keysym notation', which clarifies the format expected. This adds significant semantic value beyond the bare schema.

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

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

The description clearly states it presses a keyboard combination using xdotool's keysym notation, with concrete examples. It specifies the verb 'Press' and the resource 'keyboard combination', making it unambiguous and distinct from siblings like type_text or mouse_click.

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

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

The description provides examples but offers no guidance on when to use this tool versus alternatives like type_text (for typing strings) or mouse_actions. There is no mention of when not to use it, prerequisites, or exclusions, which limits its helpfulness for selection decisions.

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

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

Beyond the annotations (destructiveHint, openWorldHint), the description adds that 'The process is detached from this server', informing users that the tool does not wait for the process and is non-blocking. This is valuable behavioral context not captured by annotations.

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

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

The description is two sentences, front-loaded with the action and examples. Every sentence adds value: the first defines the tool, the second adds a key behavioral detail. No redundant or unnecessary content.

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 simplicity (one parameter, no output schema), the description covers all essential aspects: what it does, how to use it (with examples), and a critical behavioral detail (detached process). No further information is needed for correct invocation.

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

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

With 0% schema description coverage, the description compensates by explaining that the 'command' parameter is a shell command like 'firefox' or 'code /path/to/project', adding meaning and usage examples beyond the basic string type in the schema.

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

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

The description clearly states 'Launch an application via a shell command', providing a specific verb and resource. Examples like 'firefox', 'gnome-terminal', and 'code /path/to/project' further clarify the tool's purpose, and it is well-differentiated from sibling tools that handle clipboard, windows, or mouse actions.

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

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

The description provides clear context on when to use the tool by specifying it launches applications via shell commands and noting the process is detached. It does not explicitly exclude use cases or mention alternatives, but the examples and context make the usage straightforward.

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 specifies the output fields beyond the readOnlyHint annotation, which already marks it as safe. However, it does not disclose additional behavioral traits like whether visible windows are limited to the current host, ordering, or performance implications. The annotation covers the safety aspect, so the description adds moderate value.

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

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

The description is a single, information-dense sentence that directly states the tool's purpose and deliverables. It is front-loaded with the verb 'List' and avoids any extraneous words.

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

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

For a parameterless list operation, the description adequately covers the action and the output details. It could be slightly stronger if it clarified the scope (e.g., current display, local machine). However, given no output schema, the description is complete enough for an AI agent to understand the tool's value.

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

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

The input schema has zero parameters, so the description does not need to explain param meaning. By default, a tool with no parameters gets a baseline score of 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 explicitly states the verb 'List' and the resource 'visible windows', and enumerates the fields returned (id, pid, desktop, geometry, title, etc.). This clearly differentiates from sibling tools like close_window, focus_window, or move_window, which perform distinct actions.

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

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

No guidance is provided on when to use this tool versus alternatives such as focus_window or close_window. There is no advice on prerequisites, nor on when not to use it, leaving the agent to infer context from the tool's name alone.

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

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

The description adds value beyond annotations by explaining the conditional pointer movement. Annotations provide destructiveHint for safety awareness, and the description complements this with operational detail.

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

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

A single, well-structured sentence that front-loads the key purpose and critical behavior. No unnecessary words.

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

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

For a simple action tool with no output schema, the description covers the main behavior and parameter interaction. It assumes agent awareness of standard UI concepts, which is reasonable.

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 description explains the role of x and y together (pointer movement before click), adding context beyond the schema's minimal descriptions. For button, the schema already provides default, so the description doesn't need repetition.

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 clicks a mouse button, with optional movement to specified coordinates. It effectively distinguishes from sibling tools like 'mouse_move' and 'mouse_drag' by specifying its unique action.

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

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

The description implies when to use this tool (for clicking) versus alternatives like mouse_move or mouse_drag. However, it does not explicitly state when not to use it or mention any 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?

The description explains the basic behavior of dragging with coordinates and a button. The annotations include destructiveHint: true, which warns of potential side effects. However, the description does not elaborate further on behavioral traits (e.g., coordinate system reference, effects on UI) beyond what the annotation already 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 a single sentence of 15 words, efficiently conveying the core action and default button. No redundant information. Very 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?

Given the tool has 5 parameters including coordinate pairs, the description lacks critical details such as coordinate reference frame (screen vs window), units (pixels?), what happens if coordinates are out of bounds, and return behavior. The destructive hint suggests potential side effects but these are not explained. The description is too minimal for full agent decision-making.

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

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

Schema description coverage is 20% (only 'button' has a description). The description mentions the parameters but does not explain the coordinate system, units, or value ranges (e.g., are coordinates screen-relative?). The button options are listed but defaults are stated. The description fails to compensate for the low 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?

Description clearly states the action: drag from (x1,y1) to (x2,y2) holding a button (default left). It uses a specific verb ('drag') and resource (coordinates), and is distinguishable from sibling tools like mouse_click and mouse_move.

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

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

No explicit guidance on when to use this tool vs alternatives like mouse_click or mouse_move. No prerequisites or when-not-to-use instructions are provided. The destructive hint annotation offers some caution but not usage 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?

Annotations include destructiveHint: true, which the description does not contradict. However, the description does not add further behavioral details (e.g., instant movement, no animation). Baseline score with annotations present.

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

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

Single sentence with no wasted words; front-loaded with key information.

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

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

For a simple tool with two numeric parameters and no output schema, the description is nearly complete. Could be improved by clarifying coordinate origin or units.

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

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

Schema coverage is 0%, so the description compensates by explaining that x and y are 'absolute screen coordinates', adding meaning beyond the raw numeric types.

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 specifies the action (move), resource (mouse pointer), and that coordinates are absolute screen coordinates. It distinguishes from sibling tools like mouse_click or mouse_drag.

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

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

No guidance on when to use this tool versus alternatives like mouse_drag or mouse_scroll. No mention of prerequisites or context for 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?

The annotation destructiveHint: true indicates the action modifies state, but the description only adds the default amount. It does not elaborate on the scope (e.g., active window) or any side effects beyond the basic scroll.

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

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

Single sentence, no fluff, directly communicates the action and key defaults.

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

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

For a simple tool with two parameters and no output schema, the description covers the essential info. Could be improved by specifying the target window or that scroll is relative, but overall adequate.

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

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

Schema coverage is 50% and the description only restates the enum values and default amount already present in the schema. It does not add meaning beyond the schema for either parameter.

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 (scroll) and the resource (direction and amount). It distinguishes from sibling tools like mouse_click and mouse_drag by specifying scrolling in four directions.

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

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

No guidance is provided on when to use this tool versus alternatives, such as scrolling vs clicking or dragging. No mention of prerequisites or contexts.

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

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

The description adds behavioral context beyond annotations by explaining that omitted dimensions remain unchanged. However, it lacks details on pattern matching behavior and potential side effects.

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

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

Two sentences, no redundancy. Purpose and key behavioral rule are front-loaded and efficiently communicated.

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?

While the description covers core purpose and parameter behavior, it omits information about return values, error cases, and handling of multiple matching windows, making it somewhat incomplete for a 5-parameter 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?

With 0% schema description coverage, the description adds meaning for the optional parameters (omitted leaves unchanged) but does not clarify the title_pattern format or coordinate semantics.

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

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

The description clearly states the action 'Move and/or resize a window' and specifies the resource by 'title pattern', distinguishing it from sibling tools like close_window or focus_window.

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

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

The description implies usage for moving/resizing windows but does not provide explicit guidance on when to use this tool over alternatives, nor does it mention prerequisites or conditions.

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 file format (PNG), save location (/tmp/claude-linux-mcp/shots/), and return value (path). Annotations include readOnlyHint=true, which is not contradicted; the tool is a read operation with minimal side effects.

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

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

Two concise sentences front-load the main action and optional behavior. No unnecessary words or repetition.

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

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

For a simple tool with full parameter coverage and annotations, the description covers purpose, parameters, output, and side effects. No gaps exist given 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?

Schema coverage is 100%, so baseline is 3. The description adds the default path and clarifies the behavior of 'active_window', providing value beyond the schema.

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

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

The description clearly states the verb 'capture' and the resource 'screenshot', and distinguishes between full screen and active window. It contrasts with the sibling tool 'screenshot_text' which extracts text.

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

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

The description implies usage for visual capture but does not explicitly state when to use versus alternatives like 'screenshot_text' or specify when not to use. No exclusions or context is provided.

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

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

Annotations indicate readOnlyHint=true, and the description confirms it reads the screen. It discloses that it requires external software (tesseract-ocr) and describes the output (text + path). 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?

Three sentences with no wasted words. Front-loaded: action first, then output and usage guidance.

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

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

Covers purpose, output, usage context, and prerequisites. Lacks details on error handling (e.g., tesseract not installed) but is sufficient given 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 provides 100% coverage of parameter descriptions. The description adds no additional meaning for parameters beyond what is in the schema. 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 action (take screenshot and OCR), the resource (screen), and the output (recognized text plus PNG path). It distinguishes from sibling tools like screenshot, which likely only captures the image.

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 context for when to use this tool: 'when Claude needs to READ what is on screen' and gives concrete examples (log windows, error dialogs). It does not mention when not to use or alternative tools, but the guidance is clear.

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

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

Description adds that it emits keystrokes and targets the focused window, which complements the destructiveHint annotation without contradiction.

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

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

Two clear, well-structured sentences that efficiently convey purpose and usage guidance.

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

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

Covers tool purpose and alternative usage, but lacks details like error handling, cancellation, or behavior without a focused window.

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

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

The schema has 50% description coverage; the description only paraphrases the text parameter and does not explain the delay parameter beyond what the schema provides.

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

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

The description clearly states the tool types a string into the currently-focused window and distinguishes it from key_press for special/modifier combos.

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 tells when to use key_press instead, but doesn't provide other usage context like prerequisites or 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.