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

Annotations already indicate this is a mutation (readOnlyHint=false) and not idempotent. The description adds the useful behavioral detail that the operation syncs to all connected Obsidian devices, but it does not disclose potential side effects like broken links or the need for vault selection (though vault_id is covered in the schema).

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?

Two sentences with no wasted words. The core action is front-loaded, and the sync behavior is stated as a secondary but relevant detail. Every sentence 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 a mutation tool with a full input schema and an output schema, the description is largely sufficient. It covers the primary action and a key behavioral trait (sync). It lacks explicit usage guidance and side-effect disclosure, but those are partially covered by other dimensions and the schema.

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 minimal semantic value beyond the schema—it clarifies that old_path and new_path are paths and that the operation is a rename/move, but does not elaborate on formats, constraints, or interactions between parameters.

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 specific verb ('rename or move') and resource ('a note to a new path'), making the tool's function immediately clear. It distinguishes itself from siblings like rename_folder and move_attachment by explicitly targeting notes.

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 implies usage for renaming/moving notes but provides no explicit when-to-use or when-not-to-use guidance. It does not mention alternatives such as rename_folder for folders or patch_note for content changes, leaving the agent to infer the appropriate context.

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