register_memory_source

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

Annotations already disclose write-but-non-destructive, closed-world behavior. The description adds two things annotations cannot: it preserves source author and revision history, and it does not execute instructions contained in the file body. The guarantee about non-execution is a meaningful safety signal. It omits what happens on duplicate registration and what is returned.

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?

A single dense sentence with the scope, the precondition, the preservation behavior, and the security note, all front-loaded. Nothing repeats the schema or the annotations, so every clause earns its 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?

No output schema and no annotations beyond a basic write profile, so the description needs to carry the return and edge-case behavior. It covers purpose, precondition, and safety, but does not state what is created/returned or what happens for a duplicate or unknown matter, leaving a gap for a three-required-parameter mutation tool.

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 0%, so the description must carry the parameter load. It implicitly covers all three: 'local Markdown project memory' maps to path, '来源作者' to author, and '属于事项' to matter. The mapping is conceptual rather than naming the fields or path format, so it stops short of fully compensating.

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 gives a concrete verb/resource pair ('将...本地 Markdown 项目记忆接入' = connect a local Markdown project-memory source) and scopes it to files already verified as belonging to a matter. That is enough to distinguish it from sibling write tools like remember or create_matter, though it does not name those siblings directly.

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 phrase '已核对属于事项' establishes a precondition (only registrations after the source has been verified as belonging to the matter), which implies when the tool applies. It offers no explicit exclusions and no comparison to alternatives such as remember or link_context, so the agent is left to infer the boundary.

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