Remote Desktop Commander

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

Beyond annotations, the description discloses that the operation is idempotent in effect ('ensure a directory exists'), supports nested creation, and is sandboxed to allowed directories. It does not detail failure modes such as an existing file at the target path, but the core 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?

The description is reasonably concise and front-loads the primary purpose before adding behavioral and path guidance. The final invocation-alias sentence is slightly extraneous to tool semantics but still useful for agent instruction matching.

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 annotations and no output schema, the description covers purpose, idempotency, nested creation, directory restrictions, and path semantics. It is complete enough for correct invocation, though it could mention what happens if the target path already exists as a file.

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 only 50%, with no description for the required path parameter. The description compensates by explaining path resolution behavior: relative paths depend on the device working directory, tilde paths may not resolve, and absolute paths are most reliable.

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: creating a directory, with the additional idempotent behavior of ensuring it exists. It also notes nested-directory creation, which makes the tool's scope unambiguous relative to file-writing siblings.

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

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

The description gives clear usage context: it creates directory paths, can create nested directories in one operation, and only works within allowed directories. It does not explicitly name alternatives, but it provides enough constraint information to guide correct use.

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

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

Goes well beyond the destructiveHint/readOnlyHint annotations, disclosing vocabulary: default single replacement, expected_replacements behavior, a character-level diff on near-miss matches, header/footer fallback for DOCX, XML repack after edit, and the configurable fileWriteLineLimit warning. This is exactly the extra context an agent needs before mutating a file.

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 format-by-format structure is well organized and front-loaded, but it is long and repeats expected_replacements semantics three times (text-file section, default paragraph, uniqueness requirement). Tightening those overlaps would preserve all value at lower length.

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

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

Covers the hard cases for a destructive multi-format editor: per-format parameter sets, match-uniqueness failure feedback, and line-limit warnings. Path resolution caveats are included; only the undocumented 'options' parameter remains unaddressed.

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 only 13% schema description coverage, the description carries most of the load and does so for file_path, range (FROM:TO sheet syntax), content (2D array example), old_string/new_string, and expected_replacements. The nested 'options' object and deviceId receive no explanation, leaving a 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 ("Apply surgical edits to files") and its opening line signals scope even for multiple file formats. It implicitly separates itself from write_file by emphasizing small, verifiable edits, though it never names a sibling tool explicitly.

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 operative guidance: prefer small focused edits, make separate calls for distinct changes, include minimal surrounding context for uniqueness, and copy DOCX XML from read_file output. It lacks an explicit "use write_file for full rewrites" exclusion, so the alternative routing 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?

The annotations already declare the key safety profile: destructiveHint=true, readOnlyHint=false, openWorldHint=false. The description adds only that the target is a terminal session, without explaining consequences, child-process handling, or permission requirements. It does not contradict the annotations, but it adds minimal behavioral context beyond them.

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

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

The first sentence is concise and front-loaded. The second sentence, about how the command may be referenced as "DC: ...", does not help an agent select or invoke the tool and is unnecessary noise for this definition.

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 terminal-session termination tool with a close sibling like kill_process, the definition omits important context: when this tool should be chosen over alternatives, what happens to the terminated session, and what pid refers to. Annotations cover the general destructive nature, but they do not fill these selection and parameter 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?

Schema description coverage is only 50%: deviceId is documented, but pid has no schema description. The description does not mention either parameter or explain what pid identifies, so it does not compensate for the undocumented 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 gives a specific verb and resource: "Force terminate a running terminal session." It is clear what the tool does and distinguishes terminal sessions from general process termination. However, it does not explicitly differentiate itself from the sibling tool kill_process, so it falls 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?

The description states the action but gives no guidance on when to use this tool versus kill_process, shutdown, or interact_with_process. There are no prerequisites, exclusions, or contextual conditions beyond the implied target of a running terminal session.

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, openWorldHint=false, so the safety profile is settled. The description adds that the whole config is returned in JSON and enumerates the sections, but says nothing about whether sensitive values are redacted, caching, or size — modest added value beyond 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?

Front-loaded with the core action, which is good, but the ten-item field list is long and largely restates what the returned JSON will show. The trailing 'DC: ...' invocation-style note is metadata about the product rather than guidance for invoking the 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?

With no output schema, enumerating the returned fields does genuine work in telling the agent what it will get. The deviceId behavior is covered by the schema, and annotations cover safety, so only minor gaps (sensitive data handling) remain.

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

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

Schema coverage is 100% and the single optional deviceId parameter is fully documented in the schema itself. The description adds no routing detail for the multi-device case, so baseline 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?

States a specific verb and resource ('Get the complete server configuration as JSON') and implies the counterpart relationship with set_config_value. It doesn't explicitly name sibling tools that read a narrower slice (who_am_i, get_usage_stats), so an agent must still infer why this one over those.

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: it's a read of full config, so you use it when you need configuration values. There is no explicit when-to-use/when-not guidance, nor any routing away from set_config_value (mutation) or the narrower identity/stats tools.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds useful behavioral context beyond annotations: allowed-directory restriction and caveats about relative, tilde, and absolute path reliability across devices.

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 front-loaded with the core purpose and uses a structured list for return fields, which is useful because there is no output schema. It is somewhat long and includes an optional DC reference, but the added detail generally earns its place for a metadata-inspection 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?

