ssh_apply_patch

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 does reveal the fallback strategy (tries three tools in order), the strip=0 limitation for apply_patch, and dry-run support. However, it doesn't state side effects, requirements (e.g., the remote must have patch/git available), or behavior on failure across all three tools.

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, key facts front-loaded. Every sentence contributes: what it does, fallback tools, and supported features. Excellent concise 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 a tool with a fallback strategy and behavioral nuances (patch ordering, strip limitations, dry-run), the description provides reasonable but not exhaustive detail. There's no output schema to clarify return values, and the description doesn't explain what the tool returns on success/failure across the different tools. Adequate but could mention failure modes or prerequisites.

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 all 4 parameters are documented in the schema. The description adds context on how strip is handled (strip=0 only for apply_patch) and mentions dry-run, which supplements the schema. However, most of the parameter semantics come from the schema itself, so the description adds only marginal value beyond the baseline.

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

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

The description states the tool applies a unified diff on a remote host via SSH, distinguishing it from the many other ssh_* siblings. It clearly identifies the resource (remote host) and verb (apply_patch). However, it doesn't explicitly contrast with siblings like ssh_write_file or ssh_scp_to, though its purpose is specific enough to be understood.

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 useful context: it tries apply_patch (strip=0 only), then git apply, then patch, and supports dry-run and strip level. This implies applicability for applying diffs to remote files. However, it doesn't explicitly state when to prefer this over alternatives or when not to use it, leaving usage guidance somewhat 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.