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

The description adds a behavioral detail beyond annotations: 'launching it if needed' discloses that the tool may start an application, which is a side-effectful action. Annotations already indicate readOnlyHint=false and destructiveHint=false, so the description supplements rather than contradicts, but it does not cover failure modes or permissions.

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 first states the core behavior and secondary effect, the second gives a concrete usage instruction with examples. It is front-loaded and 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 single-parameter tool with high schema coverage and annotations present, the description covers the main purpose, the side effect of launching, and the required input format. It could mention error behavior (e.g., app not found) but this is not critical for a simple activation 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% for the single 'name' parameter, and the schema already states it is the application name to focus. The description adds examples and reinforces the input requirement, but this is marginal value on top of an already well-documented parameter.

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

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

The description clearly states the action ('Bring an application to the front') and the resource (an application by name), with examples 'Safari', 'Notes'. It also adds the launching side effect, which helps distinguish it from a pure focus operation, though it does not explicitly differentiate from siblings like open or run_applescript.

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 'so subsequent clicks/keystrokes go to it' implies when to use the tool, but there is no explicit guidance on when not to use it or which sibling tools (e.g., open, type_text) might be alternatives. Usage context is implied rather than stated.

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

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

Beyond the annotations, the description discloses operational requirements: admin mode, an environment flag, and an external dependency (cliclick). This is useful behavioral context that the annotations alone do not provide, such as installation and permission expectations.

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 front-loads the core action ('Click at screen coordinates') and then adds only necessary prerequisites. Every phrase earns its place with no filler 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 point-and-click tool, the description covers the action and all prerequisites. It does not describe the output or failure behavior, but given the simple input schema and absence of an output schema, this is not a significant gap.

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

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

Schema description coverage is 100%, and the description adds no additional parameter-level detail. Since the schema already documents x, y, and button with defaults and semantics, the description does not need to repeat them.

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 'Click at screen coordinates' clearly states a specific verb and resource: it performs a click at a given coordinate. It is easily distinguishable from siblings like move_mouse, drag, and scroll, though it does not explicitly name them.

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 important prerequisites ('Requires admin mode AND MACCTL_ALLOW_INPUT=true, and the cliclick tool'), which helps the agent know when it can be called. However, it does not provide guidance about when to prefer click over alternatives such as key_press, type_text, or open.

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

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

Beyond the destructiveHint annotation, the description adds critical behavioral details: the operation is recoverable (Trash), requires specific permissions, honors an allowlist, and refuses protected paths. This significantly enriches the agent's understanding of 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?

Two sentences convey all essential information with no fluff. The primary action is front-loaded, and constraints are succinctly listed in the second sentence.

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 single-parameter mutation tool with no output schema, the description fully covers how to invoke it correctly: prerequisites, safety restrictions, and the recoverable nature of the operation. Nothing an agent needs to call it successfully is missing.

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

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

The input schema already documents the only parameter ('path' with 'supports ~') at 100% coverage. The description adds that the path can be a file or folder, which is a minor clarification but does not carry substantial extra semantic weight.

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 ('Move') and resource ('file or folder') and clarifies the target ('to the Trash (recoverable)'). This clearly differentiates it from permanent deletion and makes the tool's function 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 clear usage context by stating the required admin mode, MACCTL_ALLOW_DELETE flag, and path allowlist constraints. It does not explicitly name alternatives, but there are no sibling delete tools, so these conditions effectively guide when the tool can be invoked.

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 mutating operation (readOnlyHint=false, idempotentHint=false). The description adds valuable behavioral context by stating the prerequisites: 'Requires admin mode AND MACCTL_ALLOW_INPUT=true, and the `cliclick` tool.' This informs the agent about environmental requirements and external dependencies. It also frames the action as human-style input simulation, which implies side effects on the target UI. 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 sentence that front-loads the core action and then adds necessary prerequisites. There is zero waste—every clause contributes either to the action definition or to operational requirements. It is concise and well-structured for quick comprehension.

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 4 required parameters and no output schema, the description covers the essential operational context: what the action is, its use cases, and its prerequisites. It does not explain the coordinate system (though schema says 'screen points') or potential side effects on the dragged object, but these are reasonably implied. The only minor gap is the lack of explicit statement about the result of the drag (e.g., no return value), but given no output schema, this is acceptable. Overall, it is sufficiently complete for an agent to decide when to invoke it.

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

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

