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

Annotations already declare destructiveHint=true and openWorldHint=true, so the safety profile is covered. The description adds non-obvious behavior beyond that: no shell state persists between calls, commands run with SSH account permissions, and background jobs must be tracked via job_output/job_kill on the same target. Missing detail on what a call returns (stdout/exit status).

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

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

Four short sentences, front-loaded with the core action and scope. Every sentence carries distinct information: execution model, permission context, background workflow, and dependency requirement. No filler.

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

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

For a destructive, open-world tool with 6 parameters and no output schema, the description covers execution model, permissions, async workflow, and dependencies. It is nearly complete, with only the return shape (output/exit code) 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 100%, so the baseline is 3. The description goes further by explaining the run_in_background flow (job_id, same target) and the constraint that the shell is fresh per call, adding semantics the schema alone does not convey about how parameters interact across invocations.

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 ('Execute bash on the selected remote host') and immediately scopes behavior with 'Each call starts a fresh shell.' This clearly separates it from local file siblings like read/write/edit/grep/glob, which operate on the workspace rather than a remote host.

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?

Explains the background-job branch explicitly: 'Background jobs return a job_id; use job_output/job_kill with the same target,' which routes the agent to the correct siblings. It also states the prerequisite (remote Linux requires bash and python3). It does not, however, tell the agent when to prefer remote bash over the local read/grep/edit 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 flag destructive=true and openWorld=true, so the safety profile is covered. The description adds genuinely new behavioral context: paths resolve against a selected ssh target and the edit executes on the remote host rather than locally. It does not describe failure behavior when old_string is absent or non-unique.

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, front-loaded with the core purpose before the remote caveat and the read-first convention. No redundant restatement of the name or schema fields.

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 annotations covering the destructive/write profile and a fully described schema, the description supplies the missing environmental context (remote host, target selection, read-first convention). Only edge-case behavior on failed matches is unaddressed, which is a minor gap for this tool's 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 coverage is 100%, so all five parameters are already documented, including the exact-match and single-occurrence rules for old_string. The description reinforces the remote-target meaning of file_path but adds no syntax or format detail beyond the schema, 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 ('Edit an existing UTF-8 text file') and narrows the mechanism to 'replacing literal text', which distinguishes it from the whole-file sibling write. It stops short of explicitly naming write as the alternative for full-file changes.

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 one useful procedural rule (read the file first; read-before-edit policy applies by convention) and clarifies the remote context. It never says when to prefer write over edit, nor when not to use this tool, so routing guidance 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?

Goes well beyond the readOnly/openWorld/non-destructive annotations: it discloses the result cap (100 paths), the sort order (modification time), that directories are excluded, that execution happens remotely over ssh, and that .git/node_modules are skipped. These are the facts an agent needs to reason about result truncation and 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?

Three compact sentences, front-loaded with the purpose, then return semantics, then the REMOTE qualifier. No filler; every clause carries a distinct fact.

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?

There is no output schema, and the description compensates by specifying return type, ordering, limit, and remote execution target. Combined with 100% schema coverage, an agent has everything needed to call it correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description reinforces the remote/ssh and target framing but adds no syntax or format detail beyond what the pattern and target schema descriptions already supply.

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: "Find files whose paths match a glob pattern." It also pins scope by declaring what is returned (file paths, never directories), separating it from content-oriented siblings like grep and from read/write which operate on named files.

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 (path-based file discovery on a remote target) but no explicit when-to-use or when-not, and it never names grep as the alternative for content search. An agent must infer the routing from the sibling names.

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=true, openWorldHint=true, destructiveHint=false, so safety is covered. The description adds valuable behavior: POSIX ERE limits, remote execution, binary/.git skipping, and a 250-match cap. These are concrete operational details not in annotations. Missing why the cap exists or what happens on overflow, but strong overall.

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

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

Three short sentences, front-loaded with the core action and regex syntax note, then output behavior, then remote execution constraints. No wasted words; every clause is informative.

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 regex flavor, output format (grouped, line numbers, cap), remote execution, and file exclusions. With no output schema, it explains the return structure well. Could mention error handling or performance implications, but it's complete enough for correct invocation.

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

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

Schema coverage is 100%, so all parameters are documented in the schema. The description mentions regex syntax (POSIX ERE) and implies the search runs remotely, which aligns with the 'target' parameter, but adds no new details about 'path', 'include', or parameter interactions. Baseline 3 for high coverage.

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: 'Search file contents with a regular expression.' It distinguishes itself from the sibling 'glob' by implying content search rather than filename search, and from 'read' by its search semantics. An agent can immediately tell what this tool does.

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

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

States the search operates on a remote target and requires explicit target selection, which differentiates it from a local search. However, it doesn't explicitly say when to use this over 'glob' (filename matching) or 'read' (full file reading), leaving some inference to the agent.

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

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

Annotations already cover the safety profile (destructiveHint=true, readOnlyHint=false, openWorldHint=true), so credit goes to what is added: the two-stage TERM/KILL escalation with a 3-second grace period, and the fact that output survives the kill and stays retrievable via job_output. That last point meaningfully changes calling behavior but is limited to one clause; no mention of what happens if the PID/target is gone or permission failures.

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

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

Two tight sentences, zero filler, and the destructive action is front-loaded ahead of the surviving-output detail. Every clause earns its place.

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

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

For a kill tool with no output schema, the description supplies the essentials: what is terminated, how forcefully, and where the output goes afterward. It stops short of failure modes or idempotency behavior, but nothing required to invoke it correctly is missing.

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

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

