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

With no annotations provided, the description carries the full burden of behavioral disclosure. It transparently states the two key failure modes: fails if the path already exists and fails if the parent directory doesn't exist. This goes beyond minimal disclosure and addresses the most likely risks for a file-creation operation. However, it does not mention authentication/session preconditions or return behavior, leaving some gaps.

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: the first states the primary purpose and orientation, the second gives essential failure conditions and the alternative tool. No redundancy, clearly front-loaded, 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?

The description thoroughly covers the core create operation and its main failure conditions, and it differentiates from ssh_edit. However, for a tool with 9 parameters and no output schema or annotations, it leaves out several pieces of context: how it interacts with SSH sessions (sibling tools ssh_start_session, ssh_ensure_session exist), how it differs from file-transfer tools like ssh_scp or ssh_sync, and what the tool returns on success. This is not fully complete, but it is adequate for the primary use case.

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

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

Schema description coverage is 67% (6 of 9 params described), which is moderate. The description adds meaningful context for the 'path' parameter by specifying it must not already exist and its parent directory must exist, and it clarifies 'content' as the full content to write. However, it does not explain the remaining parameters (port, identity_file, known_hosts_file, extra_ssh_args, timeout, strict_host_key_checking) beyond what the schema already provides. Baseline 3 is appropriate for this moderate 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?

The description clearly states the verb ('Create'), the resource ('a new remote file'), and the method ('over SSH'). It explicitly distinguishes from ssh_edit, which is the primary sibling alternative, and also references the local file-creation tool as a counterpart. This satisfies the specific verb+resource+scope requirement.

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 context: use this for creating a new remote file, not for modifying an existing one (use ssh_edit instead). It also provides a critical precondition (parent directory must exist) and a failure condition (path already exists). This is direct, actionable guidance for an AI 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?

With no annotations provided, the description carries the behavioral burden. It transparently discloses critical behavior: each old_str must match exactly one location, edits are applied in order, and ambiguous or missing matches fail without writing anything. It also explains the read-then-write batching behavior, which is useful beyond the schema. It does not mention permissions or backup behavior, but the core mutation semantics are well disclosed.

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 long, front-loaded with the core action, and every sentence contributes: the first states purpose, the second explains safety guarantees, and the third gives batching rationale. There is no redundancy or 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?

Given nine parameters, no annotations, and no output schema, the description covers the operation's main semantics well: exact matching, atomicity on failure, sequential edits, and batching efficiency. It does not describe return values or file permission implications, which are not strictly required but would round out completeness. Overall, it provides enough context for an agent to select and invoke the tool safely.

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 67%, leaving port, identity_file, and known_hosts_file undocumented. The description compensates by adding meaningful semantics to the 'edits' parameter: uniqueness requirement, sequential application, and batching benefit. It also adds guidance to prefer dedicated port/identity_file/strict_host_key_checking parameters over extra_ssh_args. This adds value beyond the schema, though some standard SSH parameters remain 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 opens with a specific verb+resource: 'Replace exact text in an existing remote file over SSH', making the purpose unmistakable. It also distinguishes itself from siblings by labeling it the 'remote counterpart of the local file-editing tool,' which clearly separates it from other SSH operations like exec, scp, or view.

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: use for exact-text replacement in remote files and batch multiple edits to avoid multiple SSH round trips. It does not name explicit alternative tools for cases like fuzzy edits or complete file rewrites, but the guidance is otherwise clear and actionable.

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 no annotations provided, the description carries the full burden of behavioral disclosure. It transparently explains the reuse-ignore semantics and the response status distinction, which are essential for correct usage. It does not mention potential side effects like tmux creation or auth behavior, but the core get-or-create behavior is well disclosed.

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

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

