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 value by specifying the exact data returned and the coordinate system (Cocoa points), which is useful behavioral context. It does not contradict annotations and does not introduce any unknown side effects. A small deduction for not mentioning error behavior or permissions, but this is minor for a simple read-only listing.

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. The action and resource are front-loaded, and the list of returned fields follows naturally without excess words. Every part contributes to 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 read-only tool with no parameters and no output schema, the description is complete. It tells the agent exactly what the tool does and what data it returns. There is no ambiguity about the scope or the result format, as 'List' implies an array and the fields are enumerated. The inclusion of 'in Cocoa points' clarifies the coordinate frame, preventing misinterpretation.

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 coverage is 100% (empty schema). With no parameters to document, the description bears no burden here. Baseline of 4 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 verb 'List' and the resource 'attached displays', and enumerates the specific attributes returned (name, main flag, scale factor, frame in Cocoa points). This makes it unambiguous and distinct from sibling tools like get_system_info or list_applications, which cover broader or different domains.

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. There is no mention of alternatives, exclusions, or conditions. While the purpose is clear, an agent is given no help in deciding between this and other system-inspection tools, such as get_system_info.

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 agent knows this is a safe read operation. The description adds value by specifying the data source (ipify) and the distinction between public and non-internal LAN addresses, giving useful context about what the tool actually returns 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 with no redundancy. It front-loads the exact data returned and then provides a concrete usage example. Every word earns its place, making it 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?

Given there are no parameters and no output schema, the description adequately conveys what the tool returns and why it might be used. It might benefit from mentioning the output format or whether it returns both addresses in a single call, but for a zero-parameter read-only tool, the provided information is largely sufficient.

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 there is nothing to explain beyond what the (empty) schema already conveys. The baseline for 0 parameters is 4, and the description adds no parameter semantics, which is appropriate since none 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 clearly states what the tool returns: public IPv4 (via ipify) and non-internal LAN IPv4 addresses. It uses a specific verb implied by the name and resource, and the mention of ipify and LAN versus WAN distinguishes it from sibling tools like get_system_info and get_system_stats, which focus on system-level data.

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 this to record the home WAN address on the status site.' This provides clear context for when the tool is appropriate, though it doesn't explicitly contrast with alternatives. Given the sibling tools are topically distinct, the guidance is sufficient.

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 readOnly, idempotent, and non-destructive behavior. The description adds one extra behavioral trait: secret-looking keys are redacted, which is valuable for the agent to know (safety/security). That goes beyond the annotations, though it's a single note.

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

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

Two concise sentences with zero filler. The main content (what is returned) is front-loaded, and the redaction note is added as a secondary detail. 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 parameterless read-only tool with safety annotations already covering read-only/idempotent/non-destructive, the description fully covers what the agent needs: the return content and the redaction behavior. No output schema exists, but listing the returned fields suffices for this simple tool.

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

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

With zero parameters, the schema is trivial and the description does not need to explain parameter semantics. Per the rules, the baseline is 4, and the description adds no irrelevant parameter information.

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 returns hostname, OS, architecture, uptime, user, home, and environment variables — a specific list that distinguishes it from siblings like get_network_info (network-specific) and get_system_stats (likely metrics). The verb is implicit in the title, but the resource scope is explicit.

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 lists the exact information returned, making it clear this is for system identity and environment retrieval. It does not explicitly name alternatives or state when not to use it, but the field list implies the use case well enough. No misleading 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, idempotentHint, and destructiveHint=false, covering safety. The description adds useful details like 'short sample' for CPU measurement and 'df -kP' for disk usage, indicating implementation specifics. This adds value but does not cover full return 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 concise sentence that front-loads the key metrics. There is no wasted wording, and it efficiently communicates the tool's output scope.

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 lists the categories returned (CPU, load, memory, disk) but omits units or format details. For a simple stats tool, this is mostly sufficient, but a bit more context on return structure would improve completeness.

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

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

