dir_ops

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

The description lists operation names and a return envelope but discloses no actual behavior: whether remove_directory recurses or fails on non-empty directories, what `mirror` and `overwrite` do to existing destinations, what `dry_run` previews, what the robocopy vs shutil engine selection implies, or what `timeout` governs. Moreover, the enumerated `remove_directory`/`move_directory` operations conflict with the declared destructiveHint=false, so the safety profile an agent reads from annotations is wrong.

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?

Headers and a compact example block give it a front-loaded, scannable shape, and the operation list is efficient. However, the 'Args: See Parameters block.' line is pure waste, and the Return Format section largely restates the output schema that already exists.

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 18-parameter, eight-operation mutation tool with zero schema descriptions, the description needs to at least map parameters to operations and flag which combinations are risky; it does neither. The output schema being present excuses the return-format brevity, but the invocation-side gaps (engine choice, dry_run scope, mirror/overwrite interactions, destination_path) are large.

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 0% across 18 parameters, and the description's only nod to them is 'Args: See Parameters block.' — a pointer to a block that contains no descriptions. Only path, operation, max_depth, recursive, and human_readable appear incidentally in examples; engine, mirror, dry_run, pattern, timeout, exist_ok, max_files, overwrite, output_format, create_parents, include_hidden, destination_path, and exclude_patterns are undocumented everywhere, including which ones apply to which operation.

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 opening line names the resource (directory structure) and the description enumerates all eight supported operations explicitly, so an agent can see the full verb set at a glance. It does not distinguish itself from the sibling `file_ops` or `search_ops` (file-vs-directory scope, listing vs searching), so the sibling differentiation is left implicit.

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 examples show three calls but never say when to pick one operation over another, when to prefer this over `file_ops`, or when a directory operation is unsafe/inappropriate. Nothing signals that remove_directory, move_directory, or copy_directory with mirror=True are destructive paths requiring care, and there are no stated preconditions.

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