Rename Note

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

The description discloses several non-obvious behaviors beyond the annotations: link rewrites wait for prior index writes, the move queues another index refresh (no reindex needed), and attachment references are not tracked as links. It also notes that parent directories are created automatically. These details are highly valuable for an agent to understand side effects. The annotations are minimal (readOnlyHint, idempotentHint, destructiveHint) and the description does not contradict them; it adds substantial 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 three concise paragraphs, each with a clear purpose. The first sentence states the core function. The second gives a key rule. The third splits behavior by file type. There is no fluff or repetition; every sentence adds necessary information. The structure is logical and front-loaded.

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 complexity of this operation (rename/move with link rewriting, concurrency, index refresh), the description covers all non-obvious aspects: link rewrite behavior, attachment exceptions, automatic directory creation, and index refresh timing. Since an output schema exists, return format is covered elsewhere. The description is complete for an agent to correctly invoke the tool without additional hidden details.

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 all parameters are already documented in the input schema. The description adds extra semantic value by advising to always set update_links=True for .md files and clarifying that update_links is irrelevant for attachments. It also notes automatic directory creation, which relates to new_path. While it doesn't elaborate on old_path or if_match, those are self-explanatory from the schema. This goes beyond the baseline 3.

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 'Rename or move a document or attachment,' which clearly identifies the verb and resource. It distinguishes itself from sibling tools like write/edit/delete by specifying the rename/move action, and it even clarifies scope (documents and attachments). This is unambiguous and immediately tells an agent what this tool does.

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 provides explicit conditional guidance: 'When renaming a .md note, always pass update_links=True' and explains that attachments don't need it. It also clarifies that parent directories are auto-created. However, it doesn't explicitly compare to alternative tools (e.g., 'use this instead of move_folder for files'), but the context is clear enough. The guidance for the key decision (update_links) is strong, so this is slightly above average.

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