List Notes By Folder

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

The description references an explicit `vaultPath` argument that does not exist in the input schema. This is misleading and could cause an agent to pass an invalid parameter. While annotations already cover readOnly/idempotent/destructive hints, the description adds inaccurate behavioral context rather than useful information, and the vault-selection behavior is described in a way that conflicts with the actual parameter list.

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 two short paragraphs. The first paragraph states purpose and plugin requirements; the second clarifies vault selection. Information is front-loaded, and every sentence serves a purpose. There is no fluff or repetition of schema details.

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?

While the description covers plugin requirements and vault behavior, the major inconsistency of referencing a `vaultPath` parameter not present in the schema creates a significant gap. An agent relying on this description might try to pass `vaultPath` and fail. The output schema exists, so that part is not an issue, but the misleading information makes the description incomplete and potentially harmful.

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%, so every parameter already has a clear explanation. The description adds an example for `sortBy` ('file.ctime desc') and clarifies the DQL mapping for where/sort/limit, but this is marginal. It does not significantly enhance understanding beyond what the schema provides, and the misleading `vaultPath` mention negatively impacts clarity.

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 clearly states it is a convenience wrapper around `LIST FROM "folder"` with optional DQL clauses. It explains the exact use case ('every note under a vault folder') and naturally distinguishes it from siblings like dataview.query (general DQL) and dataview.listByTag (by tag). The verb and resource are specific and unambiguous.

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 says it is 'useful when you want every note under a vault folder,' which is a clear usage context. It also mentions the Dataview and Local REST API plugin requirement. However, it does not explicitly name alternatives like dataview.query or state when not to use this tool, relying instead on implication from the term 'convenience wrapper.'

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