ReMCP

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

Annotations already declare destructiveHint=true and readOnlyHint=false. The description adds value by distinguishing observe-only operations from state-changing ones: 'Snapshot/find/wait operations observe state; clicks, typing, window close, app launch, clipboard writes, and recording can change local application state.' This is useful behavioral context beyond the annotations and is consistent with 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?

Three sentences with no filler. The first sentence front-loads the tool's purpose and scope, the second adds critical behavioral nuance about which operations mutate state, and the third gives a targeting preference. Every sentence earns its place.

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

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

For a tool with this much schema complexity and a rich output schema, the description is sufficiently complete: it defines the domain, separates read vs. mutate operations, and offers a targeting heuristic. It does not enumerate all supported operations, but the schema's operation enum and parameter definitions carry that burden. Minor gaps like platform-specific caveats are left to the schema.

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

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

Schema description coverage is 100%, and the schema provides extremely detailed descriptions for every parameter, including nested objects and operation-specific constraints. The description itself adds little parameter-level detail, but with full schema coverage the baseline of 3 is appropriate; it does not need to compensate.

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: 'semantic inspection or control of native desktop applications on this computer.' It lists concrete capability categories (windows, accessibility/UI elements, app launch, clipboard, recording) that clearly distinguish it from sibling file/terminal/read tools. An agent can tell this is the desktop-automation tool 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 context for when to use the tool: 'Use this for semantic inspection or control of native desktop applications on this computer.' It also provides an important operational guideline, 'Prefer semantic targets before raw coordinates.' It does not explicitly name alternatives or say when not to use it, but the domain boundary is clear enough against the sibling 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?

The description adds meaningful behavioral detail beyond the annotations: DOCX/XLSX edits can replace the input when no output is supplied, PDF write operations create or replace requested output, and read_document is read-only. This directly explains what may be destroyed, which aligns with and enriches the destructiveHint=true 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?

Three compact sentences: the first states scope and actions, the second warns about input/output replacement behavior, and the third routes text files elsewhere. Every sentence adds distinct value with no redundancy.

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

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

Given the rich conditional schema, output schema, and annotations, the description covers what an agent needs to choose and call the tool safely: operation families, destructive side effects, and the key sibling distinction. The schema handles remaining parameter-level details.

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

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

Schema description coverage is 100%, so the baseline applies. The description adds high-level operation categories but does not clarify individual parameter formats or constraints beyond what the schema already documents, such as page range syntax or output patterns.

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 concrete resources (PDF/DOCX/XLSX) and specific verbs (read, edit, merge, split, extract, inspect), so an agent immediately knows the tool's domain and scope. It also explicitly distinguishes itself from read_file, which prevents confusion with a 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?

It gives a clear trigger condition ('structured document content') and explicitly routes plain line-oriented text to read_file. It does not mention alternatives like manage_files, but the context plus the named sibling exclusion is sufficient for most selection decisions.

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

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

Beyond the annotations' destructiveHint=true, the description names which operation classes can change or remove local data and which leave files unchanged. It also discloses that parameters are validated against a closed per-operation schema. This materially improves the agent's understanding of a large, destructive-capable tool and does not contradict the annotations.

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

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

Three sentences, no filler. The use condition is front-loaded, the per-operation constraint is stated clearly, and the read/write safety split and sibling routing are compressed into the remaining sentences. Every sentence earns its place.

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

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

Despite managing 29 sub-operations, the description gives the essential orientation: domain scope, one-operation rule, destructive vs read-only behavior, and a fallback to read_file. With such a rich input schema and an output schema present, the individual operation details are already covered structurally, so nothing critical is missing.

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

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

Schema description coverage is 100%, so the baseline is 3. The description mostly restates what the schema already says ('parameters must contain only that operation's arguments and are validated against its closed schema'), adding no new meaning to individual parameters. The rich schema carries the parameter semantics.

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

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

The description clearly states the tool's scope: files, directories, archives, and filesystem search on this computer. It also distinguishes itself from the sibling read_file by routing single known text files there. The verb is somewhat generic ('manage'), but combined with the title and operation list it is clear enough.

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

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

The description explicitly states when to use the tool ('task is about files, directories, archives, or filesystem search'), gives an explicit alternative ('Use read_file for one known text file'), and also separates read/search operations from write/edit/delete operations. An agent can reliably decide between this tool and the read_file sibling without opening the schema.

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?

Even though annotations already provide destructiveHint and readOnlyHint, the description adds genuinely useful behavioral context by separating observe-only fact/log/inventory operations from operations that can interrupt work or change the machine. This tells an agent both what is safe and what consequences to expect beyond the boolean annotation hints.

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

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

The description is front-loaded and every sentence earns its place: domain, safety caveat, and routing to run_terminal. The first sentence is a lengthy category list and includes a few domains absent from the schema, so it is not perfectly tight, but overall it is appropriately concise for a broad umbrella 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 the high complexity of nine conditional operations and nested parameters, the description is only a high-level umbrella and does not help an agent choose between similar operations such as get_system_info, get_runtime_info, and get_runtime_stats. The prose also claims support for services, event logs, audio, and power actions that are not represented in the operation enum, leaving a meaningful completeness gap despite the rich schema and output schema.

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

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

Schema description coverage is 100%, and parameters like pid, limit, key, value, host, port, and action are already documented in the schema. The description contributes no parameter-level meaning, which meets the baseline for full schema coverage but does not elevate it.

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

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

The description anchors the tool to a concrete domain (operating-system/ReMCP runtime state) and gives a meaningful category list: facts, processes, preferences, networking, installed apps, environment. It also distinguishes itself from run_terminal. However, it mentions services, event logs, audio, and power actions that do not appear in the operation enum, so the claimed scope is somewhat broader than the schema actually supports.

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 clearly states when to use this tool and explicitly routes general shell commands to run_terminal. It does not give exclusions for the other sibling tools or explain how to choose among the nine operations, but the main alternative is named and the intended 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 disclose read-only and idempotent behavior)Skip the description. The description adds real behavioral context: it limits the tool to text-like files, explains paging semantics, and discloses the legacy docx/pdf extraction behavior. This goes beyond annotation coverage without redundancy.

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

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