Coverage is exactly 50% (target is documented in-schema, job_id is only a uuid pattern). The phrase 'job process group' hints that the job_id scopes to a process group rather than a single PID, but neither parameter is explained in the description, so it does not compensate for the undocumented half.

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 (Terminate) and resource (remote background job process group), and the escalation mechanism (TERM then KILL) makes the scope unambiguous. It also names the sibling it complements (job_output), so an agent can distinguish it from read-side tools without opening either schema.

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

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

Usage is implied: kill a background job you previously started. There is no explicit when-to-use statement, no guidance on when to prefer this over alternatives like bash or waiting on job_output, and no preconditions. Adequate but leaves the agent to infer the trigger conditions.

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 openWorldHint=true; the description corroborates this by explaining exactly what is destroyed (a finished job, after its last output chunk) and adds non-obvious traits the annotations cannot convey, e.g. IDs surviving MCP restarts and duplicate-free 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?

Three sentences, no filler, and the primary purpose is front-loaded ahead of pagination and cleanup details. Every clause carries distinct operational 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 should say more about the returned status/output shape, and it omits auth or target-selection prerequisites for a destructive, open-world tool. It covers the main quirks (ID persistence, dedup pagination, cleanup) but is not fully complete for a 5-parameter mutation-capable tool.

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

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

Schema coverage is only 20%, so the description carries real weight. It explains cleanup and offset/pagination semantics, but it refers to 'next_offset' while the actual schema parameter is 'offset', a naming mismatch, and leaves job_id, limit and the required target unexplained (target's meaning comes from the schema, not the 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+resource: reading remote background job status and output. It is clearly distinguishable from job_kill (which terminates) and from local read/bash siblings. It stops short of explicitly naming those siblings, so a 4 rather than 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?

Gives concrete operating guidance: reuse next_offset to paginate without duplicates, and cleanup:true deletes a finished job after the last chunk. It implies when to use cleanup and how to resume, but never states when not to use this tool or what alternative exists for running/completed jobs.

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, so the safety profile is covered. The description adds genuinely new context: that paths live on a remote ssh target and that the read executes on the remote host, which an agent could not infer from the annotations alone.

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

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

Two compact sentences, with the core purpose front-loaded before the remote-host caveat. The 'REMOTE:' prefix is slightly awkward but 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?

No output schema exists, so the description carries the burden of stating the return value, which it does ('line-numbered content'). Combined with the remote-execution note and fully documented parameters, an agent has what it needs, though pagination interaction with limit/offset is left entirely 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%, so file_path, target, limit and offset are all documented in the schema, establishing the baseline of 3. The description reinforces that file_path is remote and relative paths resolve against the target root, but adds no syntax or format detail beyond the schema.

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

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

States a specific verb and resource ('Read a UTF-8 text file') plus the return shape ('line-numbered content'), which is enough to separate it from write/edit. It does not explicitly distinguish itself from grep or glob for content search, so it falls short of the top tier.

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 explains the operating context (reads run on the selected remote target) but gives no guidance on when to pick read over grep, glob, or bash for inspecting file contents. Usage is implied by the verb rather than stated.

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

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

Beyond the annotations (destructiveHint=true, openWorldHint=true), the description adds real behavioral context: add/update verify the remote root, may open a terminal for authentication, changes apply only to the next call, and no passwords are accepted or stored. It stops short of describing what a remove destroys or connection-state side effects.

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

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

Three dense sentences with no filler, and the action inventory is front-loaded. Each sentence carries distinct information (actions, auth behavior, persistence semantics).

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

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

For an 8-parameter, mutation-capable tool with no output schema, the description covers the key behavioral facts an agent needs (auth flow, next-call application, no stored credentials). It does not describe return shapes for list/status, which is a minor gap given no output schema exists.

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

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

Schema description coverage is 88%, so the schema already documents ssh, root, port, create, target, and controlPersist well. The description adds only the no-password/auth constraint and does not clarify parameter interactions (e.g., which params apply to which action), so the baseline 3 is appropriate.

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

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

The description names specific verbs (list/add/update/remove/connect/disconnect/check) and their resources (SSH targets, ControlMaster), so the tool's scope is immediately legible. It is a bundled multi-action tool, which slightly blurs a single purpose, and it never explicitly differentiates itself from the bash/read/write 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?

Usage is implied through action-level notes (add/update verify the remote root, connect/disconnect/check a ControlMaster) but there is no explicit 'use this when' guidance or comparison to alternatives such as invoking ssh through bash. The agent must infer which action to pick from the enum.

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 openWorldHint=true, so the overwrite semantics are partly covered structurally. The description still adds value beyond them: it clarifies that replacement is total, that paths resolve on the selected remote host, and that parent directories are created automatically. It does not disclose permissions/auth needs or failure behavior, keeping it short of a 5.

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

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

Two tight sentences, zero waste. The core action is front-loaded and the remote/target constraint follows immediately after.

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 remote write with destructiveness and open-world behavior already declared in annotations, the description covers location, path resolution, and parent-directory creation. It stops short of describing what a successful call returns or how failures/partial writes surface, though no output schema exists to cover that.

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 all three parameters are documented in the schema itself (target, content, file_path with relative-path resolution). The description reinforces the target-selection constraint but adds no syntax or format detail beyond the schema. 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 pair and resource ('Create or fully replace a UTF-8 text file'), and the word 'fully replace' implicitly carves out its scope against the sibling `edit` (partial modification) and `read`. An agent can tell what this does and how it differs from the other file tools 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 real context ('REMOTE: paths live on selected target') and the requirement to pick the intended host, which is genuine usage guidance for a remote tool. However, it never explicitly says when to choose `write` over `edit` or `read`, nor does it state exclusions. Usage 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.