create_note

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

With no annotations provided, the description carries full responsibility for disclosing behavioral traits. It clearly states error behavior (refuses with structured error for non-WRITE_VAULT), overwrite protection (refuses unless overwrite=True), and side effects (creates intermediate directories). This goes beyond basic functionality to cover permission constraints and destructive actions, which are critical for an agent to use safely.

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 sentences long, each sentence delivering distinct and necessary information: the core action, safety/error conditions, and side effects. It is front-loaded with the primary purpose and contains zero filler. Every word earns its place, making it both concise and highly structured.

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?

The tool has a straightforward creation task, yet the description covers all critical aspects: path format, permission restrictions, overwrite behavior, and directory creation. Since an output schema is present, the description appropriately skips return value details. For a 3-parameter tool with no annotations, it provides a complete operational picture without over-engineering.

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 0%, so the description must compensate for the bare schema. It adds meaning to 'source' by defining the format (vault/relative/path.md) and to 'overwrite' by explaining the refusal behavior unless it is True. 'content' is not explicitly described, but it is self-evident as the note body. It adds significant value for two of the three parameters, with the remaining one being intuitive.

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 'Create a new note at source (vault/relative/path.md format),' which clearly states the verb ('Create'), resource ('note'), and a specific path format. This precisely distinguishes it from sibling tools like update_note, delete_note, and read_note. It unambiguously identifies the tool's core function.

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 operational context: it can create notes only in WRITE_VAULT, it won't overwrite without overwrite=True, and it auto-creates intermediate directories. While it doesn't explicitly say 'use this instead of update_note when the note does not exist yet,' the term 'new note' and refusal to overwrite imply this. No alternative tools are named, so it's clear context without explicit exclusions.

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