mh_write

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

No annotations are provided, so the description carries the full behavioral disclosure burden. It confirms the write nature and the mandatory completion rule, but does not mention whether the operation is new-entry-only, whether it can overwrite or merge, authentication/permissions, or any failure/error behavior. For a mutation tool with zero annotation coverage, this is a meaningful transparency gap.

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 concise and front-loads the core action, then lists the essential parameter semantics in compact clauses. It avoids excessive wording and every sentence adds information. The only minor loss is a slightly disorganized ordering of requirements, but overall it is well-suited for an efficient read.

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?

Given the tool has 7 parameters and no output schema, the description leaves several operational gaps: it doesn't state what the tool returns, how errors are signaled, or exactly what happens when a new entry conflicts with existing data. It also does not differentiate between writing a new memory and updating/replacing one via siblings. These are non-trivial details an agent needs to reliably invoke and verify the operation.

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 86% schema coverage, the schema already documents most parameters. The description reinforces layer/category semantics and adds the 'important conclusions must be persisted' rule, but it mostly duplicates the schema's own parameter descriptions. It does not add per-parameter nuance that goes beyond the schema, so the baseline of 3 is appropriate.

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 starts with a clear verb and object (写一条记忆/知识 to the memory hub), explicitly names the target resource (openmem), and constrains it with required source, layer, and category values. It does not explicitly contrast itself with the sibling mh_update, but the verb 'write' versus 'update' strongly suggests a create-style operation.

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 description gives a high-level condition (重要结论不写入=任务不算完成), which implies that important conclusions should be written here, but it does not state when not to use it or mention alternatives like mh_update or mh_service. There is no inclusion/exclusion guidance or reference to other tools, leaving an agent to infer when to switch to a sibling tool.

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