The description is compact, front-loaded with the primary purpose, and then provides essential usage and behavioral notes in three sentences. Every sentence adds value; there is no fluff or repetition of schema details.

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 14 parameters and a get-or-create workflow, the description covers the most critical contextual points: session naming for reliability, the reuse behavior, and the response interpretation. It does not enumerate every parameter (schema does that), but it gives the agent enough context to use the tool correctly in a multi-step workflow.

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 71%, and the description adds crucial semantics beyond the schema: it names the specific parameters (cwd, env, shell) that are ignored on reuse and explains their scope (only apply when creating). This directly compensates for potential ambiguity in the schema and helps the agent reason about parameter relevance per call.

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 precise verb and resource: 'Return an existing running SSH session or start a new one.' It clearly distinguishes this get-or-create tool from sibling tools like ssh_list_sessions and ssh_start_session by framing its role as the recommended session management entry point for agent workflows.

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 it ('recommended tool for agent workflows') and provides actionable guidance: always provide a descriptive session_name. It also clarifies the critical conditional behavior—when a session is reused, cwd/env/shell are ignored—and instructs the agent to check the 'created' vs 'reused' response field to know which case occurred.

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 no annotations, the description carries the full burden. It discloses non-interactive behavior, the POSIX shell requirement, and that stdout/stderr/exit metadata are returned. However, it omits potential side effects of arbitrary command execution, authentication behaviors, and timeout handling.

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 concise sentences: the first states the purpose and output, the second gives parameter guidance, and the third provides an alternative. Front-loaded and free of redundant 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?

Given the tool's complexity (12 parameters, no output schema), the description provides a good overview but does not fully specify return structure, timeout behavior, or edge cases. It explains enough to start using the tool, but the schema and sibling context are needed for complete understanding.

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

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

The schema covers 75% of parameters with descriptions, so the baseline is 3. The description adds value by mentioning cwd and env, but does not compensate for the missing port, identity_file, and known_hosts_file descriptions. Those names are self-explanatory in an SSH context, so the marginal contribution is modest.

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

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

The description clearly states the tool runs a one-off remote SSH command and returns stdout, stderr, and exit metadata. This specific verb and resource distinguish it from sibling session-management tools like ssh_ensure_session and ssh_start_session.

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 notes the non-interactive context and directs users to ssh_ensure_session for interactive or long-running commands. It also provides guidance on using cwd/env and the POSIX shell requirement, giving clear when-to-use and alternative instructions.

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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It explains the direction semantics but omits critical operational details: whether the forward is long-running, whether it blocks, how it can be stopped (the sibling ssh_stop_forward is not mentioned), authentication requirements, or failure modes. This is a significant gap for a tool that starts a persistent process.

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, all information-dense and front-loaded. The first sentence states the core purpose, the second explains the permission-gating differentiation, and the third provides actionable direction guidance. No wasted words.

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

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

This is a complex tool with 11 parameters, no output schema, and no annotations. The description covers the core concept and direction semantics, but lacks essential context about return values, long-running behavior, prerequisites, and how to manage the forward after creation. Given the complexity, the description is incomplete and leaves too much to inference.

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 73%, so the baseline is 3. The description adds meaningful context for the 'direction' parameter with detailed usage examples, but it does not clarify the undocumented parameters (port, identity_file, known_hosts_file). It adds some value beyond the schema but does not fully compensate for the missing parameter documentation.

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 'Start a dedicated SSH port forward (local or remote)', which is a specific verb+resource pairing. It explicitly distinguishes itself from ssh_exec/ssh_start_session by noting it enables permission-gating for port forwarding, clearly separating it from sibling 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 context on when to use this tool via the permission-gating rationale, and gives concrete direction guidance ('Use direction 'local' to make a remote service reachable on a local port, or 'remote' to expose a local service on the remote host'). It doesn't explicitly mention exclusions relative to other forward-related tools like ssh_list_forwards/ssh_stop_forward, but the primary usage 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?

With no annotations present, the description carries the full burden of behavioral disclosure. It adds valuable details beyond the name: enumerates via remote find, skips .git/.hg/.svn directories, performs matching locally, and explains the dot-file matching rule. It does not mention potential performance implications or return format, but the disclosed behavior is substantial.

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

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

