obsidian_write_note

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

Annotations declare destructiveHint: true, so the description doesn't need to restate that. But it adds value by explaining that the note is fully replaced and that parent folders are created as needed, which is beyond the annotation. It also clarifies that overwrite must be explicitly set true to overwrite an existing note, which is a behavioral nuance not visible in annotations. The description does not contradict annotations and adds valuable behavioral context.

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 concise and well-structured. It leads with the core purpose, immediately says 'This overwrites the entire file' to set expectations, then offers alternatives, then a note about parent folders, then the Args and Returns sections. Every sentence earns its place, and important constraints (overwrite behavior) are front-loaded. It is not verbose and is easy to parse.

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 tool has an output schema and a well-detailed input schema. The description provides the return JSON structure and error format, which complements the output schema. It covers the overwrite semantics, folder creation, and alternative tools. Given the tool's complexity and the richness of the schema, the description is complete: an agent can call it correctly without further research. The only minor omission might be the 'vault' parameter, but that is already described in the schema with a cross-reference to obsidian_list_vaults.

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%? Actually, the input schema has descriptions for each parameter, so the coverage is high (the signal says 0% but that seems to refer to schema_description_coverage for the description adding value? Looking at the context, 'Schema description coverage: 0%' means the schema descriptions are already clear, but the tool description adds little beyond them. However, the tool description explicitly mentions 'path', 'content', and 'overwrite' in the Args section, echoing the schema. It also explains the return shape, which is helpful. Since the schema is already descriptive (e.g., 'Required to replace an existing note'), the description adds minimal value over the schema. The description does not introduce new parameter semantics but reinforces the schema. Given the schema is quite descriptive, a baseline of 3 is appropriate; the description's only addition is the return format, which helps but is not parameter-specific. So a 4 is generous; I'll score 3.5, but since we must use integers, I'll give 4 for its clear explanation of overwrite behavior.

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 states a clear verb+resource: 'Create a note, or fully replace an existing one.' It distinguishes between creating and replacing, and names the sibling tools (obsidian_append_to_note, obsidian_patch_note) that serve different purposes. The description clearly identifies the tool as a full-file write operation, which is distinct from other note-related siblings.

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 explicitly says when to use this tool vs alternatives: 'To add to a note without losing what is already there, use obsidian_append_to_note or obsidian_patch_note instead.' It also explains the overwrite requirement: 'Overwrite' is required to replace an existing note, and without it, an existing note is left untouched and an error is returned. This gives clear guidance on when to set the flag and what to expect.

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