history_vault

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

No annotations are supplied, so the description carries the full burden, and it does real work: it declares the return structure ({commit, author, date, subject}), recency ordering, the model that every vault write is one commit, and that a UID still resolves for deleted nodes via the file it last lived in. It stops short of stating that the operation is non-mutating, whether history is capped or how the limit truncates results.

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?

Three short blocks: return shape first, then accepted path forms, then usage and next steps. Every sentence adds information — no restatement of the name or filler.

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?

With no output schema, the description correctly takes responsibility for explaining the return value, and it covers the identity-resolution edge case for deleted nodes. It is slightly incomplete for a 2-parameter tool because the limit default and truncation behavior go unexplained.

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 0%, so the description must compensate, and it does so well for `path` by naming the three accepted forms (UID, absolute path, vault-relative path). The second parameter, `limit`, is never mentioned, so its meaning (and what happens when history exceeds it) is undocumented in both the schema and the prose.

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 ("List the commits that changed a node") plus ordering ("newest first") and even shows the return shape. That is enough for an agent to tell this apart from siblings such as list_vault, query_recent, diff_vault and restore_vault without opening any schema.

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?

It gives a concrete trigger scenario ("when content is missing after a write") and a follow-up chain (diff_vault to see the change, restore_vault to undo it), which is unusually actionable routing. It does not state when NOT to use it — for example versus list_vault or query_recent for broader history — so it falls short of full exclusion guidance.

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