The description is three sentences and front-loads the primary purpose. Every sentence adds distinct value: purpose, pattern syntax, and behavioral details (VCS skipping, local matching, dot rule). There is no filler or redundant repetition of 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?

Given 10 parameters, no annotations, and no output schema, the description covers the key behavioral aspects: matching semantics, base directory, and VCS exclusion. It does not explicitly state the return format, but that is inferred from 'Find'. The description is largely sufficient for an agent to decide when to invoke it and how to construct patterns.

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 70%, and the description adds significant meaning beyond the schema. It explains the glob pattern syntax ('*', '?', '[seq]', '{a,b}', '**'), the special dot-segment matching rule, and clarifies that enumeration happens under 'path'. This goes well beyond the schema's simple 'Glob pattern to match' and 'Remote base directory to search under.'

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 purpose: 'Find remote files by name pattern over SSH' with the specific verb 'Find' and resource 'remote files'. It also differentiates itself by calling itself 'the remote counterpart of the local filename-pattern tool,' distinguishing it from other SSH operations like exec or scp.

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

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

The description provides clear context that this is the remote counterpart to a local filename-pattern tool, implying it should be used when you need to find files by name pattern over SSH. However, it does not explicitly mention when not to use it or name alternative sibling tools (e.g., ssh_grep), so it stops short of full when/when-not 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?

With no annotations, the description carries the burden of behavioral disclosure. It reveals regex flavor (PCRE-like -P fallback to POSIX ERE), directory skipping (.git/.hg/.svn), and default output mode. This adds meaningful context beyond the schema, though it omits details like SSH authentication behavior or error handling.

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, tightly packed with essential information. Front-loaded with purpose, then key behavioral traits. No filler or redundancy; 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 16-parameter tool with no output schema and no annotations, the description covers the core behavior well: purpose, regex variant, recursion behavior, and output modes. It does not elaborate on SSH-specific parameters like identity_file or strict_host_key_checking, but those are adequately described in the schema and are secondary to the tool's core function.

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 81%, so the baseline is 3. The description goes beyond the schema by explaining regex semantics (PCRE vs POSIX), the meaning of 'path' recursion and skipped directories, and the default output mode. These details help the agent understand parameter behavior more deeply.

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 function: 'Search remote file contents over SSH'. It distinguishes itself as 'the remote counterpart of the local content-search tool', making its role unambiguous and differentiating it from sibling tools like ssh_glob.

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 clear context that this is the remote search counterpart, implying use when remote content search is needed. Offers in-tool guidance about defaulting to files_with_matches for efficiency and using content mode for line details. However, it does not explicitly exclude alternatives or mention when not to use this tool.

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 no annotations provided, the description carries the full burden. It notes that only 'tracked' forwards are listed and includes 'running status', which conveys state reporting. However, it does not explicitly state that this is a non-mutating read operation or disclose any prerequisites or side effects, which would strengthen transparency.

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 sentence of 16 words, efficiently front-loaded with the verb and resource, and then listing the key output fields. Every word contributes value with no fluff.

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 absence of an output schema, the description compensates by enumerating the returned fields. However, it does not specify the return format (e.g., array vs. object) or the exact behavior of include_stopped beyond the schema. For a simple list tool, this is adequate but has minor gaps.

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

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

The input schema has 100% description coverage for its two parameters (target and include_stopped), so the baseline is 3. The description does not add further parameter semantics; it merely lists 'target' as an output field, which could be slightly confusing but is not harmful.

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 'List tracked SSH port forwards', a clear verb+resource combination. It enumerates the specific output fields (forward_id, direction, ports, target, running status), distinguishing it from sibling tools like ssh_forward and ssh_stop_forward.

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 clearly implies usage for listing forwards, but it does not explicitly state when to choose this tool over alternatives such as ssh_forward or ssh_stop_forward. There is no mention of when not to use it or any exclusions, leaving usage as 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?

