hedgedoc_update_note

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

With no annotations, the description carries full burden. It discloses the destructive nature of full overwrite, the alias-only constraint, and failure mode for random-ID notes. It does not mention authentication or response semantics, but for a simple update operation, the key behavioral traits are well covered.

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 front-loaded with the main action, then follows with necessary caveats. The IMPORTANT notice is somewhat lengthy but each sentence provides essential warning information. It could be tightened slightly, but it's well-structured for a mutation tool with significant constraints.

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?

Given the tool's complexity (alias-only update, full overwrite), the description covers the critical constraints and failure modes. There is no output schema, and the description doesn't explain the response shape, but that's not a major gap for a straightforward update. The main usage scenarios and pitfalls are clearly communicated.

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 coverage is 100%, so the schema already documents both parameters. The description reinforces that note_id must be a custom alias and that content replaces the entire note, but it largely restates what is already in the schema descriptions, adding minimal extra semantic value beyond the structured fields.

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 clearly states the tool's purpose: 'Overwrite the entire content of an existing note.' It identifies the specific resource (note) and the action (full overwrite), and distinguishes itself from sibling tools like create, read, and info by specifying this is an update operation with full-content replacement.

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?

Usage guidance is explicit: it specifies that this only works for notes created with a custom alias, and that random-ID notes cannot be updated via HTTP. It also states the call will fail for non-alias notes and that partial updates are not supported, giving clear when-to-use and when-not-to-use conditions.

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