Update Properties

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

Annotations already declare destructiveHint=true and idempotentHint=true, but the description goes well beyond them: it specifies shallow-merge semantics, that null deletes a key while unmentioned keys survive, that the body is never modified, a concurrent-write conflict condition, hidden-path blocking parity with Obsidian, and that arrays are replaced rather than appended. It also discloses the return value in the absence of an output schema.

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 core semantic contract and an example are front-loaded, then usage, errors, syntax, and return value, so it is easy to scan. The error enumeration is fairly long but each entry is actionable rather than filler; a slightly tighter grouping would make it ideal.

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?

For a two-parameter mutation tool with a nested free-form object and no output schema, this covers the semantics, an example, prerequisites, error taxonomy, and syntax pitfalls. Nothing an agent needs to invoke it correctly is missing, including the fact that the response is just a confirmation message.

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 the baseline is 3, but the description adds genuinely new semantics not present in the schema: a concrete call example, the warning that arrays are replaced entirely rather than appended, wikilink quoting requirements, and the risk of silent query failures from type mismatches. Only the top-level merge behavior is repeated from the schema.

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 opening sentence gives a precise verb+resource ('Update a note's frontmatter properties') and immediately defines the merge semantics, including that the body is never touched. It is clearly distinguishable from body-writing siblings like vault_write_note and vault_replace_in_note. An agent knows exactly what class of operation this is before opening the 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 has an explicit 'When to use' block (tags, status, type, any property without rewriting the body), names a specific alternative and its trigger condition ('Prefer vault_write_note when creating a new note, or replacing the body with overwrite: true'), and prescribes a prerequisite read via vault_read_note({ properties_only: true }). The only minor gap is that the closely-named sibling vault_patch_note is not contrasted.

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