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

Annotations declare create-only, non-destructive, non-open-world, and the description is consistent while adding real behavior: success is gated on the file 'verifiably exists', a NOT FOUND answer has a defined recovery path through name_platform, the folder name is plugin-owned and not caller-settable, and the returned answer marks doubt-wording lines. The one gap is that it never says what the normal return value contains.

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 lead is front-loaded, but the body sprawls into cryptic, self-referential sentences such as 'The notes folder is named by the plugin from the name this tool gave at the door, and it is the same name in every home', which is restated again later. Several sentences do not earn their place and the run-on structure makes the actual rules hard to extract.

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 4-parameter create tool with annotations but no output schema, the description covers error handling, naming, and content style. It is only partially complete: the shape of a successful response (path? confirmation?) is left implicit beyond a hint that doubt lines get marked.

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 only 50%, so the description must carry title and content: it does, specifying the 'fact — ...' title convention with newest-name-is-current ordering, and a whole 'Language:' paragraph governing how content is written (descriptive-of-truth, code blocks and quotes preserved). It also forecloses a nonexistent folder-name argument. It adds real value beyond the bare string 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?

States a specific verb and resource plus its scope: 'Save a dated, create-only note into this platform's own notes folder inside the home.' The create-only nature and Parking Lot routing are concrete. It does not, however, distinguish itself from the many capture_* siblings that presumably also write 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?

It gives conditional routing: an idea with no home goes to the Parking Lot, and a NOT FOUND answer means calling name_platform first. But there is no explicit statement of when to use save_note versus capture_decision, capture_correction, capture_definition, or organize_save, which is the main ambiguity an agent faces here.

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