add_observations

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

Annotations already declare the write/safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false), so the description's main remaining job is to disclose edge behavior — duplicate handling, what entityName must match, what happens on unknown entities. None of that appears. Worse, the one behavioral claim present ("Legacy deletion is logical and retained in history") describes deletion on a tool that adds observations, which misdirects rather than informs; it is consistent with destructiveHint=false but irrelevant here.

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 text is short but badly front-loaded: the leading sentence is about the storage backend rather than the operation. The final sentence concerns deletion, which does not belong in an add tool's description and consumes one-third of the available space with off-target content.

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 mutation tool with a nested-object array parameter, no output schema, and no parameter descriptions, the description needs to carry substantial weight — and it does not. The only genuinely useful information (shared v2 SQLite store, prefer native tools) is swamped by an unexplained deletion clause that raises more questions than it answers.

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% and the description adds nothing about the single `observations` array parameter — not its shape, the entityName/contents pairing, the 100-item and 20000-char bounds, nor whether entities must pre-exist. The definition entirely abandons the agent to reading the raw schema, and the key ambiguity (does add_observations create the entity or fail if missing?) is left unanswered.

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 never states what the tool does — the name 'add_observations' is the only clue that observations are being added, and the text never confirms it. It spends its sentences on implementation provenance ("backed by the same v2 SQLite store") and deprecation framing instead of a verb+resource statement. An agent cannot tell from the text alone whether this reads, writes, or deletes.

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?

"New callers should prefer versioned native memory tools" is real steering away from this tool, which is more than most definitions offer. But it names no specific alternative among the many siblings (remember_memory, create_entities, etc.), and it gives no condition under which this legacy path IS the right call. The exclusion is implied rather than actionable.

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