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

Adds substantial context beyond the annotations: notes are always private, saving is decoupled from asynchronous background organization tracked in organize.state, and the retry contract is spelled out — same request_id returns the same note, and calls without one are not safe to retry automatically. This clarifies the idempotentHint=false annotation rather than contradicting it.

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?

Five sentences, each carrying payload, with the core purpose and the draft_note alternative front-loaded before the retry and organization details. Slightly dense but no filler.

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 write tool with an output schema, the description covers privacy, retry safety, and async side effects — the things an agent most needs. The one meaningful gap is how overlapping content/content_blocks and id/name parameter pairs interact when both are supplied.

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?

With 0% schema description coverage across 8 parameters, the description does real work: it maps content to plain text/markdown/structured blocks, explains request_id's semantics fully, and notes that exact tag, topic and resource IDs disambiguate names. It leaves the precedence between content and content_blocks and the subject_names string-or-list form unaddressed.

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 ("Saves a private Linko note") plus the accepted input forms and optional associations, which precisely delimits it from draft_note and edit_note. An agent can tell what it creates without opening the schema.

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 explicitly names draft_note as the alternative when exact wording isn't confirmed, giving a clear selection rule. It says nothing about when to use this versus edit_note or linko_save_note for existing or partial content, so routing is clear but not exhaustive.

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