List Vault Files

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

No annotations are supplied, so the description carries the full behavioral burden and leaves out the traits that matter most for a listing tool: whether traversal is recursive into subfolders, whether hidden/dot files or non-note attachments are included, whether results are truncated or paginated on large vaults, and what the entries look like. "All files and folders" hints at breadth but never resolves recursion or return shape.

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?

A single well-formed sentence with the scope information up front and no filler. It is efficient, though its brevity is partly the cause of the missing behavioral detail rather than a virtue in itself.

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 one-optional-parameter read tool with no output schema, the definition covers the basics and the schema fully documents the parameter. It stops short of what an agent needs to interpret results correctly, namely recursion depth, filtering of non-note files, and any size limits on large vaults.

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%, and the schema already states "Optional path to list files from (empty for root)", so the baseline applies. The phrase "vault or a specific path" restates that same idea without adding format conventions (leading slash, relative vs absolute, vault-name prefix) or clarifying whether the path is a folder or a file.

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?

"List all files and folders in the vault or a specific path" gives a specific verb (list) and resource (files/folders), with the scope clearly bounded to a vault root or subtree. It is distinguishable from siblings like obsidian-get-note or obsidian-search-notes by the fact that it enumerates rather than retrieves or queries, though it never names an alternative 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?

There is no explicit when-to-use guidance, no stated prerequisites, and no pointer to alternatives such as obsidian-search-notes for filtered lookups or obsidian-get-vault-info for aggregate info. The listing intent is implied by the verb "list" but nothing tells the agent which of these exploration tools to pick.

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