The tool has zero parameters, so schema coverage is 100% vacuously. Per guidelines, baseline is 4 for 0 params. The description appropriately does not mention parameters since none 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 lists specific metrics (CPU percent, load average, memory, disk usage), which clearly states what the tool does. It distinguishes itself from get_system_info by focusing on performance stats rather than system configuration. However, it does not explicitly name sibling alternatives, so it's not a 5.

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 get_system_info or other sibling tools. It implies usage via the stat list but lacks explicit conditions, exclusions, or alternative references.

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 declare readOnlyHint, idempotentHint, and destructiveHint=false, which already communicate that this is a safe, non-mutating operation. The description adds context by specifying the data source (System Events) and clarifying that includeBackground includes agents, which goes beyond the annotation's generic safety profile. No contradictions 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 concise sentences, with the primary purpose front-loaded in the first sentence and the parameter effect in the second. Every word earns its place—no filler. It is easy 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 read-only list tool with a single optional parameter and no output schema, the description is sufficient. It states what is returned (name, pid, visible) and explains the parameter's effect. The annotations cover safety, and the simple nature of the tool means no additional context is required. Nothing critical is missing.

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

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

Schema coverage is 100%, so the schema already documents the includeBackground parameter. The description adds a specific clarification that includeBackground includes agents, which refines the schema's description of 'all processes' and helps the agent understand the parameter's effect in the macOS context. This is a modest but useful addition.

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 identifies the tool as listing foreground macOS application processes from System Events, specifying the captured fields (name, pid, visible). It distinguishes itself from sibling tools like get_system_info or list_roots by focusing specifically on running applications. The inclusion of the source makes the purpose unambiguous.

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

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

The description does not explicitly state when to use this tool over alternatives. It provides no exclusions or guidance on when not to use it. While the purpose is clear, there's no routing to other tools such as get_system_stats or get_system_info, leaving the agent to infer when this list of applications is the right choice.

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 value by disclosing the exact output fields (type, size, modified time, mode), which goes beyond what annotations state. This is useful behavioral transparency for a read-only listing operation.

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 with zero filler. It states the action, scope, and output details efficiently, earning its place entirely.

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 rich annotations, the description adequately covers what it does, what it returns, and its read-only nature. No output schema exists, but the description specifies return fields. It is sufficient for an agent to invoke it correctly without further clarification.

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 the path parameter fully documented ('Directory to list'). The description does not add any additional meaning or syntax beyond the schema, so it meets the baseline for high coverage without needing compensation.

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 ('List files and subdirectories') and the target resource (directory), and specifies the returned attributes (type, size, modified time, mode). This clearly distinguishes it from siblings like read_file (content) and search_files (search), even without naming 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 usage through its clear purpose—list directory contents—but provides no explicit when-to-use vs. alternatives (e.g., read_file for file content, list_roots for root dirs). No exclusions or conditions are given, so agents must infer the appropriate context from the name and description alone.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering safety. The description adds valuable context: the tool returns the set of allowed roots and that file tools enforce this restriction. This goes beyond the annotations by explaining the relationship with file tools, which is useful behavioral information.

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

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

The description is two sentences with zero waste. The first sentence states the primary function, and the second provides the key behavioral context (enforcement). It is perfectly 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 no-parameter, read-only tool, the description covers its purpose and the reason it matters. It could explicitly mention the return format (e.g., absolute paths), but the output is simple and the enforcement note adds completeness. No output schema exists, so the description carries the burden, but it is largely sufficient.

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 description needs to explain nothing about parameters. The baseline for 0 params is 4, and the description correctly omits any parameter detail since none 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 and resource: 'List directories' that are allowed roots. It clearly states the tool's function and adds context that these are the only directories the server can read/write. It doesn't explicitly differentiate from siblings like list_directory, but the scope is obvious and distinct.

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: it tells you that file tools reject paths outside these roots, so the agent can infer this tool is used to know valid paths before invoking file tools. However, it does not explicitly state when to use this versus alternatives, or provide exclusion conditions. The 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering safety. The description adds that it uses pbpaste to read clipboard as text—clarifying output format and implementation detail. No behavioral gaps remain.

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 that conveys purpose, scope, and method with zero redundancy. 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 tool with no output schema, the description adequately specifies the return type ('as text') and the operation. No missing details are required 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 schema provides no information. Per the rubric, a baseline of 4 applies. The description correctly states the tool takes no input, as evidenced by the empty schema, so no further 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 states a specific verb ('Read'), resource ('current macOS clipboard'), and output format ('as text'). It clearly distinguishes from siblings like write_clipboard (write vs read) and read_file (clipboard vs file).

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 the tool is for clipboard content, distinct from file and system tools. However, it does not explicitly mention when to prefer this over a sibling or any alternatives. The single-purpose nature and obvious name make it clear enough, but explicit routing guidance is absent.

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=false. The description adds behavioral context beyond these: the allowed root restriction, the base64 encoding requirement for binary files, and the 1-based line numbering semantics. 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 concise sentences with no fluff. Every clause adds information: the core purpose, encoding guidance, and offset/limit semantics. It is efficiently 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 read operation, the description covers the essential points: purpose, allowed root constraint, encoding options, and offset/limit behavior. It does not explicitly state the return format (file content), but that is implied by 'read a file'. Given no output schema, this is a minor gap, but overall the description is sufficient for an agent to call 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?

