update_note

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

With no annotations provided, the description carries full responsibility for behavioral disclosure. It does reveal a specific edge case: 'Prepend mode will error if content starts with "---" to prevent frontmatter conflicts,' which is valuable. However, it does not disclose the destructive nature of overwrite mode, what happens if the note path doesn't exist, or return value/error format. This is partial disclosure, not comprehensive.

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 two sentences long, front-loaded with the primary action ('Update an existing note'), and then efficiently summarizes the modes and a critical edge case. Every sentence adds value with zero redundancy 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?

For a 7-parameter mutation tool with no output schema and no annotations, the description covers the core functionality and one important error condition. However, it omits mention of the 'ignoreFrontmatterConflict' parameter that directly addresses the stated error, and gives no information about return values, success/failure behavior, or the default mode. This is a noticeable gap for an agent selecting and invoking the 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?

Schema description coverage is 100%, so the baseline is 3. The description adds contextual meaning to the prepend mode by explaining the frontmatter conflict error, which is not fully captured in the schema. This enriches understanding of both the 'mode' and 'ignoreFrontmatterConflict' parameters, though it doesn't mention the escape hatch parameter directly.

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 starts with 'Update an existing note,' which is a clear verb+resource statement that distinguishes it from sibling tools like create_note, read_note, and delete_note. It further clarifies the different modes (overwrite, append, prepend, replace), making the tool's purpose unmistakable.

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 phrase 'existing note' implies this is for updating notes that already exist, contrasting with create_note. The modes themselves serve as usage guidance (e.g., append to add to end, replace for find-and-replace), but there is no explicit 'when-not-to-use' or named alternative. This is clear context but not fully explicit about exclusions or sibling alternatives.

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