ssh_mkdir

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

No annotations exist, so the description carries the behavioral burden. It discloses the non-obvious mkdir -p semantics clearly: existing intermediate directories are tolerated while an existing leaf path remains an error. It could also mention authentication expectations or result/error reporting, but the most important behavioral nuances are covered.

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 focused sentences earn their place: the core operation comes first, and the second sentence explains the one flag that materially changes behavior. The code-style formatting is precise and the description contains 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?

The core operation, the important flag, and the key error semantics are all present, and the schema fully covers every parameter. The description could be more explicit about which authentication path to use or what the success/error return looks like, but the tool is simple enough that an agent can invoke it correctly with current information.

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 already documents all seven parameters at 100% coverage, so the baseline is 3. The description adds value by clarifying the recursive behavior beyond the schema, especially the tolerated-intermediate-dirs vs valid-leaf distinction. This pushes it slightly above 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 starts with a specific action and resource: create a directory on a remote host via SFTP. This clearly distinguishes it from sibling read, write, list, and transfer tools without requiring the agent to inspect schemas.

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 practical guidance for the recursive flag and explains important edge-case behavior, which implies the intended use. However, it never explicitly compares this to alternatives such as using ssh_exec for mkdir, so the when-to-use-vs-sibling 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.