With no annotations, the description carries the burden. The verb 'List' implies a read-only operation, and the description details the return fields, including 'tmux_session_name for cross-referencing with tmux ls,' which is a useful behavioral hint. It does not mention default values like include_exited=true, but the schema covers that.

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 the verb and resource front-loaded. Every clause adds value: the list of return fields and the cross-referencing hint. No filler or 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 tool is a simple list operation with three optional parameters fully described in the schema. The description explicitly enumerates the output fields, compensating for the lack of an output schema, and adds a practical cross-referencing note. This is complete for the 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 description coverage is 100%, so the schema already documents all three parameters. The description's only added semantic value is the tip about using session_name to find a specific named session, which is a minor usage nuance rather than a meaningful semantic expansion.

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 verb ('List') and resource ('tracked SSH sessions'), specifies the exact fields returned, and distinguishes it from sibling tools that operate on sessions (stop, exec, read, edit, etc.). The mention of 'session_id, session_name, target, state, uptime' adds specificity that makes the purpose unambiguous.

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

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

Provides a clear usage tip: 'Use session_name filter to find a specific named session.' This gives practical guidance on when to use the filter. However, it does not explicitly contrast with sibling tools or state when not to use this tool, so it stops short of full usage differentiation.

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 no annotations, the description discloses blocking behavior, default wait time, and the meaning of output flags. It also mentions the 'running' status check. It stops short of explicitly stating whether reading drains the buffer, though 'drain remaining output' implies it.

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 specific purpose: state the function, explain the wait_seconds behavior, and flag additional signals. No redundancy or 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?

The description covers the key operational facets: wait behavior, default, return signals, and session liveness. Since there is no output schema, these return-related details are essential. It doesn't cover error cases or exact return shape, but for a read tool it is adequate.

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

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

The schema description coverage is only 33%, so the description must compensate. It does explain wait_seconds in detail (blocking, default, examples) but max_output_chars is only implied through 'truncated' and 'pending_output_chars'. session_id is left to context, but its purpose is understandable from the overall 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 the exact operation: 'Read unread output from a tracked SSH session.' This is a specific verb+resource pairing that clearly distinguishes it from sibling tools like ssh_exec or ssh_write_session. The scope is unambiguous.

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

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

It gives explicit guidance on wait_seconds for blocking vs immediate returns, and instructs to call again if 'truncated' or 'pending_output_chars' indicates more output. It doesn't explicitly name alternative tools, but the usage context is clear enough for an agent to select it appropriately.

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?

No annotations are provided, so the description carries the full burden. It mentions copying but does not disclose behaviors like recursive handling, authentication requirements, or side effects such as overwriting. The schema reveals parameters like timeout and strict_host_key_checking, but the description adds no context about these behaviors.

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

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

The description is a single concise sentence, front-loaded with the core action and scope. Every word earns its place without unnecessary elaboration.

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 12 parameters, no output schema, and no annotations, a one-sentence description is inadequate. It neither explains return values, error handling, nor usage scenarios. The tool is more complex than the description suggests, and the lack of context around security, recursion, or path handling leaves significant 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 67%, so the baseline is 3. The description adds minimal parameter semantics beyond the schema; it does not explain the unannotated parameters (port, direction, identity_file, known_hosts_file). The schema itself provides descriptions for most parameters, but the tool description does not compensate for the gaps.

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 ('Copy') and clearly identifies the resource (files or directories) and the direction (between local machine and remote target). It also names the underlying mechanism ('local scp client'), distinguishing it from sibling tools like ssh_exec or ssh_sync.

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 for file transfer but does not explicitly state when to prefer scp over sync (ssh_sync) or other transfer tools. No exclusions or alternatives are mentioned, though the purpose itself gives a clear context.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It reveals that the session is persistent, interactive, backed by a local PTY, and that output may be buffered (truncated/pending_output_chars) requiring a follow-up call. It does not describe cleanup, side effects, or failure modes, but the persistence and buffered-output behavior are meaningfully disclosed.

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

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