Schema description coverage is 100%: each parameter has a clear description (e.g., 'Start X (screen points).'). The tool description restates these coordinates in prose but does not add additional semantic meaning beyond what the schema provides. The baseline of 3 is appropriate since the schema fully documents the parameters; the description adds no extra parameter guidance.

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 action: press at (x1,y1), move to (x2,y2), and release, explicitly calling it a 'human-style drag'. It lists concrete use cases (select text, move a window, drag a file), which distinguishes it from sibling tools like click, move_mouse, and type_text. The purpose is unambiguous and differentiates from alternatives.

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

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

The description provides clear context by naming the action and its typical uses (select text, move a window, drag a file). It does not explicitly state when not to use this tool or name alternatives, but the specificity of the drag action and the sibling list make the appropriate usage clear. A slight gap is the absence of explicit guidance about when to prefer this over click or move_mouse.

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, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds modest context by specifying 'text contents' and 'macOS', but it does not disclose potential edge cases like empty clipboard or permission requirements. 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?

A single clear sentence contains all necessary information with no filler. It is appropriately sized for such a simple tool.

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

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

For a zero-parameter, read-only operation with strong annotations, the description is complete. It states what is returned (current text clipboard contents) and the platform (macOS), which is all an agent needs to invoke it correctly.

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

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

The tool has zero parameters, so the baseline is 4. The description correctly scopes what is read ('text contents') but has no parameter meaning to add because no parameters exist.

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 ('Return') and names the exact resource ('current text contents of the macOS clipboard'). It is clearly distinct from sibling tools like read_file, list_directory, and get_frontmost_app, leaving 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 purpose strongly implies when to use it: whenever the agent needs the current text from the macOS clipboard. However, it does not explicitly state when not to use it or mention alternatives among the sibling tools, so the guidance is implied 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?

The readOnlyHint and idempotent annotations already establish safety, and the description adds only that the result is a name. It does not contradict annotations, but also does not disclose edge-case behavior or system-specific limitations.

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?

One clear, front-loaded sentence communicates the tool's purpose without filler or unnecessary detail.

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 read-only, no-parameter tool, this is nearly complete. It could optionally mention behavior when there is no frontmost application, but the description covers the core invocation context well.

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 parameter documentation is not needed. The description appropriately focuses on what the tool returns rather than input semantics.

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

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

The description clearly states a specific verb and object: "Return the name of the frontmost (active) application." This distinguishes it from sibling tools like list_apps, list_processes, and system_info.

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?

Usage context is implied by the tool's name and description, but there is no explicit guidance about when to choose this over sibling tools or what to do when no frontmost application exists.

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, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds the qualifier 'main screen' (implying it ignores secondary displays) and the unit 'points', which are useful behavioral details beyond annotations. However, it doesn't disclose the exact return structure (e.g., object vs tuple), so it does not fully exceed annotation coverage.

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

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

The description is a single, front-loaded sentence that states the action, result, and use case with no wasted words. It is highly efficient and immediately actionable.

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, read-only tool with annotations covering safety, the description is complete. It specifies what is returned (width and height in points) and why to use it, which is all an agent needs to invoke it correctly. No output schema exists, so the description's mention of the result format suffices.

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 trivially covers 100% of them. Per the rubric, a baseline of 4 applies for 0-parameter tools. The description does not need to explain parameters, and it doesn't introduce any ambiguity.

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 ('Return') and resource ('main screen size'), and specifies the output format ('in points (width, height)') along with a clear use case ('to reason about click coordinates'). This distinguishes it from sibling tools like get_clipboard or system_info, which serve different purposes.

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 a concrete use case ('use it to reason about click coordinates'), indicating when to invoke it. It does not explicitly name alternatives or exclusions, but the tool is unique among siblings and its purpose is clear, so a score of 4 is appropriate.

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

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

Annotations already indicate it is not read-only (readOnlyHint=false) and not destructive (destructiveHint=false). The description adds a crucial constraint: it requires admin mode and MACCTL_ALLOW_INPUT=true. This is valuable context beyond the annotations. It does not contradict the annotations and gives a concrete prerequisite for successful invocation.

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

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

