get_vault_stats_tool

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

No annotations are provided, so the description carries the behavioral disclosure burden. 'Return vault statistics' makes clear this is a read-only aggregation, and the vault-wide statement adds a useful invocation trait. It omits deeper behavioral details like whether stats are live or cached or whether any special access is needed, but for an apparently read-only stats tool this is a reasonable baseline.

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?

Two crisp sentences with no filler. The purpose and output fields are front-loaded, and the vault-wide scoping note follows as a relevant clarification. Every sentence earns its place.

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?

The output schema likely covers the return shape, so the description does not need to fully spell out fields, though listing them is harmless. It is missing a definition of the `vault` parameter and does not route the agent away from sibling broken-link/orphan tools, leaving a small but real completeness gap for a low-complexity tool.

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?

The input schema has one optional `vault` parameter with 0% description coverage, and the description never mentions how `vault` should be populated, what it defaults to, or when to pass null. The only parameter-adjacent statement is about `path` not being carried, which concerns a non-existent property and does not explain the actual parameter. The description fails to compensate for the schema gap.

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 uses the specific verb 'Return' and names the resource 'vault statistics', then enumerates the exact aggregates: note count, link count, orphans, broken links, most-linked notes. This makes the tool's purpose clear, though it does not explicitly differentiate it from sibling tools like get_broken_links_tool or get_orphans_tool that target a subset of these stats.

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 'Vault-wide, so the envelope carries no `path`' sentence gives a clear scope boundary: this tool is for whole-vault statistics, not note-level operations. It does not name alternatives or state when to prefer get_broken_links_tool/get_orphans_tool, but it provides clear context and an exclusion of path-scoped usage.

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