Given there is no output schema, the description usefully enumerates expected metadata fields, including special handling for text and Excel files. It also covers the key path/device caveats and allowed-directory restriction, leaving only minor unspecified behavior such as error handling for invalid paths.

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 50%, with deviceId described but path left undocumented in the schema. The description compensates strongly for path by explaining that paths refer to the selected device, relative paths depend on its working directory, tilde paths may not resolve, and absolute paths are most reliable.

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: 'Retrieve detailed metadata about a file or directory.' It also enumerates the metadata fields returned, making the purpose clear without needing to inspect the schema, though it does not explicitly distinguish the tool from siblings like list_directory or read_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?

It gives an important constraint ('Only works within allowed directories') and path-resolution guidance, which imply usage conditions. However, it does not say when to use this tool vs alternatives such as list_directory or read_file, nor does it provide 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 cover the safety profile (readOnly, non-destructive, closed-world), and the description still adds real behavioral detail: range-limited return values, 'along with search status', and the non-obvious rule that length is ignored with a negative offset. It omits what happens at end-of-results or when the session is closed, which is the main remaining gap.

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 purpose is front-loaded in the first sentence and the examples genuinely earn their place by disambiguating the negative-offset semantics. There is some redundancy: the defaults (0, 100) are restated from the schema, and the closing 'DC: ...' branding line adds nothing to tool selection.

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

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

For a 4-parameter pagination tool with no output schema, the description is nearly self-sufficient: it explains range behavior, tail reads, and return contents. Missing are the required sessionId's meaning and failure behavior (expired/unknown session), which an agent likely needs in practice.

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 25% and the schema gives no descriptions for offset/length, so the description carries that load well with concrete examples and the negative-offset tail edge case. However, the required 'sessionId' parameter is explained nowhere, in either schema or 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 resource ('Get more results from an active search') plus the mechanism ('offset-based pagination'), and implicitly anchors it to start_search as the originating tool. An agent can distinguish it from start_search, stop_search and list_searches 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?

'call this repeatedly to get progressive results from a search started with start_search' gives the exact precondition and the iteration pattern, and 'Works like read_process_output' supplies an analogy to a sibling tool. It stops short of explicit when-not-to-use cases (e.g. after stop_search or once exhausted), so it is strong but not exhaustive.

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

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

Adds substantial context beyond the readOnlyHint/openWorldHint annotations: persistence path (tool-history.jsonl), a 1000-call in-memory cap, on-disk trimming, 4 KiB output omission markers, and self-call exclusion. These are exactly the retention and completeness caveats an agent needs before trusting the results.

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?

Front-loaded with the core action and well-organized into purpose, use cases, and behavioral notes. The trailing 'DC: ... / use Desktop Commander to ...' boilerplate adds no selection or invocation value.

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 does explain the return (chronological list with arguments and outputs) and the truncation behavior. For a read-only query tool with annotations covering safety, the only real hole is the undocumented filter parameters.

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 only 25% — just deviceId is documented. The description says nothing about 'since', 'toolName', or 'maxResults' (default 50, max 1000), so an agent must infer that filtering by time and tool name is even possible. It does not compensate for the coverage gap at all.

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: 'Get recent local tool call history with arguments and outputs,' plus clarifies it is loaded from a local history file. 'Local' implicitly separates it from the sibling list_remote_tool_calls, though it never names 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?

Gives three concrete 'Useful for' scenarios (onboarding, context recovery, debugging) and a coverage caveat that it excludes its own calls and track_ui_event. It stops short of naming alternatives or stating when not to use it, so it lands at clear-context rather than explicit routing.

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, non-destructive, so safety is covered. The description adds value beyond that with a concurrency/retry discipline rule about pending or executing states, which the agent cannot infer from annotations. It does not say what status values exist or what happens if the call_id is unknown or the call was terminated.

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, both load-bearing: one defines the read, one states the retry prohibition. The scope condition is front-loaded and 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?

With no output schema, the description arguably should hint at what is returned (status values versus final result shape), which it only gestures at. Everything else an agent needs to call it correctly, including the guard against duplicate side effects, is present.

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?

One required parameter with 0% schema description coverage, so the description must carry meaning. It does explain that the call_id is the running call identifier returned by an earlier remote tool call, which is more than the bare uuid format schema, but it adds no format, lifetime, or error behavior for the id.

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: read the status or final result of a Remote MCP tool call, scoped to calls that returned a running call_id. This is clearly not write_file or list_remote_tool_calls. It stops short of naming a sibling alternative for polling or listing calls, so it is clear but not fully differentiated.

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 a concrete triggering condition ("a Remote MCP tool call that returned a running call_id") plus an explicit prohibition: do not retry the original side-effecting tool while its status is pending or executing. No sibling alternative (e.g. list_remote_tool_calls) is named for discovery, so guidance is clear but not exhaustive.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description usefully adds what the response contains (success/failure rates, performance metrics), but says nothing about the scope of aggregation (current session vs. all time) or the optional deviceId's effect on results.

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 first two sentences are front-loaded and earn their place. The third sentence about referencing "DC: ..." in instructions is generic boilerplate unrelated to invoking this tool and dilutes the definition.

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 does cover the return contents, which is the right move. It still leaves the agent guessing about aggregation scope and device targeting, gaps that matter for a stats tool sitting alongside several other telemetry-related siblings.

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 single deviceId parameter is fully documented in the schema, including the list_devices reference and the multi-device requirement. The description adds nothing beyond that, so baseline 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 names a specific verb and resource ("Get usage statistics") and enumerates the payload (tool usage summary, success/failure rates, performance metrics), so an agent knows exactly what it retrieves. It does not, however, distinguish itself from near-neighbours such as get_recent_tool_calls or list_remote_tool_calls, leaving overlap ambiguous.

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?

