update_note

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

With no annotations, the description carries the full behavioral disclosure burden. It reveals that title/content changes trigger re-embedding, title changes update wikilinks, substantial rewrites are subject to server rules, and expected_updated_at causes a refusal instead of silent overwrite. It does not mention return shape, errors, or how tag changes behave, but the core mutation behavior is 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 four dense sentences with no filler. The core action is front-loaded, side effects are stated immediately, and the concurrency/tag guidance earns its place.

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 an update tool with no output schema and no annotations, the description supplies the critical operational facts: when side effects happen, when server rules apply, and how to avoid lost updates. It could mention the return value or folder_id null behavior, but the essential information for correct invocation is present.

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?

Only expected_updated_at has a schema description, so the description must compensate for low coverage. It does clarify expected_updated_at semantics and connects title/content to side effects. However, it adds little meaning for id, tags, or folder_id beyond their names and schema types.

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 opens with a clear verb and resource: 'Update note fields.' The additional side-effect details (re-embedding, wikilink updates) help characterize this as a field-level update tool rather than an append or replace operation. It does not explicitly contrast with create_note or append_to_note, so it misses the top score.

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 gives clear context for when to use this tool: to update fields of an existing note. It also supplies actionable guidance, such as calling list_tags before coining a new tag and passing expected_updated_at for optimistic concurrency. It does not explicitly state when to prefer append_to_note or replace_in_note, so it is not a full 5.

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