Initialize Wiki

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

Beyond the idempotentHint annotation, the description details exactly what happens: existing files are preserved, folders are never deleted, and force:true re-seeds specific files. It discloses the return shape ({ created, skipped }) and the resolution order for the wiki location. This is rich behavioral context that goes well beyond the annotations.

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 well-structured: purpose, idempotency, return value, resolution order, vault selection, and examples. It is detailed but every sentence contributes useful information. The two examples cover the main use cases (first-time scaffold and forced re-seed) without being repetitive.

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?

Given the tool has 3 optional parameters, no required input, and an idempotent, non-destructive behavior, the description covers everything an agent needs: what gets created, what force does, what is returned, how the target vault is determined, and that it should be run before other wiki.* tools. No critical information is missing.

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 100%, so all parameters are documented in the schema. The description adds extra meaning by explaining the precedence order (wikiRoot arg → KOBSIDIAN_WIKI_ROOT env → wiki/) and that vaultPath always wins over the session-active vault. This synergy between parameters is not in the schema, adding genuine value.

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 opens with a specific verb and resource: 'Scaffold the LLM-Wiki layout under the vault: creates Sources/, Concepts/, Entities/ folders and seeds index.md, log.md, and wiki-schema.md'. This clearly states what the tool does. It also distinguishes itself from siblings by noting 'Use this once per vault before calling any other wiki.* tool', making its unique role unmistakable.

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 explicit usage context: 'Use this once per vault before calling any other wiki.* tool.' It also explains the idempotent default and when to pass force:true, and clarifies vault selection rules ('Operates on the session-active vault... unless an explicit vaultPath argument is passed, which always wins'). This is full guidance on when and how to use it.

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