"For debugging and analysis" is the only usage cue and is generic; it never states when to prefer this over get_recent_tool_calls, get_tool_result, or get_config. No prerequisites, no exclusions, and the boilerplate "DC: ..." line adds no selection 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 annotations already declare readOnlyHint=false, destructiveHint=true, and openWorldHint=true. The description adds valuable behavioral context beyond the annotations: prompt waiting, error/completion detection, early exit, prompt cleaning, returned status indicators, and the 3-second remote-execution cap. It does not explicitly warn that sent input can execute destructive commands, but the annotations carry that safety signal.

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 well-structured and front-loads the purpose, but it is longer than necessary for a six-parameter tool. Sections such as examples, smart detection, performance debugging, and the DC reference contain useful but partially redundant detail. Some sentences could be tightened without losing selection-critical 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 mutation-capable, open-world tool with rich annotations but no output schema, the description covers the main invocation context: process targeting, wait behavior, remote timeouts, and status indicators. The return value explanation is vague ('execution result with status indicators'), but most tool-selection needs are met. It is not fully complete, but it is solid.

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 only 17%, so the description must compensate, and it does: it documents pid, input, timeout_ms, wait_for_prompt, and verbose_timing with defaults and meaning. It omits deviceId, but the schema already describes that parameter, so the practical gap is small. Input formatting details are still somewhat thin.

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: send input to an existing terminal or REPL process and return newly available output. It also scopes the tool to processes started with start_process(), which helps distinguish it from process-creation siblings. An agent can tell what this tool does 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?

The description gives clear usage context: interactive shells, Python/Node/R/Julia REPLs, database consoles, and long-running commands started with start_process(). It does not explicitly compare itself with read_process_output or state when not to use this tool, but the context is strong enough to select it correctly in most cases.

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

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

Beyond the annotations (readOnlyHint=false, idempotentHint=true, destructiveHint=false), the description discloses the retention window (up to 30 minutes), the caller identity, and the downstream consumer that makes the stored value readable. The stated behavior is fully consistent with the annotations, with no mutation of user data implied despite write-shaped persistence.

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

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

Two sentences with zero filler; the caller restriction and TTL are front-loaded before the pointer to get_tool_result. Nothing could be removed without losing routing 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 one-parameter persistence helper with annotations and no output schema, the description covers caller, lifetime, and consumer. The only gap is the meaning of call_id, which is left implicit.

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% and call_id has no description in the schema, so the description must compensate. It only implies that the identifier selects the call whose result is kept, without saying what call_id refers to or what happens if an unknown id is passed.

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 concrete verb and resource ('keeps the full result of a call'), the precise origin of that call ('the user ran from a panel'), and the retention window. It also contrasts itself with the sibling that reads the data ('so get_tool_result can read it'), so an agent can place it immediately.

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?

Explicit when-to-use and when-not-to-use: 'Used only by Desktop Commander panels' plus the hard exclusion 'The assistant never calls this.' No inference is required, and the reader tool is named as the complement.

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 destructiveHint=true and readOnlyHint=false, so the "use with caution" sentence largely restates structured data. It does add one real behavioral signal — the termination is forceful rather than graceful — but says nothing about what happens if the PID does not exist, required permissions, or irreversibility beyond the annotation.

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

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

The purpose is front-loaded in the first sentence, which is good, but the third sentence about referencing "DC: ..." is instruction-file boilerplate that does not help the agent decide or call the 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?

This is a destructive operation with no output schema, and the description omits return behavior (success message, exit code) and failure semantics (nonexistent PID, permissions). The annotations carry the safety profile, so the remaining gaps are moderate rather than crippling.

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 50%: deviceId is documented in the schema, but pid is a bare number with no schema description. The description only repeats that a PID is used, without clarifying format, whether it must be local to the selected device, or what happens when the PID is invalid, so it does not 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?

"Terminate a running process by PID" names a specific verb (terminate), resource (process), and the key selector (PID). It is clear enough to distinguish from list_processes or read_process_output, but it does not differentiate itself from the sibling force_terminate, which sounds like it does the same thing.

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 (terminate a process by PID) and adds a caution warning, but gives no explicit when-to-use/when-not-to-use guidance. With a sibling named force_terminate, the agent is left to guess which of the two to pick.

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, non-destructive, non-open-world behavior. The description adds useful context beyond that by naming the account scope and the device status/ID information returned, though it omits details like authentication requirements or pagination.

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 with no wasted text. The phrase 'device-management guidance' is slightly vague but does not undermine overall efficiency.

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 list tool with no output schema, the description sufficiently covers what the tool returns: devices, status, IDs, and guidance. It could mention account/auth constraints more explicitly, but it is complete enough to call 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?