Three sentences, each with a distinct purpose: scope definition, alternative routing, and paging guidance. No fluff or repetition of schema fields. The phrasing is compact and front-loaded.

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

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

For a single-file read tool, the description covers scope, exclusions, paging, and compatibility, while the output schema and read-only annotations cover the rest. An agent has enough information to invoke it correctly and to decide when another tool is better.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value beyond the schema by explaining how offset and length should be used together to page through large files and clarifying the negative-offset behavior. This is meaningful, though the schema already documents each 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 action (read), a specific resource type (plain text or line-oriented file), and concrete examples (source, config, Markdown, scripts, logs). Explicitly distinguishes from read_document for PDF/DOCX/XLSX, so an agent can select it among several sibling read tools.

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

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

Provides explicit routing guidance: use read_document for structured documentsainer and notes legacy .docx/.pdf support for compatibility. Also gives concrete usage advice for large files with offset/length paging and negative offsets.

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

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

Beyond the annotations, the description explicitly warns that starting or interacting with commands can change local or external state and that force termination can lose unsaved process work, while reading, waiting, and listing do not mutate the session. This clarifies the destructive/non-destructive split across operations and matches the annotation profile.

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

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

The description is three sentences, front-loaded with the trigger condition and operation list, followed by the crucial safety caveats. Every sentence contributes selection guidance or behavioral warning with no redundancy.

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

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

The description covers when to use the tool, the need to select exactly one operation, validation behavior, and the mutation profile of each operation family. Since an output schema exists and the input schema fully documents each operation's parameters, no critical selection or invocation information is missing.

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

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

Schema description coverage is 100%, and the input schema already provides detailed descriptions for operation-specific parameters such as pid, offset, pattern, and timeout_ms. The description only adds a structural note about per-operation validation, not new meaning for individual parameters.

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

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

The description opens with a specific trigger condition ('when the task needs a shell command or an existing ReMCP terminal session') and enumerates the operation families: start, read, wait, interact, stop, and list sessions. This clearly distinguishes the terminal domain from sibling tools like manage_files or control_computer.

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 explicit context for when to use the tool and emphasizes that exactly one operation must be chosen, with parameters validated against that operation's schema. It does not explicitly name sibling alternatives or state when not to use the tool, so it stops short of a 5.

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

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

The description discloses a key behavioral trait: 'These operations return pixels without interacting with the visible UI', which is useful beyond the annotations. However, it claims capture of 'one window, monitor, or region' while the input schema for take_screenshot only exposes keep and directory parameters, leaving a behavioral promise the schema does not support. Annotations are all false and provide no additional coverage.

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

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

Two sentences, front-loaded with the key selection criterion ('when the result must be pixels'), and zero filler. The alternative and exclusion are stated efficiently in the second sentence.

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

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

The discriminated-union schema and output schema provide good structural coverage, and the description supplies overall context. However, the description overpromises window/monitor/region capture that is not reflected in the schema, creating a serious mismatch an agent must resolve before calling the tool correctly. This gap makes the definition not fully complete for its complexity.

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

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

Schema description coverage is 100%, so the baseline should be 3cars, but the description actively adds misleading meaning by mentioning 'one window, monitor, or region' capture when no schema parameter supports selecting those targets. It does not clarify how the operation discriminates between read_image and take_screenshot beyond the fixed operation enum, and the unsupported target claims could cause an agent to pass invalid parameters.

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

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

The description states a specific purpose: 'Use this when the result must be pixels from this computer', and enumerates the exact operations (read an existing image or capture desktop/window/monitor/region). It distinguishes itself from siblings by emphasizing pixels and the alternative control_computer for semantic structure or actions.

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

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

The description gives explicit when-to-use guidance ('when the result must be pixels') and names the clear alternative ('Use control_computer when semantic structure or an action is enough'). It also adds context that these operations do not interact with the visible UI, helping an agent choose correctly.

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