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

With no annotations, the description carries the full burden, and it does disclose one genuinely useful trait: partial results survive the cancellation. It says nothing about permissions, whether cancellation is immediate or graceful, or the error case when nothing is running.

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, action stated first and the consequence of calling it second. Every clause carries information and nothing is padded.

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 action with no output schema, the description covers what it does and the main side-effect question (are results lost). Only the no-active-scan behavior and any return signal are 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 tool takes zero parameters, so there is nothing for the description to disambiguate; baseline 4 applies. The empty schema is consistent with a no-argument action.

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?

"Stop the running scan" gives a specific verb (stop) and resource (scan), which clearly separates it from start_scan and get_scan_status in the sibling list. It doesn't explicitly name those siblings, so it falls short of the top score.

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 word "running" implies the tool applies only when a scan is active, but the description never states what happens if no scan is running, whether re-calling is safe, or that start_scan/get_scan_status are the counterparts. Usage is only implied.

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 only say destructiveHint=true; the description adds the crucial facts that deletion is permanent and irreversible, that user-placed items are included, and that macOS may surface an OS-level permission prompt. These are exactly the behavioral details annotations cannot convey.

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

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

Four short sentences, front-loaded with what gets destroyed, followed by irreversibility, the call precondition, and the OS prompt. Every sentence carries information an agent needs before invoking.

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 one-parameter destructive tool with no output schema, the description covers scope, irreversibility, confirmation gate, call precondition, and a possible OS interruption. Nothing needed to invoke it safely 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% and already says confirm "Must be true," so the schema does the heavy lifting. The description reinforces the parameter as a safety gate ("Requires confirm: true"), adding intent framing beyond the schema's bare constraint, though not new mechanics.

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 a specific verb and resource ("Permanently delete everything in the Trash") and adds scope detail — including items the user placed there themselves — that separates it from the sibling move_to_trash. An agent can pick the right tool without opening either schema.

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?

Gives an explicit precondition ("Only call after the user explicitly asks to empty the Trash") rather than implied usage. The distinction from move_to_trash is implicit in the verb choice but the gating condition is unambiguous.

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?

readOnlyHint=true already tells the agent this is a safe read; the description reinforces it by describing a pure information read. It adds a useful scope constraint ('startup disk', implying other volumes are not covered), but says nothing about units, rounding, or error behavior when the disk is unavailable.

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 short clause that front-loads the returned values. It is efficient with no padding, though the fragmentary phrasing (no verb) makes it read more like a label than a description.

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 query with annotations carrying the safety profile, the description covers what an agent needs to call it. Minor gaps (units, formatting of returned numbers) are tolerable given there is no output schema, though they would be nice to have.

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 takes zero parameters, so the baseline of 4 applies. There is no argument surface that the description needs to explain.

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?

Names the resource ('startup disk') and the exact data returned ('total, used and free space'), which no sibling tool provides, so it is distinguishable from the scan/trash/protect tools. It is a noun phrase rather than a verb+resource statement, which slightly weakens it but the meaning 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?

No indication of when an agent should call this versus alternatives (e.g. before deciding to run a scan or empty trash), and no exclusions. An agent must infer usage entirely from the topic.

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?

readOnlyHint=true already covers the safety profile, so the description's added value is the blocking semantics of wait_seconds and the fact that results are per-category size summaries. It does not say what happens when the scan is already finished or when the wait times out other than implicitly.

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, front-loaded with what is returned and followed by the one decision the caller has to make. There is no 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 single-optional-parameter read tool with annotations and no output schema, this covers the essentials: what comes back and how to make it wait. It could be more complete by mentioning the timeout ceiling and the behavior when no scan is active.

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

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

Schema coverage is 0%, yet the description explains what wait_seconds actually does — it blocks until the scan completes or the timeout elapses — which the bare integer schema does not convey. It omits the 0–50 bound and that the default of 0 means non-blocking, so it doesn't fully compensate for the coverage 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 names the resource (the current scan) and what it returns (progress plus a per-category size summary), which is enough to separate it from siblings like start_scan or cancel_scan. The verb is only implied by the name 'get' rather than stated, keeping it just short of 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?

It gives real guidance for the blocking case ('set wait_seconds to block until the scan finishes or the time runs out'), which implies the alternative is a non-blocking poll. However, it never states when to call this versus list_categories or get_disk_usage, nor what to do if no scan is running.

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?