The tool has zero parameters, so there are no parameter semantics to document. The baseline score for a zero-parameter tool is 4, and the description appropriately avoids discussing irrelevant inputs.

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: lists this account's Desktop Commander devices. It also clarifies the returned content (online/offline status, IDs, guidance), making the tool's purpose clear, though it does not explicitly contrast with any sibling tool.

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 implied by 'IDs for device selection' and 'device-management guidance,' but the description does not explicitly state when to call this tool versus alternatives or any prerequisites. No sibling device tools exist, so the gap is less severe, but guidance is still 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?

Beyond the readOnly/destructive annotations, it discloses the context-overflow protection rule (100-item cap on nested directories plus the warning format), the [DENIED] and [NOT_FOUND] outcomes, and the allowed-directory restriction. These are behaviors an agent could not infer from annotations or schema and would otherwise be surprised by.

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 core purpose and depth semantics are front-loaded and each subsequent section is a distinct, useful topic. The example output block and the trailing "DC: ..." / device boilerplate add length that could be trimmed without losing much.

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 listing tool with no output schema, the description fully describes the return shape ([FILE]/[DIR] prefixes, relative paths, warning lines, [DENIED]/[NOT_FOUND]). An agent has everything it needs to call the tool and interpret the response.

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 33% and the schema itself says nothing about path or depth, so the description does the heavy lifting here. It defines the depth default and what depth=1/2/3+ mean, and it explains path resolution (relative paths, tilde, absolute paths preferred), though it could clarify edge cases such as depth=0 or very large depths.

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?

It states a specific verb and resource ("Get a detailed listing of all files and directories in a specified path") and explicitly notes it returns structure without starting a shell command, separating it from start_process/interact_with_process. It is also clearly distinguishable from read_file, get_file_info, and search tools in the sibling list.

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

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

It gives clear context on when the tool fits (listing a directory tree, recursive depth control) and explains what depth values select. That said, it never explicitly names an alternative such as read_file for reading contents or start_search for finding files, so routing 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=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds value by enumerating the returned fields (PID, command name, CPU, memory), which matters since there's no output schema, but it says nothing about result volume, truncation on machines with many processes, 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 functional sentences plus one boilerplate sentence; the core purpose is front-loaded. The "DC: ..." sentence is peripheral but brief and does carry minor invocation value.

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?

Complete for a zero-required-param read tool: annotations cover safety, the schema covers the one parameter, and the description compensates for the missing output schema by listing returned fields. Only minor gaps (result size, permissions) remain.

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

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

Schema description coverage is 100% and the single deviceId parameter is fully documented in the schema, including the multi-device condition. The description adds nothing about the parameter, which is acceptable at this coverage level (baseline 3).

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?

Specific verb + resource: "List all running processes" leaves no ambiguity about the operation, and the scope (all, running) is explicit. It doesn't explicitly name a sibling it is not (e.g., read_process_output or interact_with_process), but the resource is distinct enough that an agent can separate it from the process-manipulation siblings.

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 statement of when to use this versus read_process_output, interact_with_process, or start_process. The only meta-guidance is the boilerplate about referring to the tool as "DC: ...", which is about invocation phrasing, not tool selection.

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, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds genuine context by explaining that entries are background continuations of timed-out synchronous calls. It omits ordering, retention window, and how long a background entry remains retrievable.

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, and the distinguishing qualifier arrives before any trailing clause. It is arguably too short for the gaps it leaves, but per conciseness criteria nothing is wasted.

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 whose whole point is discovering backgrounded calls, the description omits the lifecycle: how entries are identified, whether they expire, and what the agent should call next to obtain results. Annotations cover safety but not these operational facts, and there is no output schema to lean on.

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% — the single 'limit' parameter has no description, only default 20 and min/max bounds. The description does not mention 'limit' at all, so it adds nothing to clarify whether it caps returned entries and how ordering interacts with truncation. With low coverage the description was expected to compensate and does not.

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 (List) and resource (Remote MCP calls) and qualifies the scope precisely as calls that 'exceeded the bounded synchronous wait and continued in the background.' This is much sharper than the title alone. However, it never distinguishes itself from the closely-named sibling get_recent_tool_calls, leaving an agent to guess which list it wants.

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 when-to-use or when-not-to-use guidance is given, and no sibling is named. Critically, the description does not say to follow up with get_tool_result (or get_recent_tool_calls) to actually retrieve results or to compare the two lists, which is the obvious next step for an 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?

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds value beyond that by naming the returned fields and by scoping the listing to 'active' searches only, which tells the agent these are live rather than historical entries.

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 core purpose and return fields are front-loaded in two tight sentences. However, the trailing 'DC: ...' or 'use Desktop Commander to ...' boilerplate is invocation-aliasing noise that does not help an agent decide to call this 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 simple read-only listing with one optional parameter and no output schema, the description supplies purpose, scope and return fields, which is enough to call it correctly. Missing only explicit routing against siblings such as list_sessions or get_more_search_results.

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

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

There is a single optional deviceId parameter with 100% schema description coverage, so the schema already explains that it comes from list_devices and is required only when multiple devices are online. The prose description adds no parameter guidance, so the baseline 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?

