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

Annotations already declare readOnlyHint=false and destructiveHint=false, so the write semantics are partly covered; the description still adds real value by stating the tool is owner-scoped, that the server resolves plain entity names, that `gics` routes themes to megatrends, and what the return payload ({id, created_at, linked} with unresolved names) looks like. However, much of the length is editorial policy about note quality rather than behavior of the call itself, and there is no mention of rate limits, duplicate handling, or what `linked.unresolved` means operationally. Solid additions over annotations, but not a full behavioral picture.

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?

Front-loaded with the core action and a numbered typical flow, then organized under clearly labelled sections (CONTENT, ENTITY LINKS, WHEN TO SAVE, agent) — an agent can scan it quickly. It is verbose for a save operation and repeats table-preservation guidance that already appears verbatim in the body schema, so a few sentences do not fully earn their 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 13-parameter write tool with no output schema, the description covers the write semantics, the entity-linking model, the return shape, the provenance requirement, and the decision rule for when to invoke — everything needed to call it correctly. No material gap remains.

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 baseline is 3; the description earns above that by adding routing semantics the schema only hints at — e.g. that `gics` accepts plain English and the server resolves sectors/themes, that `megatrend_ids` is an advanced escape hatch normally replaced by naming a theme in `gics`, and that `agent` must be one of a fixed enumerated surface list. It omits any treatment of the `context` parameter and does not explain portfolio_id or category beyond what the schema says, so it stops short of full coverage.

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?

Opens with a specific verb+resource: 'save a NOTE to the user's account', and explicitly disambiguates the operation class ('this PERSISTS data; it is NOT a read/lookup'), which cleanly separates it from the retrieval siblings get_note and query_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 'WHEN TO SAVE' block gives explicit use criteria (capture substantive investment content, lean toward keeping), explicit exclusions (chit-chat/thanks, trivial lookups, off-topic content), and an override rule ('an explicit save this → always save'). It also prescribes timing within the turn, which is a genuine when-to-use instruction rather than inferred guidance.

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