The description is a single, front-loaded sentence that states the action, examples, modifiers, and prerequisites in order of importance. There is zero redundancy or filler. Every element earns its place, making it optimally concise for an agent to parse quickly.

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 tool with no output schema, the description covers the core functionality, gives examples, and states the critical admin mode requirement. It does not explain what happens on failure or whether the action is synchronous, but given the low complexity and existing annotations, it is adequately complete for an agent to invoke correctly.

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

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

The schema provides 100% coverage for both parameters with clear descriptions ('Key name (return, tab, escape, up…) or a single character' and 'Modifier keys to hold'). The description reinforces these by listing examples and modifier names, but it does not add substantive new meaning beyond what the schema already states. Given high coverage, the 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 presses a key, provides specific examples (return, tab, escape, arrows, character), and mentions optional modifiers. This distinguishes it from siblings like type_text (types a string) and click (mouse action), even though it doesn't name them explicitly. The verb+resource is precise and actionable.

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 explaining what it does (press a key) and the modifiers, but it does not explicitly say when to use this tool over alternatives like type_text or scroll. There are no exclusions or conditions like 'use for single key shortcuts, not for text input.' The context is clear but guidance on selection is left to inference.

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

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

Annotations already declare destructiveHint=true, readOnlyHint=false, and idempotentHint=false. The description adds valuable behavioral context beyond annotations by naming the default SIGTERM and the required prerequisites (admin mode and MACCTL_ALLOW_EXEC=true). It does not contradict any annotation.

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

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

The description is two short sentences, front-loads the core action, and includes the prerequisite in the second sentence. Every word earns its place, with 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?

Given the rich schema (both parameters documented, enum + default provided), strong annotations around destructiveness, and a clear prerequisite statement, the description is sufficient for an agent to invoke the tool correctly. A minor gap is that no return/error behavior is described, but with no output schema this is not required.

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 both pid and signal are already well-documented in the schema, including the signal enum and default. The description only repeats the default SIGTERM behavior and adds no new parameter-level meaning, so the 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 names a specific action ('Send a signal ... to a process by pid'), a concrete resource (process), and the default signal. This clearly distinguishes kill_process from siblings like list_processes (read-only), quit_app (app-level quit), and delete_path (filesystem destruction).

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

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

The description provides explicit usage context: the tool targets a pid and requires admin mode plus MACCTL_ALLOW_EXEC=true, and the schema's pid description tells the agent to use list_processes. It does not explicitly say when not to use it or mention alternatives like quit_app for graceful app termination, but the context is clear enough.

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 cover safety (readOnlyHint, openWorldHint, idempotent, non-destructive). The description adds useful scope detail ('currently running, non-background') but reveals nothing about output format, ordering, or the open-world nature of the result.

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?

One sentence conveys the action, scope, and output in a compact, front-loaded way. 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 zero-parameter read-only tool, this is nearly complete: it specifies the output is names of running non-background applicationsholový and annotations confirm safety. The only small gap is the exact output format, but the description's wording strongly implies a list of strings.

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 zero parameters肯 with an empty schema, so no parameter documentation is needed. The description does not add parameter-level meaning, but the baseline for zero-parameter tools is 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 has a specific verb ('List') and a clear resource ('names of currently running (non-background) applications'). It differentiates from list_processes by focusing on application names and excluding background processes, though it does not explicitly name sibling alternatives.

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

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

The description clearly conveys when to use this tool: when you need names of running applications. It gives no explicit exclusions or comparisons with siblings like list_processes or get_frontmost_app, so guidance is implied rather than stated.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, covering the safety profile. The description adds meaningful behavioral context beyond annotations: it discloses the path allowlist restriction and specifies the return entries (name, type, size). It stops short of describing error behavior, but the annotation coverage lowers the bar.

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 compact sentences: the first front-loads the action and output, the second states the key constraint. No filler or redundant repetition of the schema.

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

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

For a single-parameter, read-only listing tool with strong annotations and no output schema, the description is complete enough for correct invocation. It covers what the tool returns, the path allowlist, and the required input. Minor omissions like sorting or hidden-file handling are not essential.

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 path with minLength and ~ support (100% coverage), so the baseline is 3. The description adds the allowlist restriction, which is a valuable constraint on valid path values not present in the schema, pushing it above baseline.

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

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