States a specific verb+resource (list active searches) and enumerates what is shown: search IDs, types, patterns, status, runtime. The analogy to list_sessions clarifies that these are searches rather than terminal processes, though the separation is made by comparison rather than by an explicit contrast statement.

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?

'Useful for managing multiple concurrent searches' implies the use case but gives no explicit when-to-use/when-not or named alternative. There is a passing reference to list_sessions, but it is framed as an analogy, not as a routing instruction for an agent choosing between tools.

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

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

With readOnlyHint/destructiveHint/openWorldHint already declaring the safety profile, the description adds real interpretive context: it explains what "Blocked: true" signifies and that long runtime plus blocked may mean a stuck process. It omits pagination/result-size behavior, but for a session listing this is a meaningful value-add beyond the annotations.

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

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

Purpose is stated up front and the field list plus debugging tips are scannable bullet points that each earn their place. The trailing "DC: ..." aliasing note is invocation trivia that dilutes focus slightly, and the leading indentation is sloppy but harmless.

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, zero-required-parameter listing tool with full annotation coverage and no output schema, the description covers purpose, returned fields, and interpretation adequately. Only the optional deviceId trigger and behavior on larger result sets go unmentioned, both minor.

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 is one optional parameter (deviceId) with 100% schema description coverage that already explains it comes from list_devices and is only needed with multiple devices online. The description does not mention deviceId at all, so it adds nothing here, but the schema carries the load and baseline 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?

"List all active terminal sessions" gives a specific verb and resource, and the enumerated return fields (PID, Blocked, Runtime) pin down that this is about interactive terminal sessions rather than OS processes, distinguishing it from the sibling list_processes. An agent can tell at a glance which listing tool it needs.

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 DEBUGGING REPLs block gives explicit usage context: "Use this to verify sessions are running before sending input" and how to read a blocked/long-runtime state. It names the downstream action (sending input) rather than a sibling tool name, so the routing to interact_with_process 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 description adds real value beyond annotations: the allowed-directory sandbox restriction and the caveat that relative/tilde paths are fragile while absolute paths are most reliable. However, the key destructive behavior — whether an existing destination is overwritten, and whether the operation is reversible or atomic — is never stated, which is a notable gap for a tool annotated destructiveHint=true.

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 opening two sentences are tight and front-loaded with the core action. The trailing line about being referenced as 'DC: ...' is invocation boilerplate that adds no selection value and dilutes focus.

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, non-idempotent filesystem mutation with no output schema, the definition covers sandbox scope and path resolution reasonably well. It falls short on overwrite behavior, error conditions, and what the call returns, which an agent needs before invoking a destructive move.

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 33% (only deviceId is documented), so the description must carry source/destination. It partially does by explaining that paths are device-scoped and that tilde/relative forms may not resolve, which meaningfully clarifies both path parameters. It still doesn't say whether source can be a directory vs file or describe destination-collision 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?

States a specific verb set (move/rename) and resource (files and directories), and clarifies that both operations can happen in one call. It is unambiguous against siblings like write_file, create_directory, or edit_block.

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 implied by the verb, but there is no explicit 'use this instead of X' routing or exclusion guidance. The note that both paths must be within allowed directories is a constraint, not a when-to-use rule.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, but the description adds meaningful behavior: filesystem access is limited to allowed directories, URL reads ignore offset/length, and format-specific behavior differs for DOCX, Excel, PDF, images, and text. These details go well beyond the annotations without contradicting them.

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

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

The description is long but well structured and front-loaded with the core purpose before format details. Most sections earn their place because the tool supports many formats, but the performance-optimization notes and some DOCX internals are more verbose than strictly necessary for tool selection.

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 and a complex 8-parameter surface, the description still explains return behavior for major formats: text pagination, Excel JSON arrays, image base64 content, PDF markdown, and DOCX outline versus raw XML. It also covers path resolution and filesystem restrictions, making it complete enough to call 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 description coverage is only 13%, so the description carries most of the burden. It thoroughly explains offset/length semantics with examples, range/sheet for Excel, isUrl behavior, and format-dependent pagination, though it does not explain the options object or reinforce deviceId beyond 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?

The description states a specific verb and resource: read contents from files and URLs, with explicit support for PDFs, images, DOCX, Excel, and URL fetching. It clearly separates this from shell-based reading and from write/edit tools, so an agent can identify the operation 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?

It gives clear usage context: suitable for reading authorized local files directly without starting a shell command, and URL reading is enabled via isUrl=true. It does not explicitly name read_multiple_files or other alternatives, so sibling routing is implied rather than fully specified.

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/openWorldHint/destructiveHint, so the safety profile is covered; the description nonetheless adds genuinely non-obvious behavior: per-file failures do not abort the batch, images are rendered for PNG/JPEG/GIF/WebP, and access is confined to allowed directories. It stops short of stating size limits, output ordering, or how partial failures are reported.

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?

Content is front-loaded (capability, return shape, image handling, error semantics, constraints) and each line carries information. The trailing "DC: ..." invocation-phrase sentence and the leading indentation add mild noise without much payoff.

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 does the necessary work by describing the return shape (content plus path reference) and failure semantics, and it covers access constraints and path-resolution caveats. It is short of complete only on per-file error representation and any size/count limits.

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

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