readOnlyHint=true already covers the safety profile, and the description adds genuinely new behavior: categories carry a 'safe' vs 'review' risk level with an operational instruction to confirm 'review' items with the user. That's decision-relevant context beyond the annotation, though the shape of the returned list is left unspecified.

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, front-loaded with what the tool returns and immediately followed by the risk-level semantics that govern downstream actions. No filler or restatement of the tool name.

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 and no output schema, the description must carry the return-value burden; it explains the risk-level field and the action it implies, which is the key information. It omits other likely fields (category names, item counts) and any mention of how this feeds start_scan, but nothing essential to calling 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?

The tool takes zero parameters, so the baseline of 4 applies; there is nothing for the description to disambiguate on the input side.

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?

"What MacSweep can scan" plus the risk-level explanation makes clear this returns the set of scannable categories and their safety classification. It's a specific resource, but it never explicitly contrasts with list_items or start_scan, so an agent must infer the boundary from the name.

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 is only implied: the risk-level guidance ("check each item with the user") hints the agent should consult this before acting, but there is no explicit when-to-call, no prerequisites, and no reference to any of the eleven sibling tools such as list_items or start_scan.

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

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

Annotations already declare readOnlyHint=true, so safety is covered. The description adds useful context about what is returned (path, size, mtime) and the 'latest scan' constraint, but says nothing about pagination, empty results, or whether results reflect the most recent scan only.

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

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

Two tight sentences with the primary purpose front-loaded and the downstream constraint second. No wasted words.

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

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

With no output schema, the description partly compensates by naming returned fields, which is good. But for a tool with 4 parameters and pagination defaults, the lack of any ordering or paging explanation leaves a real 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 0% across 4 parameters. The description only implicitly covers 'category' ('one category'); it says nothing about sort options, limit (max 500, default 50), or offset, leaving the agent to infer pagination and ordering from enum values alone.

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

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

States a specific verb and resource ('Items found in one category'), scoped to 'the latest scan', and names the returned fields (path, size, last modified). It clearly differs from list_categories, though it doesn't explicitly contrast itself with that sibling.

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 sentence 'Only these exact paths can be passed to move_to_trash' establishes a downstream dependency and implies the tool is the way to obtain trashable paths. However, there's no explicit when-to-use vs list_categories guidance, no mention of needing a completed scan, and no 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?

The annotations already declare readOnlyHint=true, and the description adds a meaningful behavioral guarantee: protected paths are never offered or removed by MacSweep. It does not describe return ordering or format, but no output schema exists and the added safety context is substantial.

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 with no filler. The resource identity is front-loaded and the safety guarantee follows directly.

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 read tool with annotations covering safety, the description is largely complete: it says what the set represents and guarantees these paths are not offered or removed. It could more explicitly state that it returns the full protected-path list, but the current text is adequate.

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

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

The tool has zero parameters and an empty input schema, so there are no parameter semantics to explain. The baseline for a zero-parameter tool 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 identifies the resource as the set of paths the user chose to keep, and adds that MacSweep never offers or removes them. The listing action is only implicit, inherited from the tool name, and no sibling tool is explicitly named.

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?

There is no explicit when-to-use or when-not-to-use guidance, and no alternatives are mentioned. The second sentence explains a protection guarantee rather than helping the agent choose between this and sibling tools such as list_items or protect_path.

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, it discloses that moved items are restorable until Trash is emptied and that certain paths are refused. It also explains the default safe dry-run behavior and what happens when dry_run is false.

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 four sentences with no wasted text, and it front-loads the core action, safety workflow, and dry-run semantics. Each sentence adds useful information.

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

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

For a destructive mutation tool with no output schema and only two parameters, it covers the essential context: safety approval, dry-run behavior, restorability, and refusal cases. An agent has enough information to call it safely and 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?

With 0% schema description coverage, the description carries the parameter burden and does well: it explains dry_run's default and effect, and clarifies which paths are refused. The only minor gap is that it does not specify path formatting such as absolute vs relative.

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: move items from the latest scan to the Trash. It also distinguishes the operation from empty_trash by clarifying that items remain restorable until the Trash is emptied.

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 gives an explicit mandatory workflow: show the user the list and total size and obtain explicit approval before acting. It also explains that dry_run defaults to true and must be set to false to perform the move, which clearly defines when and how to invoke the mutation.

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?

Only idempotentHint is provided, so the description carries most of the burden and does add real substance: it discloses the recursive scope ('and anything inside it') and the persistent suppression of future removal offers ('again'). It does not mention reversibility via unprotect_path, how protection can be inspected (list_protected), or what happens if the path is already protected or nonexistent.

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 with no filler; the behavioral effect is front-loaded and the usage trigger follows. Nothing could be cut without losing 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 one-parameter state-changing tool with no output schema, the description covers the effect and trigger but omits the lifecycle context an agent needs: that protection is reversible via unprotect_path and enumerable via list_protected. The omission is tolerable but leaves a gap in an otherwise minimal definition.

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

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