Schema coverage is 100%, with each parameter having a description. The description adds the crucial clarification that offset and limit are 1-based line numbers, which is not explicitly stated in the schema (schema only says 'First line to return'). It also reinforces the encoding choice for binary. This adds meaningful value beyond the schema.

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

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

The description clearly states the tool reads a file within an allowed root, using a specific verb and resource. It distinguishes itself from sibling tools like write_file, list_directory, and search_files by focusing on reading a single file's content. The 'allowed root' constraint adds important 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 gives operational tips (encoding for binary, 1-based offsets) but does not explicitly compare with alternatives. It implies usage for reading a file but lacks guidance on when to prefer this over list_directory or search_files. No explicit when-not-to-use conditions 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 declare destructiveHint=true, readOnlyHint=false, idempotentHint=false, which already convey it's a potentially destructive, non-idempotent mutation. The description adds useful details: captures stdout/stderr separately, supports streaming with progress notifications, cwd restriction, and default timeout from env var. However, it doesn't mention that commands could have side effects beyond the hint, or what happens on timeout (e.g., process killed?). It doesn't describe security implications of running arbitrary commands. Adding these would increase transparency, but given annotations already flag destructiveness, the description adds moderate value.

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

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

The description is compact, three sentences, each conveying a distinct point. The first sentence states the core behavior with stream capture. The second explains streaming. The third states a critical constraint. No fluff, well organized.

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

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

The tool has 4 parameters, all documented in schema, and the description covers the key constraints (cwd restriction, streaming behavior, timeout default). However, no output schema is present, and the description does not describe the return value format (e.g., how stdout/stderr are returned, exit code, error handling). For a tool that runs arbitrary commands, the agent would benefit from knowing the response structure. Given destructiveHint, it might also be good to state that the command may mutate state. Overall, it's functional 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?

Schema coverage is 100%, so all four parameters (command, cwd, stream, timeoutMs) are documented in the schema itself. The description adds context for cwd (must be inside allowed root) and stream (sends progress notifications), which supplements the schema. It also mentions timeout default from env var. This goes slightly beyond schema, but because the schema already describes each parameter adequately, the description's added value is modest. Baseline 3 is appropriate.

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

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

The description clearly states the tool runs a command with the user shell, capturing stdout and stderr separately. It distinguishes itself from other file/system tools, though it doesn't explicitly differentiate from a potential 'run_script' sibling (none exist). It's specific about behavior (captures streams, supports streaming).

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 mentions the cwd restriction (must be inside allowed root unless environment variable overrides), which is a usage constraint. However, it does not explicitly state when to use this vs alternatives (e.g., when to use read_file/write_file instead). It provides no guidance on when not to use it, such as for read-only operations. The streaming option is explained but no guidance on selecting it. Overall, context for choosing this tool is lacking.

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 read-only, idempotent, and non-destructive behavior, so the description adds value by disclosing that symlinks are not followed and that contentPattern matches per line. Yet it omits behavior like recursion depth, how maxResults affects results, or the output format (paths vs. line matches), which are not covered by annotations.

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

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

Four concise sentences, each serving a distinct purpose: the scope (walk an allowed directory), the name pattern semantics, the content pattern semantics, and a key behavioral limitation. No fluff, front-loaded with the main action.

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

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

The description covers the core search semantics and a safety-related detail, but it leaves critical gaps: no mention of whether the walk is recursive, what the returned results look like (file paths, line numbers, matched content), or how maxResults interacts with results. An agent could call it confidently for intent but may be unsure of the return contract, especially given no output schema exists.

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 description coverage, the baseline is 3. The description goes beyond the schema for namePattern ('glob (* and **)') and contentPattern ('JavaScript regex matched per line'), clarifying syntax and matching semantics that the schema leaves vague. This meaningfully aids correct invocation.

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

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