The description is four sentences and front-loads the core purpose. It efficiently covers the tool's function, return values, follow-up handling, and alternative tool recommendation without redundancy or unnecessary detail. 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?

Considering the complexity (14 parameters, no output schema, no annotations), the description provides a clear operational flow: start session, check truncated/pending_output_chars, read remaining output, and prefer ssh_ensure_session. It covers the primary invocation patterns adequately, though it could benefit from more on session lifecycle (e.g., cleanup, auto_close behavior) which is only partially covered in 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 coverage is 71%, and most parameters already have descriptions in the schema. The description adds operational context (e.g., reading remaining output via ssh_read_session) but does not elaborate on individual parameter usage beyond what the schema provides. Since the schema does most of the heavy lifting, the description's contribution is marginal.

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 function: 'Start a new persistent interactive SSH session backed by a local PTY.' It specifies the resource (SSH session) and the action (start), and distinguishes it from sibling tools by explicitly recommending ssh_ensure_session for most workflows. The description also notes the return values (session id, initial output, observer metadata), making the purpose concrete.

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

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

The description provides explicit usage guidance: it explains when to call ssh_read_session (if truncated or pending_output_chars > 0), and when to prefer ssh_ensure_session instead ('For most agent workflows, prefer ssh_ensure_session instead — it reuses existing sessions and avoids accidental duplicates'). This directly addresses the when-to-use vs alternatives criterion.

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 no annotations, the description carries full burden. It discloses that it stops and returns final status, but does not explain side effects (e.g., whether the session remains open, forward is removed from tracking, or if stopping is reversible). Insufficient for a mutation-like operation.

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

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

A single concise sentence with the verb first, no filler. It efficiently states the action and result, though it lacks additional structural detail for edge cases.

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 tool with no output schema, the description is minimally adequate—it states the action and that status is returned. However, it misses usage context and behavioral nuance (e.g., how final status is determined, what happens to the forward tracking), leaving clear 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 coverage is 100%, so the parameter forward_id is already documented. The description adds no extra meaning beyond the schema; 'tracked' is implied by the tool name. 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 uses a specific verb ('Stop') and resource ('tracked SSH port forward') with a clear action. The word 'tracked' helps distinguish from generic stopping (e.g., ssh_stop_session), but it does not name alternative tools, so it is clear but not fully differentiating.

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

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

The description provides no guidance on when to use this tool versus siblings like ssh_stop_session or ssh_forward. It implies usage (stop a tracked forward) but offers no exclusions, prerequisites, or alternative recommendations.

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 no annotations, the description carries the burden. It discloses key side effects: session termination, tmux observer cleanup, return of unread output and exit metadata, and preservation of the transcript file. This is more transparent than typical. However, it omits details like default signal (SIGTERM vs SIGKILL) and potential blocking behavior, which are partially covered by the 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?

A single, front-loaded sentence delivers all essential information without redundancy. Every clause adds value: termination, observer cleanup, return value, and file preservation. It is optimally 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?

The core behavior is described, but key operational details are missing: parameter semantics for max_output_chars and session_id, return format details, and error handling. Since there is no output schema, the description should provide more specifics. The tool is moderately complex (4 params, no annotations), and the description is adequate but not 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 50%, and the description does not compensate. It fails to explain the format or purpose of session_id and max_output_chars. The phrase 'final unread output' hints at max_output_chars but does not explicitly connect them. The description adds no meaning beyond the schema.

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

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

