vault_move_folder

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

With no annotations provided, the description bears the full burden, and it does disclose two useful behavioral facts: links are updated, and missing parent folders are created automatically. It does not state what happens if the destination folder already exists, whether the operation can be undone, or what permissions the vault requires, which leaves gaps for a mutation tool.

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 leads with a single-sentence purpose, then gives two short parameter notes with examples. Nothing is redundant, though the trailing parenthetical about creating parent folders is attached to 'destination' rather than presented as a separate behavioral note.

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?

An output schema exists, so the description need not explain the return value, and the two required parameters are covered. For a link-rewriting mutation with no annotations, however, the missing details on destination conflicts, reversibility, and scope of link updates leave the behavior only partly specified.

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 0%, so the description must explain both parameters, and it does: 'source' is a folder path such as 'Projects/X', and 'destination' is the folder's NEW full path, which clarifies rename-versus-move semantics that the bare schema cannot convey. The examples are the main reason these parameters are usable.

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 gives a specific verb and resource: moving and/or renaming a folder in the vault, plus the side effect of updating links. The word 'folder' implicitly distinguishes it from the sibling vault_move_file, but no sibling is named explicitly.

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?

You can infer from 'folder' that this tool moves folders while vault_move_file moves files, and from 'move and/or rename' that vault_rename is probably for other objects. Beyond that inference, however, it gives no guidance on when to use this tool rather than its siblings, and no prerequisites or exclusions.

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