The description states the resource (an allowed directory) and the action (walk) plus the two patterns that define a search. It's clear this tool filters files by name glob and content regex, distinguishing it from list_directory and read_file, though it doesn't explicitly say 'search' or 'find'.

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 implies usage: use when you need to find files by name or content in a directory. However, there's no explicit guidance on when to prefer this over list_directory for inert listing or read_file for specific file access, nor any mention of alternatives or exclusions. The agent must infer the appropriate context.

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

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

The description says it 'Saves PNG under an allowed path', implying a write side effect that modifies the filesystem, while the annotations declare readOnlyHint=true indicating no state change. This is a direct contradiction, so the description actually misleads the agent about the tool's 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?

The description is concise, front-loads the action and key details, and avoids fluff. However, it could be better structured to highlight the side-effect contradiction and missing parameter semantics.

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 with 3 optional parameters, but the description omits the meaning of includeCursor, does not specify the default display when omitted, and fails to mention the return value (likely the saved file path). It also doesn't clarify behavior when an invalid path is given or permission is denied.

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 67%, so the baseline is 3. The tool description repeats the display ID and path behavior from the schema but adds no new details, especially for the includeCursor parameter which remains undocumented in both the schema and description.

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 captures the screen via screencapture and saves a PNG, distinguishing it from display-info tools like get_display_info in the sibling list. It specifies the verb and resource precisely with no 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 does not provide any guidance on when to use this tool versus alternatives, nor does it mention any exclusions or prerequisites beyond the permission requirement. It lacks explicit when-to-use or when-not-to-use context.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the description need not repeat them. It does add the context that this uses pbcopy, which hints at execution of a system command, and that it replaces the clipboard. However, it does not add significant behavioral detail beyond that, such as potential side effects 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?

The description is a single, concise sentence that directly states the action, the platform, and the underlying command. There is no superfluous information; it is front-loaded with the core purpose.

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

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

For a simple one-parameter tool with no output schema, the description covers the essential information: what it does (replace clipboard), the platform (macOS), and the command (pbcopy). It is complete enough for an agent to invoke it correctly, though it could have mentioned that it overwrites the existing clipboard, but that is implied by 'replace'.

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% description coverage for the single parameter 'text' ('Text to place on the clipboard'). The description essentially restates this as 'given text', adding no additional semantic value beyond the schema.

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

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

The description clearly states the action 'Replace the macOS clipboard with the given text' and explicitly mentions 'pbcopy', which is the underlying command. This distinguishes it from sibling tools like read_clipboard, 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 clear context: it is for setting the clipboard on macOS. While it does not explicitly name alternatives or say when not to use it, the context is clear enough for an agent to understand when this tool is applicable. It does not mention exclusions, but the platform-specific hint ('macOS') implies this is not for other OSes.

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, but the description adds meaningful behavioral context beyond that: it explains that 'createDirectories mkdir -p the parent' and 'append adds to an existing file', which are not covered by annotations. It also clarifies the overwrite semantics, consistent with the destructive hint. This improves the agent's understanding of 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?

The description is three short sentences, with the primary purpose front-loaded. It avoids redundancy with the schema and uses compact phrasing. The only minor issue is the cryptic 'mkdir -p the parent' idiom, which could be clearer, but overall it is efficient and to the point.

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 file-write tool with destructive annotations and a schema covering most parameters, the description covers the essential behaviors: overwrite, allowed-root scoping, parent-directory creation, and append mode. There is no output schema, so return values aren't expected. It doesn't address error handling or permission details, but these are not essential given the other structured support. It is adequately 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 coverage is only 60% (path, content, encoding are documented; append and createDirectories are not). The description fills that gap by explaining 'createDirectories mkdir -p the parent' and 'append adds to an existing file', clarifying the two undocumented parameters. It doesn't add anything for the already-documented parameters, but it effectively compensates for the coverage shortfall.

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 file', giving a specific verb and resource, and adds a critical scoping constraint ('inside an allowed root') that distinguishes it from sibling tools like write_clipboard or read_file. It clearly identifies this as a file-write 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 states what the tool does but gives no explicit guidance on when to use it versus alternatives. It does mention the allowed-root constraint, which is relevant context, but it doesn't say when not to use it (e.g., 'use read_file to read') or provide any exclusion criteria. The intended use case must be inferred.

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