vault_append

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

With annotations only declaring the generic safety flags, the description carries substantial extra load: it discloses upsert semantics, optimistic-concurrency requirements for existing files, a silent side effect (missing final LF is added), input rejection rules (binary/NUL refused), and retry behavior ('no automatic retry'). These are exactly the traits an agent cannot infer from 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?

Four compact clauses, no filler, and the primary action is front-loaded before the caveats. Every clause adds a distinct operational fact, so nothing could be cut without losing information.

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?

An output schema exists, so return values need not be explained, and the description covers creation, concurrency, encoding, and retry behavior. Remaining gaps are minor: no mention of the content size cap enforced by maxLength, no path-format guidance, and no note on permissions or failure modes.

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 for two of three params: ifMatch's conditional requirement and content's UTF-8/text-only constraint. It says nothing about the path parameter (format, vault-relative vs absolute), leaving one gap, and the sha256: prefix format is only conveyed by the schema pattern.

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?

States a specific verb+resource ('Append UTF-8 text') plus upsert behavior ('creates missing files'), which cleanly separates it from vault_write and vault_patch without naming them. Sibling differentiation is implied by the verb rather than stated explicitly, so it falls just short of a 5.

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?

Gives one real conditional rule ('Existing files require ifMatch'), which tells the agent when a parameter becomes mandatory. However, it never says when to choose vault_append over vault_write or vault_patch, nor any preconditions such as vault availability or path scoping, so usage is only partially covered.

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