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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds meaningful behavioral context: it is a bounded breadth-first search, supports case-insensitive substring matching, returns elementHandles, and requires Accessibility permission. This goes beyond what annotations and schema descriptions 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?

Two sentences with zero filler. The first sentence front-loads the action, scope, and criteria; the second explains the return value and permission requirement. Every clause 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 8 parameters, no output schema, and read-only annotations, the description covers purpose, return type (elementHandles), scoping (app or window), and permission. It lacks explicit mention of result ordering or error behavior, but for a bounded search tool with schema-provided limits (maxDepth, maxResults), this is adequate.

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

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

Schema coverage is 100%, so baseline is 3. The description adds semantic relationships between parameters: role, title/value substring, and AXIdentifier can be combined ('and/or'), and title/value matching is case-insensitive. This is meaningful beyond the per-field schema descriptions.

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

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

The description clearly states a specific verb ('search') and resource ('accessibility tree'), with explicit scope (app or single window) and matching criteria (role, case-insensitive title/value substring, AXIdentifier). It distinguishes itself from sibling tools like ax_snapshot by focusing on bounded search and returning elementHandles for ax_invoke/ax_set_value.

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

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

The description gives clear context: use this to find elements in the accessibility tree for later invocation or value setting, and notes that Accessibility permission is required. It does not explicitly state when not to use it or name alternatives, but the return-handle purpose implies the use case vs. ax_snapshot.

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 context beyond annotations by stating the Accessibility permission requirement and the behavior of returning available action names on invalid action requests. It also clarifies the meaning of 'AXPress'. Given annotations already indicate readOnlyHint=false and destructiveHint=false, the description adds useful extra behavioral nuance.

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 concise sentences, front-loaded with the primary action and resource. It includes necessary details (default behavior, discovery mechanism, permission) without any wasted words.

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

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

For a simple 2-parameter action tool with no output schema, the description is comprehensive: it covers purpose, default behavior, action discovery, and permission. It does not explicitly mention return values or failure modes, but these are not critical given the tool's simplicity and existing annotations.

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?

While schema descriptions cover both parameters (100% coverage), the description adds value by explaining the default action ('AXPress') and clarifying that 'elementHandle' comes from ax_snapshot or ax_find. This reinforces the schema hints and gives practical contextual meaning.

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

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

The description clearly states the tool performs an accessibility action on an element, with the default 'AXPress' (click/activate). It distinguishes itself from siblings like input_click by specifying 'accessibility action' and the discovery mechanism for available 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: this is for accessibility actions, and the default 'AXPress' maps to a click/activate. It also tells users to request an invalid action to discover available actions, which serves as a usage hint. However, it does not explicitly contrast with alternatives like input_click or mention when not to use it.

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

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

The description goes beyond the annotations by disclosing the fallback behavior (focus/select-all/type), the verification step (read-back comparison), and the permission requirement. This adds valuable context beyond the readOnlyHint and destructiveHint flags, with 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?

Two sentences carry all essential information without redundancy. The description is front-loaded with the primary action and then details fallback and reporting, making efficient use of every word.

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 mutation tool with no output schema, the description adequately explains what happens (direct set or fallback), what the return value indicates (read-back success), and the required permission. This is complete for a tool of this complexity.

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

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