Schema coverage is 0% for the single 'path' parameter, so the description is the only source of meaning and it does clarify that path may be a file or a folder and that protection applies recursively. However, it gives no information on path format (absolute vs relative, URI vs filesystem path) or error behavior for invalid paths, so it only partially compensates for the coverage 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 conveys a specific effect — the file/folder and everything inside it will never be offered for removal again — which is distinct from siblings like move_to_trash or unprotect_path. It never states the verb 'protect' directly and phrases the effect as an imperative ('Never offer or remove...'), which reads slightly like an instruction to the agent rather than a tool capability, but the meaning is inferable. Sibling differentiation is implicit rather than named.

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?

"Use when the user says to keep something" gives a clear triggering context, which is exactly what the agent needs to select this over move_to_trash. It does not name the inverse operation (unprotect_path) or state when not to use it, leaving the agent to infer the undo path.

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 the operation is read-only, and the description adds the meaningful behavioral fact that this spawns a visible GUI action (a Finder window) rather than just returning data. It does not disclose platform requirements (macOS-only) or failure behavior for invalid paths, which keeps it from a 5.

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 immediately followed by the user-facing rationale. Nothing wasted and nothing buried.

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 one-parameter, no-output, read-only tool with annotations present, the description covers what happens and why. Missing path-format expectations and platform constraints are the only real gaps.

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

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

The schema has 0% description coverage for the single required `path` parameter, so the description must carry the load. 'This item' hints that path refers to a filesystem item, but it never specifies expected format (absolute vs relative) or whether the path must 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?

States a specific verb and effect: 'Open a Finder window with this item selected', which is concrete enough for an agent to know exactly what happens. It lacks explicit differentiation from siblings, but no sibling in the list does anything similar, so ambiguity risk is low.

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?

'so the user can look at it' implies the usage context — revealing a file for human inspection — but never states when to prefer this over, say, list_items or simply returning a path. The usage signal 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?

Adds substantial behavior beyond the readOnlyHint annotation: the call returns immediately, the work runs in the background, a full scan takes 1-5 minutes, and the time is dominated by 'large_files' and 'dot_cache'. It does not say what happens to a previously completed scan's results or whether concurrent scan starts are rejected.

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

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

Three short sentences, each carrying distinct information: async contract, follow-up tool, duration profile, and the performance lever. The async/follow-up contract is front-loaded, which is exactly what an agent needs first.

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 output schema, the description correctly redirects to get_scan_status for results, and the timing estimate sets realistic agent expectations. Minor gaps remain around concurrent invocation and result persistence, but nothing blocking 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%, so the baseline is 3, but the description adds a genuinely new semantic: subsetting categories is 'much faster', which changes how an agent should choose the parameter. The omit-to-scan-everything behavior repeats the schema 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?

States a specific verb and effect ('Start scanning in the background') and immediately distinguishes the asynchronous behavior from the blocking sibling by naming get_scan_status. What exactly is scanned is only implied, but the categories enum and the cleanup-oriented siblings make the domain obvious.

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

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

Gives clear follow-up routing ('follow up with get_scan_status') and a performance-driven usage rule ('Pass categories to scan only some of them (much faster)'). No exclusions are stated, e.g. what to do if a scan is already running or when cancel_scan is the right move.

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 second sentence discloses a genuinely non-obvious consequence the annotation does not cover: the path reappears in the next scan, implying the removal is not a durable exclusion. That is useful context an agent would not otherwise infer. However, it is ambiguous whether the path is re-protected or merely re-listed, and no permission or mutation semantics are given.

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 with zero waste; the action is front-loaded and the side-effect caveat follows immediately. Nothing is padded.

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 only idempotentHint and no output schema, the definition covers the action and one side effect but leaves the path format and the exact meaning of the reappearance unstated. It is workable but has clear gaps that matter before calling 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?

The single path parameter has no schema description at all (0% coverage; only type string), so the description carries the full burden. It says only 'a path' and gives no indication of format, absolute vs relative, or whether files and directories are both accepted. It does not compensate for the schema 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?

States a specific verb and resource: remove a path from the protected list. This is clearly the inverse of the sibling protect_path, but it never names that sibling to make the distinction explicit. The intent is unambiguous without opening the schema.

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 is only implied via the resource name; there is no explicit 'use this when' or reference to the alternative (protect_path) or to list_protected for verification. No prerequisites or scope conditions are given beyond the protected-list framing.

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