Schema coverage is 50%: deviceId is documented in the schema, but the required `paths` array has no schema description. The description partially compensates by explaining that paths target the selected device and that relative and tilde paths may not resolve, favoring absolute paths — but it never states that paths is an array or whether globs/duplicates are accepted.

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 ("Read") and resource ("contents of multiple files") with explicit batch scope in the word "multiple", which cleanly separates it from the singular read_file sibling. There is no ambiguity about what the tool returns at a high level.

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 by the word "multiple" — the agent must infer that this is the batch alternative to read_file. There is no explicit when-to-use/when-not guidance, though the "Only works within allowed directories" line does flag a real precondition.

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 readOnly/non-destructive, and the description adds substantial non-obvious context on top: output truncation via fileReadLineLimit, the literal status line format returned, blocking behavior for offset=0 up to timeout_ms, and the 3000ms cap under remote execution. This is exactly the operational detail 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?

Front-loaded with the verb and the pagination model, then layered detail, which is the right ordering. The examples block is somewhat padded (offset: 0 with and without length restates the same behavior) and the 'DC: ...' branding line plus the REMOTE EXECUTION section add length, though the latter carries real behavioral 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 6-parameter, 1-required tool with no output schema, the description supplies the return shape (status line), the blocking/timeout model, and per-offset behavior — enough to call it correctly. The main residual gap is verbose_timing, whose effect on the response is left entirely to the schema's type-only declaration.

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 only 17%, so the description must carry the load, and it does for the two parameters that matter most: offset (with three distinct sign-based semantics and worked examples) and length (default plus config source). timeout_ms gets partial treatment, but verbose_timing and the semantics of pid are never explained, leaving a small 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 opening sentence states a specific verb and resource ('Read output from a running process') plus the distinguishing capability ('file-like pagination support'). It is clearly separable from siblings like list_processes, start_process, and interact_with_process, which do not read accumulated output.

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 offset semantics section effectively documents the different usage modes (poll-new, absolute position, tail), which functions as when-to-use guidance per parameter value. The DETECTION STATES block routes the agent to interact_with_process when the process is waiting for input. It stops short of explicitly stating when not to use this tool (e.g., after force_terminate or on a finished pid).

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, and the description is consistent with them while adding real context: the panel contents, the fact that the tool itself executes nothing, and that 'Run' sends the call once through the client as a normal tool call. That last point is essential behavior not encoded anywhere in the annotations or schema.

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?

Front-loaded with the trigger condition, followed by what the panel shows, what the tool does not do, and the exclusions. It is dense but nearly every sentence carries a rule. Minor redundancy between 'Call this right away' and 'Always use it in that case instead of telling the user to run the command themselves'.

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 five-parameter tool with an output schema and full schema descriptions, the description covers the missing pieces: when it fires, what the user sees, that it does not execute, and what Run does. Nothing an agent needs in order to call it correctly appears to be absent.

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

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

Schema coverage is 100%, so the baseline is 3. The description still adds a non-obvious constraint beyond the schema: pass the exact tool name and arguments and 'never change, split or encode them', which is a correctness rule an agent could otherwise violate while trying to be helpful.

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 action and resource: it shows a stopped Desktop Commander call to the user in a review panel, with the exact tool and arguments and Run/Cancel buttons. It also explicitly disclaims what the tool is not ('This tool runs nothing itself'), which an agent could easily get wrong given the 'Run' button. It is clearly distinguishable from siblings such as get_recent_tool_calls or list_remote_tool_calls.

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

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

Gives a precise trigger (a call blocked by the client before reaching the device, plus one unchanged retry also blocked, without asking the user first), a second trigger (user asks to see a call before it runs), and explicit exclusions (never after a timeout or connection error, never for a call the user declined or cancelled). It also names the alternative behavior it replaces: telling the user to run the command themselves.

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

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

Annotations already flag destructiveHint=true and readOnlyHint=false, so the mutation character is known. The description goes beyond that by disclosing a concrete blast radius: setting allowedDirectories to [] grants full filesystem access on any OS, and changes alter later file and command behavior. It does not say whether changes persist across sessions or apply per-device.

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?

Front-loads the core action in one line, then the security constraint, then the key reference list, then the critical empty-array warning. The trailing 'DC: ...' invocation boilerplate is the only non-earning content and it is a single line.

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 3-parameter destructive mutation with no output schema, the description covers what keys exist, their value types, and the highest-risk misconfiguration. It omits what the return looks like, invalid-key behavior, and default values, which are minor gaps given annotations carry the safety profile.

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 33% (only deviceId is documented), so the description must compensate, and it does by enumerating the allowed key values and their expected value types (array, string, array of paths, number, boolean). That mapping makes the untyped `key` and polymorphic `value` parameters usable; the `deviceId` relationship to list_devices is left entirely to 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 a specific verb and resource (set a configuration value by key) and enumerates the configurable keys, which makes the tool's scope concrete. It never names get_config as the read counterpart, so sibling differentiation is left to inference.

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 security note implies when this should be invoked (config changes should be isolated from untrusted file/command content), which is real usage guidance. However, it gives no explicit when-not guidance and does not point to get_config for reading current values before overwriting them.

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, but the description adds consequences that annotations cannot convey: no tool can reach the device afterward until the user manually runs the `npx @wonderwhy-er/desktop-commander@latest remote` command, plus the clarification that the computer itself is not shut down. That recovery path is critical behavioral context for a destructive action.

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 tightly scoped sentences, front-loaded with the action and immediately followed by the gating condition. No filler, though the negative-usage and recovery sentences could be marginally tightened; nothing is wasted as-is.

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, non-openWorld tool with one optional param and no output schema, the description supplies everything an agent needs: the exact effect, the trigger condition, the exclusions, the post-condition lockout, the manual recovery step, and the scope limit (does not power off the machine).

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 deviceId description already explains sourcing from list_devices and the single-device omission case, so the schema carries the full burden. The description adds nothing about the parameter, which is acceptable here but not 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?