The description clearly states the action ('Terminate'), the resource ('tracked SSH session'), and additional distinguishing behaviors ('close any attached tmux observer', 'return final unread output plus exit metadata'). This differentiates it from siblings like ssh_stop_forward and ssh_read_session.

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 usage context is implied: it is the tool to stop an SSH session. However, there is no explicit 'when to use' vs alternatives or exclusions. Sibling tools are not mentioned, so the agent must infer when to choose this over similar 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 no annotations provided, the description carries the full burden of disclosing behavioral traits. It says 'incrementally sync' and 'via rsync over SSH', which hints at the transfer mechanism, but it does not warn about potential destructive effects (e.g., overwriting files, deletion when delete=true), authentication requirements, or what happens on failure. The risk profile of a sync tool is significant, and this one-liner does not surface it.

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 that packs a clear verb, resource, and mechanism into minimal words. There is no redundant language or repetition of the tool name. Every phrase 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 having 15 parameters, 4 required, and no output schema, the description gives no information about return values, error handling, prerequisites (like an active SSH session), or when to prefer this over siblings. The complexity of the tool warrants more contextual detail than a single sentence. The description is not sufficient for an agent to confidently invoke this tool in all reasonable scenarios.

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 73%, and most parameters have their own descriptions. The tool description adds no per-parameter information, but it does clarify the overall local-remote split (one local side, one remote target), which helps interpret source/destination. Since coverage is neither high nor low, a baseline of 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 states a specific verb ('sync'), a specific resource ('files or directories'), and a specific mechanism ('local rsync over SSH'). It also scopes the operation to one remote target, which distinguishes it from sibling tools like ssh_scp (one-off copy) and ssh_exec (command execution). The purpose is immediately clear.

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 guidance is provided on when to use this tool versus alternatives. It does not mention that one-off copies should use ssh_scp, or that this tool is suited for incremental/backup scenarios. The description lacks any 'when to use' or 'when not to use' context, so the agent must infer usage from the name and 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?

With no annotations, the description carries the full burden. It discloses file return fields (size_bytes, total_lines), default 20KB truncation, view_range bypass, force_read_large_files behavior, and directory depth/visibility limits. It does not mention auth or error behavior, but the key behavioral traits are transparent.

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, front-loaded with purpose, and each subsequent sentence adds behavioral detail without fluff. Excellent conciseness and structure.

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 11-param tool with no output schema and no annotations, the description covers the primary use cases and important behavioral details: file output, directory listing, truncation, and paging. It omits the exact return format for directories and some edge cases, but it is adequate given standard SSH parameters are self-explanatory.

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 73%, so the description adds meaning by explaining how max_bytes, view_range, and force_read_large_files interact with truncation. However, most parameters (port, identity_file, timeout, etc.) rely on the schema or are self-explanatory, and the description doesn't compensate for uncovered 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 verb-resource pair: 'Read a remote file or list a remote directory over SSH,' which immediately conveys purpose and scope. It also notes it is the 'remote counterpart of the local file-viewing tool,' distinguishing it from siblings like ssh_exec or ssh_grep.

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?

Clear context is provided: use for reading files or listing directories, and use view_range to page through large files instead of reading the truncated default. It does not explicitly name alternative sibling tools or exclusion criteria, but the usage is well-scoped and practical.

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 no annotations, the description carries the full burden and does well by disclosing control-character encoding, newline behavior, and the response field pending_output_chars. It explains how writes should be submitted and how to drain output, but it does not mention error cases or invalid session handling, leaving some gaps.

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 earning its place: the write action, newline/control characters, and the wait/drain workflow. There is no redundancy with the schema, and the information is front-loaded and directly actionable.

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 four-parameter tool with no output schema and no annotations, the description covers the essential workflow: how to write, what to expect (pending_output_chars), and when to call ssh_read_session. It omits max_output_chars semantics, but the operational flow is adequately specified for effective use.

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

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

The schema covers only 50% of parameters (input and wait_seconds), and the description significantly enriches those: control codes, newline requirement, and wait_seconds usage. However, max_output_chars is never mentioned in the description, so one parameter remains underdocumented.

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 the specific verb 'Write' and the resource 'tracked SSH session PTY', clearly distinguishing it from siblings like ssh_read_session and ssh_exec. It also states the exact scope (text or control sequence), making the tool's function immediately obvious.

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

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

The description gives concrete usage rules: trailing newline to submit, control character mappings, wait_seconds recommendation (1-5), and when to follow up with ssh_read_session based on pending_output_chars. It does not explicitly contrast with ssh_exec, but the interactive PTY context implies the appropriate use case.

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