The description states a specific verb, 'List', and a clear resource: directory entries including name, type, and size. This unambiguously differentiates it from siblings like read_file (file contents) and list_processes (running 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 intended use is implied by the name and action but never made explicit. There is no mention of when to choose this tool over alternatives, no exclusion criteria, and no routing to a sibling. The allowlist constraint hints at a condition but does not guide usage decisions.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true, so safety is covered. The description adds the ordering behavior ('busiest first') which is not in annotations, providing useful context beyond the structured metadata. It doesn't mention return format or error conditions, but for a read-only list tool, the description adds sufficient behavioral detail.

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

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

The description is a single, front-loaded sentence that states the action, the resource, the returned fields, and the ordering. There is no redundant or unnecessary text; every word adds value. Excellent conciseness.

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

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

For a read-only tool with two optional parameters and no output schema, the description covers the essential information: what is returned and how results are ordered. It does not explain pagination or platform variations, but these are minor for such a simple tool. The description is complete enough for an agent to invoke it correctly without additional guidance.

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%: both 'limit' and 'filter' have clear descriptions in the schema. The tool description adds no additional parameter context beyond what the schema provides. Since the schema fully documents the parameters, the baseline 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 states a specific verb (list) and resource (running processes) and enumerates the returned fields (pid, cpu%, mem%, command). It clearly distinguishes from siblings like list_apps (apps) and system_info (system-level metrics) by focusing on process details. This is a precise, unambiguous 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: if you need process-level details with CPU/memory usage, use this tool. However, it does not explicitly state when NOT to use it or point to alternatives. With siblings like list_apps and system_info present, the guidance is implicit rather than explicit, so a 3 is appropriate.

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

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

Annotations already establish that this is read-only, idempotent, and non-destructive. The description adds meaningful behavioral context beyond the annotations by disclosing the Accessibility permission requirement and restricting scope to the frontmost app.

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, front-loaded sentence states the action, the resource, the returned fields, the practical benefit, and the permission prerequisite. Every clause earns its place 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?

With no parameters, strong read-only annotations, no output schema, and a simple list operation, the description fully covers what an agent needs to call the tool correctly. It names the output fields, scope, and prerequisite.

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 zero parameters, so the baseline is 4. The description correctly avoids inventing parameter details and instead explains the operation's output and scope, which is appropriate 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 uses a specific verb ('List') and resource ('windows of the frontmost app'), and additionally names the data returned: name, position, and size. This clearly differentiates it from siblings like list_apps and get_frontmost_app.

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 'so you can click or drag reliably' gives clear situational context for when to use the tool. It does not explicitly name alternatives or exclusions, but the intended use case is unambiguous enough.

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 meaningful behavioral context beyond the annotations by naming the underlying tool (cliclick) and stating required permission settings. It does not elaborate on failure behavior or side effects, but the prerequisite disclosure is valuable given the annotations only cover read-only/destructive hints.

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 short sentences: the first states the purpose, the second states prerequisites. There is no filler, and the most important 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?

For a simple two-parameter move action with no output schema, the description covers purpose and prerequisites sufficiently. Minor gaps such as coordinate origin and failure behavior are not critical because sibling 'get_screen_size' provides coordinate context and the action is straightforward.

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 both x and y described as coordinates in screen points. The tool description adds no extra parameter meaning, so the baseline of 3 applies since the schema already does the heavy lifting.

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 and resource: 'Move the cursor to screen coordinates.' This clearly states the action and distinguishes it from click/drag/scroll by naming the outcome, though it doesn't explicitly reference sibling tools to differentiate them.

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 concrete prerequisite conditions ('Requires admin mode AND MACCTL_ALLOW_INPUT=true (cliclick)'), which is useful context. However, it does not explain when to choose this tool over siblings like click or drag, leaving the selection to inference.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, idempotentHint=false, and openWorldHint=true. The description adds no further behavioral context such as permission requirements, blocking behavior, or potential side effects beyond 'posting'.

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?

One sentence, front-loaded with the action and resource, with no wasted words. Every part contributes to understanding the tool's core function.

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 tool with no output schema and annotations covering safety traits, the description fully covers what the tool does and what it takes. Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100% with clear descriptions for both parameters. The description simply mentions 'title and message' without adding constraints, formats, or additional meaning beyond the schema.

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

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

States the action ('Post') and the resource ('macOS notification') precisely, with the payload (title and message). No sibling tool provides notifications, so it is easily distinguished.

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

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

No explicit when-to-use or alternative is given, but the purpose clearly implies the use case: displaying a notification to the user. There are no conditions, exclusions, or sibling comparisons.

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 convey the safety profile: not read-only, not idempotent, not destructive, and an external-world effect. The description adds useful behavioral detail that the target is passed to the default handler or launched as an app, but it does not disclose outcomes like focus changes, errors, return behavior, or external side effects in more depth.

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 sentence packs the core behavior and the one mode-switching condition without any filler. It is front-loaded and 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?

For a simple two-parameter tool with full schema coverage, the description covers the main behaviors and the app-mode distinction. It is slightly incomplete only in not describing return/failure behavior, which is acceptable given there is no output schema, but it remains sufficient for invoking the tool correctly.

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

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

Schema coverage is 100%, and the description largely restates what the schema already documents: target can be a path, URL, or app name, with app=true to switch modes. It adds little extra meaning beyond the schema rather than compensating for any gap.

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

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

The description states a specific verb and three supported resource kinds — file/folder path, URL, or app name — and differentiates the app mode with the app=true flag. It reads clearly as the 'open with default handler' tool, distinct from siblings like read_file and run_command.

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 clarifies when to use the tool and even separates the app-launch case via app=true. It does not explicitly name alternatives or exclusions, but the 'default handler' phrasing implies this is not for reading content into the agent, so context is clear.

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

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

Annotations already indicate non-destructive and open-world behavior, but the description adds the graceful nature and the fact that unsaved changes may prompt inside the app. This is useful behavioral context beyond the annotations, though it doesn't mention whether the call returns a result or can fail silently.

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 short, purposeful sentences. It front-loads the primary action and then adds relevant caveats and parameter instruction. No fluff, but the third sentence is slightly redundant with the schema.

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

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

For a simple one-parameter tool with no output schema, the description covers the action, the potential side effect, and the required input. It is sufficient for an agent to invoke correctly, though it could note whether the action is asynchronous or whether it confirms success.

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 parameter name 'name' is described as 'Application name to quit.' The description adds 'Give the app's name,' which is redundant with the schema. With high schema coverage, 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 states a clear verb (ask/quit), a specific resource (application), and a mode (graceful). This distinguishes it from siblings like kill_process (forceful) and open/activate_app, and it names the action without ambiguity.

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 graceful quitting and mentions potential unsaved-change prompts, but it does not explicitly contrast with kill_process or state when to choose this over a force-quit alternative. Usage guidance is implied 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?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, covering safety. The description adds the size cap and path allowlist, which are behavioral constraints not in annotations, providing additional transparency without contradiction.

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

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

Two concise sentences, with the action front-loaded and constraints following. No filler or redundant information.

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

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

For a simple read operation, the description, combined with full schema coverage and annotations, covers the essential behavior. It could mention return format or error cases, but these are not critical given the tool's simplicity and the existing structured data.

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% for the single parameter, with 'path' already described as supporting '~'. The description adds no further parameter semantics, so the baseline of 3 applies 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 verb 'read' and the resource 'text file', with additional constraints (size cap, allowlist) that distinguish it from sibling file operations like write_file or delete_path. It is specific and unambiguous.

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

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

The description implies usage for reading file contents, and the allowlist constraint hints at permitted paths, but it does not explicitly contrast with alternatives or state when not to use it. Given the simplicity and obvious sibling distinctions, this is clear context without 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 mark destructiveHint=true and readOnlyHint=false, so the description does not need to restate those. It adds valuable context by warning that the tool is 'Powerful' and by specifying the admin and environment-variable requirements for execution. This goes beyond the structured annotations by addressing authentication/configuration needs.

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

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

The description is two sentences with no wasted words. The core action is front-loaded, followed by the power caveat and then the prerequisite. Every phrase adds distinct value and nothing is redundant.

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

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

For a tool with only two parameters, an output schema absent, and annotations covering destructive behavior, the description is reasonably complete. It covers purpose, capabilities, and essential prerequisites. It does not describe return values or error behavior, but given osascript's well-known behavior and the schema's completeness, this is a minor gap.

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

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

Schema description coverage is 100%, so the schema already documents both parameters. The description reinforces that the script can be AppleScript or JXA ('JavaScript for Automation'), which maps to the language enum, but it does not add meaningful detail 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 a specific verb and resource: 'Run an AppleScript (or JavaScript for Automation) snippet via osascript.' This distinguishes it from sibling tools like run_command, write_file, or click by naming the exact scripting mechanism and scope. The additional phrase 'can drive any scriptable app' further clarifies its intent.

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 prerequisites—'Requires admin mode AND MACCTL_ALLOW_EXEC=true'—and implies use for scripting apps with 'can drive any scriptable app.' However, it does not explicitly name alternatives or state when not to use this tool versus run_command or other execution tools, leaving some selection judgment to the agent.

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

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

The description adds meaningful context beyond the annotations, explaining that no shell expansion occurs and that execution is gated by admin mode and an allowlist. This complements the destructiveHint=true annotation by showing what preconditions govern execution. It does not describe output or exit-status behavior, but the safety-critical behavior is well covered.

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 dense sentences convey the core behavior, the shell caveat, the required environment flags, and the workaround for pipelines. There is no filler 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?

For calling the tool correctly, the description is largely sufficient: it covers invocation, prerequisites, and argument formatting. It does not mention what the tool returns, but with no output schema that would be helpful; still, the missing return details are less critical than the clearly documented execution constraints.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds value by explaining the no-shell argv semantics and by giving a concrete zsh -c example. This helps the agent understand how to construct arguments correctly rather than just reading field names.

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

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

The description states a precise action: run a program with arguments. It also clarifies the critical distinction from other tools: no shell, pass argv rather than a command line. This clearly separates it from sibling tools like run_applescript or open.

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

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

The description gives explicit invocation guidance: pass argv, not a command line, and use zsh -c for pipelines. It also states prerequisites such as admin mode and MACCTL_ALLOW_EXEC, which helps the agent know when the call will fail. It does not enumerate when to prefer sibling tools, but the usage context is clear.

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

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

The annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds valuable operational context beyond annotations: the tool returns a PNG and requires Screen Recording permission for the host process.

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 short, front-loaded sentences. The first states the action and output; the second states the key prerequisite. No filler or repetition of schema 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 simple zero-parameter tool, the description is complete: it explains what is captured, the output format, and the permission required. The annotations cover safety/idempotency, and there is no output schema that would require return-value documentation.

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

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

There are zero parameters, so per the rubric the baseline is 4. The description correctly indicates that no configuration is needed—just capture the screen.

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: 'Capture the screen' and specifies the output format ('PNG image'). It is clearly distinguishable from all sibling tools, none of which capture the screen.

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 tool's intended use is implied by its name and description, but there is no explicit statement of when to use it versus alternatives, nor any when-not-to-use guidance. The permission requirement 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?

The description discloses a critical behavioral constraint: 'Requires admin mode AND MACCTL_ALLOW_INPUT=true.' This is beyond what annotations provide (which only indicate non-readonly, non-destructive). It also clarifies that scrolling applies to whatever is under the cursor/frontmost, adding operational 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?

A single sentence that front-loads the action and target, followed by the permission requirement. Zero wasted words; every element earns its place.

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

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

For a simple input-action tool with full schema coverage, the description covers the core behavior and the only notable prerequisite (admin mode). It does not describe return values, but as a side-effect action, that is not critical. It is complete enough for correct invocation.

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

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

Schema coverage is 100%: both 'direction' and 'amount' are fully described in the input schema. The description adds no extra parameter semantics beyond what the schema already states, so the baseline 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 clearly states the action: 'Scroll the mouse wheel in a direction by a number of lines' with a specific target ('over whatever is under the cursor / frontmost'). This distinguishes it from sibling input tools like click, move_mouse, or key_press.

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

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

It provides context about the target (cursor/frontmost) but does not explicitly guide when to use this tool over alternatives like move_mouse or key_press. No exclusionary language or mention of alternatives. However, the action is distinct enough that the intended use is fairly 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=false and destructiveHint=false, so the write nature is covered. The description adds the platform context (macOS) and the word 'replace' which reinforces overwriting. However, it does not mention any side effects like clearing other clipboard formats, but this is minor for a simple tool.

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

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

The description is a single, concise sentence with no wasted words. It is front-loaded with the action and resource.

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

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

For a simple tool with one parameter and no output schema, the description plus schema fully specify what an agent needs to call it correctly. No additional context is required.

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

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

The schema has 100% description coverage for the single 'text' parameter. The description adds no extra semantic detail beyond the schema, so the 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 ('Replace') and the resource ('the macOS clipboard contents'), which is specific and distinct from the sibling 'get_clipboard'. The purpose is 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?

While there is no explicit 'when to use' statement, the description clearly implies this is for setting the clipboard, and the sibling 'get_clipboard' suggests the alternative for reading. The usage context is obvious, though not explicitly stated.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is fully covered. The description adds modest value by naming the exact categories returned, but it does not disclose operational details such as output format or timing. This is acceptable for a zero-parameter read-only tool, but it does not exceed the baseline.

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 one sentence with a leading verb and a compact list of deliverables, containing no filler or redundant restatements of the title. 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 tool has zero parameters, no output schema, and clear safety annotations, the description is complete enough for an agent to select and call it correctly. It enumerates all the information categories the tool reports, which is all an agent needs for this simple read-only snapshot.

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

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

The input schema is empty with 100% coverage, so there are no parameter semantics to clarify. Following the 0-parameter baseline, the description does not need to compensate, and listing the reported data categories is more than sufficient.

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

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

The description opens with a specific verb ('Report') and enumerates a precise set of system data: macOS version, hardware, memory, load, uptime, and current user. This clearly distinguishes it from siblings like list_processes, get_clipboard, and list_apps by content, even though it does not name them.

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 an agent needs a high-level snapshot of macOS system state, and the readOnlyHint annotation reinforces that it is a safe diagnostic tool. It does not explicitly state when not to use it or name alternatives, but no sibling covers this exact aggregate of system information and there are no preconditions.

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=false, destructiveHint=false, idempotentHint=false, and openWorldHint=true. The description adds valuable context beyond annotations: it requires admin mode, MACCTL_ALLOW_INPUT=true, and Accessibility permission, and it types into the frontmost app. It doesn't mention whether the text is typed at the current cursor position or whether it replaces existing content, but the permission requirements are significant 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?

One sentence, front-loaded with the core action ('Type literal text into the frontmost app'), followed immediately by the critical prerequisites. Every word earns its place; no fluff or repetition of the schema.

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

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

For a single-parameter tool with a 100% schema coverage and no output schema, the description covers the action, target, and prerequisites. It doesn't explain what happens on failure (e.g., if permissions are missing) or whether the text is typed at the cursor position, but these are minor gaps given the tool's simplicity and the annotation coverage.

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% — the only parameter 'text' is described as 'Text to type.' The description adds the nuance that the text is 'literal' and typed as 'keystrokes,' which is slightly more than the schema provides, but the schema already fully documents the parameter. 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 states a specific verb ('Type'), a specific resource ('literal text'), and a specific target ('frontmost app'), and clarifies it operates via keystrokes. This clearly distinguishes it from siblings like key_press (which sends individual key combinations) and set_clipboard (which sets clipboard content).

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 states the prerequisites for use: admin mode, MACCTL_ALLOW_INPUT=true, and Accessibility permission. It doesn't explicitly name alternatives or say when not to use it, but the prerequisites and the 'literal text' qualifier give clear context for when this tool is appropriate versus key_press or set_clipboard.

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=false and destructiveHint=false, so the description's added value comes from disclosing specific behaviors: allowing path restrictions, protecting certain paths, and requiring confirmation before overwrite. This gives the agent useful safety expectations beyond what structured fields convey. The description does not contradict 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 short sentences that front-load the core action and then compactly list the key behavioral constraints. Every clause adds useful information with no repetition 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 simple two-parameter write tool, the schema covers parameters, annotations cover safety posture, and no output schema is needed. The description is sufficient for correct invocation; a minor omission is not showing an example path or explaining failure modes, but these are not essential here.

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 both parameters are already well described: path supports ~ and content is full UTF-8. The description adds only the generic 'text file' wording, which is not needed to compensate for a documentation gap, so the 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 opens with 'Create or overwrite a text file,' a specific verb-resource pair that clearly identifies the tool's action and target. It also implies a mutation operation, which distinguishes it from read-only siblings like read_file and get_clipboard.

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

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

It provides clear context for when to use the tool—creating or overwriting a text file—and adds practical guardrails: path allowlist, protected-path refusal, and confirmation before overwriting. It does not explicitly name sibling 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.