States a specific verb and resource — disconnecting a device from remote access by stopping its Desktop Commander remote agent — which is far more precise than the bare name 'shutdown' would suggest. It explicitly disambiguates from process-termination siblings, so an agent will not confuse this with killing a command or task.

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 positive trigger ('only when the user explicitly asks to disconnect this device or stop remote access') and an explicit negative one, naming the alternatives force_terminate and kill_process for the confusable case. This is exactly the when/when-not/alternative structure that earns a top score.

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 mark it as non-readOnly, destructive and open-world; the description adds substantially to that: the 3000ms remote-execution cap despite higher timeout_ms values, background continuation with PID return, early-exit heuristics, and the three detectable states. Those are exactly the behavioral traits an agent cannot infer from the structured fields.

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

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

Purpose is correctly front-loaded and the device/syntax caveat is well placed, but the body is bloated: 'SMART DETECTION' and 'STATES DETECTED' restate the same idea, and the 'DC: ...' invocation-aliasing note adds little for tool selection. Roughly a third of the text could be cut without losing decision-relevant 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?

With no output schema, the description does the heavy lifting: it explains what comes back when the process keeps running (background PID), how to read new output, and how to debug timing. It falls just short of complete because the 'shell' parameter and the normal (non-background) return payload are never characterized.

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 20% (only deviceId documented), so the description must compensate and largely does: it explains command syntax via examples, that the connected device determines shell/path semantics, the real timeout ceiling, and verbose_timing's full output contents. The 'shell' parameter, however, is never mentioned anywhere, leaving one of five parameters completely undefined.

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 (start a terminal process on the authorized device) and enumerates concrete instantiations (Python REPL, Node REPL, one-shot shell command). It also names what this tool is not for: when the process is running, it says to use read_process_output, letting an agent separate it from that sibling without opening a 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?

The 'Suitable for...' sentence plus four worked examples give a clear picture of when to reach for it, and the description points to read_process_output for the running-state case. It stops short of explicitly contrasting with interact_with_process (it only hints that sessions 'support follow-up input' after start), so the boundary between starting and interacting is left partly implicit.

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 read-only and non-destructive annotations, the description discloses that this starts a background process and returns immediately with a session ID. It also covers result retrieval, early cancellation, remote-execution timeout capping, and path-resolution caveats.

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 heavily repetitive: searchType guidance, ambiguous-search advice, and examples are restated across multiple sections. Headings provide structure, but the overall length and duplication make it far from front-loaded and concise.

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

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

For a complex streaming search tool with no output schema, the description explains the session-based flow, result retrieval via get_more_search_results, and early termination via stop_search. It is mostly complete, though it could document the remaining lesser-used parameters and any error behavior.

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 only 8%, so the description must carry parameter meaning. It explains the important search parameters well, including pattern, searchType, literalSearch, filePattern, ignoreCase, earlyTermination, and timeout_ms, but it omits maxResults, contextLines, and includeHidden.

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

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

The description opens with a specific verb and resource: it starts a streaming search that returns results progressively. It also names the downstream tools get_more_search_results and stop_search, making the tool's role distinct from siblings.

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 explicit when-to-use guidance for searchType="files" versus searchType="content", plus a strategy for ambiguous queries. It also explains that results are retrieved via get_more_search_results and that stop_search can end the search early.

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 non-read-only, non-destructive, closed-world behavior, and the description adds genuinely new context: the stop is graceful and results remain readable for 5 minutes until automatic cleanup. That lifecycle detail is not derivable from the annotations and materially affects follow-up behavior. It doesn't state what happens if the sessionId is invalid or already stopped.

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?

Front-loaded with the core action, followed by usage conditions and lifecycle behavior in a sensible order. The trailing 'DC: ...' invocation boilerplate is generic across the server and adds little, but overall the text is tight.

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 two-parameter stop tool with annotations and no output schema, the behavioral picture is mostly complete, but the missing guidance on sourcing the required sessionId and on the return/error behavior leaves a real gap an agent would hit on first 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 only 50%: deviceId is documented in the schema, but the required sessionId has no description anywhere. The description never explains what a sessionId is or where to get one, so it fails to compensate for the coverage gap on the one mandatory 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?