The schema already fully describes both parameters (elementHandle and value) with clear descriptions. The tool description adds no additional parameter-specific detail, so the baseline of 3 applies given the 100% 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 a specific action (set an element's AXValue), the resource (the element), and a fallback mechanism. It distinguishes itself from sibling tools like ax_invoke by focusing on value setting.

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 the tool (when you need to set an element's value) and notes a prerequisite (Accessibility permission), but it does not explicitly contrast with alternatives like input_type or ax_invoke, nor does it state when not to use it.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context beyond annotations: depth/node-count caps, the requirement for Accessibility permission, and the scope options (whole app vs specific window). 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?

A single, well-structured sentence that leads with the core action and resource, then lists return data, caps, and permission requirement. Every word earns its place, and the main information is front-loaded.

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

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

Given no output schema, the description adequately explains what is returned (attributes + elementHandle), the scoping options, the limits, and the permission prerequisite. It doesn't mention error conditions or the explicit pid/windowHandle exclusivity rule, but the schema covers that, so the description is reasonably complete for a moderate-complexity tool.

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

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

Schema description coverage is 100% and all four parameters (pid, maxDepth, maxNodes, windowHandle) are documented in detail. The description adds the general concept of caps but no additional per-parameter semantics beyond what the schema already provides, so it meets the baseline but does not elevate it.

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

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

The description uses the specific verb 'Walk' to describe traversing the accessibility tree, and explicitly states the per-node return fields (role/title/value/description/identifier/enabled/frame) plus an elementHandle. It clearly distinguishes from siblings like ax_find by describing the full-tree snapshot scope (app or window) and connecting to ax_invoke/ax_set_value.

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

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

The description clearly implies when to use this tool: when a snapshot of the accessibility tree is needed, with optional scoping to a window. It also mentions the returned elementHandle is usable with ax_invoke/ax_set_value, which clarifies its place among siblings, but it does not explicitly exclude cases like 'if you only need a specific element, use ax_find'.

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 important behavioral context beyond the read-only annotation: it requires Screen Recording permission and falls back to the `screencapture` CLI if the native helper is unavailable. This discloses prerequisites and error-handling behavior, which is genuinely useful.

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 every sentence adds value. It is concise and well-structured 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 simple screenshot tool with thorough annotations and full parameter schema, the description covers the core behavior, permissions, and fallback. It does not state the return format, but given the lack of output schema and the tool's straightforward nature, this is a minor gap, not a critical omission.

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 already provides 100% coverage with descriptions for both maxWidth and displayId. The description adds little beyond the schema, only reinforcing that main display is default. Since schema coverage is high, a baseline of 3 is appropriate.

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

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

The description clearly states the tool takes a screenshot of a full display, with a specific default (main display). The verb 'Take a screenshot' and resource 'full display' distinguish it from siblings like capture_region and capture_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 provides clear context for when to use this tool: for full-display screenshots, with main display as default. It doesn't explicitly mention alternatives or exclusions, but the 'full display' wording implies usage scope and differentiates from region/window capture.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the agent knows it's a safe read operation. The description adds valuable behavioral context by noting the Screen Recording permission requirement and the fallback mechanism to 'screencapture -R' if the helper is unavailable. This goes beyond the annotations without contradicting them.

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 core action, and every word contributes useful information (action, coordinate system, permission, fallback). There is no wasted content or unstructured rambling.

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

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

The description covers purpose, coordinate system, permission, and fallback, but it does not mention the return format (e.g., file path, base64, image object) despite the lack of an output schema. This is a notable gap for a screenshot tool, as the agent would need to know what to do with the result. Given the schema is well-documented and annotations cover safety, the description is adequate but not fully complete.

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

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

The input schema covers all parameters with descriptions, so the baseline is 3. The description adds a minor clarification about 'top-left origin' for the coordinate system, but this is largely redundant given the schema's 'left edge' and 'top edge' phrasing. It does not add meaningful semantics beyond the schema, so a score of 3 is appropriate.

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

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

The description clearly states a specific action ('Take a screenshot of a rectangular region') and specifies the scope ('in global screen points (top-left origin)'). This distinguishes it from sibling tools like 'capture' (presumably full screen) and 'capture_window' (window-specific), making the tool's unique purpose obvious.

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 by mentioning the coordinate system ('global screen points') and the requirement for Screen Recording permission. It implicitly differentiates from capture_window by focusing on coordinate-based regions, but it does not explicitly name alternatives or exclusions. Thus, it offers clear context without full when/when-not guidance.

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

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

The description goes well beyond the annotations by disclosing a prerequisite (Screen Recording permission) and a fallback mechanism (`screencapture -l`) with a detail about how the raw windowId is reused. This is rich behavioral context that is not present in the readOnlyHint/destructiveHint annotations, making the tool's runtime behavior more 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 two sentences with no wasted words. It front-loads the core purpose and then efficiently adds permission, fallback, and handle details. Every sentence carries meaningful information, and the structure is easy 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?

The description covers the essential aspects: purpose, input source, permission, and fallback. However, since there is no output schema, it does not specify the return format (e.g., image path, data URL). This is a minor gap, as the behavior is otherwise thoroughly documented, but it prevents a perfect score.

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 already provides descriptions for both parameters (100% coverage), so the baseline is 3. The description adds extra meaning by explaining that the windowHandle contains a raw windowId that is reused in fallback mode, which gives the agent a deeper understanding of the handle's internal structure. It also reinforces the relationship to list_capturable_windows.

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 a specific verb ('Take a screenshot') and resource ('a single window'), and distinguishes it from sibling tools like capture and capture_region by specifying that it operates on a window identified by a windowHandle. This is a precise, action-oriented description that leaves no ambiguity about what the tool does.

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

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

The description provides clear usage context by referencing list_capturable_windows as the source for the handle, and it explains the fallback behavior when the helper is unavailable. However, it does not explicitly contrast this tool with alternatives such as capture (full screen) or capture_region, so the when-not-to-use guidance is implicit rather than explicit.

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?

Annotation contradiction: readOnlyHint=false conflicts with the description stating 'Read the current contents', which is a read-only operation. The fallback and permission details are useful, but the contradiction with annotations forces a score of 1 per the rubric.

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 crisp sentences immediately state the purpose and key behavioral details. No wasted words; the structure is front-loaded and efficient.

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

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

For a zero-parameter tool with no output schema, the description covers the return contents, fallback behavior, and permission requirements. It is sufficiently complete for an agent to use correctly.

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

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

There are no parameters, so the baseline is 4. The description clarifies what will be returned (text, file references, image presence), which is helpful given the absence of an output 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 reads the clipboard and specifies the content types (text, file references, image presence). It is easily distinguished from the sibling clipboard_write.

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 it (to read clipboard contents) and notes that no permission is required. It doesn't explicitly say when not to use it, but the sibling clipboard_write provides a clear contrast.

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

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

Discloses that it overwrites existing clipboard content, uses NSPasteboard with a pbcopy fallback for text only, and requires no permission. This adds substantial behavioral context beyond the annotations (readOnlyHint=false, destructiveHint=false). No contradiction exists between the description and annotations.

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

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

Three concise sentences, front-loaded with the main action, followed by fallback behavior and overwrite side effect. Every sentence contributes meaningful information without redundancy.

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

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

Covers purpose, implementation details, fallback behavior, overwrite side effect, and permissions. For a two-parameter tool with no output schema, this description is comprehensive and leaves no significant gaps.

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

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

The schema already provides 100% parameter descriptions, but the description adds operational context: filePaths require the native helper and have no CLI fallback, while text has a fallback. This clarifies conditions beyond the schema's static descriptions, adding 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?

The description clearly states the tool replaces the system clipboard contents with text or file references. It specifies the verb 'Replace', identifies the resource (system clipboard), and distinguishes between text and file references, effectively differentiating from sibling clipboard_read.

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 clear context on when to use the tool (to set clipboard content) and important constraints: file references require the native helper, text falls back to pbcopy, and no permission is required. It doesn't explicitly name alternatives, but the writing vs reading distinction is implicit through the sibling clipboard_read.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds useful behavioral context beyond the annotations: 'No permission required', iCloud Drive included conditionally, and the specific resolved-path/existence/allowed-path output. This enriches the agent's understanding of runtime behavior.

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

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

The description is a single dense sentence that front-loads the action and resource, then packs in the folder list and output fields. Every clause carries useful information, with no fluff or redundant restatement.

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 values (resolved path, existence, allowed-path status) and notes the environmental dependency on MACCTL_ALLOWED_PATHS. The input side is trivial (no parameters), so the description is complete for the tool's actual complexity.

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

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

The tool has zero parameters, making schema coverage 100% trivially. The baseline for 0 parameters is 4, and the description does not need to add parameter-level detail since there are none to document.

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 uses the specific verb 'List' with the resource 'well-known macOS folders', enumerating the exact folders and the output attributes (resolved path, existence, allowed-path membership). This clearly distinguishes it from sibling tools like file_list or file_search.

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 through context—listing standard macOS folders without requiring permissions—but does not explicitly state when to prefer this tool over alternatives like file_list or file_search. No exclusions or alternative comparisons are provided.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is known. The description adds context about path checks against MACCTL_ALLOWED_PATHS/DENIED_PATHS, which is not present in annotations. It also mentions recursion with depth cap, enriching behavioral understanding. It does not describe error handling, but that's minor given annotations.

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

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

Two sentences, front-loaded with the core action and output fields, followed by optional recursion and a security note. Every sentence earns its place; no fluff or repetition of schema details.

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, good annotations, and full schema coverage, the description is nearly complete. It explains return fields, notes optional recursion, and mentions access-control checks. It does not describe the exact output structure or error behavior, but with no output schema, it covers the essentials for a listing tool.

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

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

Schema coverage is 100%, so parameters are already documented. The description adds some context (e.g., 'depth cap' aligns with depth parameter, 'Optionally recursive' matches recursive), but it does not provide additional syntax or format details beyond 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 verb ('List') and resource ('a directory's entries'), plus the specific output fields (name, type, size, modification time). This distinguishes it from sibling tools like file_read (file content), file_search (search), and file_write (write).

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 (list directory contents) but does not explicitly name alternatives or provide when-not-to-use guidance. It does not mention file_read or file_search as alternatives, leaving the AI to infer based on sibling names. This is adequate but not explicit.

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 mark destructive, but the description adds valuable context: confirmation requirement with 'confirm: true', the framework's per-tool gating, and path allow/deny checks. This goes beyond the annotation's binary signal and helps agents predict failures.

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

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

Two sentences, front-loaded with operations, then necessary caveats. No redundant filler.

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

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

The description and schema together cover the required parameters and destructive nature, but no output schema exists and edge cases like overwrite behavior are not mentioned. Still sufficient for basic 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 80% schema coverage, the schema already documents most parameters. The description adds the 'mkdir -p semantics' clarification and the uniform confirmation requirement, which slightly enhances understanding of the confirm and operation parameters.

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 lists the four operations (copy, move, delete, mkdir) and identifies the resource as file/directory, distinguishing it from sibling tools like file_read/file_write. The addition of 'mkdir -p semantics' adds precision about directory creation behavior.

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 filesystem mutations but does not explicitly state when to prefer it over siblings like file_write or file_read. It lacks exclusions or alternative guidance, so an agent must infer boundaries from the operation list.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds meaningful behavior: support for utf8/base64, maxBytes cap, and path validation against MACCTL_ALLOWED_PATHS/DENIED_PATHS. It does not disclose whether truncation occurs when maxBytes is exceeded, but this is not a 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 tightly written sentences with no fluff. The verb and object are front-loaded, and every sentence carries useful 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 read-only tool with helpful annotations, the description covers purpose, encoding modes, size cap, and access control. Missing details about error behavior on exceeding maxBytes, but overall it is sufficient for an agent to select and invoke the tool correctly.

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

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

Schema covers encoding and maxBytes with defaults, but path lacks a description. The description adds meaning to path by explaining the access control check, and reinforces the maxBytes cap. This compensates for the 67% 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 reads a file's contents as utf8 text or base64 for binary data, with a maxBytes cap. This distinguishes it from sibling write/manage tools by focusing on the read operation.

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 context about reading files and path access control, but does not explicitly mention when to use this tool versus alternatives like file_write or file_search. Usage is implied rather than stated as a clear rule.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds useful behavioral context: path is checked against MACCTL_ALLOWED_PATHS/MACCTL_DENIED_PATHS, content search is size-capped, and results are capped. This goes beyond the annotations.

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

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

The description is three sentences, each carrying distinct information: core search functionality, mdfind acceleration path, and path validation/caps. It is front-loaded and concise with no wasted words.

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

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

For a tool with 7 parameters and no output schema, the description provides substantial context: explains both search modes, the mdfindQuery requirement, path restrictions, and result caps. However, it does not describe the return format (e.g., list of paths), which would be useful 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 coverage is 100%, so the baseline is 3. The description reinforces parameter meaning (e.g., mdfindQuery required when useMdfind is true) but does not add significant new detail beyond the schema. The schema already documents defaults and examples.

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 recursively searches a directory for files/directories matching a glob pattern and/or content regex. It specifies the unique features (useMdfind, content regex) that distinguish it from sibling tools like file_list or file_read.

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 context for when to use the tool (searching by name/content) and provides guidance on using useMdfind to accelerate search via Spotlight. It does not explicitly name alternative tools or exclusion criteria, but the purpose is self-evident.

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 flag destructiveHint=true, but the description adds substantial context: the confirm:true requirement is gated per-tool for all modes (not just overwrite), path verification against allowed/denied lists, and implicit parent directory creation. This goes well beyond the annotation flags and helps the agent understand safety and 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?

Three sentences, front-loaded with the core purpose. Each sentence provides distinct information (modes, confirmation requirement, path restrictions/auto-creation) with no repetition of schema details. Highly efficient and easy 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?

Despite having no output schema, the description covers the tool's behavior comprehensively: operation modes, confirmation requirement, path validation, and directory creation. For a write operation, this is sufficient context for an agent to invoke it correctly. No critical behavioral aspects appear to be missing.

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

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

The schema already documents mode, confirm, content, and encoding with good descriptions (80% coverage). The description adds value by clarifying path behavior (path checked against access lists, parent dirs created), which fills the gap for the undocumented path parameter. It also confirms encoding types align with the schema.

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

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

The description opens with 'Write, append to, or create a text/base64-encoded file,' a specific verb+resource+scope that immediately distinguishes this tool from read-oriented siblings like file_read and file_list. All three modes are enumerated, making the tool's 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?

The description clearly explains when to use each mode ('write' overwrites, 'append' adds, 'create' fails if exists), giving practical guidance for mode selection. It also mentions parent directory auto-creation, which helps users know prerequisites. However, it does not explicitly contrast against alternative tools (e.g., 'use file_read for reading'), though sibling names make this obvious.

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

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

Annotations provide readOnlyHint=false and destructiveHint=false, but the description adds 'Requires Accessibility permission,' which is a crucial behavioral constraint not captured in structured fields. It also implies a mouse input action beyond the annotation hints. No contradiction with annotations.

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

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

The description is two sentences, front-loaded with the primary action. Each clause provides distinct useful information: action, button options, click count, and permission requirement. No redundant or filler 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?

For a 4-parameter tool with no output schema, the description covers the core invocation requirements: global coordinates, button choices, click counts, and a permission prerequisite. It does not describe return values, but for an input action this is often standard and not necessary for selection.

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 covers 50% of parameters (button and clickCount have descriptions), while x and y lack descriptions. The description compensates by clarifying that x and y are 'a global screen point,' giving meaning to the coordinate pair. This is the key semantic addition 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 starts with a specific verb+resource: 'Click the mouse at a global screen point.' It clearly distinguishes from sibling tools like input_move_mouse or input_scroll. It also specifies button types and click counts, 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 phrase 'global screen point' establishes the context of coordinate-based clicking. It does not explicitly name alternatives or exclusions, but the sibling tool list makes the distinction clear (e.g., input_drag for dragging, input_scroll for scrolling). This meets the 'clear context, no exclusions' level.

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

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

Annotations indicate readOnlyHint=false and destructiveHint=false, but the description adds the auth requirement 'Requires Accessibility permission' and reveals the behavior of 'interpolated intermediate points,' which is not present in the annotations. This provides meaningful context beyond the 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?

The description is a single clear sentence of 19 words with no filler. It front-loads the core action and includes the essential permission note. 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?

For a tool with 7 parameters and no output schema, the description covers the core action and the required permission. It defines the purpose of the required coordinate parameters via the 'point' language, and optional parameters have schema descriptions. While it could mention coordinate units or synchronous execution, these are not critical for basic understanding of a drag operation.

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 low (43%), with fromX/fromY/toX/toY lacking descriptions. The description partially compensates by framing these as 'one point' and 'another,' clarifying they are start/end coordinates. However, it does not explain units (pixels) or coordinate system, and optional parameters rely on schema descriptions. Still, it adds some meaning 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 the action: 'Press the mouse button at one point, drag through interpolated intermediate points, and release at another.' This specific verb+resource (drag) distinguishes it from sibling tools like input_click and input_move_mouse.

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 no guidance on when to use this tool versus alternatives. It does not mention exclusions, alternatives, or typical use cases beyond the basic action. The only additional note is the Accessibility permission requirement, which is a prerequisite, not usage 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?

Beyond the annotations (readOnlyHint=false, destructiveHint=false), the description discloses important behavioral traits: auto-release after 30 seconds as a safety net, release on helper shutdown, and the requirement for Accessibility permission. This adds meaningful context not present in annotations.

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

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

Two sentences, no fluff. The first sentence states the function and use case; the second conveys safety and permission. Every sentence earns its place and the structure is front-loaded with the primary 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?

For a simple two-parameter tool with no output schema, the description covers purpose, usage context, behavioral safety net, and prerequisites. No significant gaps remain for an agent to correctly select and invoke the 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?

The schema describes 'key' but not 'action'; the description fills that gap by explaining action values ('down'/'up') and provides a practical example ('shift') that aids understanding. With 50% schema coverage, the description compensates well without redundancy.

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 uses specific verbs 'Hold' and 'release' with a clear resource ('a single key') and explains the action parameter values (down/up). It distinguishes itself from siblings like input_press_keys by explicitly targeting gesture-like sequences, making the 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?

The description provides a concrete use case ('holding shift while clicking multiple items'), clearly implying when to use this tool. It does not explicitly name alternative tools or exclusions, but the example gives sufficient context to differentiate from other input 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?

Annotations already indicate this is a non-read-only operation, but not destructive. The description adds crucial behavioral context: the coordinate system (top-left origin, points not pixels) and the Accessibility permission requirement, which goes beyond the annotations.

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

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

Two concise sentences, front-loaded with the action. Every word adds value: the verb, target, coordinate system, and permission requirement are all clearly stated without fluff.

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

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

For a simple tool with two numeric parameters and no output schema, the description adequately covers the essential context: what it does, coordinate system, and a prerequisite. It does not mention edge cases like out-of-bounds coordinates, but such details are less critical for this basic operation.

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 each parameter is described as 'Target X/Y in global screen points'. The description reinforces the meaning by clarifying 'points not pixels', adding value beyond the schema by disambiguating the unit of measurement.

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), the resource (mouse cursor), and the destination (global screen point), with additional coordinate system clarity (top-left origin, points not pixels). This distinguishes it from sibling tools like input_click and input_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?

The description implies usage for moving the cursor but does not explicitly contrast with alternatives such as click or drag. It does provide a prerequisite (Requires Accessibility permission), which offers some context for when it can be used.

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 annotations already indicate non-read-only, non-destructive behavior. The description adds an authentication requirement ('Requires Accessibility permission') and clarifies the chord syntax with valid modifiers, which goes beyond the structured data. No description of return behavior, but for a simple action tool this is acceptable.

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, front-loaded with the action and examples, then essential modifiers and permission note. No fluff.

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

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

The description plus schema fully cover the tool's usage for a single-parameter action tool. It includes examples, modifier list, and permission requirement; no output schema is needed for a fire-and-forget key press. Sibling list also helps disambiguate.

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 only states 'Chord like "cmd+shift+4".' The description enriches this by listing valid modifiers (cmd, shift, alt/option, ctrl, fn) and providing additional examples for special keys ('return', 'left'), significantly improving the agent's ability to construct valid parameter values.

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 uses the specific verb 'Press' with resource 'keyboard chord' and provides concrete examples ('cmd+shift+4', 'cmd+c', 'return', 'left'), making it clear this tool sends key combinations/special keys. This differentiates it from siblings like input_type (text entry) and input_key_hold (single key hold).

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 examples and modifier list clearly imply when to use this tool (for chords and special keys), and it mentions a prerequisite (Accessibility permission). However, it does not explicitly contrast with sibling tools like input_key_hold or input_type, so it stops short of full exclusion 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?

The description discloses that the cursor may be moved first, that deltaY direction follows system convention, and that Accessibility permission is required. These details go beyond the annotations, which only indicate non-read-only and non-destructive, adding valuable behavioral context.

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

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

Three short, focused sentences cover the core behavior, the cursor side-effect, the direction convention, and the permission requirement. No wasted words; the structure is efficient and front-loaded.

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

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

For a 5-parameter input tool with no output schema, the description provides the essential behavioral context: what it does, the optional cursor movement, the deltaY direction convention, and the permission requirement. Parameter details are already in the schema, making this sufficiently complete.

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

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

Schema descriptions cover all parameters, so the baseline is 3. The description adds meaningful semantic context for deltaY (positive scrolls up/content-down) and clarifies x/y as optional cursor positions, which goes beyond the schema's basic 'Move the cursor here' and 'Vertical scroll amount'.

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 posts a scroll-wheel event, with optional cursor movement first. The verb 'scroll' and the specific parameters distinguish it from sibling input tools like input_click, input_drag, and input_type.

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

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

The description implies use when a scroll-wheel event is needed and mentions the system convention for deltaY, but it does not explicitly compare to alternatives or state when not to use it. With multiple input tools available, some exclusion guidance would help.

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 important behavioral traits beyond the annotations: character-by-character synthesis for short text, clipboard paste for long text with restoration of prior clipboard contents, and the Accessibility permission requirement. These are significant side effects and prerequisites that are not captured in the annotations.

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

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

The description is two sentences, front-loaded with the main purpose, and each sentence adds critical detail (behavior, permission). No filler or redundancy. It is highly concise while remaining informative.

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 (1 parameter, no output schema, annotations present), the description fully covers what an agent needs to know: what it does, how it behaves for different input lengths, and its prerequisite. There are no gaps that would prevent 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?

The input schema already has a single parameter 'text' with a description. The tool description adds semantics by specifying that the text is Unicode and layout-independent, and explains length-dependent behavior. Since schema coverage is 100%, the baseline is 3, but 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 specific verb ('Type') with a resource ('Unicode text') and a clear target ('at the current keyboard focus'). It also adds 'layout-independent', which distinguishes it from input methods that may depend on keyboard layout. This clearly differentiates it from sibling tools like input_click or input_scroll.

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 for when to use the tool: for typing Unicode text at the current keyboard focus. It mentions a prerequisite (Accessibility permission) and describes behavior for short vs. long text, which helps the agent decide. However, it does not explicitly name alternatives or state when not to use it, so it falls short of a 5.

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

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

Beyond the readOnlyHint annotation, the description discloses that it uses ScreenCaptureKit and requires Screen Recording permission, adding meaningful behavioral context. It also explains how to pass windowId to capture_window, giving additional practical transparency. The description does not contradict 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 core action and purpose. It efficiently includes the data fields, the target use case, and a key prerequisite without fluff. Every sentence contributes meaningfully.

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 read-only listing tool, the description covers all essential aspects: what it lists, why you'd use it, what data it provides, and the required permission. Even without an output schema, the field list gives sufficient context for expected 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?

With zero parameters and an empty schema, the baseline for this dimension is 4. The description adds value by enumerating the fields that will be returned (windowId, title, frame, owning app details), which helps users understand what they will get even though there are no inputs to document.

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 function: listing on-screen windows available for capture_window. It specifies the data returned (windowId, title, frame, app ownership) and ties it to the capture_window workflow, distinguishing it from generic window listing tools like window_list.

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

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

The description explicitly says the results are for use with capture_window, which implies this is the prerequisite step for window capture. It also mentions the Screen Recording permission requirement, which is a practical prerequisite. It doesn't explicitly exclude alternative uses or compare with sibling tools, but provides sufficient contextual guidance.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description adds value beyond this by explaining the implementation (mdfind, /Applications scan, system_profiler), fallback behavior, performance trade-offs, and permission requirements. This gives the agent a clear picture of what happens during execution.

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

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

The description is concise and front-loaded: the core purpose and return fields are in the first sentence, followed by necessary implementation and parameter details. Every sentence earns its place, with no fluff 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 one optional parameter and no output schema, the description is fully complete. It covers what is returned, how it works, permission requirements, and parameter semantics. The presence of annotations covers safety expectations, so no further behavioral disclosure is needed.

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

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

Schema coverage is 100% and the schema already describes the 'thorough' parameter. The description goes further by contrasting the fast path with thorough:true and explaining what additional info thorough provides (code-signing/obtained-from info), enhancing the schema's bare definition.

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: 'List installed applications' and enumerates the returned fields (name, bundle id, version, path). This clearly distinguishes it from sibling tools like process_list or file_list by focusing on installed applications.

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 how to use the tool, including the fast mdfind path, fallback behavior, and the slower thorough mode. It also states 'No permission required,' which is a useful prerequisite. However, it does not explicitly mention alternatives or when not to use this tool, so it stops short of a 5.

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

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

Annotations already indicate read-only and non-destructive behavior. The description adds value by specifying the exact data returned (frame, visible frame, scale factor, main) and stating that no permission is required, which goes beyond the annotations. It doesn't cover edge cases, but the tool is simple.

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 starts with the verb 'List', immediately states the resource, and includes all relevant details without any wasted words. It is highly concise and well-structured.

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 zero parameters, present annotations, and no output schema, the description is complete enough. It specifies what is listed, the fields returned, and permission requirements. There is no ambiguity about the tool's behavior within its simple scope.

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 tool has zero parameters, so the schema is trivially complete (100% coverage). The description doesn't need to explain parameters, and with zero params, a baseline of 4 is appropriate per the rubric.

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 function: 'List connected displays' with specific attributes (frame, visible frame, backing scale factor, and which one is main). The verb 'List' and resource 'displays' are specific, and the attribute list distinguishes it from other listing 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 provides clear context that it lists monitor information and notes that no permission is required. It doesn't explicitly mention alternatives, but there are no direct sibling tools for monitors, so usage is straightforward. The guidance is clear though not exhaustive.

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

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

Annotations already declare readOnlyHint=true, so the read-only nature is covered. The description adds meaningful behavioral context: it describes the join of running processes with installed plists, lists the exact directories scanned, and states that no permission is required. This provides value beyond the annotation flags.

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

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

The description is a single, well-structured sentence that front-loads the action and resource, then provides necessary detail on data sources. There is no redundancy or filler.

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

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

For a tool with one optional parameter and no output schema, the description covers the core behavior, data sources, and permission requirements. It does not explicitly mention the includeSystem parameter, but the schema provides that detail. Overall, it is sufficiently complete.

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

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

The input schema has 100% coverage with the includeSystem parameter clearly described. The description does not mention parameters, but the schema handles that semantics fully. Baseline score of 3 is appropriate.

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

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

The description clearly states the action ('List') and the resource ('launchd services'), and further specifies the data sources (launchctl list joined with plists from specific directories). This makes it unambiguous and distinguishes it from sibling tools like process_list or list_installed_apps.

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 mention alternatives or when not to use the tool. It does provide a useful usage hint ('No permission required'), implying easy accessibility, but lacks exclusions or comparisons. The intended use case is clear from the resource name, but no explicit guidance is given.

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

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

Annotations already provide readOnlyHint=true and destructiveHint=false. The description adds behavioral context beyond annotations: it uses `ps`, the enrich option cross-references systeminformation.processes() and is slower, and no permission is required. No contradiction with annotations.

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

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

Two sentences with no filler. The purpose is front-loaded, the output fields are compactly listed, and the enrich caveat is included efficiently.

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 tool is simple, has no output schema, and full param coverage. The description covers purpose, output fields, enrichment behavior, and permission requirements. It could mention the limit default, but the schema already handles 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%, so the baseline is 3. The description adds value by explaining the enrich parameter ('additionally cross-reference... slower') and listing the output fields, which complements the schema without redundant 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 opens with a specific verb and resource: 'List running processes' and enumerates the exact output fields (pid, ppid, cpu%, etc.). It clearly distinguishes itself from all sibling tools, none of which list processes.

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: it mentions the underlying command (`ps`), states 'No permission required', and explains the enrich:true option for additional detail with the caveat 'slower'. It doesn't explicitly name alternatives, but the sibling list shows no competing process tool, so the intended usage is obvious.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, establishing it as a safe read operation. The description adds important behavioral context: the tool can always be invoked regardless of the active profile, and it reports specific diagnostic areas. It does not contradict annotations.

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

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

Two tight sentences. Front-loaded purpose ('Report macctl's health') immediately followed by a detailed list, then a crisp usage directive. No wasted words.

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

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

For a zero-parameter tool with no output schema, the description clearly enumerates the diagnostic information returned (TCC statuses, helper reachability, profile tiers, audit log location, version). It also addresses availability and when to use it, making it self-contained for an agent.

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

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

The input schema has zero parameters, so the baseline is 4. The description explains the tool's purpose and output scope, which is sufficient given no parameters are required.

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 uses 'Report' as a specific verb and identifies a clear resource (macctl's health), listing concrete components (TCC permissions, helper reachability, profile tiers, audit log, version). It distinguishes itself from sibling system tools by focusing on permission/helper diagnostics and availability regardless of profile.

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 instructs to 'Use this first when other tools fail with PERMISSION_MISSING or HELPER_UNAVAILABLE' and notes it's 'Always available regardless of profile.' This provides a clear contextual trigger and differentiates it from alternatives that may be blocked in certain profiles.

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

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

Annotations already declare readOnlyHint and destructiveHint, so the description adds extra context by revealing the specific mechanisms (systeminformation, sw_vers, sysctls, system_profiler) and the fact that no permission is required. This goes beyond the annotations without contradicting them, providing useful behavioral insight.

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

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

The description is two sentences, with the primary function front-loaded and supplemental details (sources, permission) included efficiently. Every word earns its place, and there is no redundancy or filler.

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

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

For a tool with no parameters and no output schema, the description adequately lists the types of data returned and the underlying commands. It does not describe the output format (e.g., object structure or value types), but the scope is sufficiently complete for an agent to decide when to invoke this tool.

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

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

The tool has zero parameters, and the schema is empty. The description correctly implies this by not mentioning any inputs. Baseline for zero parameters is 4, and no additional parameter explanation is needed.

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 a specific verb ('Report') and enumerates the exact resources it covers (CPU, memory, disk, network, battery, graphics, macOS version, hardware sysctls, hardware model). This explicitly distinguishes it from sibling tools like system_doctor or list_monitors.

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 when system information is needed by listing the various data categories, but it does not explicitly state when to use this tool versus alternatives like system_doctor, nor does it mention any exclusions. The 'No permission required' note offers some context but does not substitute for explicit 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?

Beyond the annotations (readOnlyHint=false, destructiveHint=true), the description discloses the specific consequence of unsaved changes being lost and the prerequisite of Accessibility permission. This adds meaningful behavioral context.

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

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

Two succinct sentences cover action, mechanism, risk, and permission. 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 two-parameter destructive action with annotations and complete schema descriptions, this description fully covers purpose, mechanism, danger, and permission. No gaps are evident.

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

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

Schema coverage is 100% with clear descriptions for confirm and windowHandle. The description itself adds no additional parameter semantics; 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?

Clearly states the action (close a window) and mechanism (pressing AXCloseButton), distinguishing it from sibling tools like window_focus or window_set_state. The purpose is unambiguous and specific.

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

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

Provides useful context via the destructive warning and Accessibility permission requirement, making clear when to invoke and what to consider beforehand. However, it does not explicitly name alternatives or exclusion criteria, though for a close operation this is less critical.

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

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

Annotations already indicate it is not read-only (readOnlyHint=false) and not destructive (destructiveHint=false). The description adds the Accessibility permission requirement, which is behavioral context beyond the annotations, but does not describe side effects, error behavior, or what happens if permission is missing.

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 short sentences: the first states the action, the second states the requirement. It is front-loaded with the purpose and contains zero fluff 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?

Given a simple single-parameter tool with schema coverage and annotations, the description is adequate. However, with no output schema, it does not mention return values or failure modes. The permission requirement is useful, but the lack of success/error behavior leaves a gap in completeness for an agent.

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

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

The schema provides 100% coverage of the single parameter, windowHandle, with a clear description ('A windowHandle from window_list or window_get_active'). The tool description adds no additional parameter semantics, so the baseline score of 3 applies.

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

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

The description uses a specific verb ('activate') and resource ('a window's owning app') plus the outcome ('raise the window'), clearly distinguishing it from sibling tools like window_close or window_set_state. It also mentions the prerequisite permission, reinforcing its 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 implies usage by stating its core function and the required Accessibility permission, but it does not explicitly contrast with alternative tools or provide when-to-use/when-not-to-use guidance. The permission note gives some context, but no exclusions or alternatives are mentioned.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds value by mentioning that Accessibility permission is required, which is a key behavioral prerequisite not captured in the annotations. It also explains the output's role in chaining, going beyond the structured metadata.

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 concise sentences that pack the core purpose, output details, and a critical prerequisite without any redundant wording. Every phrase 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 simple 0-parameter, read-only tool with strong annotations and no output schema, the description adequately covers the essential usage, permission requirement, and the purpose of the returned handle. It is complete for its intended 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?

The tool has zero parameters, so the schema is trivially 100% covered. The description adds meaningful context about the return value (frontmost application, focused window, windowHandle), which is more than sufficient for a parameterless tool.

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 gets the frontmost application and focused window, specifying a concrete verb and resource. It distinguishes itself from siblings like window_list (list all windows) or window_focus (set focus) by focusing on retrieving the active window and providing a handle for follow-up calls.

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 for when to use this tool: to obtain the frontmost application and focused window, with the windowHandle intended for follow-up calls. However, it does not explicitly name alternative tools or state when not to use it, so it lacks explicit exclusions.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description adds the useful note 'No permission required,' which goes beyond the annotations. It also transparently lists the data returned. No contradiction with annotations.

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

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

The description is a single, focused sentence that front-loads the main action and lists content in a compact, readable manner. Every phrase adds value, with no redundancy or bloat.

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 (no parameters, read-only annotations) and no output schema, the description sufficiently covers what the tool returns. It could be more explicit about whether 'screen layout' applies to all monitors or the primary display, but the overall scope is clear enough for effective use.

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 tool has zero parameters, so the schema is empty and trivially covered. Per rubric, a 0-parameter tool gets a baseline of 4, and the description appropriately does not need to explain parameters.

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 a specific verb ('Get') and resource ('desktop info'), and enumerates the exact content: screen layout frames, visible frames, scale factors, system appearance, and cursor position. This distinguishes it from sibling tools like list_monitors or system_info by its comprehensive 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 provides clear context for when to use the tool (when desktop-wide layout, appearance, or cursor info is needed) but does not explicitly mention alternatives or exclusions. However, the detailed content makes the use case obvious, so it earns a 4 rather than a 5.

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

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

Beyond the readOnlyHint and destructiveHint annotations, the description adds that the tool requires Accessibility permission, which is important behavioral context. It also clarifies the scope ('all on-screen windows') and the nature of the windowHandle ('opaque'). The description goes beyond annotation safety and gives practical operational details without contradicting the annotations.

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

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

The description is two sentences: the first states the action and the output fields, the second provides the permission requirement and usage context. Every word adds value, with no redundancy or filler. It is appropriately sized for the tool's simplicity.

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 (no params, no output schema), the description covers all its essential aspects: what it returns, the permission requirement, and how the result connects to other tools. There is no missing information that would leave an agent uncertain about invocation or expected output.

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 tool has zero parameters, and the schema is empty. The baseline for 0 params is 4. The description does not need to explain parameters; it focuses on output fields, which is appropriate. Since there are no parameters, the description fully covers what the agent needs to know about inputs (that there are none).

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: 'List all on-screen windows'. It enumerates the return fields (title, owning app, pid, bounds, layer, minimized state, windowHandle) and distinguishes itself from sibling tools by focusing on the complete window list rather than active/capturable windows. The reference to passing windowHandle to other window tools further clarifies its role.

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 the tool: when you need an overview of all windows or need a windowHandle for subsequent window operations. It mentions a prerequisite (Accessibility permission) and explains the handle is meant for window_focus/window_set_state/window_move/window_close. It does not explicitly contrast with alternatives like window_get_active or list_capturable_windows, so it lacks explicit exclusions.

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

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

Discloses meaningful behavioral traits beyond annotations: requires Accessibility permission, returns a verified final frame, and notes that apps may clamp requested geometry. This adds context about safety and reliability that annotations (readOnly=false, destructive=false) do not fully capture.

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

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

Three concise sentences, each serving a purpose: action, parameter grouping, and behavioral outcome. No fluff or repetition of schema details; information is front-loaded and easy 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 five parameters and no output schema, the description is complete: it covers what it does, prerequisites, parameter combination rules, return behavior, and potential clamping. The sibling tools are distinct enough that no further caveats are needed.

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

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

With 100% schema coverage, the baseline is 3, but the description adds value by clarifying the grouping logic (x and y together, width and height together, or both sets). This complements the schema's per-field 'requires' notes and helps the agent understand valid combinations at a glance.

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.' It distinguishes from siblings like window_focus and window_set_state by specifying exactly what geometry changes are performed. The independent handling of position and size adds specificity beyond the title.

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 clear context on how to use the tool (pass only x+y, only width+height, or both) and a prerequisite (requires Accessibility permission). However, it doesn't explicitly mention when not to use this tool or name alternatives, though the function is self-evident from the name and description.

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

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

Annotations already indicate a non-read-only, non-destructive operation. The description adds valuable context beyond annotations by clarifying that hide/show affect the owning app, not just the window, and by stating the Accessibility permission requirement. This goes beyond what structured fields convey.

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

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

The description is two succinct sentences, front-loaded with the verb and resource, and enumerates states in a clean parentheses list. Every word contributes without redundancy.

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

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

For a straightforward state-change tool with two required parameters and no output schema, the description covers the action, permission need, and state specifics. It lacks detail on return values or failure behavior, but these are less critical for this type of mutating action.

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 50% schema coverage, the schema documents windowHandle but not the state enum. The description compensates by listing all state values and adding the important nuance that hide/show apply to the owning app, providing meaning beyond the schema's bare enum.

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 uses the specific verb 'Change' with the resource 'a window's state' and enumerates all possible states (minimize, restore, maximize, fullscreen, hide, show), clearly distinguishing it from sibling window tools (focus, move, close).

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 enumerated states imply when to use this tool, but there is no explicit guidance on when to choose this over alternatives like window_focus or window_move. The Accessibility permission requirement provides context but not comparative usage direction.

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