update_memory

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

With no annotations, the description carries the full disclosure burden and reveals the most important side effects: changing content preserves the old version (marked invalid + superseded_by) and creates a new version for the audit chain, while changing tags/confidence/subject updates in place. It does not specify behavior for dedup_key changes or possible errors, so it is not fully transparent.

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 description is a single compact sentence with no filler. The core purpose is front-loaded, and the behavioral distinction between content changes and metadata changes is stated precisely and efficiently.

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 no annotations and no output schema, the description covers the main behavioral risk: versioning and the audit chain. It also clarifies which fields are updated in place. Minor gaps remain around dedup_key semantics, return values, and failure behavior, but the essential information needed to call the tool correctly is present.

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 17%, so the description must compensate for missing parameter documentation. It adds meaningful semantics for content, tags, confidence, and subject by explaining whether each triggers versioning or in-place updates, but it says nothing about dedup_key and adds no detail about id. This is partial compensation, not complete.

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 ('事实'), and goes beyond the tool name by explaining the actual update semantics. It clearly distinguishes update_memory from sibling tools like save_memory and forget_memory through the versioning versus in-place behavior.

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?

Usage is implied: use this tool when modifying an existing fact. However, it does not explicitly say when to prefer update_memory over save_memory or forget_memory, nor does it mention alternatives or exclusions. The conditional guidance about content versus metadata changes is useful but not a full when-to-use/when-not-to-use statement.

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