ssh_edit

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.