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

Annotations only declare readOnlyHint=false, destructiveHint=false and openWorldHint=false; the description adds real signal beyond that — append-only semantics, no mutation of prior notes, paid/owner-only access, no live orders or model inference, and subscription-gated auth. What's missing is any statement about failure modes (e.g., what happens if version_id does not belong to book_id).

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 most decision-relevant facts — append semantics, non-destructive scope, cost and ownership — are front-loaded in the first two clauses. The trailing 'keyless: subscription_required with a subscribe link' is telegraphic and reads like pasted metadata, but it is short and does not bury the main point.

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 5-parameter mutation tool with no output schema, the description covers safety profile, access requirements, and scope of effect, which is most of what an agent needs. It does not say what the append returns (note ID or event linkage) or whether book_id and version_id must be mutually consistent, leaving a small gap.

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 schema description coverage at 100%, the schema already documents all five parameters including the optional event_id and the enum values for kind. The description only reinforces the version-linkage constraint implied by version_id/event_id, adding little beyond the structured fields.

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 and resource ('Append a version-linked journal note') and immediately scopes it with 'does not modify existing notes', which distinguishes it from the edit-oriented sibling research_paper_revise_journal. It stops short of naming that sibling outright, so the differentiation is inferential rather than explicit.

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 clause 'does not modify existing notes' functions as a when-not condition, implicitly routing edits to the revise tool, and 'Paid, owner-only' adds the precondition for calling it. There is no explicit 'use X instead' sentence, so an agent must infer the alternative from the sibling list.

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