States a specific verb and resource ('Stop an active search') and explicitly contrasts itself with the sibling force_terminate, which handles terminal processes rather than searches. An agent can distinguish it from start_search and force_terminate without opening any 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 concrete when-to-use conditions ('when you've found what you need or if a search is taking too long') and names the analogous sibling force_terminate. It stops short of saying how to obtain a sessionId (e.g., via list_searches) or when not to call it, but the invocation 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 declare readOnlyHint=false, idempotentHint=false, openWorldHint=false, so the safety/mutation profile is covered. The description adds the crucial behavioral fact that this is a panel-driven telemetry sink rather than an assistant-callable action. It does not say what happens if an agent calls it anyway (error, silent write, discarded), which is the one remaining gap.

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, each earning its place: the first defines the tool and gives examples, the second delivers the decisive usage constraint without preamble.

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 non-agent-callable telemetry tool with no output schema, the description is complete enough: the agent's only needed decision is not to call it, and that is stated unambiguously. The undocumented parameters matter only to the panel code that calls this, though a one-line note on what happens on an unintended call would close the loop.

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%, so the description must carry all meaning, but it only hints that 'event' takes action-like names (Run, Cancel) via examples. 'component' and the nested 'params' object are left entirely unexplained in both 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?

States a specific verb and resource ('record what the user did' in 'Desktop Commander panels') and gives concrete examples of the events ('pressing Run or Cancel'). The second sentence explicitly delimits who the caller is, so an agent can distinguish this from every sibling tool at a glance.

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

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

Provides explicit when-not guidance: 'The assistant never calls this.' That is the strongest possible routing instruction and removes any ambiguity about whether an agent should invoke this among 30+ siblings.

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, openWorldHint=false, and destructiveHint=false, so the safety profile is covered. The description adds that the response includes authenticated-user details and a monthly remote tool-call usage percentage. With no output schema, it could say a bit more about the return shape, but it adds useful context beyond the annotations.

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

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

The description is a single front-loaded sentence with no wasted words. It communicates the main purpose and one notable return field efficiently.

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

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

For a parameterless read-only identity tool with annotations covering safety and no output schema, the description is nearly complete. It tells the agent what identity information is available and that usage percentage is included. A small gap remains: it does not distinguish the tool from usage-related siblings.

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 parameter semantics are not applicable and the baseline is 4. The description does not need to explain parameters, and the schema is fully specified for an empty object.

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: get details about the currently authenticated user. It also names a specific payload element, this month's remote tool-call usage percentage. It does not explain how this differs from potentially overlapping siblings such as get_usage_stats or list_remote_tool_calls.

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

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

There is no explicit guidance on when to use this tool versus alternatives. An agent can infer that it is for identity/account context, but the description does not mention siblings like get_usage_stats or get_config or state exclusions.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=true, and the description adds substantial context on top: chunk sizes of 25-30 lines, performance notes above 50 lines, a sandbox restriction to allowed directories, and path-resolution caveats for relative and tilde paths. It stops short of stating outright that mode='rewrite' truncates existing file contents, which is the single most important consequence for a destructive 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?

Well front-loaded and organized under CHUNKED WRITES and FORMAT HANDLING headers, so an agent can scan it. Slight redundancy remains: the 50-line performance note and the 25-30 line chunk advice overlap, and the 'DC: ...' invocation line is boilerplate that doesn't help selection.

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, four-parameter write tool with no output schema, the definition covers formats, modes, chunking, sandbox limits, and path resolution. It leaves open whether parent directories are auto-created and what error surface a failed or permission-denied write produces.

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 25% (deviceId alone is documented), so the description carries the burden and does: it defines the rewrite-vs-append semantics of mode, explains that content type is determined by extension with a concrete Excel JSON 2D-array example, and gives guidance on absolute vs relative vs tilde paths. That is meaning well beyond the bare schema.

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

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

Opens with a specific verb+resource ('Write or append to file contents') and immediately routes PDF and DOCX-editing cases to their dedicated siblings. An agent can tell this apart from write_pdf and edit_block without opening any 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?

Explicitly names the alternatives and the conditions selecting them: PDF creation goes to write_pdf, existing DOCX content goes to edit_block, new DOCX files are created here. It also prescribes the rewrite-then-append pattern for long content, which is real when-to-use guidance rather than restatement.

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 readOnlyHint=false, but the description adds crucial context: modifications preserve the original PDF and require a new outputPath, and operation is limited to allowed directories. That goes beyond the annotation, though it doesn't discuss error behavior or return payload shape.

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?

Front-loads the core purpose and modes well, but carries redundancy ('Dedicated PDF creation and modification tool' repeats the opening) and trailing boilerplate about 'DC:' references that doesn't help correct invocation. The examples earn their space, but trimming would improve it.

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

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

For a mutation tool with no output schema and nested operation objects, the description covers modes, operations, page breaks, styling, and path constraints thoroughly. The opaque 'options' parameter is left undocumented, which keeps it from 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 only 20%, so the description must compensate and largely does: it explains path, the dual string/array nature of content with worked examples, the required outputPath for new files, and the exact operation object shapes (delete/insert with pageIndexes/pageIndex/markdown/sourcePdfPath). It leaves 'options' and 'deviceId' unexplained, keeping it from a 5.

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 ('Create a new PDF file or modify an existing one') and reinforces it as a 'Dedicated PDF creation and modification tool.' An agent can immediately tell this apart from the generic write_file sibling because it operates on PDFs specifically.

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

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

Explicitly lays out two modes (CREATE NEW vs MODIFY EXISTING) and the condition selecting each: a string content for creation, an array of operations for modification. It also states the constraint that modification requires a different filename. It does not compare against write_file or other siblings, so not a 5.

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